Metadata Templates

A template is a tree: a template has top-level groups, a group has fields and, optionally, nested subgroups. Fields are where the actual metadata values live - a group only exists to organize fields (and other groups) together, for example a "Rights" group containing "Attribution" and "Usage rights" fields.

1. short_name - unique identifier for the group or field within the template.
2. label / description - localized text, keyed by language code.
3. sort_index - controls display order among siblings.
4. is_required / is_searchable / is_multiple - field-level behavior flags.
5. min_level_view / min_level_edit - minimum user level required to view or edit the field.
6. options - the list of choices for select-type fields.

{
  "template_id": "aB3xQ9",
  "name": "Example template",
  "groups": [
    {
      "short_name": "rights",
      "sort_index": 0,
      "label": { "en": "Rights", "nl": "Rechten" },
      "description": { "en": "", "nl": "" },
      "groups": [],
      "fields": [
        {
          "short_name": "rights_attribution",
          "type": "text",
          "is_required": true,
          "is_searchable": true,
          "is_quicksearch": false,
          "is_multiple": false,
          "sort_index": 0,
          "min_level_view": null,
          "min_level_edit": null,
          "label": { "en": "Attribution", "nl": "Attributie" },
          "description": { "en": "", "nl": "" },
          "options": []
        }
      ]
    }
  ]
}

short_name only has to be unique within its own group, but fields are exposed under a flat meta_<short_name> name in search, FTP export, and single-field lookups, which don't know about groups. To avoid two fields silently colliding there, we recommend prefixing each field's short_name with its group, e.g. rights_attribution or tech_codec, keeping it unique across the whole template.

1. text a single line of text.
2. textarea a multi-line block of text.
3. select a dropdown with a fixed list of options.
4. selectlookup a dropdown whose options are looked up dynamically.
5. checkbox a boolean true/false value.
6. number a whole number.
7. float a decimal number.
8. date a calendar date.
9. datetime a date and time.
10. time a time of day.
11. timecode a media timecode, e.g. for marking a point in a video.
12. json a raw JSON value for advanced/structured data.

1. min_level_view - a user below this level never sees the field at all, in the UI or the API - it's omitted entirely, not just hidden or read-only.
2. min_level_edit - a user below this level can see the field but any attempt to change it is rejected.
3. null - leave either value null for no restriction.

1. GET /api/meta/template returns the current template as JSON, already filtered to the fields the calling user is allowed to see.
2. POST /api/meta/template creates a new template, PUT /api/meta/template updates the existing one, both accept the same tree shape.
3. Both write endpoints accept an is_dry_run flag (defaults to true). A dry run validates the request and returns a changelog of exactly what would change, without saving anything - always run one before committing a change.
4. A dry-run response also includes a digest and changelog_digest. Submit these back with the real (non-dry-run) write and the API verifies the template hasn't changed since the dry run before applying anything - if it has, the write is rejected instead of silently applying a changelog that no longer matches the current template. Always test on the latest digest right before saving for real.
5. Owners can also build and edit a template visually from Settings → Extensions → Metadata template, without calling the API directly. By default only Owners can edit the template through the API or the UI; an Owner can opt in to also allow Administrators to edit it.
6. GET /api/files/{file_id}/meta/user returns just that file's current metadata values, flattened and keyed by meta_<short_name>, without the group structure - use this when you only need the values, not the template shape.
7. GET /api/meta/fields (or GET /api/meta/fields/{short_name} for a single field) lists the template's fields flattened, again without groups - useful for building a flat form or looking up one field directly.