Objects and schemas

An object is a structured record kept in the project — a character, a location, a piece of equipment, a recipe, a config. Where a document is prose, an object is fields.

Each object is a file, so objects diff in git and can be edited outside Zero like anything else.

Objects on their own

Create an object on the Objects page and you get an editor with tabs over the same document:

• Form — one control per field.
• JSON — the document itself.
• Page — appears only when the object's schema has a page view.

Without a schema, an object is free-form: whatever JSON you write is the object. That is the right starting point when you do not yet know the shape.

Schemas

A schema is a JSON Schema that describes a shape — the fields a kind of object has, which of them are required, and what may go in them.

Attach a schema to an object and two things change: the Form tab builds itself from the schema instead of being empty, and the JSON tab validates as you type, marking what does not fit.

Schemas live on the Object Schemas page, whose header reads Schemas. Each one has:

• a name, a free label for reading;
• an alias, a short unique key used to refer to the schema from elsewhere — Zero checks it is not already taken;
• an icon and a colour, picked in the editor header;
• the definition itself.

The icon and colour belong to the type, so they are chosen once and then drawn on the schema and on every object of it, everywhere objects are listed. Giving each kind of thing its own mark is most of what makes a project with five schemas readable at a glance.

The field holding the JSON Schema is called the definition, not the "schema", so that a schema does not end up containing a schema.

The schema editor

One strip of tabs across the same record:

• Fields — a visual editor: add a field, pick its type, mark it required.
• JSON — the definition as text, for anything the field editor cannot express.
• Actions — behaviour: buttons that run workflows. See Views and actions.
• Views — how objects of this schema are drawn. Same page.

Actions and Views carry a count when they hold anything.

Switching away from Fields is never refused. A definition the field editor cannot read stays in the draft, and JSON is where it gets fixed — the editor declining to leave would trap you with a document only the other tab can repair.

What a schema can describe

The form is generated from the schema, so schemas are kept to a shape a form can honestly represent: plain fields (text, number, yes/no, a choice from a list), references to other items, and lists whose entries are plain fields or a flat group of them.

A field the form cannot render is shown as unsupported rather than left out. Silently dropping a row would say "the schema does not declare this", which would be a lie — and the JSON tab is always there to edit it directly.

A list of records is one of those cases: the Form tab sends you to the JSON tab for it. A view renders the same list as a table without difficulty, which is often the better answer than editing it as a form at all.

References

A field can point at another item in the project rather than repeating its contents. Pick the target with the item picker; the reference stores the target's identity, so renaming the target does not break the link.

From a view, a reference can be followed one step and opened as a link — which is how a week plan lists the recipes it names, or a quest names its patron.

Finding objects

Two surfaces exist for browsing them, because they answer different questions:

• Object Browser, from the tray at the foot of the nav rail, opens as a tab: schemas with counts down the left, the objects of the selected schema on the right, and a search box over them.
• Objects, a tab in the bottom browser panel: the same split, sized for keeping open beside whatever you are working on.

Objects without a schema are a legal state, not an error. They are counted and visible in both.