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-journalschema exposes a singlethemeColorso 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-monographsample keeps it minimal: its schema has a single free-textcommentfield, and the book metadata comes from theBookMetacomponent.
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
- Create or update
metaData.schema.ymlin your template directory. - Document the required values in
spec.readmeso editors know when to fill them in. - Reference metadata in Handlebars assets with the
getMetaDatahelper, asgeneric-journal/assets/headers-and-footers.hbsdoes with{{getMetaData 'themeColor'}}. Component settings do not read custom fields on their own; the Reader'stheme.color, for example, is a separate setting. - 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.