Craft

Reference fields

Every form a reference field takes in a schema and in a file. Each section stands on its own.

One reference

A field that points at one file of one type. It is a string field with referencedFileTypeSlug naming the target type:

{ "armor": { "type": "string", "referencedFileTypeSlug": "armor" } }

The value in a file is one reference (see stored form).

A list of references

An array whose items are references. Use it when a file points at many things: known spells, members, active conditions.

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

References inside rows

A reference can sit inside the rows of a list, beside details that belong to the link rather than to the target, like how many of an item a character carries:

{
  "inventory": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "item": { "type": "string", "referencedFileTypeSlug": "item" },
        "quantity": { "type": "number" }
      }
    }
  }
}

Several target types

A field that accepts files of more than one type lists them in reference.targets. Each target may carry a filter.

{
  "loot": {
    "type": "array",
    "items": {
      "type": "string",
      "reference": {
        "targets": [{ "fileTypeSlug": "weapon" }, { "fileTypeSlug": "item" }]
      }
    }
  }
}

A field can target at most 5 types. referencedFileTypeSlug and a one-target reference.targets mean the same thing; a filter needs the reference.targets form.

Stored form

Once a reference is saved, it is stored as an object with three keys:

{
  "armor": {
    "slug": "leather-armor",
    "referenceId": "0197a4c2-5b1e-7c3d-9f20-6a8b4c2d1e0f",
    "fileTypeSlug": "armor"
  }
}
  • referenceId is the lasting pointer. It survives renames and is what load() follows.
  • slug is the target's slug when the reference was last saved. After a rename, it is brought up to date the next time the file holding the reference is saved.
  • fileTypeSlug is the target's type, which matters when the field has several target types.

Every reference is stored this way: a single one, each item of a list and each one inside a row.

Writing a reference

Write the target file's slug: "leather-armor", or a list of them, ["mage-armor", "magic-missile"]. A file's slug comes from its name ("Nature's Tongue" is natures-tongue; the rule is in names and slugs). The save looks the slug up among the target type's files and stores the full reference.

In a field with several target types, write type/slug ("weapon/dagger"), because slugs are only unique within a type.

In the app you never type slugs: you pick the file in the field's picker. Slugs matter only when you edit a file's JSON by hand.

To clear an optional reference, set it to null or leave the field out. Never write "".

Unresolved references

A slug that matches no file is kept as a draft, { "slug": "fire-arrow" }, and the save goes through. It becomes a full reference on a later save, once the target exists. A draft points at nothing: load() gives null for it and the page shows no file.

A bare slug that matches files of two target types also stays a draft; write type/slug instead. A reference whose file was deleted keeps its id and points at nothing while the file is in the trash; restoring the file links it again.

Filters

A filter narrows which files of a target type the field can point at. It belongs to one target in reference.targets:

{
  "fileTypeSlug": "spell",
  "filter": {
    "op": "and",
    "args": [
      { "op": "eq", "left": { "scope": "target", "path": "class" }, "right": { "scope": "source", "path": "class" } },
      { "op": "lte", "left": { "scope": "target", "path": "level" }, "right": { "scope": "source", "path": "level" } }
    ]
  }
}

A filter is one comparison (op, left, right), or an and or or group in args. A group can hold comparisons and other groups, up to the depth in Limits. A plain array of comparisons means and.

Pickers only offer files that pass. A comparison whose source field is empty is skipped, so a character with no class set sees every spell. A reference that fails its filter (written by hand, or the character changed class since) still saves and stays in place.

The filter is checked when the schema is saved: an unknown op, a field that doesn't exist, or a comparison that could never match is refused with the reason.

Filter operands

Each side of a comparison is one of:

Operand What it reads
{ "scope": "target", "path": "level" } A field of each file the picker considers (the spell).
{ "scope": "source", "path": "level" } A field of the file being edited (the character).
A plain value: "head", 3, true, ["common", "rare"] That value.
{ "scope": "literal", "value": "head" } The same value, written out in full.

A path names a stored field, with dots for nested fields. A filter can compare text, number, enum, true/false and reference fields, and lists of references on the right of in and nin. It can't use computed fields (their values aren't stored) or lists of plain values.

  • gt, gte, lt and lte need numbers on both sides.
  • A true/false field compares with true or false.
  • A reference compares with another reference or a slug, never a number or true/false. Two references must share a target type, or they could never match.

Filter ops

Op Matches when
eq Equal. Two references are equal when they point at the same file; a reference also matches its file's slug.
neq Not equal.
in One of a list: a fixed list of enum values or slugs on the right, or a list-of-references field on the right that includes the left side.
nin Not one of a list: the opposite of in.
gt Greater than. Numbers only.
gte Greater than or equal. Numbers only.
lt Less than. Numbers only.
lte Less than or equal. Numbers only.

Booleans compare with true or false, never the text "true". in and nin take a fixed list only for enum and reference fields (a list of slugs); for free text, use eq.

Comparing references

Two references are equal when they point at the same file, so a filter can compare reference fields directly. To offer only feats of the character's class:

{ "op": "eq", "left": { "scope": "target", "path": "class" }, "right": { "scope": "source", "path": "class" } }

When each feat lists several classes, put the list on the right of in ("the feat's classes include the character's class"):

{ "op": "in", "left": { "scope": "source", "path": "class" }, "right": { "scope": "target", "path": "classes" } }

A reference also matches a slug, so { "op": "eq", "left": { "scope": "target", "path": "class" }, "right": "wizard" } works too.

In the filter editor, in and nin against a list field read includes and excludes.

Limits

Limit Value
File types one reference field can target 5
Comparisons in one and or or group that holds only comparisons 3
Conditions in one filter, in all 12
Levels in a filter, counting each group and the comparisons inside the last one 3
Values in an in or nin list 10

In layouts and expressions

  • A layout shows references with FileReferenceGrid (cards with an add and remove picker) or Select, and one field of each referenced file with ReferenceValue. See layout components.
  • An expression reads the referenced file with load(). See the expression language.