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"
}
}
referenceIdis the lasting pointer. It survives renames and is whatload()follows.slugis 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.fileTypeSlugis 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,ltandlteneed numbers on both sides.- A true/false field compares with
trueorfalse. - 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) orSelect, and one field of each referenced file withReferenceValue. See layout components. - An expression reads the referenced file with
load(). See the expression language.