Advanced

Expressions

Audience: collection authors and tool authors using computed fields.

Authoritative for:

the shared expression language
computed field definitions, sibling-field scope, and stored-value evaluation

`computed`#

computed defines a stored text field whose value is derived from sibling frontmatter fields instead of being authored directly. Unlike generated, it is not about value origination from time, randomness, identity, or tool-specific automation; it is the single schema-defined mechanism for sibling-field derivation in this specification version. It uses the shared text-template expression context.

Example:

first_name:
  type: text
  nullable: false
last_name:
  type: text
  nullable: false
full_name:
  type: text
  computed: '${capitalize(first_name)} ${capitalize(last_name)}'
  nullable: false

Rules:

FDR-218 computed MAY be omitted.
FDR-219 If present, computed MUST be a non-empty string in the shared text-template expression context.
FDR-220 computed MAY be declared only on top-level frontmatter fields.
FDR-221 computed is the single schema-defined mechanism for deriving a field value from sibling fields of the same managed note.
FDR-222 generated and computed are distinct: generated covers value origination without sibling-field inputs; computed covers sibling-field derivation.
FDR-223 A field declaring computed MUST declare type: text.
FDR-224 A field declaring computed MUST NOT declare generated, default_value, or const_value.
FDR-225 A field declaring computed MUST NOT declare immutable: true, because its stored value is recomputed from its dependencies.
FDR-226 computed does not make a field virtual. Computed fields still follow the same type validation, optionality, stored-frontmatter, and canonical materialization rules as other declared fields.
FDR-227 For computed, the shared expression-language scope is the managed note's sibling top-level fields in the effective frontmatter.
FDR-228 Every reference name used by a computed expression MUST resolve to a sibling top-level field declared in the same effective frontmatter, and MUST NOT resolve to the declaring field itself or to a field that itself declares computed.
FDR-229 Every field referenced by a computed expression MUST declare type: text.
FDR-230 computed uses the shared expression-language syntax and transform semantics; it defines no local syntax extensions.
FDR-231 A computed expression is evaluated against the managed note's materialized sibling-field values after non-computed defaults, schema-derived values, and generation strategies have been applied.
FDR-232 Every referenced field MUST hold a concrete non-null string when the computed expression is evaluated; otherwise the computed field has no conforming value and MUST be reported as invalid_field_value.
FDR-233 Tools that create, scaffold, import, normalize, or otherwise write managed-note frontmatter MUST evaluate every computed expression and store the resulting value before writing the note.
FDR-234 A stored computed value MUST equal the result of its computed expression; a mismatch is an invalid_field_value failure.
FDR-235 The computed result MUST satisfy the field's declared constraints; a schema MUST NOT combine computed with constraints its expression cannot satisfy.
FDR-236 computed MUST NOT depend on the note body, resolved note links, query results, collection-global state, or any data outside the sibling-field scope defined above.
FDR-237 A computed field whose stored value disagrees with its evaluated expression is a note-level invalid_field_value failure, not a schema-shape failure.
FDR-238 A syntactically invalid shared expression, an unresolved sibling-field reference, a type-incompatible reference, or an unknown transform name makes the declaring artifact invalid.

Shared Expression Language#

Several governed surfaces need to derive values from structured data. Rather than defining separate mini-languages for each feature, TypedMark defines one shared expression language and lets each consumer define its own input scope, required result type, and evaluation timing.