Craft

Field types

A schema is a JSON Schema object: "type": "object", its fields under properties, and the names of the fields every file must fill in under required. Each entry below is one kind of field, as the schema editor names it. The examples are checked against the same rules a save uses.

Base fields

Craft adds these to every type, Markdown or JSON. Don't define them: a copy you write is replaced. voice is reserved, and only character types have it.

Field Type Required What it is
name Text yes The file's name. Every file has one, and it can't be empty.
description Text A short blurb shown on cards and lists.
image Image The file's cover picture.
voice Text Character types only: the voice the character speaks with. Empty uses the GM's voice.

Options every field takes

  • required (on the object holding the field) lists the fields a file must have. Leave computed fields out of it.
  • default (top-level fields) fills the field when a new file is made without it. It is never applied to files that exist, and it must keep the field's own limits.
  • title and description are a label and a hint shown in the editor.
  • keyField marks a field key (true), or turns a default key field off (false). See key fields.

A file can hold values for fields the schema doesn't name. They are kept as they are and never checked, so a field removed from the schema leaves its old values in the files.

Limits

  • At most 200 top-level fields in a type, and 100 in each object field.
  • At most 100 file types in a world.
  • $craft can't be a field name.

Values

Text

Words: a name, a short label or pages of prose.

Schema { "type": "string" }
Options minLength, maxLength, default

In properties:

{"motto":{"type":"string","maxLength":120}}

In a file:

{"motto":"Never twice the same road."}

Long prose and short labels are both text: the layout decides how much room it gets. A value that only ever takes a few known words is an enum.

Number

A number you count, compare or use in a computed field.

Schema { "type": "number" }, or "integer" for whole numbers
Options minimum, maximum, default

In properties:

{"level":{"type":"number","minimum":1,"maximum":20,"default":1}}

In a file:

{"level":3}

Agents and players sometimes write a number as text ("12"); it is stored as a number when the field is one.

Boolean

Yes or no: a switch that is on or off.

Schema { "type": "boolean" }
Options default

In properties:

{"requiresAttunement":{"type":"boolean","default":false}}

In a file:

{"requiresAttunement":true}

Enum

One value from a fixed list of choices, picked from a menu.

Schema { "type": "string", "enum": [ … ] }
Options default (one of the values)
Limits At most 50 values.

In properties:

{
  "rarity": {
    "type": "string",
    "enum": ["common","uncommon","rare","legendary"],
    "default": "common"
  }
}

In a file:

{"rarity":"rare"}

A value is matched to the list without regard to case or spaces around it when a file is written, so "Rare" is stored as "rare". Keep the list short and closed. When an entry needs its own description or stats, make it a type and use a reference.

Image

A picture, with its focal point and how it was made.

Schema { "type": "object", "format": "image" } ({ "type": "image" } is read the same way)

In properties:

{"portrait":{"type":"object","format":"image"}}

Never use a text field for a picture. A file stores an image object (its url, focal point and how it was made), not a bare link, and a link from another site or a data: URL is refused. For no picture, leave the field out. What the object holds: image fields.

Lists and groups

List

Any number of values of one kind, in order.

Schema { "type": "array", "items": { … } }
Options minItems, maxItems

In properties:

{"tags":{"type":"array","items":{"type":"string"},"maxItems":10}}

In a file:

{"tags":["noble","exiled"]}

For a list of links to other files, the items are a reference field. For rows with their own values, the items are an object: an inventory row pairs an item reference with a quantity, because the quantity belongs to the row, not the item. Many files can link the same file: an item file is the kind of item, and each holder's row is their copy, so never copy an item file for each holder.

Object

A group of named fields kept together inside one field.

Schema { "type": "object", "properties": { … } }
Options required (its own required fields)
Limits At most 100 fields.

In properties:

{
  "reward": {
    "type": "object",
    "properties": {
      "gold": {"type":"number","minimum":0},
      "reputation": {"type":"string"}
    }
  }
}

In a file:

{"reward":{"gold":50,"reputation":"The miners' guild owes you."}}

Use named fields in an object for slots that mean different things (mainHand, offHand, armor). For a family keyed by name (one entry per skill), a file can store any keys in an object field whose schema lists none of them.

Reference

A link to another file, or a list of links.

Schema { "type": "string", "referencedFileTypeSlug": "<type slug>" }, or "reference": { "targets": [ … ] } for several types; inside items for a list
Options a filter on each target
Limits At most 5 target types; at most 3 conditions in a filter group.

In properties:

{
  "knownSpells": {
    "type": "array",
    "items": {"type":"string","referencedFileTypeSlug":"spell"}
  }
}

In a file:

{"knownSpells":["magic-missile"]}

A file stores a reference as the target file's slug, and Craft keeps the target's id beside it so the link survives a rename. To point at several types, give each target its own entry in reference.targets, and write values as "<type>/<slug>". Targets, filters and how values are written: reference fields.

Computed

A value worked out from other fields when the file is read. It is never stored and can't be edited.

Schema any type above with an "expression"; the type is what the expression gives back
Options items or properties to say the shape of a list or object it gives back
Limits Top-level fields only. Never in required. Not stored, so it takes no default.

In properties:

{
  "strength": {"type":"number"},
  "strengthModifier": {
    "type": "number",
    "expression": "floor((($self.strength ?? 10) - 10) / 2)"
  }
}

The expression reads the file's own fields as $self.<field> and a referenced file through load(). Nothing is stored, and a value written to a computed field is dropped. The language and its functions: expressions.