Download the PHP package kraenzle-ritter/anton-import-format without Composer

anton-import-format

Canonical JSON Schema (Draft 2020-12) and a framework-free PHP Validator for the metadata.json shape that Anton's importers consume.

This package is the single source of truth for "what does an Anton-import look like" — used both by Anton itself (read-side validation in AgateImportHelper, write-side dump via anton:import --dump-metadata-json) and by external producers (notably agate, the digital-preservation pipeline).

Install

This package is distributed via VCS / GitHub. Add the repository entry and the package as a Composer dependency:

Quickstart

Validator::validate() returns a ValidationResult:

Version-aware validation

If you want a structured warning when the document declares a version that does not match the loaded schema's major.minor:

Schema reference

A document is a top-level wrapper object with these required fields:

Entries

Each entry is a collection or record and includes (among others):

• uuid (required) — UUID of the AntonObject. Primary identifier across the import; works even before DB ids exist.
• type — "collection" or "record".
• level_of_description — ISAD(G) level: collection, recordgroup, fonds, series, class, file, item.
• identifier — archival signature (e.g. KBA 1.1.1).
• title — multilingual object: {de: "...", fr: "...", en: "..."}. Keys MUST be ISO-639-1 two-letter codes.
• parent — object reference: {uuid: "..."} (preferred), or {identifier: "..."} / {id: 42} for already-persisted parents.
• events, notes, keywords, places, languages — see below.
• files — only on record entries. Each file has at minimum name, mime_type, md5sum.

References to other AntonObjects

Use parent or any other object-reference slot with the resolution order uuid > identifier > id:

Authority references (Actor, Place, Keyword)

Two mutually-exclusive forms:

match_by enum: label (any locale), label.de, label.fr, label.en, label.it, alternative_names.

on_not_found enum: create, error, skip.

Both default from the wrapper's defaults object; per-spec values override.

Multilingual content

Keys are ISO-639-1 two-letter codes (de, fr, en, it). The languages[] array on entries uses ISO-639-2 three-letter codes (ger, fre, eng, lat) — matching Anton's languages.name column.

Files

Files are nested inside record entries (1:N):

md5sum is required and must match ^[a-f0-9]{32}$. nara_risk enum: low, moderate, high, unknown.

Version policy

• 0.x.y releases may break across both y (point) and x (minor) while the schema iterates.
• 1.0.0 will be the first stability commitment — breaking changes from then on require a major bump.
• Consumers should pin ^0.1 while the schema is in 0.x.

Test fixtures

Under tests/Fixtures/:

• valid/minimal.json — smallest valid document.
• valid/full.json — exercises every schema feature.
• broken/*.json — intentionally-broken cases, each pinning the validator's error reporting against regression.
• agate-target/folder-input.json — the v0.1 form that agate's CreateMetadataJsonStep should emit after migration. Companion to legacy-agate-output/folder-input.json (pre-restructure).
• legacy-agate-output/*.json — read-only snapshots of agate's pre-restructure emit. Not validated against the current schema; kept as migration baseline.

Producer mapping

If you're emitting metadata.json from a producer (agate's CreateMetadataJsonStep, Anton's Excel-Import dump, anything new), read docs/producers.md. It maps the producer-side flat fields (e.g. agate's parent_uuid, creation_actors, scope_and_content) to the v0.1 wrapper shape.

Development

Consumers

• Anton — read-side validation in AgateImportHelper, write-side dump option in anton:import.
• agate — pipeline emits this shape in CreateMetadataJsonStep and validates pre-finalize via ValidateInitializedStep.

License

MIT — see LICENSE.