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.titleanddescriptionare a label and a hint shown in the editor.keyFieldmarks 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.
$craftcan'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.
Links and worked-out values
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.