# DIO/ODI metadata registry

This directory is the operational metadata source of truth for the DIO/ODI publication corpus and the DIO/ODI Reference Model.

It is deliberately separate from the canonical DIO/ODI Reference Vocabulary. Updating these files does not modify vocabulary definitions, hierarchy, or concept provenance.

## Files

- `works.json` — identities and publication metadata of DIO/ODI works and Reference Model releases.
- `relations.json` — directed inter-work relation graph. Only relations with `approved_for_zenodo: true` should be projected automatically into Zenodo metadata.
- `references.json` — canonical bibliographic strings for internal and external references.
- `distributions.json` — external distribution, identical, variant, and supplementary representations of each canonical work, preserving the exact relation type.
- `keywords.json` — canonical invariant keyword core, work-specific keyword profiles, and non-export aliases.
- root `.zenodo.json` — Zenodo-specific projection for future GitHub → Zenodo Reference Model releases.

## Workflow

1. Maintain work identities, DOI/version information, relations, distribution representations, keywords, and citations here.
2. Before a new Reference Model release, ensure `.zenodo.json` reflects the approved subset of this registry.
3. Zenodo GitHub archiving reads `.zenodo.json` for new releases.
4. Existing historical Zenodo records are not retroactively changed by these files; they require metadata synchronization through Zenodo's editor, API, or browser automation.
5. Zenodo assigns the version-specific DOI only after the GitHub Release is archived. Do not guess or prepopulate that DOI in the tagged snapshot. After publication, synchronize `metadata/works.json`, `README.md`, and `CITATION.cff` in the live `main` branch with the minted DOI; do not rewrite the immutable archived snapshot.

## Reference Vocabulary identity and parent Reference Model DOI

The canonical DIO/ODI Reference Vocabulary is identified by its own SKOS ConceptScheme URI:

`https://vocab.danielberanek.cz/dio-odi/#ReferenceVocabulary`

The Zenodo Concept DOI `10.5281/zenodo.23272897` identifies the **DIO/ODI Reference Model**, not the Reference Vocabulary as an independently archived object. The vocabulary is a component of that broader Reference Model. Therefore:

- use the vocabulary URI as the identifier of the SKOS ConceptScheme;
- represent its relation to the parent Reference Model with `dcterms:isPartOf` (or the equivalent Schema.org relationship);
- never label the Reference Model Concept DOI as a vocabulary-specific DOI;
- distinguish the live vocabulary version from the vocabulary state included in a particular archived Reference Model release.

The live and currently archived vocabulary is v0.2.1 in Reference Model v0.7.0; archived Reference Model v0.6.0 contains the earlier vocabulary state v0.2.0. The `reference_vocabulary_inclusion_history` field in `works.json` records the first Reference Model release containing each archived vocabulary version. Its DOI values identify those enclosing Reference Model releases, not separately archived Vocabulary packages. Vocabulary v0.2.1 is a metadata-only update to v0.2.0 and is included in the v0.7.0 archive; it does not constitute a separately archived vocabulary work. The Vocabulary has no separate version-specific Zenodo DOI; use its canonical ConceptScheme URI. The `reference-vocabulary-v0.2.0` entry in `references.json` provides the corresponding URI-based citation without assigning the parent model's DOI to the Vocabulary.

## Relation discipline

The graph is intentionally conservative. A relation should not be strengthened merely to make the graph denser.

In particular, the candidate relation between the archived Reference Model package and the namespace URI `https://vocab.danielberanek.cz/dio-odi/#` is currently marked for semantic review rather than exported automatically as `isIdenticalTo`.


## Distribution representations

External copies and distribution layers are part of the metadata graph but are not automatically treated as identical to the canonical work.

For each canonical work, audit ResearchGate, Figshare, SSRN, Kaggle, Hugging Face, institutional repositories, and other known distribution layers where applicable. Preserve the precise relation actually justified by the record:

- `isIdenticalTo` for genuinely identical objects;
- `isSupplementedBy` where the external representation supplements the canonical record;
- other supported relation types where more accurate.

Do not collapse all distribution channels into a generic equivalence relation.


### Verification rule for existing Related Works

Existing Zenodo relations are observations of previously entered metadata, not automatically canonical truth.

Before approving a distribution relation:

1. compare the actual files/content, not only titles and landing pages;
2. determine whether the external object is the exact same research output, a modified/variant form, a distinct version, or a genuine supplement;
3. use `IsIdenticalTo` only for the exact same research output stored in two locations;
4. use `IsSupplementedBy` only when the external resource genuinely supplements the canonical resource;
5. keep the relation unapproved if the distinction cannot be established safely.

A prior relation already present on Zenodo may therefore be corrected during metadata normalization.


### Version-scoped distribution relations

Distribution relations may legitimately change between versions of the same canonical work.

When a later Zenodo version differs from an external distribution copy, do not automatically inherit an earlier `isIdenticalTo` relation. Record the relation against the specific version for which it is valid and preserve the earlier relation as historical provenance where appropriate.

Current-version relation semantics take precedence for projection to the current Zenodo record; historical relation semantics must not be retroactively overwritten.


## Keyword discipline

`keywords.json` defines a canonical **ordered metadata grammar**, not an unordered bag of tags.

The fixed chunk order is:

`C0 Identity invariant → C1 Reconstruction environments → C2 Work positioning → C3 Reconstruction mechanics → C4 K6 → C5 Reconstruction failures and robustness → C6 Machine-readable representation`

Rules:

1. C0 is always first and identical across the DIO/ODI corpus.
2. C1 is always second and identifies the main reconstruction environments: artificial intelligence, search engines, knowledge graphs, and human observers.
3. C2 is work-specific.
4. C3, C5, and C6 are master-ordered chunks: works may activate only a subset, but selected terms retain the same relative order.
5. C4 (K6) is all-or-nothing and always exported as the complete sequence: K6 Semantic Connectome, Entity, Representation, Interpretation, Trust, Relationship, Reconstruction.
6. Flattened keyword arrays preserve chunk order and term order.
7. Aliases support reconstruction and variant recognition but are not exported by default.
8. Keyword assignment must not retroactively project concepts into a work that the work does not substantively carry.
9. Every exportable metadata surface that supports the complete sequence, including `.zenodo.json` and `CITATION.cff`, must use the exact resolved sequence for its work profile; do not maintain manually curated shorter parallel sets.
10. `registry_version` identifies the keyword-registry data version; `keyword_grammar_version` identifies the structural grammar version. These version fields are distinct and must not be conflated.

This creates lexical and structural consistency across records while preserving the conceptual scope of each work.


## Description discipline

Zenodo Description is treated as a semantic identity surface, not as a repository tagline.

For canonical DIO/ODI records, descriptions should follow a stable high-level order where supported by the work:

1. **Identity and scope** — what the work is and how it positions DIO/ODI.
2. **Corpus position and genealogy** — which earlier/later DIO/ODI works it develops, refines, references, or operationalizes.
3. **Core conceptual content** — the main mechanisms, models, dimensions, or analytical distinctions carried by the work.
4. **Failure / robustness structure** — Reconstruction Failure Modes, Semantic Vulnerability, Semantic Robustness, Identity Collapse, or related concepts where genuinely present.
5. **Application / external mappings** — only where the work maps DIO/ODI into an external domain.
6. **Metadata, distribution, and relation layer** — where relevant, explain versioning, provenance, distribution identity, typed relations, and machine-readable metadata.
7. **Epistemic boundary and use** — state what the work does not claim, preserve distinctions from stronger formalizations, and identify its intended interpretive/reuse role.

The grammar constrains sequence and function, not wording. A work must not acquire concepts merely to fill a description block. Later descriptions may be structurally consistent while remaining faithful to the historical scope of each publication.


## Resource type discipline

Use the actual publication state of each work and do not strengthen it through metadata.

- Manifest v1: `dataset`
- DIO Conceptual Framework: `publication-preprint`
- Crisis of Entity Resolution: `publication-preprint`
- MVDIO: `publication-preprint`
- Taxonomic Note: `publication-preprint`
- DIO/ODI Reference Model: `software`
- Externally published HEM source: `publication-article`

A Zenodo-hosted research manuscript is not a journal article merely because Zenodo exposes an article-like publication category. Canonical metadata must preserve the distinction between a preprint and peer-reviewed journal publication.


## Archival continuity and correction

DIO/ODI metadata maintenance does not silently rewrite history in order to produce an artificially clean record.

When a metadata error or weaker historical representation is identified:

1. the archived historical state remains identifiable as the state that actually existed;
2. the canonical current representation is corrected transparently;
3. the correction must not imply that the earlier metadata state never existed;
4. version, provenance, and relation information should preserve continuity between historical and corrected representations;
5. a metadata correction alone does not justify creating a new research-object version unless the underlying files or substantive object have changed.

This applies the DIO principle of identity-preserving change to the DIO/ODI corpus itself: continuity is maintained through explicit transformation and provenance, not by erasing earlier states.


## Commit-Boundary preprint version relationship

The DIO/ODI corpus registry records the arXiv v2 representation of *Constraining the Commit Boundary* as `isNewVersionOf` the specific Zenodo v1 record `10.5281/zenodo.23580733`. The author confirmed on 7 November 2026 that the Zenodo v1 record now carries two complementary relations: **Is identical to** the matching v1 representation, and **Is previous version of** arXiv v2 (`10.48550/arXiv.2610.37407`, the arXiv concept DOI; current version v2). The first relation records identity of the v1 representations; the second records version succession from v1 to v2.

The record's **Cites** relation to `10.48550/arXiv.2607.27435` identifies the separate paper *AgenticER: the next frontier in Entity Resolution* by Papadakis et al. It is a bibliographic citation, not an identifier for this preprint, and must not be conflated with the two version relations. The distribution registry records the Zenodo change as author-confirmed; it was not independently re-fetched during this update.