Schema field types

Named field-type shortcuts for inline schema frontmatter values — the registered names, the canonical CUE each one resolves to, and example usage.

A field-type shortcut is a short name a schema frontmatter value can use instead of spelling out a CUE expression. created: date is shorter and harder to typo than created: '=~"^\\d{4}-\\d{2}-\\d{2}$"', and every project using the shortcut gets the same regex — no three projects land on three slightly different ISO patterns.

Shortcuts work the same way for inline schemas (kinds.<name>.schema:) and for proto.md frontmatter. The library ships embedded in the mdsmith binary; no network access is needed to resolve a shortcut.

# How a value is interpreted

A frontmatter value (right-hand side of key: value in the schema’s frontmatter: block) is classified by shape:

A “bare identifier” is a YAML scalar matching [a-zA-Z_][a-zA-Z0-9_-]* — letters, digits, underscores, and hyphens, starting with a letter or underscore. Anything containing whitespace, operators, quotes, brackets, or other punctuation is treated as raw CUE.

The strict third row catches typos at config-load time. A schema that writes created: iso-date errors with unknown shortcut "iso-date" instead of sliding through to an undefined-reference error deep in CUE evaluation.

# Registered shortcuts

The following names are accepted in a schema frontmatter value:

The regex bodies are shape-only. date accepts 2024-02-30 even though February never has 30 days; semantic validation is out of scope.

# Inline schema example

kinds:
  rfc:
    schema:
      frontmatter:
        created: date
        modified: datetime
        contact: email
        homepage: url
      require:
        filename: "RFC-[0-9][0-9][0-9][0-9].md"

mdsmith check validates every file in the rfc kind: created must match the ISO-date regex, contact must look like an email, and so on.

# proto.md example

The same shortcuts work in a proto.md schema’s YAML frontmatter:

---
created: date
homepage: url
---
# ?

## Goal

## Tasks

Substitution happens at schema-load time. After that the validator treats the canonical CUE the same way whether a user typed it out or the loader expanded the shortcut.

# Composing a shortcut with extra constraints

A value that needs both a shortcut and an extra constraint is not a bare name. Write the canonical CUE directly:

frontmatter:
  created: '=~"^\\d{4}-\\d{2}-\\d{2}$" & >="2020-01-01"'

The shortcut form is only triggered when the value is exactly the bare name. Anything more complex passes through as raw CUE.

# Adding a shortcut

The library lives at cue/types/types.cue in this repository. The runtime registry is in internal/schema/shortcuts.go; a drift test pins the two to each other. User-defined shortcuts are not yet a configuration surface — a project that needs a custom shortcut should write the canonical CUE in a shared proto.md (or wait for a follow-up plan if the need recurs).

# See also

• Schemas — the broader story on inline schemas, proto.md, and per-scope rule overrides.
• MDS020 — the rule that surfaces schema diagnostics.
• File kinds — how kinds attach schemas (and other rule config) to file groups.