MeshNotes Annotation Format Specification

Version 1.0

1. Introduction

This document specifies the JSON-LD document that MeshNotes produces and consumes as its native annotation format. A MeshNotes export is a single W3C Web Annotation Data Model [WADM] AnnotationCollection that gathers the annotations placed on one 3D model, together with the description of that model, the annotation groups, optional model-level notes, and an optional structured metadata report.

The format is W3C Web Annotation at its core, extended in two controlled ways. First, the geometry of each annotation is identified by a MeshNotes 3D selector, defined in the companion MeshNotes 3D Selector Specification [SEL]; that document is normative for everything inside an annotation's selector, including the coordinate frame, WKT notation, CRS handling and model-binding hash, and is not repeated here. Second, MeshNotes-specific information that the W3C model does not cover is carried under the meshnotes: namespace, resolved through the JSON-LD context at https://meshnotes.org/ns/context-v1.jsonld.

The design goal is interoperability: a consumer that understands only the W3C Web Annotation Data Model can read every annotation, its target, its bodies and its grouping, and ignore the meshnotes: extensions; a consumer that understands the extensions additionally recovers the full editing state for a faithful round-trip. The format is designed to be cleanly mappable to CIDOC CRM and ingestible by infrastructure such as NFDI4Objects, though it emits neither RDF nor LIDO directly in this version.

2. Namespaces and conformance

A document conforms to this specification when:

• its top-level resource is an AnnotationCollection carrying the members marked must in §3;
• it declares "dcterms:conformsTo": "https://meshnotes.org/spec/annotation/v1/" at the collection level;
• every annotation it contains is a W3C Annotation whose target.selector conforms to [SEL];
• its terms resolve through the JSON-LD context at https://meshnotes.org/ns/context-v1.jsonld;
• it validates against the JSON Schema at https://meshnotes.org/spec/annotation/v1/schema.json.

A few coordinate-frame and identity terms — upAxis, unit, annotationType, surfaceProjection — are intentionally exposed without the meshnotes: prefix (the context aliases them) so that non-JSON-LD consumers can read them as plain keys; all MeshNotes-implementation-specific members retain the prefix. A consumer should tolerate either the aliased or the fully-qualified meshnotes: form of these terms.

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

3. The AnnotationCollection envelope

The document root is a W3C AnnotationCollection ([WADM] §3.3) holding a single embedded AnnotationPage. Its members:

{
  "@context": [
    "http://www.w3.org/ns/anno.jsonld",
    "https://meshnotes.org/ns/context-v1.jsonld"
  ],
  "type": "AnnotationCollection",
  "id": "urn:meshnotes:collection:7b1f…",
  "label": "MeshNotes: skyphos.glb",
  "dcterms:conformsTo": "https://meshnotes.org/spec/annotation/v1/",
  "generator": { "type": "Software", "name": "MeshNotes",
                 "schema:version": "1.1.0", "homepage": "https://meshnotes.org" },
  "generated": "2026-06-08T09:14:00.000Z",
  "modelSource": { … },
  "stylesheet": { "type": "CssStylesheet", "value": ".group-1 { color: #EDC040; }" },
  "meshnotes:groups": [ … ],
  "modelInfo": { … },
  "metadata": { … },
  "total": 12,
  "first": { "type": "AnnotationPage", "items": [ … ] }
}

4. The model description (modelSource)

modelSource is the single canonical description of the annotated model. Every annotation's target.source references the same model by the same id, so the coordinate frame, unit and integrity hash are stated once, here.

"modelSource": {
  "id": "urn:meshnotes:model:skyphos.glb",
  "type": "Dataset",
  "schema:name": "skyphos.glb",
  "format": "model/gltf-binary",
  "upAxis": "Z",
  "unit": "cm",
  "schema:sha256": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08"
}

5. The Annotation object

Each entry in first.items is a standard W3C Annotation.

5.1 target

The target is an oa:SpecificResource whose source references the model and whose selector identifies the geometry.

{
  "type": "Annotation",
  "id": "urn:meshnotes:annotation:3c9a…",
  "motivation": "describing",
  "schema:name": "Handle attachment scar",
  "created": "2026-06-08T09:10:11.000Z",
  "annotationType": "point",
  "meshnotes:groupUuid": "b2e1…",
  "target": {
    "type": "SpecificResource",
    "source": { "id": "urn:meshnotes:model:skyphos.glb",
                "type": "Dataset", "format": "model/gltf-binary" },
    "styleClass": "group-1",
    "selector": {
      "type": "meshnotes:PointSelector",
      "dcterms:conformsTo": "https://meshnotes.org/spec/selector/v1/",
      "meshnotes:wkt": "POINT Z (12.4 -3.15 8.02)"
    }
  },
  "body": [ … ]
}

6. Bodies

Each observation on an annotation is one oa:TextualBody in the body array. Multiple bodies represent multiple entries (e.g. from different contributors) on the same feature.

6.1 creator

creator identifies the author of an entry as a person.

"creator": {
  "id": "https://orcid.org/0009-0003-7750-2818",
  "type": "Person",
  "name": "Nils Schnorr"
}

Because id maps to @id in the W3C Web Annotation context, the ORCID URI is a first-class node identifier for the author — the conventional, interoperable way to attach an ORCID to a Web Annotation creator, and a clean attachment point for a CIDOC CRM E21 Person mapping.

6.2 meshnotes:versions

Each element of meshnotes:versions records a superseded state of the entry, oldest to newest, as { "value", "creator" (optional), "schema:url" (optional), "meshnotes:savedAt" }. This preserves the edit history for accountability in collaborative documentation.

7. Groups

Annotations are organised into named, colour-coded groups. Group definitions are carried in meshnotes:groups; each annotation references its group by UUID (meshnotes:groupUuid), and group colours are also expressed as an oa:CssStylesheet so that a generic W3C consumer can render them via each target's styleClass.

8. Model Information and Metadata

modelInfo carries free-text notes about the model as a whole. It is shaped as a W3C Annotation with "motivation": "describing" and a body array of TextualBody entries identical in structure to §6, but it has no geometric target — it describes the model rather than a region of it.

metadata carries the structured meta- and paradata report (project, capture, reference, processing, paradata and legal information). Its internal field structure is producer-defined and is treated as an open object by this version of the format; a consumer may preserve it verbatim on round-trip and should not reject unknown members within it. A future version may give this block a normative schema and a CIDOC CRM / LIDO crosswalk.

9. Coordinate frame, units and model binding

All geometric coordinates in this format — within selectors and their embedded points — follow the coordinate frame, WKT notation, CRS rules, rotation convention and model-binding hash defined normatively in [SEL] §3 and §5. In summary: coordinates are Z-up and right-handed in the model's local frame; the up-axis and unit are declared on modelSource (§4); face identifiers in surface selectors are a non-authoritative hint valid only against the mesh identified by modelSource.schema:sha256.

10. Extensibility and unknown terms

The format is deliberately open. A conforming consumer must ignore members it does not recognise rather than reject the document, and should preserve them on round-trip where feasible. Within version 1, MeshNotes may add further optional members (in the meshnotes: namespace, or as context-aliased plain keys) without a version bump; it will not add new required members, remove members, or change the meaning of an existing member within version 1. The accompanying JSON Schema (§12) is correspondingly lenient: it validates the required core and the shape of known members, and permits additional properties.

11. Versioning policy

The term namespace https://meshnotes.org/ns/ is unversioned and append-only: identifiers, once published, keep their meaning permanently, and new terms are only ever added. This specification, its JSON Schema, the companion JSON-LD context and the selector specification are versioned and frozen: a breaking change is published at a new version path and the prior version remains resolvable indefinitely, so that files referencing it continue to validate.

12. Conformance and validation

A document can be validated structurally against the JSON Schema at https://meshnotes.org/spec/annotation/v1/schema.json (JSON Schema draft 2020-12). The schema is forward-compatible: it checks the required members of the collection, the model description, annotations, targets, selectors and bodies, applies light pattern checks to WKT and identifier strings, and otherwise permits additional properties. Semantic rules that JSON Schema cannot express — polygon ring closure, quaternion normalisation, the hint status of face identifiers — are stated normatively in [SEL] and are not enforced by the schema.

13. References

• [WADM] Web Annotation Data Model. W3C Recommendation, 23 February 2017.
• Web Annotation Vocabulary. W3C Recommendation, 23 February 2017.
• [SEL] MeshNotes 3D Selector Specification, Version 1.0. Normative for selector geometry, coordinate frame, CRS and model binding.
• JSON-LD 1.1. W3C Recommendation, 16 July 2020.
• JSON Schema 2020-12.
• Schema.org vocabulary (Person, Dataset, sha256, name, color, url, version).
• RFC 2119: Key words for use in RFCs to Indicate Requirement Levels.
• BCP 47: Tags for Identifying Languages.
• ORCID: Open Researcher and Contributor ID.