Skip to content

Metadata extensions

Custom metadata lets templates collect publication-specific fields while keeping the global project schema tidy. The optional metaData.schema.yml lives beside configuration.sfo.yml and follows standard JSON Schema semantics.

When to add metadata

  • Journal templates usually add a small set of visual toggles. The reference generic-journal schema exposes a single themeColor so header assets can pick up brand colours.
  • Monograph templates can capture additional administrative data, such as faculty names or defence dates, and may mark fields as required. The generic-monograph sample keeps it minimal: its schema has a single free-text comment field, and the book metadata comes from the BookMeta component.

Document which components consume these fields. For example, the journal's Handlebars header looks up {{getMetaData 'themeColor'}}, while a coverpage might render dissertation details.

Anatomy of the schema

# docs extracted from generic samples
_ui_icon: dataset
_readme: Templates can take on custom data that may be unique to the targeted publication.
type: object
properties:
  themeColor:
    type: string
    title: Theme color
    default: "#000000"

Key conventions: - _ui_icon controls how the form appears in the editor. - _readme provides author guidance; keep it short and link to internal standards if needed. - properties uses standard JSON Schema; set default, enum, or format values to streamline data entry.

Wiring metadata into templates

  1. Create or update metaData.schema.yml in your template directory.
  2. Document the required values in spec.readme so editors know when to fill them in.
  3. Reference metadata in Handlebars assets with the getMetaData helper, as generic-journal/assets/headers-and-footers.hbs does with {{getMetaData 'themeColor'}}. Component settings do not read custom fields on their own; the Reader's theme.color, for example, is a separate setting.
  4. Test exports with and without metadata populated. Monograph workflows often expect these fields; make sure the template handles missing values gracefully.

Maintenance checklist

  • Review metadata fields whenever you add a variant or asset that depends on them.
  • Keep language in field titles consistent with the template’s default locale (e.g., German for the monograph sample).
  • Avoid duplicating global metadata (DOI, authors) unless you need a specialised presentation.