MeshNotes Metadata Format Specification

Version 1.0

1. Introduction

This document specifies the metadata member that MeshNotes embeds in its annotation export (the AnnotationCollection defined by the MeshNotes Annotation Format Specification [ANN] §8) and that MeshNotes also reads and writes as a standalone metadata-report JSON file. The block records the structured meta- and paradata of a 3D documentation project: general project information, the object's archaeological context, capture and processing parameters, referencing, paradata (the reasoning behind the documentation), and legal information.

The block is organised into sections of fields. Every field has a stable identifier that is independent of its display label, so labels can be edited or translated without breaking the data; selected fields additionally carry an optional authority URI linking their free-text value to a controlled vocabulary. The whole block is, and remains, fully optional: any field may be empty, and an empty report is valid.

The design goal is that the metadata, while a plain JSON object, is cleanly mappable to CIDOC CRM and ingestible by infrastructure such as NFDI4Objects. §5 (subject kind) and §6 (the crosswalk) define that mapping. The mapping is documented here rather than serialised per-field in the export: an exported field carries only its identifier, label, value and optional URI; the CRM path for each identifier is given by this specification.

2. Conformance

A metadata block conforms to this specification when:

• it is a JSON object with a sections array of the shape defined in §4;
• it declares "dcterms:conformsTo": "https://meshnotes.org/spec/metadata/v1/";
• every field carries a stable id and a value (possibly empty), as in §4;
• where present, subjectKind is one of the values in §5;
• it validates against the JSON Schema at https://meshnotes.org/spec/metadata/v1/schema.json.

No field is ever required to be non-empty. The schema validates the shape of what is present; it never requires any particular field to be filled. A consumer must ignore members it does not recognise rather than reject the block, and should preserve them on round-trip.

The key words must, must not, should, should not and may are used as defined in RFC 2119.

3. Relationship to the annotation format

Within a MeshNotes export, this block is the value of the metadata member of the AnnotationCollection ([ANN] §8). It is self-describing through its own dcterms:conformsTo, independent of the collection's. The same block is also the content of the standalone metadata-report file (wrapped as { "generator", "type": "MetadataReport", "exported", "model", "metadata": { … } }). The two are byte-for-byte the same object, so a report can be round-tripped between the two carriers without loss.

4. The metadata block

4.1 Section

This version defines seven sections: general, object_context, capture, reference, processing, paradata, legal.

4.2 Field

4.3 Custom field

User-added fields have no stable identifier; their label is their identity.

"metadata": {
  "dcterms:conformsTo": "https://meshnotes.org/spec/metadata/v1/",
  "template": "3d-documentation",
  "subjectKind": "object",
  "sections": [
    {
      "id": "object_context",
      "title": "Object Context",
      "fields": [
        { "id": "object_type", "label": "Object Type / Classification",
          "value": "skyphos", "uri": "http://vocab.getty.edu/aat/300043171" },
        { "id": "dating_period", "label": "Dating / Period",
          "value": "Augustan", "uri": "http://n2t.net/ark:/99152/p0qhb66kmtr" },
        { "id": "additional_notes", "label": "Additional Notes", "value": "" }
      ],
      "customFields": [
        { "label": "Ware", "value": "Eastern Sigillata A" }
      ]
    }
  ]
}

5. Subject kind

A 3D model may document a movable artefact, a fixed architectural feature, a whole building, an excavation site or city, or a tract of landscape. These are not the same kind of entity in CIDOC CRM, and forcing them all to a single class would mis-state most of them. The subjectKind member therefore declares what is being documented, and that single choice fixes the CRM root class of the subject. It does not change which fields exist or which are shown — every field remains available and optional for every kind. Only the class of the root node onto which the §6 properties hang is substituted.

Because the §6 field properties are defined on common CRM ancestors (E18 Physical Thing, E24 Physical Human-Made Thing), they apply unchanged whether the root is an E22 artefact, an E25 feature or an E27 site. Only the root class differs. One consequence: for an E27 Site the find_spot field (§6, P53) is conceptually redundant, since the site is its place; a CRM exporter may omit the P53 assertion in that case rather than create a place distinct from the site.

6. CIDOC CRM crosswalk

This section maps each template field, by its stable id, to a CIDOC CRM property path rooted at the subject (the class chosen in §5, generically “subject” below) or at one of the events that produced or processed it. The mapping is based on CIDOC CRM 7.1.3; the digitization tier additionally uses CRMdig classes. Where a field is genuinely free reasoning or administrative text, it maps to P3 has note; any field not listed below, and any custom field, defaults to P3 has note (typed by the field label).

6.1 Object tier

Properties of the subject itself.

Dating is modelled through the production event (P108i → E12 → P4 → E52), not attached directly to the object, because in CIDOC CRM time-spans belong to events. A PeriodO URI on dating_period identifies the period concept that the time-span instantiates.

6.2 Digitization tier (CRMdig)

The capture and processing of the model are modelled as events that produced the 3D model as a CRMdig D9 Data Object: a digitization event (capture) and a processing event. These fields describe those events. They use CRM-base properties (P14, P16, P32, P4, P7), which apply to CRMdig D-classes by inheritance; the precise CRMdig L-properties (e.g. for “used software”) follow CRMdig v5.0 and are left to the exporter where a base property does not suffice.

Person fields (capture_operator, processing_operator, project_lead) are free text that may name several people; this version does not attach ORCID identifiers to them in the metadata block. Authorship of annotations carries ORCID separately ([ANN] §6.1). The fine capture parameters (lens, iso, aperture, focal_length, filter, color_card, scan_resolution, working_distance, calibration, number_of_captures) are deliberately mapped at note level (P3) on the digitization event rather than given a property each, to avoid over-modelling.

6.3 Note tier

The following fields map to P3 has note (typed by the field label), on the subject or the relevant event. They record free reasoning or administrative text for which a more specific CRM property would over-state structure in version 1:

project_title, project_description, documentation_purpose, excavation_reference, referenced_by, image_preprocessing, versions, algorithm_parameters, workflow_description, postprocessing_information, quality_summary, lighting_conditions, technical_notes, funding, acknowledgments, every additional_notes, and all Paradata fields (method_rationale, sources_consulted, interpretive_decisions, known_limitations, uncertainty_notes).

Two of these are flagged for future, more expressive modelling rather than P3 in a later version: stratigraphic_context is a target for CRMarchaeo (stratigraphic units), and the Paradata fields are targets for CRMinf (belief and argumentation). Until then they are honest free-text notes.

7. Authority vocabularies

Five fields accept an optional uri linking their value to a controlled vocabulary. The vocabulary is a recommendation, not a constraint: any resolvable URI is accepted, and the field stays usable with no URI at all.

8. Extensibility and unknown terms

The format is deliberately open. A conforming consumer must ignore members it does not recognise rather than reject the block, and should preserve them on round-trip. Within version 1, MeshNotes may add further optional members (new fields, new section members, new field descriptors such as uri) without a version bump; it will not change the meaning of an existing field id, remove a field id, or make any field required to be non-empty within version 1. The JSON Schema (§10) is correspondingly lenient: it validates the shape of known members and permits additional properties.

9. Versioning policy

Field and section identifiers, once published, keep their meaning permanently. This specification and its JSON Schema are versioned and frozen: a breaking change — renaming or removing an identifier, or changing a field's CRM mapping in an incompatible way — is published at a new version path (/spec/metadata/v2/), and this version remains resolvable indefinitely so that files referencing it continue to validate.

10. Conformance and validation

A metadata block can be validated structurally against the JSON Schema at https://meshnotes.org/spec/metadata/v1/schema.json (JSON Schema draft 2020-12). The schema checks the block structure (sections, fields, custom fields), the subjectKind enumeration and the conformance target, applies a light pattern check to uri values, and otherwise permits additional properties. It never requires any field value to be non-empty.

11. References

• [ANN] MeshNotes Annotation Format Specification, Version 1.0.
• CIDOC Conceptual Reference Model, version 7.1.3.
• CRMdig, an extension of CIDOC CRM for provenance metadata of digitization, version 5.0.
• CRMarchaeo, an extension for archaeological excavation (future target for stratigraphy).
• CRMinf, an extension for argumentation and inference (future target for paradata).
• LIDO — Lightweight Information Describing Objects, version 1.1.
• Getty Vocabularies — Art & Architecture Thesaurus (AAT).
• PeriodO — a gazetteer of period definitions.
• iDAI.gazetteer, Pleiades, GeoNames — place authorities.
• NFDI4Objects — research data infrastructure for the material remains of human history.
• RFC 2119: Key words for use in RFCs to Indicate Requirement Levels.