4. Facets

A facet says what a key means: its type, how many values it holds, its choices, its unit, its other names and its version. A facet's definition is pairs about a key, written in the long form (4.2), in one line of shorthand (4.5), or as JSON (4.6). All three hold the same settings.

A facet never says what is true of a record, what a kind of thing asks for, or what must hold. Those are data (chapter 1), classes (chapter 5) and rules (chapter 6). Some settings are shortcuts for rules (4.4): they are written on the facet because nearly every facet needs them, and they expand to rules with one engine behind them.

4.1 Identity and versions #

• The key is the identity and never changes. It is written with its owner's prefix (me:videoCodec); inside the owner's own files the bare key is enough. A rename changes the label, and the old spelling becomes a key alias (4.3).
• Versions are dated: YYYY-MM-DD, with .2, .3 … for a second or later version published the same day (2026-10-13.2). A published version MUST NOT change. Each facet is versioned on its own; a package version is a frozen set of member versions (chapter 11).
• A facet MAY carry a short ID (F-7KQ2) for display or tooling. It is never the identity.
• Lifecycle. A facet is candidate, active or retired (state:, default active). A candidate is proposed vocabulary: it is stored and reviewable, but forms, views and rules don't see it, and class lines can't name it. A review decision promotes it to active, or merges it into an existing facet (its key and aliases become that facet's aliases). A retired facet keeps its stored values readable but is never asked for again; retiring is breaking (4.8). Classes have the same lifecycle (chapter 5.1).
• Stored values carry no version. A breaking change (4.8) ships a migration recipe (chapter 10).

4.2 The long form #

facet: videoCodec
  label: Video codec
  ask: How is the picture encoded on the disc?
  describe: The codec of the main feature, as read from the disc or its case.
  type: choice
  values: MPEG-2, H.264, VC-1 ~vc1, HEVC, AV1
  aliases: codec, "Video Format"
  same-as: schema:encodingFormat
  version: 2026-10-13

A definition is a block under facet: key. Its settings:

Every type #

By type #

Shortcuts for rules #

required, na, unique, when, length, range and combine (4.4).

Package settings #

A setting key with a prefix (me:scanRank) belongs to that package. A reader that doesn't know it MUST carry it unchanged and MUST NOT let it change what the facet means. Machinery (which service fills a facet, how a scanner ranks it) lives here, never in the core settings.

4.2.1 Open, closed and fixed lists #

A list is fixed only when the world fixes it (Blu-ray regions A, B, C). A closed list is just the list we have so far. ... and fixed: yes MUST NOT both be set.

4.3 Aliases #

Aliases are naming, not rules. They mean the same thing always, everywhere, for that facet.

• Key aliases (aliases: codec) are other spellings of the key.
• Value aliases (VC-1 ~vc1 ~"VC 1") are other spellings of one choice value.

Folding. Aliases are folded before any rule runs. Stored data never holds an alias, and printers write only the real name. Matching compares fold keys: the spelling in NFC, with Unicode default case folding, leading and trailing spaces removed, and every run of white space made one space. The real key and the real value match under the same folding, so dvd folds to DVD without an alias.

What isn't an alias. If it depends on context, it is a suggest rule. If it is another system's vocabulary, it is a contract's value map (->). If it is the same thing under different facets, it is a shared link (&wd:…).

Dictionary rules (checked when a package is published, 4.7):

• a key alias MUST NOT fold to the same key as another facet's key or key alias in the package;
• a value alias MUST NOT fold to the same key as another value or value alias of the same facet;
• two values of one facet MUST NOT fold to the same key.

Changes. Adding an alias is safe. Removing one is safe for stored data but can break imports, so it is a minor change. Turning a value into an alias of another is a merge, which is breaking (4.8).

4.4 Shortcuts for rules #

Each shortcut expands to one rule (chapter 6), with the facet as its subject. The expanded rule is the truth; the setting is a short way to write it.

A rule written in full and a shortcut that say the same thing are the same rule; a package MUST NOT carry both.

Combine rules: join, sum, best, narrow, worst, deduct, replace, keep. The default is join for many-valued facets and replace for single ones. best and worst need a ranked choice, a number or a date. Only replace depends on the order contributions arrive in.

4.5 Shorthand #

One facet on one line, for the common case. It always expands to the long form.

!title$200 ~name =schema:name
videoCodec{MPEG-2|H.264|VC-1~vc1|HEVC|AV1} ~codec =schema:encodingFormat /2026-10-13
productionFormat{Full Length Movie|Shorts|...}
releaseDate@any
runtime#min 1..600
price#USD
sealed?
condition{NM|VG|G|F|P} ranked
cast(person&Person character$)* identity: person
genres{Comedy|Holiday|Drama|...}*

Read left to right:

line     = [ "!" ] key type [ count ] *( " " tail )
type     = "$" [ digits ]                      ; text, optional length
         / "#" [ unit ]                        ; number, optional unit or currency
         / "@" ( "y" / "ym" / "ymd" / "ymdh" / "ymdhm" / "ymdhms" / "any" )   ; date, its precision
         / "@" ( "hm" / "hms" )                ; time of day, its precision
         / "?"                                 ; yes-no
         / "{" choice *( "|" choice ) [ "|..." ] "}"   ; choice, optionally open
         / "&" target                          ; link
         / "^"                                 ; image
         / "(" line *( " " line ) ")"          ; compound
choice   = value *( "~" value )                ; a value and its spellings
count    = "*" [ digits ]                      ; any, or up to N
tail     = "~" key                             ; key alias
         / "=" key                             ; same as
         / "+" combine                         ; combine rule
         / "/" version                         ; version
         / number ".." number                  ; range
         / setting                             ; a bare word or "name: value" from 4.2

• ! is required: yes. @ alone means @any. The letters after @ always run y, m, d, h, m, s, so the second m is minutes: @ymdhm is a date with a time to the minute, @hm a time of day.
• A choice value holding |, ~, {, }, (, ) or a space at either end is quoted with chapter 2's quoting: {"A|B"|C}.
• Inside a compound's parentheses, children are separated by spaces and are themselves shorthand lines.
• Settings with no mark (label, ask, describe, qualifiers, accepts, places, words, ranked, scored, fixed, na, unique, when, ordered, identity, package settings) go on the line as bare tails: a word alone means yes (ranked), and name: value gives a value (identity: person). A list value runs on after each comma (accepts: g, lb, oz); any other value with a space is quoted.
• The level mark unit:: belongs to class lines (chapter 5), not to a facet's own definition. Where a facet varies is declared by kinds and classes, never by the facet.

A printer SHOULD write the shorthand when every setting fits on one line within 100 characters, and the long form otherwise. It MUST NOT drop a setting to make a line fit.

4.6 The JSON form of a definition #

The long form's pairs as one object. Member names are the setting names; values follow chapter 3, with yes/no as true/false and numbers as strings.

{
  "facet": "videoCodec",
  "type": "choice",
  "label": "Video codec",
  "ask": "How is the picture encoded on the disc?",
  "values": [
    { "value": "MPEG-2" }, { "value": "H.264" }, { "value": "VC-1", "aliases": ["vc1"] },
    { "value": "HEVC" }, { "value": "AV1" }
  ],
  "aliases": ["codec", "Video Format"],
  "same-as": ["schema:encodingFormat"],
  "version": "2026-10-13"
}

• values is an array of {"value", "aliases"?}; an open list adds "open": true at the top level.
• facets (compound) is an array of child definitions, each with its own facet key.
• range is {"min": "1", "max": "600", "step"?: "0.5"}.
• Settings equal to their default are left out. Package settings keep their prefix as the member name.
• A shortcut is stored as its setting. The expansion (4.4) happens when rules are built, never in storage.

4.7 Well-formed definitions #

A package MUST be refused at publish when any definition breaks these:

1. type is one of the nine types, and every setting is one its type allows (4.2).
2. A choice facet has at least one value. A compound has at least one child.
3. identity names a child of the compound, and that child is a link.
4. ordered is set only when pick is not 1.
5. ranked, scored, fixed and ... are set only on choice facets; fixed and ... not both.
6. unit and accepts are spellings from the units table or ISO 4217 codes, and accepts is set only with unit.
7. Every qualifiers entry names a facet whose own values can't be qualified.
8. No alias collides (4.3).
9. range has min ≤ max, and step, when set, divides the span.
10. A compound's children have distinct keys, and none is named row, origin, via or owner.

4.8 Changes and versions #

A breaking version MUST ship a recipe (chapter 10). A store applies it before it accepts data written under the new version.

4.9 Checking a value against its facet #

At the Dictionary level, after aliases fold, each value is checked against its facet. The result is one of chapter 9's intake outcomes, and the checks are:

A value that fails is kept: on the intake record and beside the facet, never dropped.

Edit on GitHub · Markdown