Definitions use one normalized topology. Root files under definitions/ own stable IDs and invariant fields. Locale files under content/<locale>/definitions/ own translated payloads. IDs are YAML mapping keys and are not repeated as id: values. Localized payloads resolve in a site context: the requested locale wins, and supported fallback comes only from that site's effective defaultLocale. There is no project-global definitions fallback.

Labels and categories

# definitions/labels.yml
labels:
  new:
    color: "#10B981"

# definitions/categories.yml
categories:
  beta-testing:
    color: "#2563EB"
  cloud_services: {}

# content/en/definitions/labels.yml
labels:
  new:
    name: New
    compact: NEW
    tooltip: Recently added

# content/en/definitions/categories.yml
categories:
  beta-testing:
    name: Beta testing
    tooltip: Features available for early evaluation
  cloud_services:
    name: Cloud services

Root color is global. name and tooltip are localized; label-only compact is also localized. A local non-fallback entry requires name; an optional field omitted from a local entry remains absent in that locale.

Locale availability and fallback

Each locale has exactly one of these states for a root identity:

1. No entry: unavailable in that locale.
2. A local entry: wholly local, with required name and optional compact/tooltip.
3. An entry containing only inherited: true: use the complete entry from the current site's effective defaultLocale.

These states are explicit. A missing entry stays unavailable; Codocation does not synthesize a fallback without the marker. The marker enables fallback but does not choose the source; the current site's effective default is always the source.

# content/de/definitions/labels.yml
labels:
  new:
    inherited: true

Fallback cannot be combined with local fields, used in the site's effective default locale, or used without a root identity and valid default-locale payload. Each case is an ERROR with a targeted quick fix. Creating from Catalog writes the root identity and selected-locale payload atomically; adding a locale creates fallback entries only for identities available in that site's effective default. Editing inherited text first materializes a complete local entry and removes inherited: true.

Variables, glossary terms, and keymaps use missing requested-locale entries from the same site default without requiring a marker. A shared locale payload can therefore resolve differently for two sites whose effective defaults differ.

Other definition files

Variables, glossary, and keymaps retain their domain-specific fields:

# definitions/variables.yml
variables:
  - name: product-name

# content/en/definitions/variables.yml
variables:
  - name: product-name
    value: Codocation

# definitions/glossary.yml
terms:
  - id: api

# content/en/definitions/glossary.yml
terms:
  - id: api
    term: API
    definition: "Application Programming Interface."

# definitions/keymaps.yml
id: default
layouts:
  - id: windows
    platform: PC
mappings:
  - key: ctrl
    value: Ctrl

# content/en/definitions/keymaps.yml
id: default
layouts:
  - id: windows
    name: Windows

Structural CRUD of global IDs and colors, including stable-ID rename, is available from any selected locale. Localized text edits affect the selected locale; global operations update root data, locale keys, and all supported page and heading references. Locale-only deletion removes that locale's payload and references; global deletion removes the root, every payload, and every reference. Removing the last page assignment does not delete a definition.