Orientation

Mental Model

A SJON document is a flat list of roots. Most authored files use one root form:

(scene :bpm 130)

Open in playground →

Inside that form:

• (scene ...) is a form.
• scene is the form head.
• :bpm 130 is a kvpair.
• 130 is an atom.

SJON itself does not know what scene means. A host application is the program embedding SJON, such as a game engine, compiler, or build tool. It loads one or more plugins, then validates the document against the vocabulary those plugins provide. Ordinary .sjon files do not import plugins.

Expressions use the same surface as data forms:

(camera :zoom (* 2 4))

Open in playground →

(* 2 4) is just a form in source. It becomes a safe expression only when the active schema says * is an expression function and the host chooses to evaluate that value.

Worked Example

From ../../examples/basic.sjon:

(scene :bpm 130 :name "intro"
  (canvas :name "main" :size [1920 1080]
    (camera :ortho :zoom 2)
    (stack :mode :overlay
      (shape :sdf :radius 0.5 :color [0.9 0.4 0.2 1.0])
      (shape :path :closed true
        :points [[0 0] [1 0] [1 1] [0 1]]))
    (placeholder :note "TODO" :enabled false :data nil)))

Open in playground →

Read it as a tree:

• The document has one root: the (scene ...) form.
• scene has two kvpairs before its child: :bpm 130 and :name "intro".
• canvas, camera, stack, shape, and placeholder are nested forms.
• [1920 1080], [0.9 0.4 0.2 1.0], and [[0 0] [1 0] [1 1] [0 1]] are vectors.
• "intro" and "TODO" are strings.
• true, false, and nil are reserved literal atoms.
• :ortho, :sdf, and :path are positional flags in this source. Two more flags are hiding in (stack :mode :overlay ...); section 5 explains why two consecutive keywords don’t pair into a kvpair.

Exercises

1. Open ../../examples/basic.sjon.
2. Count the root values. Then count the forms.
3. Mark each vector and write its likely role: size, color, point, or list of points.
4. Find every string. Decide whether each string is a label, note, or payload.
5. Find every positional flag. Do not decide whether the schema likes it yet; just identify the parse shape.

Repair drill:

:bpm 130

Open in playground →

This cannot be a valid top-level kvpair because kvpairs only live inside forms. Repair it by wrapping it in a form:

(scene :bpm 130)

Open in playground →

Mastery Check

1. Can a document have more than one root?

   • Yes — a document is a sequence of root values.
   • No — every document must have exactly one root form.
   • Only if separated by a blank line.

2. Does a .sjon file import plugins?

   • No — the host loads plugins; the file just uses their vocabulary.
   • Yes, with an (import ...) form at the top.
   • Only when the document begins with (plugins ...).

3. Is (* 2 4) always evaluated just because it looks like arithmetic?

   • Yes — any list whose head is * is multiplied automatically.
   • Only inside (let ...) blocks.
   • No — it is just a form in source; it becomes an expression only when the active schema and host say so.

4. Where can a kvpair appear?

   • At the top level, between root forms.
   • Only inside a form, as a :key value pair among the form's children.
   • Inside a vector, between two values.

Submit answers