Metadata

cr4te metadata lives in cr4te.json files beside the folders they describe. Metadata files contain editable structured metadata only. Long-form descriptions belong in README.md.

Build Reconciliation

The build command creates and reconciles metadata before rendering:

• Missing creator and project files are created.
• Missing editable keys are added.
• Existing editable values are preserved.
• Missing display_name and display_title fields are added using their folder names.
• Inactive creator type branches are pruned.
• Empty stale project facets are pruned.
• Stale project facets with values are kept as a domain-change failsafe.

Creator Metadata

Creator metadata has a type and one active type-specific branch.

Person creator:

{
  "display_name": "Astra Vey",
  "type": "person",
  "aliases": [],
  "collaborations": [],
  "tags": {},
  "person": {
    "active_since": "2015",
    "birth": {
      "date": "1986-01",
      "place": "Berlin"
    },
    "death": {
      "date": "",
      "place": ""
    },
    "civil_name": "",
    "nationalities": ["Swiss"]
  }
}

Collaboration creator:

{
  "display_name": "Marin & The Mesa",
  "type": "collaboration",
  "aliases": [],
  "collaborations": [],
  "tags": {},
  "collaboration": {
    "active_since": "",
    "members": ["Joe Duldree", "Kurt Monroe"],
    "founding": {
      "date": "",
      "place": ""
    },
    "dissolution_date": "",
    "nationalities": []
  }
}

When type is person, the collaboration branch is removed. When type is collaboration, the person branch is removed.

If you change a creator from person to collaboration, or from collaboration to person, run build again. The rebuild reconciles the JSON file so the active branch gets the right fields and the inactive branch is removed.

Automatic creator type detection only happens when type is missing. If a creator folder name contains one of the configured collaboration separators, such as & or , by default, cr4te treats it as a collaboration. A band named The Foobars does not contain a separator, so it is treated as a person unless you set "type": "collaboration" explicitly.

Creator folder names are canonical identities used for paths and creator references. display_name controls visible text, search, and user-facing sorting. A blank display name falls back to the folder name.

Collaboration members and creator collaborations contain canonical creator folder names. When a referenced creator exists, cr4te displays that creator's display_name; an unresolved member string is displayed unchanged.

Project Metadata

Project metadata stores core fields plus domain/config-driven facets:

{
  "display_title": "Glass Circuit",
  "release_date": "2021-03-08",
  "tags": {
    "Mood": ["Luminous"]
  },
  "facets": {
    "genres": ["Electro-pop"],
    "labels": ["Orbit"],
    "instruments": ["Synth"]
  }
}

facets are generic project metadata fields such as genres, labels, actors, publishers, or instruments. The active facet set comes from the resolved configuration.

Project folder names are canonical identities used for output paths. display_title controls visible text, search, and user-facing sorting. A blank display title falls back to the folder name.

Dates

Dates accept only valid calendar dates in one of these forms:

• yyyy
• yyyy-mm
• yyyy-mm-dd

Display preserves stored precision. A year displays as a year, a month displays as month and year, and a full date displays with day, month, and year.

Portraits And Covers

cr4te selects portraits and covers from the filesystem using the configured portrait and cover basenames.

cr4te selects the lexicographically first matching image directly inside the creator or project folder. If none exists there, it selects the lexicographically first matching image below that folder. If no matching basename exists, the configured automatic-selection behavior applies; card contexts may still use generated defaults when no source image is selected.

Tags

Tags are free-form category-to-list mappings:

{
  "tags": {
    "Mood": ["Luminous", "Nocturnal"],
    "Era": ["2020s"]
  }
}

Tags appear on pages and feed search/filter action menus.

Invalid Metadata

Extra or obsolete fields fail validation. By default, invalid creators or projects are reported as build issues and skipped where possible. With --strict, metadata errors fail the build immediately.