# Vercy AI instruction - YAML 1.2 (JSON-compatible) { "vercy": "1.0-draft", "publication": { "status": "published", "adjudicationStatus": "reviewable-draft", "publishableCanonical": false, "generatedAt": "2026-08-24T22:06:02Z", "synthesisSha256": "73fa180b2b36658377daf7fe6112f5874292780ada21a9d961e2875a417be8a8", "providerMode": "dual-provider", "providers": [ "Claude", "Grok" ], "waivedProviders": [] }, "metaModel": { "id": "WM-DAT-004", "registryId": "vr.wm-dat-004", "name": "Data Schema / Data Contract", "version": "0.3.0-research.1", "previousVersions": [], "entryKind": "entity", "family": "World Models", "category": "Information and virtual systems", "industry": [ "Cross-industry" ], "domain": [ "INF.DAT.SCH" ], "tags": [ "data", "schema", "contract", "inf.dat.sch" ], "status": "published" }, "canonicalUrl": "https://ver.cy/models/wm-dat-004-data-schema-data-contract/", "sourceUrl": "https://github.com/ver-cy/world-models/tree/feat/mega-model-registry/research/runs/wm-dat-004", "model": { "registry_id": "vr.wm-dat-004", "model_id": "WM-DAT-004", "name": "Data Schema / Data Contract", "entry_kind": "entity", "purpose": "Give an agent the context needed to understand, author, validate, version and operate a governed description of data structure, semantics and constraints, together with the producer-consumer agreement that makes that description binding.", "scope_statement": "This model covers the governed artefact that declares what data means, how it is structured, which constraints and quality expectations hold, who produces and consumes it, and how it may change. It covers both the narrow technical case (a schema document such as a JSON Schema, Avro schema or SHACL shapes graph) and the wider agreement case (a data contract such as ODCS that wraps schema with obligations, service levels and terms). It stops at the boundary of the data instances themselves, of runtime execution, and of enforcement machinery. Storage and interface are projections: the same semantics must survive expression as YAML, JSON, RDF, Markdown, a Git tree, an MCP resource or a MongoDB document.", "in_scope": [ "Identity, version designation and status of a schema or contract as a governed, citable resource", "The subject the contract governs and the granularity at which it governs it", "Structural definition: objects, properties, nesting, arrays, keys, uniqueness and declared relationships", "Logical-to-physical type mapping, encoding conventions and temporal representation rules", "Binding of properties to business terms, conceptual domains and value domains", "Constraint expression, including assertion versus annotation semantics and cross-field constraints", "Declared data quality rules, dimensions, thresholds, severity and business impact", "Validation outcome structure and conformance evidence", "Compatibility modes, schema resolution rules and breaking-change determination", "Change control, approval authority, deprecation and sunset", "Producer and consumer parties, obligations, acceptance and service-level declarations", "Classification, personal-data flags, usage terms and retention statements carried by the contract", "Physical binding to servers, formats and media types", "Provenance of the contract artefact itself and its registry publication", "Alignment and mapping to other schema languages and catalogue profiles" ], "out_of_scope": [ "The data records or instances themselves, and their storage lifecycle", "Dataset-level catalogue description, discovery metadata and distribution inventory, which belong to the parent dataset model", "Runtime pipeline orchestration, job scheduling and execution state", "Run-level lineage events and column-lineage facts produced by execution", "Access enforcement, authentication, entitlement grants and key management", "Business glossary authoring and ontology maintenance as an independent discipline", "Pricing, billing and chargeback execution", "Physical storage layout, file compaction and table maintenance operations", "Incident management and observability alerting workflows" ], "boundary_notes": [ { "neighbor": "WM-DAT-001 Dataset", "distinction": "The dataset is the thing described; the contract is the description plus the agreement. DCAT expresses this with dcterms:conformsTo on the resource, pointing at the standard or schema it conforms to. Dataset-level discovery metadata (theme, keyword, publisher, distribution list) belongs to the dataset model, not here; only the conformance link and the governed-subject reference are held here.", "source_refs": [ "SRC-008", "SRC-003" ] }, { "neighbor": "Data quality assessment and observation model", "distinction": "This model holds the declaration of a quality rule (metric, dimension, operator, threshold, severity, schedule) as ODCS defines it. The measured result of running that rule, and its time series, is an observation and belongs to the quality/observation sibling. Confusing declaration with measurement is the single most common overreach in data-contract tooling.", "source_refs": [ "SRC-005", "SRC-013" ] }, { "neighbor": "Data lineage model", "distinction": "OpenLineage attaches a schema facet and dataQualityAssertions facet to datasets within run events. Those facets are emitted observations about a run; the contract is the design-time statement they are compared against. Lineage owns Run, Job and facet emission; this model owns the normative expectation.", "source_refs": [ "SRC-013" ] }, { "neighbor": "API and interface contract model (OpenAPI, AsyncAPI)", "distinction": "Interface contracts own operations, transport, endpoints and status codes. This model owns payload structure and meaning. The overlap is the message payload schema, which should be defined once here and referenced by the interface model rather than duplicated.", "source_refs": [ "SRC-001", "SRC-011" ] }, { "neighbor": "Metadata registry model (ISO/IEC 11179 family)", "distinction": "A metadata registry administers reusable data element concepts, conceptual domains, value domains and registration authorities across many datasets. A data contract consumes those administered items by reference. Where an organisation runs a registry, the contract must not re-declare the semantics; it binds to them. Treat 11179 as an alignment, not a conformance claim.", "source_refs": [ "SRC-016", "SRC-004" ] }, { "neighbor": "Data product model", "distinction": "ODCS bundles pricing, support channels, team and SLA into the contract document. That is a packaging decision, not a semantic one. Where a separate data-product model exists, those sections should be composed by reference; this model keeps only what constrains the producer-consumer exchange of the described data.", "source_refs": [ "SRC-003", "SRC-014" ] } ] }, "sources": [ { "id": "SRC-001", "title": "JSON Schema: A Media Type for Describing JSON Documents (draft-bhutton-json-schema-01)", "organization": "JSON Schema Organization / IETF Internet-Draft", "url": "https://json-schema.org/draft/2020-12/json-schema-core", "version_or_date": "Draft 2020-12, published 2022-06-16", "source_type": "standard", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T09:05:00Z", "relevance": "Normative source for schema resource identity ($id canonical URI), dialect declaration ($schema), vocabulary declaration ($vocabulary), static and dynamic referencing, meta-schemas, the annotation-versus-assertion distinction and the four structured output formats." }, { "id": "SRC-002", "title": "JSON Schema Validation: A Vocabulary for Structural Validation of JSON", "organization": "JSON Schema Organization / IETF Internet-Draft", "url": "https://json-schema.org/draft/2020-12/json-schema-validation", "version_or_date": "Draft 2020-12, published 2022-06-16", "source_type": "standard", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T09:06:00Z", "relevance": "Normative validation keywords (type, required, enum, pattern, numeric and length bounds) and the split of format into a format-annotation vocabulary and a format-assertion vocabulary, which determines whether a declared format is checkable." }, { "id": "SRC-003", "title": "Open Data Contract Standard (ODCS) - Fundamentals", "organization": "Bitol (Linux Foundation AI & Data)", "url": "https://bitol-io.github.io/open-data-contract-standard/latest/fundamentals/", "version_or_date": "v3.1.0", "source_type": "standard", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T09:10:00Z", "relevance": "Defines the required identity surface of a data contract: apiVersion, kind, id, version and status are required; name, tenant, domain, dataProduct, tags and the description block (purpose, usage, limitations, authoritativeDefinitions) are optional." }, { "id": "SRC-004", "title": "Open Data Contract Standard (ODCS) - Schema", "organization": "Bitol (Linux Foundation AI & Data)", "url": "https://bitol-io.github.io/open-data-contract-standard/latest/schema/", "version_or_date": "v3.1.0", "source_type": "standard", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T09:12:00Z", "relevance": "Defines schema objects and properties: name (required), logicalType, physicalType, physicalName, required, unique, primaryKey, primaryKeyPosition, partitioned, partitionKeyPosition, classification, encryptedName, criticalDataElement, authoritativeDefinitions, transformSourceObjects, transformLogic, examples, items and property-level quality." }, { "id": "SRC-005", "title": "Open Data Contract Standard (ODCS) - Data Quality", "organization": "Bitol (Linux Foundation AI & Data)", "url": "https://bitol-io.github.io/open-data-contract-standard/latest/data-quality/", "version_or_date": "v3.1.0", "source_type": "standard", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T09:14:00Z", "relevance": "Defines the four quality rule types (text, library, sql, custom), the comparison operators (mustBe, mustNotBe, mustBeGreaterThan, mustBeGreaterOrEqualTo, mustBeLessThan, mustBeLessOrEqualTo, mustBeBetween, mustNotBeBetween), the seven dimensions and attributes such as metric, severity, businessImpact, scheduler, schedule and unit." }, { "id": "SRC-006", "title": "Apache Avro 1.12.0 Specification", "organization": "Apache Software Foundation", "url": "https://avro.apache.org/docs/1.12.0/specification/", "version_or_date": "1.12.0", "source_type": "standard", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T09:18:00Z", "relevance": "Normative rules for Schema Resolution between a writer's and a reader's schema, aliases, default values, type promotion, logical types (decimal, uuid, date, time, timestamp, local-timestamp, duration), Parsing Canonical Form and schema fingerprints (SHA-256, MD5, 64-bit Rabin)." }, { "id": "SRC-007", "title": "Shapes Constraint Language (SHACL)", "organization": "World Wide Web Consortium (W3C)", "url": "https://www.w3.org/TR/shacl/", "version_or_date": "W3C Recommendation, 20 July 2017", "source_type": "standard", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T09:20:00Z", "relevance": "Normative separation of shapes graph from data graph, node shapes and property shapes, constraint components (cardinality, value type, enumeration, pattern) and the validation report as the standard machine-readable outcome of validation." }, { "id": "SRC-008", "title": "Data Catalog Vocabulary (DCAT) - Version 3", "organization": "World Wide Web Consortium (W3C)", "url": "https://www.w3.org/TR/vocab-dcat-3/", "version_or_date": "W3C Recommendation, 22 August 2024", "source_type": "standard", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T09:22:00Z", "relevance": "Provides the catalogue-side attachment points for a contract: dcterms:conformsTo for standards conformance, dcat:mediaType and dcat:accessService on distributions, dcterms:accrualPeriodicity, dcat:temporalResolution and dcat:previousVersion for version chains." }, { "id": "SRC-009", "title": "PROV-O: The PROV Ontology", "organization": "World Wide Web Consortium (W3C)", "url": "https://www.w3.org/TR/prov-o/", "version_or_date": "W3C Recommendation, 30 April 2013", "source_type": "ontology", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T09:24:00Z", "relevance": "Supplies the provenance vocabulary for the contract artefact itself: Entity, Activity, Agent, wasGeneratedBy, wasDerivedFrom, wasAttributedTo, used, wasRevisionOf and specializationOf." }, { "id": "SRC-010", "title": "RFC 3339 - Date and Time on the Internet: Timestamps", "organization": "IETF / RFC Editor", "url": "https://www.rfc-editor.org/rfc/rfc3339", "version_or_date": "July 2002", "source_type": "standard", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T09:26:00Z", "relevance": "Normative date-time grammar: full-date, full-time with mandatory seconds, time-offset expressed as Z or as a signed hh:mm numeric offset, leap-second value 60, and -00:00 reserved for an unknown local offset." }, { "id": "SRC-011", "title": "Schema Evolution and Compatibility Types", "organization": "Confluent", "url": "https://docs.confluent.io/platform/current/schema-registry/fundamentals/schema-evolution.html", "version_or_date": "Confluent Platform current documentation, accessed 2026-08-25", "source_type": "first-party-doc", "primary_source": true, "authority_tier": 3, "accessed_at": "2026-08-25T09:30:00Z", "relevance": "Defines the operative compatibility vocabulary in wide production use: BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE and NONE, together with subject, subject name strategy, schema id and version." }, { "id": "SRC-012", "title": "Schema Compatibility (Event Streaming Patterns)", "organization": "Confluent Developer", "url": "https://developer.confluent.io/patterns/event-stream/schema-compatibility/", "version_or_date": "Accessed 2026-08-25", "source_type": "first-party-doc", "primary_source": true, "authority_tier": 3, "accessed_at": "2026-08-25T09:32:00Z", "relevance": "States the deployment-order consequence of a compatibility mode: under backward compatibility consumers upgrade first, under forward compatibility producers upgrade first, and enumerates the permitted field additions and deletions in each mode." }, { "id": "SRC-013", "title": "OpenLineage Object Model", "organization": "OpenLineage (LF AI & Data)", "url": "https://openlineage.io/docs/spec/object-model", "version_or_date": "Specification 1.52.0", "source_type": "schema", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T09:35:00Z", "relevance": "Shows how schema is carried as a dataset facet alongside dataSource, version and lifecycleStateChange, with dataQualityMetrics and dataQualityAssertions as input facets, marking the boundary between design-time contract and run-time observation." }, { "id": "SRC-014", "title": "Data Contract Specification (datacontract-specification)", "organization": "Data Contract Specification project (INNOQ)", "url": "https://github.com/datacontract/datacontract-specification", "version_or_date": "v1.2.1; deprecated in favour of ODCS v3.1.0, support stated through end of 2026", "source_type": "schema", "primary_source": true, "authority_tier": 3, "accessed_at": "2026-08-25T09:38:00Z", "relevance": "Competing contract structure (dataContractSpecification, id, info required; models, definitions, servicelevels, quality, terms, servers optional) with field attributes classification, pii, references, primaryKey and unique; its deprecation is a live interoperability conflict." }, { "id": "SRC-015", "title": "DCAT Application Profile for data portals in Europe (DCAT-AP) 3.0.0", "organization": "SEMIC / Interoperable Europe, European Commission", "url": "https://semiceu.github.io/DCAT-AP/releases/3.0.0/", "version_or_date": "Version 3.0.0, 14 June 2024", "source_type": "public-authority", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T09:40:00Z", "relevance": "Shows how a jurisdictional profile constrains a base vocabulary: mandatory classes, mandatory controlled vocabularies (dcat:theme, dct:format, dct:language, dcat:mediaType, adms:status) and dcterms:conformsTo on Catalogue and Distribution; also defines provider versus receiver conformance." }, { "id": "SRC-016", "title": "ISO/IEC 11179-3:2023 Information technology - Metadata registries (MDR) - Part 3: Metamodel for registry common facilities", "organization": "International Organization for Standardization / IEC", "url": "https://www.iso.org/standard/78915.html", "version_or_date": "Edition published 2023", "source_type": "standard", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T09:42:00Z", "relevance": "Catalogue record for the metadata registry metamodel underpinning administered items, registration authority and registration status, and the data element / data element concept / value domain / conceptual domain constructs used for semantic binding. Full text is paywalled; only catalogue-level metadata was verified." }, { "id": "SRC-017", "title": "Semantic Versioning 2.0.0", "organization": "Semantic Versioning project", "url": "https://semver.org/", "version_or_date": "2.0.0", "source_type": "standard", "primary_source": true, "authority_tier": 3, "accessed_at": "2026-08-25T09:44:00Z", "relevance": "Normative rules for MAJOR/MINOR/PATCH increments, the requirement that a released version MUST NOT be modified, pre-release and build-metadata identifiers, and the rule that build metadata is ignored for precedence." }, { "id": "SRC-018", "title": "Apache Iceberg - Evolution", "organization": "Apache Software Foundation", "url": "https://iceberg.apache.org/docs/latest/evolution/", "version_or_date": "Iceberg 1.11.0 documentation", "source_type": "first-party-doc", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T09:46:00Z", "relevance": "Documents schema evolution, partition evolution and sort-order evolution as distinct, independently versioned concerns, and the use of column identifiers rather than names so that rename operations do not invalidate stored data." }, { "id": "SRC-019", "title": "Open Data Contract Standard (ODCS) v3.1.0", "organization": "Bitol / LF AI and Data Foundation (Linux Foundation)", "url": "https://bitol-io.github.io/open-data-contract-standard/v3.1.0/", "version_or_date": "v3.1.0", "source_type": "standard", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T16:00:00Z", "relevance": "Normative structure of a data contract: fundamentals (id, version, status, domain, purpose, limitations), schema objects and properties, logical and physical types, quality rules, SLA properties including retention and end of life, and consumer roles." }, { "id": "SRC-020", "title": "JSON Schema: A Media Type for Describing JSON Documents (Core)", "organization": "JSON Schema project (Internet-Draft draft-bhutton-json-schema-01)", "url": "https://json-schema.org/draft/2020-12/json-schema-core.html", "version_or_date": "Draft 2020-12, 16 June 2022", "source_type": "schema", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T16:00:00Z", "relevance": "Canonical schema-resource identity ($id, $anchor, $ref), dialect and vocabulary ($schema, $vocabulary), applicators, assertions versus annotations, and evaluation output independent of storage format." }, { "id": "SRC-021", "title": "JSON Schema Validation: A Vocabulary for Structural Validation of JSON", "organization": "JSON Schema project (Internet-Draft draft-bhutton-json-schema-validation-01)", "url": "https://json-schema.org/draft/2020-12/json-schema-validation.html", "version_or_date": "Draft 2020-12, 16 June 2022", "source_type": "schema", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T16:00:00Z", "relevance": "Assertion keywords for type, enum, const, numeric bounds, string pattern and length, array and object cardinality, required and dependentRequired, format, content encoding, and metadata such as deprecated, readOnly, writeOnly, default and examples." }, { "id": "SRC-022", "title": "ISO/IEC 11179-31:2023 Information technology — Metadata registries (MDR) — Part 31: Metamodel for data specification registration", "organization": "ISO/IEC JTC 1/SC 32", "url": "https://www.iso.org/standard/78925.html", "version_or_date": "2023-01, Edition 1", "source_type": "standard", "primary_source": true, "authority_tier": 1, "accessed_at": "2026-08-25T16:00:00Z", "relevance": "Registration of data elements, data-element concepts, object classes, properties, conceptual domains, value meanings, value domains, datatypes and permissible values, independent of bits-and-bytes physical representation." }, { "id": "SRC-023", "title": "OpenAPI Specification v3.1.1", "organization": "OpenAPI Initiative", "url": "https://spec.openapis.org/oas/v3.1.1.html", "version_or_date": "v3.1.1, 24 October 2024", "source_type": "standard", "primary_source": true, "authority_tier": 2, "accessed_at": "2026-08-25T16:00:00Z", "relevance": "Schema Object as a superset of JSON Schema Draft 2020-12, jsonSchemaDialect, OAS base vocabulary, and the boundary that OAS document text is authoritative if a companion JSON Schema differs." }, { "id": "SRC-024", "title": "Data Contracts: The Complete Guide (ODCS as industry standard; Data Contract Specification deprecated)", "organization": "datacontract.com / Bitol TSC members", "url": "https://datacontract.com/", "version_or_date": "accessed 2026-08-25; states ODCS 3.1 as common standard", "source_type": "secondary", "primary_source": false, "authority_tier": 4, "accessed_at": "2026-08-25T16:00:00Z", "relevance": "Records the competing Data Contract Specification being deprecated in favour of ODCS 3.1, confirming a single open contract standard and the producer-consumer API-for-data framing." } ], "structure": { "bundles": [ { "id": "identity-and-governance", "name": "Contract identity and governance", "description": "Who or what the contract is, what it governs, which version is in force, what state it is in and who has authority over it.", "rationale": "Every downstream operation - validation, compatibility checking, notification, retirement - depends on being able to name one specific contract version unambiguously and to know who may change it. ODCS makes id, version and status required precisely because nothing else is safe to automate without them.", "source_refs": [ "SRC-003", "SRC-001", "SRC-017" ], "layers": [ { "id": "l-identity-scope", "name": "Identity and governed subject", "description": "The citable identity of the contract resource and the precise data it governs.", "source_refs": [ "SRC-003", "SRC-001", "SRC-011" ], "findings": [ { "id": "f-contract-identifier", "name": "Contract and schema resource identity", "description": "A contract or schema must be identifiable independently of where its bytes are stored. ODCS requires a contract id plus apiVersion and kind; JSON Schema assigns a schema resource a canonical URI through $id and declares its dialect through $schema; a schema registry assigns a subject plus a numeric schema id; Avro derives a content fingerprint from Parsing Canonical Form. These are four different identity mechanisms with different guarantees, and an agent must know which one is authoritative in a given deployment.", "source_refs": [ "SRC-003", "SRC-001", "SRC-011", "SRC-006" ], "questions": [ { "id": "q-cid-authoritative", "text": "Which identifier is the authoritative master-system identifier for this contract, and which system of record issues it?", "kind": "identity", "answer_data": [ "Authoritative identifier value", "Issuing system of record", "Identifier scheme name" ] }, { "id": "q-cid-global-iri", "text": "Does the contract carry a governed global identifier or IRI in addition to its local identifier, and is that IRI resolvable?", "kind": "identity", "answer_data": [ "Global IRI or URI", "Resolution mechanism", "Whether the IRI is normalized" ] }, { "id": "q-cid-dialect", "text": "Which specification and dialect does this artefact declare itself to be written in, and is that declaration machine-readable?", "kind": "definition", "answer_data": [ "Specification name and version (apiVersion, dataContractSpecification or $schema)", "Artefact kind", "Meta-schema URI if applicable" ] }, { "id": "q-cid-fingerprint", "text": "Is a content fingerprint computed for the schema, and over which canonical form is it computed?", "kind": "evidence", "answer_data": [ "Fingerprint algorithm", "Canonical form definition used", "Fingerprint value" ] } ], "data_elements": [ { "id": "de-contract-id", "name": "contractIdentifier", "description": "Authoritative identifier for the contract as issued by its system of record.", "value_kind": "identifier", "cardinality": "1", "required": true, "source_refs": [ "SRC-003" ] }, { "id": "de-schema-canonical-uri", "name": "schemaCanonicalUri", "description": "Canonical URI or IRI of the schema resource, as established by $id or by catalogue publication.", "value_kind": "identifier", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-001", "SRC-008" ] }, { "id": "de-schema-fingerprint", "name": "schemaFingerprint", "description": "Digest over the canonical form of the schema, used for equality and cache keys rather than for human reference.", "value_kind": "text", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-006" ] } ], "artifacts": [ { "id": "af-contract-document", "name": "Contract definition document", "description": "The serialized contract or schema itself, in whatever dialect it declares.", "media_or_form": [ "structured document (YAML, JSON, RDF or equivalent)", "registry record", "version-controlled file" ], "serial": false, "identity_strategy": "Authoritative contract identifier from the system of record, qualified by version; canonical URI recorded as a secondary governed identifier; fingerprint used only for integrity comparison.", "source_refs": [ "SRC-003", "SRC-001", "SRC-006" ] } ], "inline_only_rationale": null }, { "id": "f-governed-subject", "name": "Governed subject and granularity", "description": "A contract binds to something concrete: a table, a topic subject, a file layout, a message payload or an API resource. The binding target and its granularity determine what a validation failure means. ODCS expresses this through domain, dataProduct, tenant and the physical name and type of each schema object; a schema registry expresses it through the subject and its naming strategy; DCAT expresses it as a conformance link from a dataset or distribution.", "source_refs": [ "SRC-003", "SRC-004", "SRC-011", "SRC-008" ], "questions": [ { "id": "q-gsub-target", "text": "Which specific datasets, topics, tables or message types does this contract govern, and by what binding mechanism?", "kind": "relationship", "answer_data": [ "Governed target references", "Binding mechanism (subject name strategy, physical name, conformsTo link)", "Cardinality of contract to target" ] }, { "id": "q-gsub-granularity", "text": "At what granularity does one contract instance apply - one object, one product, one domain or one tenant?", "kind": "classification", "answer_data": [ "Granularity level", "Domain and tenant values", "Data granularity description" ] }, { "id": "q-gsub-partial", "text": "Does the contract govern the entire target or only a declared subset of its fields and partitions?", "kind": "composition", "answer_data": [ "Coverage statement", "Excluded fields or partitions", "Rationale for exclusion" ] }, { "id": "q-gsub-collision", "text": "What happens when two contracts claim authority over the same target?", "kind": "exception", "answer_data": [ "Precedence rule", "Conflict detection point", "Escalation owner" ] } ], "data_elements": [ { "id": "de-governed-target-ref", "name": "governedTargetReference", "description": "Reference to the dataset, topic subject, table or message type the contract governs.", "value_kind": "reference", "cardinality": "1..n", "required": true, "source_refs": [ "SRC-011", "SRC-008" ] }, { "id": "de-domain-tenant", "name": "domainAndTenant", "description": "Organisational scoping values that qualify the governed subject.", "value_kind": "code", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-003" ] } ], "artifacts": [], "inline_only_rationale": "The governed-subject binding is pure reference data: it is a set of pointers held inside the contract document and mirrored as a conformsTo link on the catalogue side. It produces no artefact of its own, and materialising a separate binding file would create a second place for the binding to drift out of agreement with the contract that owns it." }, { "id": "f-dialect-and-vocabulary", "name": "Dialect, vocabulary and kind", "description": "The language that interprets the schema must be explicit: ODCS apiVersion and kind DataContract; JSON Schema $schema meta-schema URI and $vocabulary set; OpenAPI jsonSchemaDialect or OAS dialect id; SHACL Core versus SHACL-SPARQL. Companion JSON Schemas for ODCS and OAS are non-authoritative if they conflict with the standard text.", "source_refs": [ "SRC-019", "SRC-020", "SRC-007", "SRC-023" ], "questions": [ { "id": "f-dialect-and-vocabulary-q01", "text": "Is this artefact a DataContract, a JSON Schema document, a SHACL shapes graph, an Avro schema, or an OpenAPI Schema Object, and which kind value is declared?", "kind": "classification", "answer_data": [ "kind or media type", "language family", "declared kind value" ] }, { "id": "f-dialect-and-vocabulary-q02", "text": "Which meta-schema, apiVersion or dialect URI must a processor load before interpreting keywords?", "kind": "interoperability", "answer_data": [ "dialect URI", "ODCS apiVersion", "$schema URI", "OpenAPI jsonSchemaDialect" ] }, { "id": "f-dialect-and-vocabulary-q03", "text": "Which vocabularies are required versus optional, and must a processor refuse the schema if an unknown required vocabulary is declared?", "kind": "requirement", "answer_data": [ "required vocabulary URIs", "optional vocabulary URIs", "processor refusal rule" ] }, { "id": "f-dialect-and-vocabulary-q04", "text": "If a companion JSON Schema disagrees with the ODCS or OpenAPI standard text, which source is authoritative?", "kind": "authority", "answer_data": [ "authoritative specification", "companion schema URI", "conflict note" ] } ], "data_elements": [ { "id": "f-dialect-and-vocabulary-data01", "name": "Kind", "description": "ODCS required kind; valid value is DataContract. Other families use media type or language name instead of this field.", "value_kind": "code", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-019" ] }, { "id": "f-dialect-and-vocabulary-data02", "name": "Standard version", "description": "ODCS apiVersion of the contract standard used to author the document.", "value_kind": "text", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-019" ] }, { "id": "f-dialect-and-vocabulary-data03", "name": "Schema dialect URI", "description": "JSON Schema $schema or OpenAPI jsonSchemaDialect identifying the meta-schema that the document must validate against.", "value_kind": "identifier", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-020", "SRC-023" ] }, { "id": "f-dialect-and-vocabulary-data04", "name": "Vocabularies in use", "description": "Map of vocabulary URIs to required-or-optional booleans from $vocabulary.", "value_kind": "object", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-020" ] }, { "id": "f-dialect-and-vocabulary-data05", "name": "SHACL profile", "description": "Whether processors must implement SHACL Core only or also SHACL-SPARQL constraint components.", "value_kind": "code", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-007" ] } ], "artifacts": [ { "id": "f-dialect-and-vocabulary-artifact01", "name": "Declared meta-schema or dialect document", "description": "The meta-schema, ODCS version definition or OAS dialect identified by the contract, used to validate the schema itself.", "media_or_form": [ "JSON Schema meta-schema", "ODCS version declaration", "OpenAPI dialect schema" ], "serial": true, "identity_strategy": "Identify by the dialect or meta-schema URI, not by local filename.", "source_refs": [ "SRC-020", "SRC-023" ] } ], "inline_only_rationale": null } ] }, { "id": "l-version-status", "name": "Version designation and status", "description": "How a specific version is named, made immutable and moved through its states.", "source_refs": [ "SRC-003", "SRC-017", "SRC-011" ], "findings": [ { "id": "f-version-designation", "name": "Version designation and immutability", "description": "ODCS requires a version on every contract. Semantic Versioning supplies the widely used rules: MAJOR for incompatible change, MINOR for backward-compatible addition, PATCH for backward-compatible fixes, with the hard rule that a released version's contents MUST NOT be modified. A schema registry adds an orthogonal monotonic version number per subject plus a globally unique schema id. An agent must not conflate a contract's semantic version, a registry version number and a fingerprint - they answer different questions.", "source_refs": [ "SRC-003", "SRC-017", "SRC-011" ], "questions": [ { "id": "q-ver-scheme", "text": "Which versioning scheme governs this contract, and what rule decides when the major component increments?", "kind": "constraint", "answer_data": [ "Versioning scheme identifier", "Major-increment rule", "Pre-release and build-metadata conventions" ] }, { "id": "q-ver-immutability", "text": "Once published, is the version immutable, and what mechanism prevents in-place edits?", "kind": "constraint", "answer_data": [ "Immutability guarantee", "Enforcement mechanism", "Correction procedure when a bad version is published" ] }, { "id": "q-ver-chain", "text": "Which version precedes and which supersedes this one, and how is that chain expressed to consumers?", "kind": "relationship", "answer_data": [ "Previous version reference", "Superseding version reference", "Chain expression (dcat:previousVersion or registry ordering)" ] }, { "id": "q-ver-concurrent", "text": "How many versions may be simultaneously in force, and how does a consumer pin to one?", "kind": "state", "answer_data": [ "Concurrent-version policy", "Pinning mechanism", "Default version resolution rule" ] } ], "data_elements": [ { "id": "de-contract-version", "name": "contractVersion", "description": "Version designation of this contract instance under the declared scheme.", "value_kind": "text", "cardinality": "1", "required": true, "source_refs": [ "SRC-003", "SRC-017" ] }, { "id": "de-previous-version-ref", "name": "previousVersionReference", "description": "Link to the immediately preceding version, forming an ordered chain.", "value_kind": "reference", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-008" ] } ], "artifacts": [ { "id": "af-version-series", "name": "Published contract version series", "description": "The ordered, immutable set of published versions of one contract, each independently retrievable.", "media_or_form": [ "registry version series", "tagged repository history", "immutable document set" ], "serial": true, "identity_strategy": "Contract identifier plus version designation forms the composite key; registry-assigned monotonic version number is retained as the ordering key where a registry is the master system.", "source_refs": [ "SRC-017", "SRC-011" ] } ], "inline_only_rationale": null }, { "id": "f-contract-status", "name": "Contract status and lifecycle states", "description": "ODCS makes status a required field. Status is what tells a consumer whether the contract may be relied on, and it is distinct from version. Registry-style governance adds a registration status assigned by a registration authority, and DCAT-AP requires a controlled vocabulary for distribution status. The set of permitted states, the permitted transitions and who may perform each transition must be explicit; an unconstrained free-text status is a governance failure disguised as flexibility.", "source_refs": [ "SRC-003", "SRC-015", "SRC-016" ], "questions": [ { "id": "q-sta-vocabulary", "text": "What is the closed set of permitted status values, and is it drawn from a controlled vocabulary?", "kind": "classification", "answer_data": [ "Permitted status values", "Controlled vocabulary reference", "Whether the set is closed or extensible" ] }, { "id": "q-sta-transitions", "text": "Which status transitions are permitted, and which are forbidden or require a waiver?", "kind": "lifecycle", "answer_data": [ "Permitted transition pairs", "Forbidden transitions", "Waiver requirement" ] }, { "id": "q-sta-effective", "text": "At what instant does a status change take effect, and is that instant recorded separately from when it was observed?", "kind": "temporal", "answer_data": [ "Effective timestamp", "Recorded or ingestion timestamp", "Time zone offset used" ] }, { "id": "q-sta-binding", "text": "Which statuses make the contract binding on producers, and which make it advisory only?", "kind": "authority", "answer_data": [ "Binding statuses", "Advisory statuses", "Consequence of breach per status" ] } ], "data_elements": [ { "id": "de-contract-status", "name": "contractStatus", "description": "Current lifecycle state of the contract version.", "value_kind": "code", "cardinality": "1", "required": true, "source_refs": [ "SRC-003" ] }, { "id": "de-status-effective-time", "name": "statusEffectiveTime", "description": "Instant at which the current status became effective, recorded with an explicit offset.", "value_kind": "timestamp", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-010" ] } ], "artifacts": [ { "id": "af-status-transition-log", "name": "Status transition log", "description": "Append-only record of every status change with actor, reason, event time and record time.", "media_or_form": [ "append-only log", "audit table", "signed event stream" ], "serial": true, "identity_strategy": "Contract identifier plus version plus monotonically increasing sequence number assigned by the governing registry; no date component is used as the identifier.", "source_refs": [ "SRC-003", "SRC-009" ] } ], "inline_only_rationale": null } ] }, { "id": "l-ownership-authority", "name": "Ownership and change authority", "description": "The accountable parties and the authority to approve or reject a change.", "source_refs": [ "SRC-003", "SRC-014", "SRC-009" ], "findings": [ { "id": "f-ownership-stewardship", "name": "Ownership, stewardship and approval authority", "description": "The registry names a data product owner or data steward as maintainer. ODCS carries team and roles sections; the deprecated Data Contract Specification carries an owner in its info block. Ownership answers accountability; approval authority answers who can bind the organisation to a change. These are frequently the same person and must still be modelled separately, because delegation and vacancy are normal states.", "source_refs": [ "SRC-003", "SRC-014", "SRC-009" ], "questions": [ { "id": "q-own-accountable", "text": "Which single party is accountable for the correctness of this contract, and how is that party identified?", "kind": "ownership", "answer_data": [ "Accountable party reference", "Party identifier scheme", "Accountability start time" ] }, { "id": "q-own-approve", "text": "Who is authorised to approve a breaking change, and is that authority delegable?", "kind": "authority", "answer_data": [ "Approver role", "Delegation rule", "Quorum or single-approver requirement" ] }, { "id": "q-own-vacancy", "text": "What is the fallback when the named owner is absent, has left, or the role is vacant?", "kind": "exception", "answer_data": [ "Fallback owner", "Maximum vacancy period", "Automatic escalation target" ] }, { "id": "q-own-attribution", "text": "Which agent is recorded as having authored each version, distinct from who approved it?", "kind": "provenance", "answer_data": [ "Authoring agent", "Approving agent", "Attribution relation used" ] } ], "data_elements": [ { "id": "de-owner-ref", "name": "ownerReference", "description": "Reference to the accountable party in the party or organisation model.", "value_kind": "reference", "cardinality": "1", "required": true, "source_refs": [ "SRC-003" ] }, { "id": "de-approval-role", "name": "approvalRole", "description": "Role holding authority to approve changes at each severity level.", "value_kind": "code", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-003" ] } ], "artifacts": [ { "id": "af-stewardship-record", "name": "Stewardship and approval register", "description": "Register of accountable owners, stewards and approvers with effective periods and delegations.", "media_or_form": [ "register entry", "role assignment record" ], "serial": false, "identity_strategy": "Party identifier from the authoritative identity master system, joined to the contract identifier; never keyed on personal name.", "source_refs": [ "SRC-003", "SRC-009" ] } ], "inline_only_rationale": null } ] } ] }, { "id": "schema-structure-and-semantics", "name": "Schema structure and semantics", "description": "What the data looks like structurally, how its types map to physical representation, and what its fields actually mean.", "rationale": "Structure without semantics produces syntactically valid but meaningless data. ODCS separates logicalType from physicalType and offers authoritativeDefinitions precisely because structure and meaning are different layers, and ISO/IEC 11179 formalises the same split between conceptual and representational levels.", "source_refs": [ "SRC-004", "SRC-006", "SRC-016" ], "layers": [ { "id": "l-structural-definition", "name": "Structural definition", "description": "Objects, properties, nesting, keys, uniqueness and declared relationships.", "source_refs": [ "SRC-004", "SRC-002", "SRC-007" ], "findings": [ { "id": "f-object-property-structure", "name": "Object and property structure", "description": "ODCS models a schema as an array of objects, each with a required name and a properties array; each property has a required name and optional logicalType, physicalType, required, unique, items for arrays and nested properties for objects. JSON Schema expresses the same shape through properties, items, prefixItems and applicator keywords; SHACL through node shapes carrying property shapes. Nesting depth, array element typing and the treatment of additional or unexpected properties are the decisions that most often break consumers.", "source_refs": [ "SRC-004", "SRC-002", "SRC-007", "SRC-001" ], "questions": [ { "id": "q-str-composition", "text": "What is the full set of objects and properties, including nesting depth and array element definitions?", "kind": "composition", "answer_data": [ "Object list with names", "Property list per object with names", "Nested and array element definitions" ] }, { "id": "q-str-openness", "text": "Is the structure closed, or may an instance carry properties not declared in the contract?", "kind": "constraint", "answer_data": [ "Open or closed declaration", "Handling rule for undeclared properties", "Whether undeclared properties fail validation" ] }, { "id": "q-str-order", "text": "Does property ordering carry meaning for the physical representation, and where is that ordering authoritative?", "kind": "constraint", "answer_data": [ "Ordering significance flag", "Authoritative ordering source", "Positional attributes such as key position" ] }, { "id": "q-str-reuse", "text": "Which property definitions are reused from a shared definitions library rather than declared locally?", "kind": "composition", "answer_data": [ "Reused definition references", "Library location", "Local override rules" ] } ], "data_elements": [ { "id": "de-schema-object", "name": "schemaObject", "description": "A named container in the schema corresponding to a table, view, topic or message type.", "value_kind": "object", "cardinality": "1..n", "required": true, "source_refs": [ "SRC-004" ] }, { "id": "de-property-definition", "name": "propertyDefinition", "description": "A named attribute within a schema object, carrying type, requiredness and nested structure.", "value_kind": "object", "cardinality": "1..n", "required": true, "source_refs": [ "SRC-004" ] }, { "id": "de-additional-properties-policy", "name": "additionalPropertiesPolicy", "description": "Declared treatment of properties present in an instance but absent from the contract.", "value_kind": "code", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-002" ] } ], "artifacts": [ { "id": "af-schema-definition", "name": "Structural schema definition", "description": "The machine-readable structural definition expressed in the declared schema language.", "media_or_form": [ "schema document", "shapes graph", "registry-held schema string" ], "serial": false, "identity_strategy": "Registry subject and schema id where a registry is master; otherwise the schema canonical URI; fingerprint over canonical form used to detect duplicates.", "source_refs": [ "SRC-004", "SRC-011", "SRC-006" ] } ], "inline_only_rationale": null }, { "id": "f-keys-and-relationships", "name": "Keys, uniqueness and declared relationships", "description": "ODCS v3.1.0 added relationships (foreign keys), supporting property-level relationships with an implicit from field, schema-level relationships with explicit from and to, composite keys expressed as arrays, and nested property references using dot notation. It also carries primaryKey, primaryKeyPosition and unique on properties. Declared referential relationships are assertions about data that a schema validator alone cannot check - they need a referential validation step against a second dataset.", "source_refs": [ "SRC-004", "SRC-014", "SRC-007" ], "questions": [ { "id": "q-key-primary", "text": "Which properties form the primary key, and in what order for a composite key?", "kind": "identity", "answer_data": [ "Primary key property names", "Key position ordering", "Whether the key is natural or surrogate" ] }, { "id": "q-key-unique", "text": "Which uniqueness constraints hold beyond the primary key, and over what scope are they evaluated?", "kind": "constraint", "answer_data": [ "Unique property or property sets", "Evaluation scope (partition, whole dataset, time window)", "Duplicate handling rule" ] }, { "id": "q-key-foreign", "text": "Which declared relationships point at other datasets, and is referential integrity enforced or merely asserted?", "kind": "relationship", "answer_data": [ "From and to property references", "Target dataset or contract reference", "Enforcement level (enforced, checked, asserted only)" ] }, { "id": "q-key-orphan", "text": "What is the agreed behaviour when a referenced target row is missing or arrives late?", "kind": "exception", "answer_data": [ "Orphan handling rule", "Permitted lateness window", "Escalation severity" ] } ], "data_elements": [ { "id": "de-primary-key", "name": "primaryKeyDefinition", "description": "Ordered set of properties designated as the primary key of a schema object.", "value_kind": "collection", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-004" ] }, { "id": "de-relationship-declaration", "name": "relationshipDeclaration", "description": "Declared foreign-key style relationship with from and to references, possibly composite or nested.", "value_kind": "reference", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-004" ] } ], "artifacts": [ { "id": "af-referential-check-result", "name": "Referential integrity check result", "description": "Outcome of evaluating declared relationships against actual data in the referenced target.", "media_or_form": [ "check result record", "validation report fragment" ], "serial": true, "identity_strategy": "Contract identifier plus relationship identifier plus run identifier assigned by the executing system; run identifiers are opaque UUID or ULID values.", "source_refs": [ "SRC-004", "SRC-013" ] } ], "inline_only_rationale": null }, { "id": "f-composition-references-and-shape-targets", "name": "Composition, references and shape targets", "description": "JSON Schema applicators apply subschemas in place or to children via $ref, $defs, allOf, anyOf, oneOf, not, if/then/else, properties, prefixItems and $dynamicRef. $id in a subschema starts a new resource. SHACL distinguishes node shapes from property shapes with sh:path (predicate, inverse, sequence, alternative, quantified paths) and targets class, node, subjects-of and objects-of. Avro references named types by fullname and uses unions instead of oneOf. OpenAPI Schema Object $ref follows JSON Schema 2020-12 inside schemas.", "source_refs": [ "SRC-020", "SRC-007", "SRC-006", "SRC-023" ], "questions": [ { "id": "f-composition-references-and-shape-targets-q01", "text": "Which reusable definitions exist, and which $ref, named-type or shape IRIs must be resolved before evaluation?", "kind": "relationship", "answer_data": [ "definition identifiers", "reference URIs", "resolution base URI" ] }, { "id": "f-composition-references-and-shape-targets-q02", "text": "How are subschemas combined (allOf, anyOf, oneOf, not, union), and does adding a constraint follow open-world JSON Schema rules or Avro field lists?", "kind": "composition", "answer_data": [ "applicator list", "union branches", "combination semantics" ] }, { "id": "f-composition-references-and-shape-targets-q03", "text": "Which nodes does each SHACL shape target, and what property path is constrained from the focus node?", "kind": "relationship", "answer_data": [ "target declaration", "property path", "focus node rule" ] }, { "id": "f-composition-references-and-shape-targets-q04", "text": "What happens if a reference cannot be dereferenced, or if $dynamicRef depends on evaluation-time dynamic scope?", "kind": "exception", "answer_data": [ "failure mode", "dynamic anchor", "unresolved reference handling" ] } ], "data_elements": [ { "id": "f-composition-references-and-shape-targets-data01", "name": "Schema references", "description": "$ref, $dynamicRef, Avro named-type references or SHACL sh:node links.", "value_kind": "collection", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-020", "SRC-007", "SRC-006" ] }, { "id": "f-composition-references-and-shape-targets-data02", "name": "Reusable definitions", "description": "$defs (and legacy definitions) or named Avro types available for reference.", "value_kind": "object", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-020", "SRC-006" ] }, { "id": "f-composition-references-and-shape-targets-data03", "name": "Applicators", "description": "allOf, anyOf, oneOf, not, if/then/else or Avro union ordered branches.", "value_kind": "object", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-020", "SRC-006" ] }, { "id": "f-composition-references-and-shape-targets-data04", "name": "Shape targets", "description": "SHACL targetClass, targetNode, targetSubjectsOf, targetObjectsOf or implicit class targets.", "value_kind": "collection", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-007" ] }, { "id": "f-composition-references-and-shape-targets-data05", "name": "Property path", "description": "SHACL well-formed property path mapping to a SPARQL path.", "value_kind": "object", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-007" ] } ], "artifacts": [ { "id": "f-composition-references-and-shape-targets-artifact01", "name": "Shapes graph or subschema set", "description": "Reusable shapes, $defs and named types that the root schema applies by reference or applicator.", "media_or_form": [ "shapes graph", "subschema set", "named type set" ], "serial": true, "identity_strategy": "Identify by canonical URI, shape IRI or Avro fullname of each reusable resource.", "source_refs": [ "SRC-020", "SRC-007", "SRC-006" ] } ], "inline_only_rationale": null } ] }, { "id": "l-type-representation", "name": "Type system and representation", "description": "Logical types, physical types, encodings and temporal conventions.", "source_refs": [ "SRC-004", "SRC-006", "SRC-010" ], "findings": [ { "id": "f-logical-physical-types", "name": "Logical to physical type mapping", "description": "ODCS deliberately separates logicalType (string, date, timestamp, number, integer, object, array, boolean) from physicalType (the platform-specific type such as VARCHAR or INT) and physicalName. Avro layers logical types (decimal, uuid, date, time, timestamp, local-timestamp, duration) over primitive representations. The mapping is lossy in both directions: precision, signedness and nullability behave differently across engines, and the contract must state which side is authoritative.", "source_refs": [ "SRC-004", "SRC-006" ], "questions": [ { "id": "q-typ-logical", "text": "What logical type is declared for each property, and from which type vocabulary is it drawn?", "kind": "classification", "answer_data": [ "Logical type per property", "Type vocabulary reference", "Logical type options or parameters" ] }, { "id": "q-typ-physical", "text": "What physical type and physical name does each property take in each target platform?", "kind": "interoperability", "answer_data": [ "Physical type per platform", "Physical name per platform", "Platform identifier" ] }, { "id": "q-typ-precision", "text": "For numeric and decimal properties, what precision, scale and rounding behaviour is guaranteed?", "kind": "measurement", "answer_data": [ "Precision and scale", "Rounding rule", "Overflow behaviour" ] }, { "id": "q-typ-null", "text": "How is absence distinguished from an explicit null and from a defined sentinel value?", "kind": "definition", "answer_data": [ "Absence semantics", "Null semantics", "Sentinel values in use" ] } ], "data_elements": [ { "id": "de-logical-type", "name": "logicalType", "description": "Platform-independent type of a property.", "value_kind": "code", "cardinality": "1", "required": true, "source_refs": [ "SRC-004" ] }, { "id": "de-physical-type-binding", "name": "physicalTypeBinding", "description": "Platform-specific type and name to which the logical type maps on a given server.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-004" ] } ], "artifacts": [ { "id": "af-type-mapping-table", "name": "Logical to physical type mapping table", "description": "Explicit, reviewable table of logical type to physical type per target platform, including known lossy mappings.", "media_or_form": [ "mapping table", "reference document" ], "serial": false, "identity_strategy": "Contract identifier plus target platform identifier; mapping tables shared across contracts carry their own governed identifier from the standards registry.", "source_refs": [ "SRC-004", "SRC-006" ] } ], "inline_only_rationale": null }, { "id": "f-encoding-temporal-conventions", "name": "Encoding, units and temporal conventions", "description": "Two datasets with identical structure can still be incompatible over character encoding, decimal separators, unit of measure and time representation. RFC 3339 requires seconds and an explicit offset, permits Z, treats -00:00 as an unknown local offset and allows second value 60 only for a leap second. Avro further distinguishes global-timeline timestamps from timezone-independent local timestamps. ODCS carries a unit attribute on quality rules; units on data properties themselves are a known weak point.", "source_refs": [ "SRC-010", "SRC-006", "SRC-005" ], "questions": [ { "id": "q-enc-time", "text": "How are date and time values represented, and does the representation carry an explicit offset?", "kind": "temporal", "answer_data": [ "Time format specification", "Offset handling rule", "Precision (seconds, milliseconds, microseconds)" ] }, { "id": "q-enc-eventvsingest", "text": "Which timestamp property carries event time and which carries observation or ingestion time?", "kind": "temporal", "answer_data": [ "Event-time property name", "Ingestion-time property name", "Permitted skew between them" ] }, { "id": "q-enc-character", "text": "What character encoding, collation and normalisation form apply to text properties?", "kind": "constraint", "answer_data": [ "Character encoding", "Collation", "Unicode normalisation form" ] }, { "id": "q-enc-units", "text": "For quantity properties, what unit of measure is guaranteed and is it stated in the contract or assumed?", "kind": "measurement", "answer_data": [ "Unit of measure per property", "Unit vocabulary reference", "Whether the unit is contractual or conventional" ] } ], "data_elements": [ { "id": "de-temporal-convention", "name": "temporalConvention", "description": "Declared representation rules for temporal properties, including offset and precision.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-010", "SRC-006" ] }, { "id": "de-unit-of-measure", "name": "unitOfMeasure", "description": "Declared unit for a quantity property, drawn from a named unit vocabulary.", "value_kind": "code", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-005" ] } ], "artifacts": [], "inline_only_rationale": "Encoding and unit conventions are inline attributes of property definitions and of the serialization binding. They have no independent existence and no separate retrieval need; extracting them into a standalone artefact would split one property's meaning across two documents and create a drift surface with no compensating benefit." } ] }, { "id": "l-semantic-binding", "name": "Semantic binding", "description": "Connection of structural properties to governed business meaning and value domains.", "source_refs": [ "SRC-004", "SRC-016", "SRC-015" ], "findings": [ { "id": "f-term-value-domain-binding", "name": "Business term and value domain binding", "description": "ODCS provides authoritativeDefinitions at contract and property level, letting a property point at the definition that governs its meaning. The ISO/IEC 11179 family formalises this as a separation between the conceptual level (data element concept, conceptual domain) and the representational level (data element, value domain), administered by a registration authority. DCAT-AP shows the jurisdictional variant: certain properties must draw values from named controlled vocabularies. Without this binding, a schema is a set of labelled boxes.", "source_refs": [ "SRC-004", "SRC-016", "SRC-015" ], "questions": [ { "id": "q-sem-definition", "text": "Where is the authoritative definition of each business-significant property held, and is it dereferenceable?", "kind": "definition", "answer_data": [ "Authoritative definition URL or identifier", "Definition type", "Dereference mechanism" ] }, { "id": "q-sem-valuedomain", "text": "Which properties draw values from an enumerated value domain or code list, and which list version applies?", "kind": "classification", "answer_data": [ "Value domain reference", "Code list version", "Whether the list is closed or extensible" ] }, { "id": "q-sem-registry", "text": "Is the concept registered in a metadata registry as an administered item, and what is its registration status?", "kind": "provenance", "answer_data": [ "Administered item identifier", "Registration authority", "Registration status" ] }, { "id": "q-sem-divergence", "text": "Where does the contract's local meaning of a property deliberately diverge from the governed definition?", "kind": "exception", "answer_data": [ "Divergent property names", "Nature of the divergence", "Approving authority for the divergence" ] } ], "data_elements": [ { "id": "de-authoritative-definition", "name": "authoritativeDefinitionReference", "description": "Pointer to the governing definition of a property or of the contract as a whole.", "value_kind": "reference", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-004" ] }, { "id": "de-value-domain-ref", "name": "valueDomainReference", "description": "Reference to the code list or enumerated domain that constrains a property's permitted values, with its version.", "value_kind": "reference", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-015", "SRC-016" ] } ], "artifacts": [ { "id": "af-term-binding-map", "name": "Property to term binding map", "description": "Reviewable map from each contract property to its governed business term and value domain, including version pins.", "media_or_form": [ "binding map", "concordance table", "RDF alignment graph" ], "serial": false, "identity_strategy": "Governed term identifier from the glossary or metadata registry of record, paired with the contract property path; UUID assigned by the adopting Dimension only where no governed term identifier exists.", "source_refs": [ "SRC-004", "SRC-016" ] } ], "inline_only_rationale": null } ] } ] }, { "id": "constraints-validation-and-quality", "name": "Constraints, validation and quality", "description": "What must be true of conforming data, how that is checked, and what evidence the check produces.", "rationale": "JSON Schema distinguishes assertions from annotations and splits format into an annotation vocabulary and an assertion vocabulary; SHACL produces a validation report as its standard outcome; ODCS defines rule types, dimensions and operators. Together these establish that a constraint is only meaningful if its checkability and its outcome format are defined.", "source_refs": [ "SRC-002", "SRC-007", "SRC-005" ], "layers": [ { "id": "l-constraint-expression", "name": "Constraint expression", "description": "How permitted values and permitted combinations are declared and whether they are enforceable.", "source_refs": [ "SRC-002", "SRC-007", "SRC-001" ], "findings": [ { "id": "f-structural-value-constraints", "name": "Structural and value constraints", "description": "JSON Schema validation keywords impose requirements on instances: type, required, enum, pattern, numeric bounds and length bounds are assertions. The format keyword is different: under the format-annotation vocabulary it is only an annotation, and only under the format-assertion vocabulary is it a checked assertion. SHACL offers the parallel set as constraint components on property shapes. An agent must record, per constraint, whether it is enforced, annotated or merely documented, because this determines whether a violation is detectable at all.", "source_refs": [ "SRC-002", "SRC-001", "SRC-007", "SRC-004" ], "questions": [ { "id": "q-con-enumerate", "text": "What value constraints apply to each property, expressed in which constraint vocabulary?", "kind": "constraint", "answer_data": [ "Constraint keyword and value per property", "Constraint vocabulary identifier", "Applicable schema object" ] }, { "id": "q-con-assertion", "text": "For each declared constraint, is it an enforced assertion, an annotation, or documentation only?", "kind": "validation", "answer_data": [ "Assertion or annotation classification", "Vocabulary declaring the behaviour", "Whether the validator implements it" ] }, { "id": "q-con-required", "text": "Which properties are mandatory, and does mandatory mean present, non-null, or both?", "kind": "requirement", "answer_data": [ "Required property list", "Definition of satisfaction", "Interaction with default values" ] }, { "id": "q-con-format", "text": "Which declared formats are actually validated by the deployed toolchain, and which are advisory?", "kind": "quality", "answer_data": [ "Declared format list", "Validated subset", "Toolchain and vocabulary declaration" ] } ], "data_elements": [ { "id": "de-constraint-declaration", "name": "constraintDeclaration", "description": "A single declared constraint on a property or object, with its vocabulary and enforcement class.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-002", "SRC-007" ] }, { "id": "de-enforcement-class", "name": "constraintEnforcementClass", "description": "Whether the constraint behaves as an assertion, an annotation, or is documentation only.", "value_kind": "code", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-001", "SRC-002" ] } ], "artifacts": [ { "id": "af-constraint-set", "name": "Executable constraint set", "description": "The set of constraints in a form a validator can execute, separated from constraints that are advisory.", "media_or_form": [ "validation schema", "shapes graph", "rule set" ], "serial": false, "identity_strategy": "Derived from the parent schema identity: schema canonical URI plus a stable constraint identifier; where a registry is master, the registry schema id governs.", "source_refs": [ "SRC-002", "SRC-007" ] } ], "inline_only_rationale": null }, { "id": "f-cross-field-constraints", "name": "Cross-field, conditional and cross-dataset constraints", "description": "The constraints that matter most operationally are rarely single-property. Conditional application (if one property has a value, another becomes required), mutual exclusivity, ordering between two timestamps, and referential checks against another dataset all fall outside what a single-property type declaration can express. JSON Schema handles some through applicator keywords, SHACL through shape-level constraint components, and ODCS pushes the remainder into SQL or custom quality rules. Recording where each constraint is expressed is essential, because it determines who can execute it.", "source_refs": [ "SRC-001", "SRC-007", "SRC-005" ], "questions": [ { "id": "q-crf-conditional", "text": "Which constraints apply conditionally, and on what condition are they triggered?", "kind": "constraint", "answer_data": [ "Conditional constraint definition", "Triggering condition", "Consequence when triggered" ] }, { "id": "q-crf-crossdataset", "text": "Which constraints require reading a second dataset, and who is responsible for executing them?", "kind": "process", "answer_data": [ "Cross-dataset constraint definition", "Required additional dataset", "Executing party" ] }, { "id": "q-crf-expression", "text": "In which language or engine is each non-structural constraint expressed, and is that expression portable?", "kind": "interoperability", "answer_data": [ "Expression language", "Engine dependency", "Portability assessment" ] }, { "id": "q-crf-timing", "text": "At what point in the data flow is each constraint evaluated - on write, on publish, or after the fact?", "kind": "process", "answer_data": [ "Evaluation point", "Blocking or non-blocking", "Latency between write and evaluation" ] } ], "data_elements": [ { "id": "de-cross-constraint", "name": "crossFieldConstraint", "description": "A constraint spanning more than one property, object or dataset, with its expression language.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-005", "SRC-007" ] }, { "id": "de-evaluation-point", "name": "constraintEvaluationPoint", "description": "Stage in the data flow at which a constraint is evaluated.", "value_kind": "code", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-005" ] } ], "artifacts": [], "inline_only_rationale": "Cross-field constraint definitions live inside the constraint set and the quality rule set already captured as artefacts elsewhere in this model. Creating a third artefact for them would fragment one logical rule inventory across three stores and make it impossible to answer which constraints exist without joining them; the distinction is analytical, not physical." } ] }, { "id": "l-quality-expectations", "name": "Declared quality expectations", "description": "The measurable expectations attached to the contract and their consequences.", "source_refs": [ "SRC-005", "SRC-013" ], "findings": [ { "id": "f-quality-rule-declaration", "name": "Quality rule declaration, threshold and consequence", "description": "ODCS defines four rule types - text (human-readable, not yet executable), library (predefined metrics such as nullValues, missingValues, invalidValues, duplicateValues, rowCount), sql (a query returning a numeric or boolean value) and custom (vendor-specific, for example Soda, Great Expectations, dbt or Monte Carlo). Rules carry a dimension drawn from accuracy, completeness, conformity, consistency, coverage, timeliness and uniqueness; a unit; a comparison operator from a set of eight; and governance attributes severity, businessImpact, scheduler and schedule. A threshold without a stated consequence is not an expectation, it is a dashboard.", "source_refs": [ "SRC-005", "SRC-013" ], "questions": [ { "id": "q-qua-ruletype", "text": "What type is each quality rule, and is it executable as written or only human-readable?", "kind": "classification", "answer_data": [ "Rule type", "Executability flag", "Engine or metric name where applicable" ] }, { "id": "q-qua-threshold", "text": "What metric, comparison operator, threshold value and unit define pass or fail for each rule?", "kind": "measurement", "answer_data": [ "Metric name", "Comparison operator", "Threshold value and unit" ] }, { "id": "q-qua-consequence", "text": "What severity and business impact attach to a failure, and does failure block publication?", "kind": "requirement", "answer_data": [ "Severity level", "Business impact statement", "Blocking or non-blocking outcome" ] }, { "id": "q-qua-schedule", "text": "On what schedule is each rule evaluated, and against which slice of the data?", "kind": "temporal", "answer_data": [ "Scheduler and schedule expression", "Evaluated data slice or window", "Expected evaluation frequency" ] }, { "id": "q-qua-dimension", "text": "Which quality dimension does each rule serve, and is the dimension vocabulary controlled?", "kind": "classification", "answer_data": [ "Dimension value", "Dimension vocabulary reference", "Coverage of dimensions across the contract" ] } ], "data_elements": [ { "id": "de-quality-rule", "name": "qualityRule", "description": "A declared quality expectation with type, metric, operator, threshold, unit, dimension and schedule.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-005" ] }, { "id": "de-rule-severity", "name": "ruleSeverity", "description": "Severity assigned to failure of a rule, driving escalation and blocking behaviour.", "value_kind": "code", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-005", "SRC-007" ] } ], "artifacts": [ { "id": "af-quality-rule-set", "name": "Declared quality rule set", "description": "The full inventory of declared quality rules for one contract version, with thresholds and consequences.", "media_or_form": [ "rule inventory", "contract section", "executable check suite" ], "serial": false, "identity_strategy": "Contract identifier plus contract version plus the stable rule id that ODCS provides for refactor-safe reference; opaque identifiers preferred over rule text.", "source_refs": [ "SRC-005" ] } ], "inline_only_rationale": null } ] }, { "id": "l-validation-evidence", "name": "Validation outcome and evidence", "description": "The structure and retention of the evidence that a validation actually happened.", "source_refs": [ "SRC-001", "SRC-007", "SRC-013" ], "findings": [ { "id": "f-validation-outcome-report", "name": "Validation outcome and conformance evidence", "description": "SHACL defines the validation report as the standard outcome, carrying conformance and per-violation detail. JSON Schema defines four structured output formats - flag, basic, detailed and verbose - with standardised location reporting and separation of errors from annotations. OpenLineage carries dataQualityAssertions and dataQualityMetrics as input dataset facets on run events. An agent needs to know which output format is produced, where it is kept, for how long, and whether it is admissible as evidence of compliance.", "source_refs": [ "SRC-007", "SRC-001", "SRC-013" ], "questions": [ { "id": "q-val-format", "text": "In what output format are validation results produced, and does it identify the failing instance location?", "kind": "evidence", "answer_data": [ "Output format name", "Location reporting scheme", "Error and annotation separation" ] }, { "id": "q-val-conformance", "text": "What exactly does a conformance result assert, and against which contract version was it evaluated?", "kind": "validation", "answer_data": [ "Conformance boolean or grade", "Contract version evaluated", "Validator identity and version" ] }, { "id": "q-val-retention", "text": "How long are validation reports retained, and what triggers their deletion?", "kind": "retention", "answer_data": [ "Retention period", "Deletion trigger", "Legal hold exceptions" ] }, { "id": "q-val-times", "text": "Which timestamps are recorded for a validation run, distinguishing the data's event time from the run's observation time?", "kind": "temporal", "answer_data": [ "Run start and end timestamps with offset", "Data event-time window covered", "Report ingestion timestamp" ] } ], "data_elements": [ { "id": "de-validation-result", "name": "validationResult", "description": "Outcome of evaluating a contract against data, including conformance and violation detail.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-007", "SRC-001" ] }, { "id": "de-validation-run-time", "name": "validationRunTimestamp", "description": "Observation time of the validation run, recorded with seconds and an explicit offset.", "value_kind": "timestamp", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-010" ] } ], "artifacts": [ { "id": "af-validation-report", "name": "Validation report", "description": "Machine-readable record of one validation run against one contract version, listing conformance and each violation.", "media_or_form": [ "validation report document", "structured output payload", "lineage facet" ], "serial": true, "identity_strategy": "Opaque run identifier assigned by the executing system, preferably a UUID or ULID, joined to contract identifier and version; the run timestamp is an attribute and is never used as the identifier.", "source_refs": [ "SRC-007", "SRC-013" ] } ], "inline_only_rationale": null } ] } ] }, { "id": "evolution-and-compatibility", "name": "Evolution and compatibility", "description": "How a contract may change without breaking the parties that depend on it.", "rationale": "Compatibility is the operational heart of a data contract. Confluent's compatibility modes, Avro's schema resolution rules and Iceberg's column-identifier approach are three independent, production-proven treatments of the same problem, and each imposes different obligations on deployment order.", "source_refs": [ "SRC-011", "SRC-012", "SRC-006", "SRC-018" ], "layers": [ { "id": "l-compatibility-policy", "name": "Compatibility policy and resolution", "description": "The declared compatibility mode and the mechanics that make old and new readers interoperate.", "source_refs": [ "SRC-011", "SRC-012", "SRC-006" ], "findings": [ { "id": "f-compatibility-mode", "name": "Compatibility mode and breaking-change determination", "description": "A registry-governed compatibility mode is drawn from BACKWARD, BACKWARD_TRANSITIVE, FORWARD, FORWARD_TRANSITIVE, FULL, FULL_TRANSITIVE and NONE, configurable globally or per subject. The mode is not cosmetic: under backward compatibility consumers must be upgraded first and permitted changes are field deletion and addition of optional fields with defaults; under forward compatibility producers must be upgraded first and permitted changes are field addition and deletion of optional fields with defaults. Transitive modes extend the check across all prior versions rather than only the immediate predecessor.", "source_refs": [ "SRC-011", "SRC-012", "SRC-017" ], "questions": [ { "id": "q-cmp-mode", "text": "Which compatibility mode is in force for this contract, and is it set globally or per subject?", "kind": "constraint", "answer_data": [ "Compatibility mode value", "Configuration scope", "Who may change the mode" ] }, { "id": "q-cmp-order", "text": "Given the mode, which party must be upgraded first when a new version is published?", "kind": "process", "answer_data": [ "Upgrade-first party", "Coordination requirement", "Rollback plan" ] }, { "id": "q-cmp-breaking", "text": "What test determines that a proposed change is breaking, and is that test automated?", "kind": "decision", "answer_data": [ "Compatibility check procedure", "Automation status", "Check result record" ] }, { "id": "q-cmp-transitive", "text": "Is compatibility checked only against the immediately previous version or against all prior versions?", "kind": "constraint", "answer_data": [ "Transitive flag", "Version range checked", "Reason for the chosen depth" ] } ], "data_elements": [ { "id": "de-compatibility-mode", "name": "compatibilityMode", "description": "Declared compatibility mode governing permitted changes for this subject or contract.", "value_kind": "code", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-011" ] }, { "id": "de-compatibility-check-outcome", "name": "compatibilityCheckOutcome", "description": "Result of evaluating a candidate version against the mode and the relevant prior versions.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-011" ] } ], "artifacts": [ { "id": "af-compatibility-check-record", "name": "Compatibility check record", "description": "Record of a candidate version tested against the declared mode, listing incompatibilities found.", "media_or_form": [ "check record", "gate result in a change pipeline" ], "serial": true, "identity_strategy": "Registry subject plus candidate schema fingerprint plus check sequence number issued by the checking system; the candidate is not assigned a schema id until it passes.", "source_refs": [ "SRC-011", "SRC-006" ] } ], "inline_only_rationale": null }, { "id": "f-schema-resolution-defaults", "name": "Schema resolution, defaults and identifier stability", "description": "Avro specifies resolution between a writer's schema and a reader's schema: fields match by name, writer fields absent from the reader are ignored, reader fields absent from the writer are filled from defaults and error without one, aliases may map old names to new, and defined type promotions apply (int to long, float or double; long to float or double; float to double; string and bytes interchangeably). Iceberg takes a different route, tracking columns by identifier rather than name so a rename does not invalidate stored data, and evolving partition and sort order independently of schema. The contract must say which mechanism it relies on.", "source_refs": [ "SRC-006", "SRC-018" ], "questions": [ { "id": "q-res-defaults", "text": "Which properties carry default values, and what do those defaults mean when a writer omits the field?", "kind": "definition", "answer_data": [ "Default value per property", "Semantics of the default", "Whether the default implies optionality on write" ] }, { "id": "q-res-alias", "text": "How are renames handled - through aliases, through stable column identifiers, or not at all?", "kind": "interoperability", "answer_data": [ "Rename mechanism", "Alias or identifier mapping", "Historical name history" ] }, { "id": "q-res-promotion", "text": "Which type changes are treated as safe widening, and which force a new major version?", "kind": "constraint", "answer_data": [ "Permitted promotion pairs", "Forbidden type changes", "Governing specification" ] }, { "id": "q-res-independent", "text": "Are partitioning and sort order versioned independently of the schema, and who tracks that?", "kind": "composition", "answer_data": [ "Partition specification version", "Sort order version", "Owning system" ] } ], "data_elements": [ { "id": "de-property-default", "name": "propertyDefaultValue", "description": "Default applied by a reader when a writer omits the property.", "value_kind": "other", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-006" ] }, { "id": "de-stable-column-id", "name": "stablePropertyIdentifier", "description": "Identifier that survives renames, used to match stored data to a current property definition.", "value_kind": "identifier", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-018" ] }, { "id": "de-property-alias", "name": "propertyAlias", "description": "Alternative historical name recognised during schema resolution.", "value_kind": "text", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-006" ] } ], "artifacts": [ { "id": "af-resolution-mapping", "name": "Writer to reader resolution mapping", "description": "Explicit mapping of how a specific writer version resolves against a specific reader version, including defaults applied and aliases used.", "media_or_form": [ "mapping record", "migration note" ], "serial": false, "identity_strategy": "Composite of writer schema identity and reader schema identity as issued by the master registry; fingerprints used where a registry id is unavailable.", "source_refs": [ "SRC-006", "SRC-011" ] } ], "inline_only_rationale": null }, { "id": "f-canonical-form-and-fingerprint", "name": "Canonicalization, fingerprints and language alignments", "description": "Avro Parsing Canonical Form strips docs and aliases, expands fullnames, orders attributes and removes whitespace so two schemas that serialise identically in PCF are the same for readers. Fingerprints of PCF (SHA-256, MD5, CRC-64-AVRO) tag data and cache codecs; they are not security guarantees. JSON Schema $id is an identifier, not necessarily a network locator. OpenAPI Schema Object is a superset of JSON Schema 2020-12 with an OAS dialect. Alignments must record conflicts: JSON Schema is open-world constraints; Avro is a closed data definition with positional binary encoding.", "source_refs": [ "SRC-006", "SRC-020", "SRC-023", "SRC-024" ], "questions": [ { "id": "f-canonical-form-and-fingerprint-q01", "text": "What canonical form is used to decide whether two schemas are the same for reading, and which attributes are stripped?", "kind": "definition", "answer_data": [ "canonical form name", "stripped attributes", "normalisation rules" ] }, { "id": "f-canonical-form-and-fingerprint-q02", "text": "What fingerprint algorithm and digest identify this canonical schema, and is it used as a cache key rather than as a security signature?", "kind": "identity", "answer_data": [ "algorithm", "digest", "intended use" ] }, { "id": "f-canonical-form-and-fingerprint-q03", "text": "Which external standards is this contract aligned to, and which semantic conflicts are recorded instead of claimed conformance?", "kind": "interoperability", "answer_data": [ "aligned standards", "conflict notes", "conformance claim status" ] }, { "id": "f-canonical-form-and-fingerprint-q04", "text": "If string-encoded content declares contentEncoding or contentMediaType, is automatic decode disabled by default as JSON Schema requires for safety?", "kind": "security", "answer_data": [ "content encoding", "media type", "auto decode disabled" ] } ], "data_elements": [ { "id": "f-canonical-form-and-fingerprint-data01", "name": "Canonical form", "description": "Normalised schema text such as Avro Parsing Canonical Form.", "value_kind": "text", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-006" ] }, { "id": "f-canonical-form-and-fingerprint-data02", "name": "Schema fingerprint", "description": "Short digest of the canonical form used as a tag or cache key.", "value_kind": "identifier", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-006" ] }, { "id": "f-canonical-form-and-fingerprint-data03", "name": "Alignment set", "description": "Named external standards and the mapping notes, including known conflicts.", "value_kind": "collection", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-020", "SRC-023", "SRC-024" ] }, { "id": "f-canonical-form-and-fingerprint-data04", "name": "Content encoding and media type", "description": "JSON Schema contentEncoding, contentMediaType and optional contentSchema for string-encoded payloads.", "value_kind": "object", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-021" ] } ], "artifacts": [ { "id": "f-canonical-form-and-fingerprint-artifact01", "name": "Canonical schema and fingerprint record", "description": "Canonicalised schema text plus fingerprint and declared alignments, including conflict notes.", "media_or_form": [ "canonical schema text", "fingerprint record" ], "serial": true, "identity_strategy": "The fingerprint identifies the canonical bytes; the master-system schema id remains the business identifier.", "source_refs": [ "SRC-006" ] } ], "inline_only_rationale": null } ] }, { "id": "l-change-and-deprecation", "name": "Change control and retirement", "description": "The process by which a change becomes official and by which a version stops being supported.", "source_refs": [ "SRC-003", "SRC-017", "SRC-014" ], "findings": [ { "id": "f-change-approval-process", "name": "Change proposal, review and approval", "description": "A change to a binding contract is a governed event, not a commit. It needs a proposal, an impact assessment against registered consumers, a compatibility check outcome, an approving authority appropriate to the severity, and a recorded decision. Semantic Versioning supplies the discipline that the released version itself is never edited: a correction is a new version. Where a jurisdictional profile applies, the change may also require re-checking conformance to that profile.", "source_refs": [ "SRC-017", "SRC-003", "SRC-015" ], "questions": [ { "id": "q-chg-trigger", "text": "What events may trigger a contract change, and which of them are producer-initiated versus consumer-requested?", "kind": "event", "answer_data": [ "Trigger event types", "Initiating party", "Request record reference" ] }, { "id": "q-chg-impact", "text": "Which registered consumers are affected by the proposed change, and how was that determined?", "kind": "relationship", "answer_data": [ "Affected consumer list", "Impact determination method", "Impact severity per consumer" ] }, { "id": "q-chg-decision", "text": "Who approved the change, on what date and offset, and on what evidence?", "kind": "decision", "answer_data": [ "Approver identity", "Decision timestamp with offset", "Evidence referenced in the decision" ] }, { "id": "q-chg-notice", "text": "What minimum notice period must elapse between approval and the change taking effect?", "kind": "temporal", "answer_data": [ "Notice period duration", "Notice start event", "Exceptions permitted for urgent fixes" ] } ], "data_elements": [ { "id": "de-change-proposal", "name": "changeProposal", "description": "Proposed change to a contract with rationale, impact assessment and target version.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-017" ] }, { "id": "de-notice-period", "name": "noticePeriod", "description": "Minimum duration between approval of a change and its effective date.", "value_kind": "duration", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-014" ] } ], "artifacts": [ { "id": "af-change-record", "name": "Change proposal and decision record", "description": "The proposal, impact assessment, compatibility evidence and approval decision for one change.", "media_or_form": [ "change record", "review thread", "signed decision entry" ], "serial": true, "identity_strategy": "Change identifier issued by the change-management system of record; where none exists, a ULID assigned by the adopting Dimension, joined to contract identifier and target version.", "source_refs": [ "SRC-017", "SRC-003" ] } ], "inline_only_rationale": null }, { "id": "f-deprecation-and-sunset", "name": "Deprecation, sunset and retirement", "description": "Retiring a contract version is the step most often left undefined, and it is where consumers break silently. The contract needs a deprecation state distinct from retirement, a sunset instant after which the version is no longer served or supported, a migration path to the successor version, and a rule for what happens to data already produced under the retired version. DCAT-AP requires a controlled status vocabulary for distributions, and the Data Contract Specification's own deprecation in favour of ODCS with support stated through end of 2026 is a worked example of the pattern.", "source_refs": [ "SRC-015", "SRC-014", "SRC-003" ], "questions": [ { "id": "q-dep-states", "text": "What distinguishes a deprecated version from a retired one in terms of what the producer still guarantees?", "kind": "state", "answer_data": [ "Deprecated-state guarantees", "Retired-state guarantees", "Difference in support obligations" ] }, { "id": "q-dep-sunset", "text": "At what instant does support for this version end, and is that instant published in advance?", "kind": "temporal", "answer_data": [ "Sunset timestamp with explicit offset", "Publication lead time", "Announcement channel" ] }, { "id": "q-dep-migration", "text": "What migration path is offered to consumers, and who bears the migration cost?", "kind": "process", "answer_data": [ "Successor version reference", "Migration guidance reference", "Cost allocation statement" ] }, { "id": "q-dep-legacy-data", "text": "What happens to data already produced under a retired version - is it re-written, re-interpreted or left as-is?", "kind": "retention", "answer_data": [ "Legacy data treatment rule", "Readability guarantee period", "Archive location" ] } ], "data_elements": [ { "id": "de-sunset-time", "name": "sunsetTimestamp", "description": "Instant after which the version is no longer supported, recorded with an explicit offset.", "value_kind": "timestamp", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-010", "SRC-014" ] }, { "id": "de-successor-ref", "name": "successorVersionReference", "description": "Reference to the version consumers should migrate to.", "value_kind": "reference", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-014" ] } ], "artifacts": [ { "id": "af-deprecation-notice", "name": "Deprecation and sunset notice", "description": "Published notice stating the deprecated version, the sunset instant, the successor and the migration path.", "media_or_form": [ "published notice", "catalogue status update", "consumer notification message" ], "serial": true, "identity_strategy": "Contract identifier plus deprecated version plus notice sequence number from the publishing system; the sunset date is an attribute of the notice, not its identifier.", "source_refs": [ "SRC-014", "SRC-015" ] } ], "inline_only_rationale": null } ] } ] }, { "id": "agreement-and-obligations", "name": "Agreement and obligations", "description": "The parties bound by the contract, what each of them promises, and the terms under which data may be used.", "rationale": "This is what separates a data contract from a schema. ODCS carries team, roles, service levels, support channels and description.usage and limitations; the Data Contract Specification carries terms and servicelevels. Without named parties and stated obligations there is no contract, only a description.", "source_refs": [ "SRC-003", "SRC-014", "SRC-004" ], "layers": [ { "id": "l-parties-obligations", "name": "Parties and obligations", "description": "Who is bound, in what role, and what each side has committed to.", "source_refs": [ "SRC-003", "SRC-014" ], "findings": [ { "id": "f-producer-consumer-parties", "name": "Producer and consumer parties", "description": "A contract that does not know its consumers cannot assess the impact of a change. ODCS carries team and roles sections describing who is involved and what access each role holds. Registered consumers are the population that must be notified on deprecation and whose upgrade order matters under a compatibility mode. Unregistered consumption is a real and common state and must be modelled as such rather than assumed away.", "source_refs": [ "SRC-003", "SRC-012" ], "questions": [ { "id": "q-par-producer", "text": "Which party produces the data under this contract, and is there more than one producer?", "kind": "ownership", "answer_data": [ "Producer party reference", "Producer count", "Producer system identifiers" ] }, { "id": "q-par-consumer", "text": "Which consumers are registered against this contract, and how is registration recorded?", "kind": "relationship", "answer_data": [ "Registered consumer list", "Registration mechanism", "Registration effective period" ] }, { "id": "q-par-roles", "text": "What role does each party hold, and what does that role entitle them to?", "kind": "access", "answer_data": [ "Role name per party", "Entitlements per role", "Approval requirement for the role" ] }, { "id": "q-par-unregistered", "text": "How is unregistered or shadow consumption detected, and what is the policy toward it?", "kind": "exception", "answer_data": [ "Detection method", "Policy toward unregistered consumers", "Remediation path" ] } ], "data_elements": [ { "id": "de-producer-party", "name": "producerParty", "description": "Party accountable for producing data conforming to this contract.", "value_kind": "reference", "cardinality": "1..n", "required": true, "source_refs": [ "SRC-003" ] }, { "id": "de-consumer-registration", "name": "consumerRegistration", "description": "Record of a consumer registered against a specific contract version, with role and effective period.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-003" ] } ], "artifacts": [ { "id": "af-consumer-register", "name": "Registered consumer register", "description": "The authoritative list of consumers bound to a contract version, used to drive impact assessment and notification.", "media_or_form": [ "register", "subscription table", "access grant record" ], "serial": false, "identity_strategy": "Party identifier from the authoritative identity master system plus contract identifier plus version; registration events carry their own opaque sequence identifiers.", "source_refs": [ "SRC-003" ] } ], "inline_only_rationale": null }, { "id": "f-obligations-acceptance", "name": "Obligations and acceptance", "description": "ODCS description.usage and description.limitations state what the data may and may not be used for; the Data Contract Specification's terms block covers usage policy, limitations, billing and notice period. Acceptance is the act that makes these binding on a specific consumer, and it has an effective period. An agent needs to distinguish an obligation the producer owes (structure, quality, freshness) from one the consumer owes (permitted use, attribution, no redistribution, notice on cessation).", "source_refs": [ "SRC-003", "SRC-014" ], "questions": [ { "id": "q-obl-producer", "text": "What exactly does the producer commit to deliver, and in what form is that commitment testable?", "kind": "requirement", "answer_data": [ "Producer obligation statements", "Test or measure per obligation", "Consequence of non-delivery" ] }, { "id": "q-obl-consumer", "text": "What restrictions bind the consumer's use, redistribution and derivation of the data?", "kind": "constraint", "answer_data": [ "Permitted use statement", "Prohibited use statement", "Redistribution and derivation rules" ] }, { "id": "q-obl-acceptance", "text": "How does a consumer accept the contract, and over what period is that acceptance effective?", "kind": "process", "answer_data": [ "Acceptance mechanism", "Effective start and end with offsets", "Renewal or lapse rule" ] }, { "id": "q-obl-breach", "text": "What counts as breach by either party, and what remedy follows?", "kind": "exception", "answer_data": [ "Breach definition per party", "Remedy or escalation", "Termination conditions" ] } ], "data_elements": [ { "id": "de-obligation-statement", "name": "obligationStatement", "description": "A single stated commitment attributed to a named party with its testability and consequence.", "value_kind": "text", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-003", "SRC-014" ] }, { "id": "de-acceptance-record", "name": "acceptanceRecord", "description": "Record that a specific consumer accepted a specific contract version, with effective period.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-014" ] } ], "artifacts": [ { "id": "af-acceptance-record", "name": "Consumer acceptance record", "description": "Durable evidence that a named consumer accepted a named contract version, with timestamps and acting agent.", "media_or_form": [ "acceptance record", "signed agreement entry", "audit log entry" ], "serial": true, "identity_strategy": "Consumer party identifier plus contract identifier plus version plus acceptance sequence number issued by the agreement system of record.", "source_refs": [ "SRC-014", "SRC-009" ] } ], "inline_only_rationale": null }, { "id": "f-declared-access-roles", "name": "Consumer roles and access", "description": "ODCS roles list IAM role names, access mode (read or write), and first- and second-level approvers. JSON Schema readOnly and writeOnly describe instance properties managed exclusively by the owning authority or never returned on read. These are contract-level access terms, not a full IAM model.", "source_refs": [ "SRC-019", "SRC-021" ], "questions": [ { "id": "f-declared-access-roles-q01", "text": "Which roles may access data under this contract, with what access mode, and who approves grants?", "kind": "access", "answer_data": [ "role name", "access mode", "first level approvers", "second level approvers" ] }, { "id": "f-declared-access-roles-q02", "text": "Which properties are readOnly or writeOnly, and what does the owning authority do if a consumer sends or requests them incorrectly?", "kind": "access", "answer_data": [ "readOnly properties", "writeOnly properties", "authority behaviour" ] }, { "id": "f-declared-access-roles-q03", "text": "What is the default access rule when no role matches, and which break-glass exceptions exist?", "kind": "security", "answer_data": [ "default deny or allow", "exception process", "audit requirement" ] }, { "id": "f-declared-access-roles-q04", "text": "What decision record authorises a new consumer role binding to this contract?", "kind": "decision", "answer_data": [ "decision identifier", "approver", "effective time", "scope" ] } ], "data_elements": [ { "id": "f-declared-access-roles-data01", "name": "Role identifier", "description": "Optional stable id for a role entry.", "value_kind": "identifier", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-019" ] }, { "id": "f-declared-access-roles-data02", "name": "Role name", "description": "IAM role name that provides access to the dataset under the contract.", "value_kind": "text", "cardinality": "1", "required": true, "source_refs": [ "SRC-019" ] }, { "id": "f-declared-access-roles-data03", "name": "Access mode", "description": "Type of access provided, for example read or write.", "value_kind": "code", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-019" ] }, { "id": "f-declared-access-roles-data04", "name": "Approvers", "description": "First- and second-level approvers of the role grant.", "value_kind": "object", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-019" ] }, { "id": "f-declared-access-roles-data05", "name": "readOnly and writeOnly", "description": "JSON Schema flags for properties managed only by the owning authority or never returned on read.", "value_kind": "object", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-021" ] } ], "artifacts": [ { "id": "f-declared-access-roles-artifact01", "name": "Contract role binding", "description": "Declared consumer or producer role, access mode and approval path for this contract.", "media_or_form": [ "role binding", "access clause" ], "serial": true, "identity_strategy": "Identify by role.id or contract id plus role name in the governing IAM or contract registry.", "source_refs": [ "SRC-019" ] } ], "inline_only_rationale": null } ] }, { "id": "l-levels-terms-protection", "name": "Service levels, terms and data protection", "description": "Quantified service promises and the protective classification the data carries.", "source_refs": [ "SRC-014", "SRC-004", "SRC-008" ], "findings": [ { "id": "f-service-levels-support", "name": "Service level declarations and support", "description": "The Data Contract Specification defines servicelevels covering availability, latency, freshness and retention; ODCS carries a service-level agreement section plus support and communication channels. DCAT supplies dcterms:accrualPeriodicity for update frequency and dcat:temporalResolution for the finest temporal spacing. Each declared level needs a measurement definition, a measurement point and a named channel for raising a breach - a promise with no measurement definition cannot be breached or honoured.", "source_refs": [ "SRC-014", "SRC-003", "SRC-008" ], "questions": [ { "id": "q-svc-dimensions", "text": "Which service levels are promised - availability, freshness, latency, completeness of delivery, retention?", "kind": "measurement", "answer_data": [ "Service level names", "Target values and units", "Measurement window" ] }, { "id": "q-svc-measurement", "text": "How is each service level measured, at which point, and by whom?", "kind": "measurement", "answer_data": [ "Measurement definition", "Measurement point in the flow", "Measuring party" ] }, { "id": "q-svc-frequency", "text": "At what frequency is data updated, and what is the finest temporal resolution the data supports?", "kind": "temporal", "answer_data": [ "Update frequency value", "Temporal resolution", "Expected delivery window with offset" ] }, { "id": "q-svc-support", "text": "Through which channel is an issue raised, and what response commitment attaches to it?", "kind": "process", "answer_data": [ "Support channel and address", "Channel scope (issues, announcements, questions)", "Response commitment" ] } ], "data_elements": [ { "id": "de-service-level", "name": "serviceLevelDeclaration", "description": "A quantified promise about availability, freshness, latency or retention, with its measurement definition.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-014" ] }, { "id": "de-support-channel", "name": "supportChannel", "description": "Named channel through which issues, questions or announcements are handled, with its scope.", "value_kind": "reference", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-003" ] } ], "artifacts": [ { "id": "af-service-level-declaration", "name": "Service level declaration", "description": "The declared, measurable service commitments attached to a contract version, with measurement definitions.", "media_or_form": [ "contract section", "service level record" ], "serial": false, "identity_strategy": "Contract identifier plus version plus service level name; where the organisation runs a service management system of record, its service level identifier takes precedence.", "source_refs": [ "SRC-014", "SRC-003" ] } ], "inline_only_rationale": null }, { "id": "f-classification-privacy-terms", "name": "Classification, personal data and usage restriction", "description": "ODCS carries a classification attribute on properties (for example confidential, restricted, public), a criticalDataElement flag and an encryptedName; the Data Contract Specification carries classification and an explicit pii boolean at field level. These declarations drive downstream access decisions but are not themselves access control: they are the input a policy engine consumes. Retention statements and jurisdictional restrictions belong here as declarations, with enforcement delegated to the access and records-management siblings.", "source_refs": [ "SRC-004", "SRC-014", "SRC-015" ], "questions": [ { "id": "q-cls-level", "text": "What confidentiality classification applies to each property, and from which controlled vocabulary is it drawn?", "kind": "security", "answer_data": [ "Classification value per property", "Classification vocabulary", "Default classification for unclassified properties" ] }, { "id": "q-cls-personal", "text": "Which properties carry personal or specially protected data, and on what basis was that determination made?", "kind": "privacy", "answer_data": [ "Personal data property list", "Special category flags", "Determination basis and reviewer" ] }, { "id": "q-cls-protection", "text": "What protective measures does the contract require for classified properties - encryption, masking, tokenisation or pseudonym columns?", "kind": "security", "answer_data": [ "Required protective measure per property", "Encrypted or masked property name", "Party responsible for applying it" ] }, { "id": "q-cls-retention", "text": "What retention period and deletion obligation does the contract state for the described data?", "kind": "retention", "answer_data": [ "Retention period", "Deletion trigger and method", "Propagation obligation to downstream copies" ] }, { "id": "q-cls-jurisdiction", "text": "Are there jurisdictional or residency restrictions on where the described data may be stored or processed?", "kind": "access", "answer_data": [ "Permitted jurisdictions", "Residency restriction basis", "Cross-border transfer conditions" ] } ], "data_elements": [ { "id": "de-classification", "name": "propertyClassification", "description": "Confidentiality classification assigned to a property.", "value_kind": "code", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-004" ] }, { "id": "de-personal-data-flag", "name": "personalDataFlag", "description": "Declaration that a property carries personal data, driving privacy handling downstream.", "value_kind": "boolean", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-014" ] }, { "id": "de-retention-statement", "name": "retentionStatement", "description": "Declared retention period and deletion obligation for the described data.", "value_kind": "duration", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-014" ] } ], "artifacts": [ { "id": "af-classification-schedule", "name": "Property classification schedule", "description": "Per-property schedule of classification, personal-data flags, required protection and retention.", "media_or_form": [ "classification schedule", "contract section", "policy input record" ], "serial": false, "identity_strategy": "Contract identifier plus version plus property path; classification values reference the organisation's governed classification vocabulary rather than free text.", "source_refs": [ "SRC-004", "SRC-014" ] } ], "inline_only_rationale": null } ] } ] }, { "id": "binding-provenance-and-interoperability", "name": "Binding, provenance and interoperability", "description": "Where the contract touches real systems, where it came from, and how it maps to other standards.", "rationale": "A contract is only actionable if it binds to a physical location and format, only trustworthy if its own origin is traceable, and only reusable if its relationship to neighbouring standards is stated as an alignment rather than assumed as equivalence.", "source_refs": [ "SRC-004", "SRC-009", "SRC-008", "SRC-015" ], "layers": [ { "id": "l-physical-binding", "name": "Physical binding and distribution", "description": "The servers, formats and media types through which the described data is actually reached.", "source_refs": [ "SRC-004", "SRC-008", "SRC-018" ], "findings": [ { "id": "f-server-serialization-binding", "name": "Server, format and serialization binding", "description": "ODCS carries an infrastructure and servers section and per-object physicalName and physicalType; DCAT expresses reachability through Distribution with dcat:mediaType and dcat:accessService, and DCAT-AP mandates IANA media types for dcat:mediaType and an EU vocabulary for dct:format. Iceberg treats partitioning and sort order as separately evolving physical concerns. The same logical contract may bind to several environments, and environment-specific differences must be visible rather than implied.", "source_refs": [ "SRC-004", "SRC-008", "SRC-015", "SRC-018" ], "questions": [ { "id": "q-bnd-servers", "text": "Which servers or environments does this contract bind to, and what distinguishes them?", "kind": "spatial", "answer_data": [ "Server or environment list", "Environment type (production, staging)", "Connection descriptor per environment" ] }, { "id": "q-bnd-format", "text": "In what serialization format and media type is the data made available for each binding?", "kind": "interoperability", "answer_data": [ "Serialization format", "Media type from a controlled vocabulary", "Compression or container format" ] }, { "id": "q-bnd-physical-name", "text": "What is the physical name of each schema object in each target system?", "kind": "identity", "answer_data": [ "Physical name per environment", "Physical type (table, view, topic, file)", "Naming convention applied" ] }, { "id": "q-bnd-partitioning", "text": "How is the data partitioned or ordered physically, and is that part of the contract or an implementation detail?", "kind": "composition", "answer_data": [ "Partition properties and positions", "Sort order", "Whether partitioning is contractual" ] } ], "data_elements": [ { "id": "de-server-binding", "name": "serverBinding", "description": "Descriptor of one environment where data conforming to the contract is served, with format and connection details.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-004", "SRC-008" ] }, { "id": "de-media-type", "name": "mediaType", "description": "IANA media type of the served distribution.", "value_kind": "code", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-015", "SRC-008" ] } ], "artifacts": [ { "id": "af-binding-descriptor", "name": "Environment binding descriptor", "description": "Per-environment descriptor mapping the logical contract to physical names, formats, media types and partitioning.", "media_or_form": [ "binding descriptor", "server configuration section", "catalogue distribution record" ], "serial": false, "identity_strategy": "Contract identifier plus environment identifier from the infrastructure system of record; catalogue distribution IRI recorded as the governed global identifier where a catalogue is published.", "source_refs": [ "SRC-004", "SRC-008" ] } ], "inline_only_rationale": null } ] }, { "id": "l-provenance-registration", "name": "Provenance and registration", "description": "Where the contract came from and how it is published for discovery.", "source_refs": [ "SRC-009", "SRC-011", "SRC-008" ], "findings": [ { "id": "f-contract-provenance", "name": "Provenance and derivation of the contract artefact", "description": "The contract is itself an entity with provenance. PROV-O supplies the relations: wasGeneratedBy for the activity that produced it, wasAttributedTo for the responsible agent, used for the inputs consumed, wasDerivedFrom for derivation from another artefact and wasRevisionOf for a revision relationship. This matters practically because a schema inferred from sampled data carries a very different warrant than one authored from a governed specification, and consumers deserve to know which they are relying on.", "source_refs": [ "SRC-009", "SRC-013" ], "questions": [ { "id": "q-prv-origin", "text": "Was this contract authored from a specification, inferred from data, or derived from another contract?", "kind": "provenance", "answer_data": [ "Origin classification", "Source artefact reference", "Derivation relation used" ] }, { "id": "q-prv-agent", "text": "Which agent generated this version, and was that agent human, automated or a combination?", "kind": "provenance", "answer_data": [ "Generating agent identity", "Agent type", "Attribution relation" ] }, { "id": "q-prv-inputs", "text": "What inputs were used to produce this version, and are they retained for reproducibility?", "kind": "evidence", "answer_data": [ "Input artefact references", "Retention status of inputs", "Reproduction procedure" ] }, { "id": "q-prv-times", "text": "When was this version generated, and when was that generation recorded in the registry?", "kind": "temporal", "answer_data": [ "Generation timestamp with offset", "Registry record timestamp with offset", "Reason for any divergence" ] } ], "data_elements": [ { "id": "de-generation-activity", "name": "generationActivity", "description": "Activity that produced this contract version, with its agent and inputs.", "value_kind": "object", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-009" ] }, { "id": "de-derivation-source", "name": "derivationSourceReference", "description": "Artefact from which this contract version was derived or of which it is a revision.", "value_kind": "reference", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-009" ] } ], "artifacts": [ { "id": "af-provenance-record", "name": "Contract provenance record", "description": "Structured provenance for one contract version: generating activity, responsible agent, inputs used and derivation links.", "media_or_form": [ "provenance graph", "provenance record", "attached metadata block" ], "serial": true, "identity_strategy": "Contract identifier plus version as the described entity; activity and agent identified by identifiers issued by their own master systems, with UUID fallback assigned by the adopting Dimension.", "source_refs": [ "SRC-009" ] } ], "inline_only_rationale": null }, { "id": "f-registry-publication", "name": "Registry publication and discovery", "description": "A contract that cannot be found is not operative. A schema registry publishes under a subject determined by a subject name strategy and assigns a schema id and version. A catalogue publishes the governed dataset with a conformance link and, under DCAT-AP, a catalogue record whose application profile is declared. The two publication surfaces have different audiences - runtime serialisers versus human and agent discovery - and a contract usually needs both, with an explicit statement of which is authoritative.", "source_refs": [ "SRC-011", "SRC-008", "SRC-015" ], "questions": [ { "id": "q-reg-where", "text": "In which registries or catalogues is this contract published, and which of them is the system of record?", "kind": "authority", "answer_data": [ "Registry and catalogue references", "System of record designation", "Synchronisation direction" ] }, { "id": "q-reg-naming", "text": "Under what subject or record name is the contract published, and which naming strategy produced it?", "kind": "identity", "answer_data": [ "Subject or record name", "Naming strategy identifier", "Collision handling rule" ] }, { "id": "q-reg-discovery", "text": "How does a prospective consumer discover this contract and determine its applicability?", "kind": "access", "answer_data": [ "Discovery interface", "Search or listing metadata", "Applicability criteria published" ] }, { "id": "q-reg-sync", "text": "How is divergence between the registry copy and the catalogue copy detected and resolved?", "kind": "quality", "answer_data": [ "Divergence detection method", "Reconciliation frequency", "Resolution precedence rule" ] } ], "data_elements": [ { "id": "de-registry-subject", "name": "registrySubject", "description": "Subject or record name under which the contract is registered, with the naming strategy that produced it.", "value_kind": "identifier", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-011" ] }, { "id": "de-catalogue-record-ref", "name": "catalogueRecordReference", "description": "Reference to the catalogue record describing the registration of the contract or its governed dataset.", "value_kind": "reference", "cardinality": "0..1", "required": false, "source_refs": [ "SRC-008", "SRC-015" ] } ], "artifacts": [ { "id": "af-registry-entry", "name": "Registry or catalogue entry", "description": "The published entry that makes a contract version discoverable and retrievable by consumers and runtime components.", "media_or_form": [ "registry entry", "catalogue record", "published metadata resource" ], "serial": true, "identity_strategy": "Registry-assigned schema id and version where a schema registry is the master system; otherwise the catalogue record IRI as the governed global identifier.", "source_refs": [ "SRC-011", "SRC-008" ] } ], "inline_only_rationale": null } ] }, { "id": "l-standard-alignment", "name": "Cross-standard alignment", "description": "How this contract maps to other schema languages and jurisdictional profiles, and where those mappings lose information.", "source_refs": [ "SRC-014", "SRC-006", "SRC-015", "SRC-002" ], "findings": [ { "id": "f-standard-alignment-mapping", "name": "Schema language alignment and mapping fidelity", "description": "The same contract is routinely expressed in more than one language: JSON Schema for payload validation, Avro for wire format and evolution, SHACL for graph validation, ODCS for governance. These are alignments, not equivalences. Concrete losses are known: Avro records default-driven resolution that JSON Schema does not model; a JSON Schema format keyword under the format-annotation vocabulary is not an assertion at all; ODCS v3.1.0 added strict JSON Schema validation and relationships that older versions could not express. Claims of conformance to any of these require evidence, not assertion.", "source_refs": [ "SRC-002", "SRC-006", "SRC-007", "SRC-014" ], "questions": [ { "id": "q-aln-languages", "text": "In which schema languages is this contract expressed, and which expression is normative?", "kind": "authority", "answer_data": [ "Language list with versions", "Normative expression designation", "Generation direction between expressions" ] }, { "id": "q-aln-loss", "text": "Which contract facts are lost or weakened when projected into each target language?", "kind": "interoperability", "answer_data": [ "Lost or weakened facts per target", "Compensating mechanism", "Severity of the loss" ] }, { "id": "q-aln-conformance", "text": "What evidence supports any claim that this contract conforms to a named standard?", "kind": "evidence", "answer_data": [ "Conformance claim", "Supporting validation evidence", "Validating tool and version" ] }, { "id": "q-aln-conflict", "text": "Where do two aligned standards make contradictory requirements, and which one wins?", "kind": "exception", "answer_data": [ "Conflicting requirement pair", "Precedence decision", "Deciding authority" ] } ], "data_elements": [ { "id": "de-alignment-declaration", "name": "alignmentDeclaration", "description": "Declared alignment to a named external standard, with its version and the evidence supporting it.", "value_kind": "object", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-008", "SRC-002" ] }, { "id": "de-mapping-loss-note", "name": "mappingLossNote", "description": "Recorded information loss incurred when projecting the contract into a target language or profile.", "value_kind": "text", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-006", "SRC-014" ] } ], "artifacts": [ { "id": "af-alignment-mapping", "name": "Cross-standard alignment mapping", "description": "Mapping from this contract's constructs to each aligned standard, annotated with fidelity and known losses.", "media_or_form": [ "mapping table", "crosswalk document", "transformation definition" ], "serial": false, "identity_strategy": "Contract identifier plus target standard identifier and version; the target standard is identified by its governed URI rather than by an informal name.", "source_refs": [ "SRC-006", "SRC-002", "SRC-014" ] } ], "inline_only_rationale": null }, { "id": "f-profile-jurisdictional-conformance", "name": "Profile and jurisdictional conformance", "description": "DCAT-AP 3.0.0 demonstrates how a jurisdiction narrows a base standard: it designates mandatory classes, marks properties as reused as-is, extended or profile-specific, mandates controlled vocabularies for named properties, and separates provider conformance from receiver conformance. A contract operating in a regulated or public-sector setting may have to satisfy such a profile in addition to its own rules, and profile obligations can differ for the party publishing and the party consuming.", "source_refs": [ "SRC-015", "SRC-008" ], "questions": [ { "id": "q-prf-applicable", "text": "Which jurisdictional or sectoral profiles apply to this contract, and on what legal or policy basis?", "kind": "authority", "answer_data": [ "Applicable profile references with versions", "Basis for applicability", "Territory or sector scope" ] }, { "id": "q-prf-mandatory", "text": "Which profile-mandated properties and controlled vocabularies must the contract populate?", "kind": "requirement", "answer_data": [ "Mandatory property list", "Required controlled vocabulary per property", "Current population status" ] }, { "id": "q-prf-role", "text": "Do profile obligations differ between the publishing party and the receiving party, and how?", "kind": "classification", "answer_data": [ "Provider obligations", "Receiver obligations", "Party role assignment" ] }, { "id": "q-prf-evidence", "text": "How is profile conformance demonstrated and re-verified after a contract change?", "kind": "validation", "answer_data": [ "Conformance test procedure", "Re-verification trigger", "Evidence artefact reference" ] } ], "data_elements": [ { "id": "de-profile-reference", "name": "applicableProfileReference", "description": "Reference to a jurisdictional or sectoral application profile the contract must satisfy, with version.", "value_kind": "reference", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-015" ] }, { "id": "de-profile-conformance-status", "name": "profileConformanceStatus", "description": "Current verified conformance status against an applicable profile.", "value_kind": "code", "cardinality": "0..n", "required": false, "source_refs": [ "SRC-015", "SRC-008" ] } ], "artifacts": [ { "id": "af-profile-conformance-evidence", "name": "Profile conformance evidence", "description": "Evidence of testing the contract or its catalogue projection against an applicable profile, retained per contract version.", "media_or_form": [ "conformance test report", "validation report", "attestation record" ], "serial": true, "identity_strategy": "Profile identifier and version plus contract identifier and version plus test run identifier issued by the testing system as an opaque UUID or ULID.", "source_refs": [ "SRC-015", "SRC-007" ] } ], "inline_only_rationale": null } ] } ] } ] }, "functions": [ { "id": "fn-author-contract-version", "name": "Author or amend a contract version", "description": "Create a new contract version by declaring identity, governed subject, structure, semantics, constraints, quality rules, parties and terms, without modifying any already published version.", "inputs": [ "Governed subject reference", "Structural definition", "Semantic bindings", "Owner and approver references" ], "outputs": [ "Draft contract version", "Draft structural schema definition" ], "preconditions": [ "Governed subject exists and is identifiable", "An accountable owner is named", "Versioning scheme is declared" ], "effects": [ "A draft version exists in status draft", "No previously published version is altered" ], "source_refs": [ "SRC-003", "SRC-017", "SRC-004" ] }, { "id": "fn-validate-instance", "name": "Validate data against a contract version", "description": "Evaluate a data instance or dataset against the executable constraints of a named contract version and emit a structured validation report distinguishing errors from annotations.", "inputs": [ "Contract version reference", "Data instance or dataset reference", "Requested output format" ], "outputs": [ "Validation report with conformance result", "Per-violation locations" ], "preconditions": [ "Contract version is retrievable", "Validator implements the declared dialect and vocabularies", "Data is readable by the validator" ], "effects": [ "A validation report artefact is produced and retained", "Non-conformance is signalled to the declared support channel when severity requires it" ], "source_refs": [ "SRC-001", "SRC-007", "SRC-002" ] }, { "id": "fn-check-compatibility", "name": "Check compatibility of a candidate version", "description": "Evaluate a candidate contract version against the declared compatibility mode and the relevant prior versions, and classify the change as compatible or breaking.", "inputs": [ "Candidate version", "Declared compatibility mode", "Prior version set" ], "outputs": [ "Compatibility check record", "Breaking-change classification" ], "preconditions": [ "A compatibility mode is declared for the subject", "Prior versions are retrievable", "Candidate parses under the declared dialect" ], "effects": [ "Candidate is gated from publication if it fails", "Required upgrade order is determined from the mode" ], "source_refs": [ "SRC-011", "SRC-012", "SRC-006" ] }, { "id": "fn-publish-version", "name": "Publish a contract version", "description": "Register an approved version to the system of record and, where applicable, project it to the catalogue, assigning identifiers and making the version immutable.", "inputs": [ "Approved contract version", "Registry or catalogue target", "Approval decision reference" ], "outputs": [ "Registry or catalogue entry", "Assigned version identifiers and fingerprint" ], "preconditions": [ "Compatibility check passed or a recorded exception applies", "Approval by the authorised role is recorded", "Notice period requirements are satisfied" ], "effects": [ "Version becomes immutable and discoverable", "Status transitions to an in-force value and the transition is logged" ], "source_refs": [ "SRC-011", "SRC-008", "SRC-017" ] }, { "id": "fn-evaluate-quality-rules", "name": "Evaluate declared quality rules", "description": "Execute the declared quality rules of a contract version on schedule and record measured values against thresholds, with severity-driven consequences.", "inputs": [ "Quality rule set", "Target data slice", "Schedule trigger" ], "outputs": [ "Measured metric values", "Pass or fail per rule with severity" ], "preconditions": [ "Rules are of an executable type", "Metric engine supports the named metric", "Target data slice is resolvable" ], "effects": [ "Measurements are recorded as observations distinct from the contract", "Failures escalate according to severity and business impact" ], "source_refs": [ "SRC-005", "SRC-013" ] }, { "id": "fn-manage-consumer-registration", "name": "Register or deregister a consumer", "description": "Bind a named consumer to a contract version with a role and effective period, or release that binding, so that impact assessment and notification lists stay accurate.", "inputs": [ "Consumer party reference", "Contract version reference", "Role and requested effective period" ], "outputs": [ "Consumer registration record", "Updated notification list" ], "preconditions": [ "Consumer party is identifiable in the party master system", "Contract version is in force", "Role is defined for the contract" ], "effects": [ "Consumer appears in or disappears from impact assessments", "Acceptance obligations attach or lapse accordingly" ], "source_refs": [ "SRC-003", "SRC-014" ] }, { "id": "fn-deprecate-and-sunset", "name": "Deprecate and sunset a version", "description": "Move a version to deprecated, publish a sunset instant and successor reference, notify registered consumers, and later retire the version.", "inputs": [ "Version to deprecate", "Successor version reference", "Proposed sunset instant" ], "outputs": [ "Deprecation and sunset notice", "Status transition log entries" ], "preconditions": [ "A successor exists or an explicit no-successor decision is recorded", "Notice period satisfied", "Registered consumer list is current" ], "effects": [ "Consumers are notified through the declared channel", "Support obligations end at the sunset instant" ], "source_refs": [ "SRC-014", "SRC-015", "SRC-003" ] }, { "id": "fn-project-to-target-language", "name": "Project a contract to a target language or profile", "description": "Generate an expression of the contract in a target schema language or jurisdictional profile, recording the fidelity of the projection and any information lost.", "inputs": [ "Normative contract expression", "Target language or profile identifier and version" ], "outputs": [ "Target-language expression", "Mapping loss notes" ], "preconditions": [ "Normative expression is designated", "A mapping definition exists for the target", "Target version is pinned" ], "effects": [ "A derived expression exists with a recorded derivation link", "Known losses are documented rather than silently dropped" ], "source_refs": [ "SRC-006", "SRC-002", "SRC-015", "SRC-009" ] }, { "id": "fn-record-exception", "name": "Record a contract exception or waiver", "description": "Record a time-bounded, approved departure from a contract requirement, compatibility rule or profile obligation, with its scope, justification and expiry.", "inputs": [ "Requirement being waived", "Justification and compensating control", "Requested expiry" ], "outputs": [ "Exception record with expiry", "Updated conformance status" ], "preconditions": [ "Approver holds authority for the requirement's severity", "Affected consumers are identified", "An expiry is set" ], "effects": [ "Validation gating is relaxed only for the recorded scope and period", "Exception expiry restores the original requirement automatically" ], "source_refs": [ "SRC-003", "SRC-011", "SRC-015" ] }, { "id": "fn-resolve-references", "name": "Resolve references and compose subschemas", "description": "Dereference $ref, named types and shape links, applying applicators to produce the effective schema for a location.", "inputs": [ "root schema", "reference base URI", "optional instance for dynamic references" ], "outputs": [ "effective schema", "unresolved reference list" ], "preconditions": [ "$id and base URI are known", "cyclic references are detectable" ], "effects": [ "evaluation uses the resolved resource set", "unresolved required references cause failure" ], "source_refs": [ "SRC-020", "SRC-007", "SRC-006" ] }, { "id": "fn-canonicalize-and-fingerprint", "name": "Canonicalize and fingerprint", "description": "Normalise a schema to Parsing Canonical Form or an agreed JSON canonicalisation and compute a fingerprint.", "inputs": [ "schema document", "canonicalisation profile" ], "outputs": [ "canonical form", "fingerprint" ], "preconditions": [ "schema is valid for the language" ], "effects": [ "canonical bytes become the comparison basis", "fingerprint may tag serialised data" ], "source_refs": [ "SRC-006" ] } ], "composition": [ { "target": "WM-DAT-001 Dataset", "relation": "REFERENCE", "purpose": "A dataset declares conformance to one or more schemas or data contracts; the contract references the governed dataset without absorbing its catalogue description. DCAT models this as dcterms:conformsTo on the resource.", "required": true, "source_refs": [ "SRC-008", "SRC-003" ] }, { "target": "Data quality assessment and observation model", "relation": "REFERENCE", "purpose": "This model declares quality rules, dimensions and thresholds; the observation model holds measured results, their time series and their run context. The link carries the rule identifier so measurements can be attributed to the declaration that produced them.", "required": false, "source_refs": [ "SRC-005", "SRC-013" ] }, { "target": "Data lineage model (run, job and dataset events)", "relation": "REFERENCE", "purpose": "Lineage emits schema, version and data quality facets on dataset events at run time. The contract is the design-time expectation those facets are compared against; the link enables drift detection between declared and observed schema.", "required": false, "source_refs": [ "SRC-013" ] }, { "target": "API and interface contract model (OpenAPI, AsyncAPI)", "relation": "ALIGN", "purpose": "Interface contracts reference payload schemas defined here rather than redefining them, aligning on the schema resource identity so a payload has one definition across transport and storage.", "required": false, "source_refs": [ "SRC-001", "SRC-011" ] }, { "target": "Business glossary and ontology model", "relation": "REFERENCE", "purpose": "Properties bind to governed business terms through authoritative definitions; the glossary owns the term and its definition history, the contract owns only the binding and any recorded divergence.", "required": false, "source_refs": [ "SRC-004", "SRC-016" ] }, { "target": "Reference data and code list model", "relation": "REFERENCE", "purpose": "Enumerated value domains are versioned code lists administered elsewhere. The contract pins a code list version rather than inlining values, which is what jurisdictional profiles require through mandatory controlled vocabularies.", "required": false, "source_refs": [ "SRC-015", "SRC-016" ] }, { "target": "Party, organisation and role model", "relation": "REFERENCE", "purpose": "Owners, stewards, approvers, producers and registered consumers are parties with identifiers issued by an identity master system; the contract stores references, never duplicated party attributes.", "required": true, "source_refs": [ "SRC-003", "SRC-009" ] }, { "target": "Access policy and entitlement model", "relation": "REFERENCE", "purpose": "Classification and personal-data flags declared here are inputs to policy decisions made and enforced by the access model. The boundary keeps declaration separate from enforcement so a contract change cannot silently grant access.", "required": false, "source_refs": [ "SRC-004", "SRC-014" ] }, { "target": "Data product model", "relation": "COMPOSE", "purpose": "Where a data product model exists, pricing, support channels, team and commercial terms compose into the product and are referenced by the contract rather than duplicated, resolving the packaging overlap ODCS creates.", "required": false, "source_refs": [ "SRC-003", "SRC-014" ] }, { "target": "Physical storage and table format model", "relation": "REFERENCE", "purpose": "Table format specifications version schema, partition specification and sort order independently. The contract references the physical binding and states which physical aspects are contractual and which are implementation detail.", "required": false, "source_refs": [ "SRC-018", "SRC-004" ] }, { "target": "Metadata registry model (ISO/IEC 11179 family)", "relation": "ALIGN", "purpose": "Where an organisation operates a metadata registry, contract properties align to administered items with a registration authority and registration status; the alignment is asserted, not a conformance claim, since clause-level text was not verified.", "required": false, "source_refs": [ "SRC-016", "SRC-004" ] }, { "target": "Change control and approval workflow model", "relation": "EXTEND", "purpose": "Contract change proposals, impact assessments and approval decisions extend the organisation's general change control process with contract-specific gates such as the compatibility check and the notice period.", "required": false, "source_refs": [ "SRC-017", "SRC-011" ] } ], "serviceLayers": { "dimension": { "owner_package_requirements": [ "The adopting Dimension must name a single accountable owner for the contract package - the registry designates a data product owner or data steward - and record that ownership as a reference to a party identifier, not a personal name.", "The Dimension must declare which system is the master for contract identity (contract registry, schema registry or catalogue) before any contract is published, because identity priority cannot be resolved retrospectively.", "The Dimension must declare a default compatibility mode and the authority permitted to override it per subject, since the mode determines deployment order for every consumer.", "The Dimension must publish its controlled vocabularies for status, classification and quality dimension, or explicitly adopt the ODCS and profile vocabularies by reference." ], "namespace_guidance": "Contract identifiers are namespaced by the owning Dimension and, where present, by domain and tenant, matching the ODCS domain, dataProduct and tenant scoping. Governed global identifiers use a Dimension-controlled HTTPS base IRI whose path encodes model, contract identifier and version; the IRI must be normalized and must not encode a publication date. Registry subjects follow one declared subject name strategy per registry and never mix strategies within a subject namespace.", "registry_links": [ "vr.wm-dat-004 is the registry entry for this model; WM-DAT-001 is the parent dataset model and the source of the REFERENCE relation stating that a dataset conforms to schemas or data contracts.", "Contract versions link outward to the schema registry subject and schema id where a registry is the master system, and to the catalogue record IRI where a catalogue is published.", "Aligned external registries recorded as alignments only: JSON Schema meta-schema URIs, IANA media types, the ODCS specification identifier and any applicable jurisdictional profile identifier with its version." ] }, "canon_and_patch": { "canonicalization_rules": [ "Canonical form is the semantic content of the contract, independent of serialization: property ordering is not significant unless the contract explicitly declares ordering to be contractual, and formatting, comments and whitespace are excluded from canonical comparison.", "Where a schema language defines its own canonical form - for example a parsing canonical form used for fingerprinting - that form governs fingerprint computation for that language, and the fingerprint algorithm must be recorded alongside the value.", "All identifiers are compared after URI normalization; all time values are compared after normalizing to a common instant while retaining the originally recorded offset." ], "patch_rules": [ "A published version is never patched in place. A correction is a new version, and the defective version transitions to deprecated or retired with a reason recorded in the status transition log.", "A patch expressed as a change proposal must state, per changed element, whether the change is an addition, removal, widening, narrowing or rename, because compatibility classification depends on that distinction rather than on textual diff.", "Renames must be expressed through the declared rename mechanism - alias or stable property identifier - and never as a paired remove-and-add, which destroys the resolution path for existing data.", "Every patch carries the compatibility check outcome that gated it, or a recorded exception with an expiry." ], "compatibility_rules": [ "The declared compatibility mode governs which patches are admissible and determines whether consumers or producers upgrade first; the mode must be recorded on the version, not assumed from a global default at read time.", "Transitive modes are checked against all prior versions in scope, not only the immediate predecessor; the checked version range is recorded on the check outcome.", "A change that removes a required property, narrows a type outside the permitted promotion set, or changes the meaning of an existing property without renaming it is breaking regardless of what a syntactic checker reports, and requires a major version increment.", "Adding a property that is required on read without a default is breaking even when a syntactic diff shows only an addition." ] }, "artifact_rules": { "identity_priority": [ "Authoritative master-system identifier issued by the governing system of record for contracts - for example the ODCS contract id held by the contract registry, or the schema registry subject together with its assigned schema id and version.", "Governed global identifier or IRI where no master-system identifier exists - for example the schema resource canonical URI established by $id, or the catalogue record IRI published under the applicable profile.", "UUID or ULID assigned by the adopting Dimension as a last resort, recorded as Dimension-assigned so that it can be superseded when a master-system identifier becomes available.", "A version designation, a fingerprint or a date is never an identifier on its own: a version qualifies an identifier, a fingerprint proves content equality, and a date is an attribute." ], "timestamp_rule": "All time values are recorded as RFC 3339 date-time values that include seconds and an explicit numeric offset or the literal Z; the value -00:00 is reserved for an unknown local offset and must not be used as a synonym for UTC. Event time and observation or ingestion time are recorded separately whenever they can differ: the effective instant of a status change, a version's generation instant and a sunset instant are event times, while the registry publication receipt instant, the validation run instant and the quality measurement instant are observation or ingestion times. Both are stored; neither is derived from the other, and no timestamp is used as an identifier.", "serial_naming_rule": "Serial artefacts - version series, status transition entries, validation reports, compatibility check records, change records, deprecation notices, registry entries and conformance evidence - are named by the identifier of the entity they describe plus a monotonically increasing sequence number or opaque run identifier issued by the producing system of record. Sequence values are never reused after deletion, never encode a date, and never carry semantic meaning beyond ordering; where ordering across systems is required, the recorded event timestamp with offset provides the tiebreak, not the sequence number.", "integrity_rule": "Every published contract version carries a content digest computed over the canonical form of its normative expression, with the algorithm recorded beside the value. Retrieval verifies the digest before the version is used for validation or code generation. Derived expressions record a derivation link to the normative expression and its digest, so that a divergence between a projection and its source is detectable rather than inferred. Serial evidence artefacts are append-only: a superseded report is retained and marked superseded rather than replaced." }, "policies": [ "Declaration is separated from enforcement and from measurement. This model holds what must be true and what is promised; access enforcement belongs to the access model and measured outcomes belong to the observation model. Any function that appears to enforce or measure within this model in fact produces evidence referencing an external actor.", "No conformance to an external standard is asserted without retained evidence naming the validating tool and its version. Alignments are recorded as alignments, and conflicts between aligned standards are recorded with an explicit precedence decision and deciding authority.", "Published versions are immutable and evidence artefacts are append-only. Corrections create new versions; superseded artefacts are marked, never overwritten.", "Every exception or waiver is time-bounded and carries an expiry; on expiry the original requirement resumes without further action. An exception with no expiry is invalid.", "A contract may not be published without an accountable owner, a declared compatibility mode and a resolvable governed-subject reference.", "No contract may move to active status without a master-system or Dimension identifier, a declared dialect, an owner, and a documented purpose or limitations statement.", "Publishing a new version MUST run compatibility checks against the policy in force; failures block publish unless an exception with approver and expiry is recorded.", "Quality rules and SLA retention clauses are part of the agreement; deleting a retired version before the contracted retention period is a policy breach.", "Classification and encryptedName on elements constrain who may read instance values even when the schema document itself is widely readable." ], "crud": { "read": [ "Any authenticated agent may read a contract version's structure, semantics, constraints, quality declarations and service levels in order to produce conforming data or to consume it.", "Reading a specific version requires resolving contract identifier plus version; resolving without a version returns the current in-force version and must state which version was resolved.", "Reading validation reports and quality measurements requires the finding-level scope granted for evidence, since reports can disclose data values in violation messages.", "Reads never mutate status; a read that triggers a resolution or a fetch is logged as an access event, not as a change." ], "create": [ "Creation produces a draft version only; publication is a separate governed function requiring approval and a passed compatibility check or a recorded exception.", "A new contract requires an accountable owner reference, a governed-subject reference and a declared versioning scheme before it can enter draft.", "Creating a derived expression in another schema language requires a mapping definition and records a derivation link plus any known information loss." ], "update": [ "Draft versions may be updated freely by the owner and delegates; published versions may not be updated at all.", "Updating status is permitted only along declared transitions, by the role holding authority for that transition, and always writes a status transition log entry with actor, reason, event time and record time.", "Updating the compatibility mode is a governed change requiring the same approval as a breaking change, because it alters the safety guarantees consumers rely on.", "Updating the registered consumer list is permitted to the contract owner and to the consumer party for its own registration." ], "delete": [ "Published contract versions are never deleted; they are deprecated then retired, retaining full retrievability for as long as data produced under them remains readable.", "Draft versions may be deleted by their owner before publication, with the deletion recorded in the change log.", "Evidence artefacts - validation reports, compatibility checks, conformance evidence - are deleted only on expiry of their stated retention period, never on request from the party they evaluate, and never while a legal hold applies.", "Deletion of personal data described by a contract is executed by the data owner in the dataset and records-management models; this model records only the declared retention and deletion obligation and the propagation requirement to downstream copies." ] }, "roles": [ { "name": "Contract owner (data product owner or data steward)", "responsibilities": [ "Hold accountability for the correctness, currency and completeness of the contract", "Approve or reject change proposals within delegated authority and escalate breaking changes", "Maintain the registered consumer list and initiate deprecation with a successor and sunset instant" ] }, { "name": "Producer engineer", "responsibilities": [ "Implement the physical binding so that produced data satisfies the declared structure, constraints and service levels", "Run compatibility checks before proposing a new version and honour the upgrade order the mode dictates", "Raise an exception request rather than shipping a silent departure from a declared requirement" ] }, { "name": "Consumer representative", "responsibilities": [ "Register consumption against a specific contract version and accept its terms", "Assess and respond to change notices within the stated notice period", "Report observed non-conformance through the declared support channel with the validation evidence attached" ] }, { "name": "Governance and conformance reviewer", "responsibilities": [ "Verify semantic bindings against governed terms and value domains, and challenge undeclared divergence", "Verify that applicable jurisdictional or sectoral profile obligations are satisfied and re-verified after change", "Review exceptions for expiry, compensating control and cumulative risk" ] }, { "name": "Registry operator", "responsibilities": [ "Operate the system of record for contract identity, assign identifiers and enforce version immutability", "Enforce the declared compatibility mode at publication and retain the check outcome as evidence", "Maintain synchronisation and detect divergence between registry and catalogue projections" ] } ], "access": { "default_rule": "Contract structure, semantics, constraints, service levels and status are readable by any authenticated agent within the adopting Dimension, because a contract that cannot be read cannot be complied with. Write access is restricted to the contract owner and delegates, and publication is restricted to the registry operator acting on a recorded approval.", "scopes": [ "bundle", "layer", "finding", "artifact" ], "exceptions": [ "Findings covering classification, personal data and protective measures may be restricted to governance and security roles where the classification schedule itself reveals sensitive structure, such as which properties hold special-category data.", "Validation reports and quality measurement artefacts may be restricted at artefact scope because violation messages can echo actual data values.", "Server and connection binding descriptors are restricted at artefact scope; connection secrets are never held in this model at all and must be referenced indirectly.", "Exception and waiver records are readable by affected consumers even where the underlying finding is restricted, because a waiver changes the guarantees those consumers rely on.", "Pre-publication draft versions may be restricted to the owning team to avoid consumers building against an unapproved shape.", "Break-glass read of a restricted contract for incident response, with dual approval and time-boxed grant", "Compatibility override that publishes an incompatible version with recorded decision and consumer notice" ], "audit_requirements": [ "Every status transition, publication, deprecation and exception grant is logged with actor identity, reason, event time and record time, both with explicit offsets.", "Every access to a restricted finding or artefact is logged with the requesting agent, the scope invoked and the justification where the scope requires one.", "Compatibility check outcomes and validation reports are retained as immutable evidence for at least the support period of the version they gated, and are retrievable during audit without reconstruction.", "Divergence between the registry copy and any catalogue or derived projection is logged when detected, together with the reconciliation action taken.", "Log register, publish, status change, compatibility override, validation run and role grant with actor, event time and target identifier", "Retain audit records at least as long as the contract retention SLA" ] }, "agents_bootstrap": { "filename": "AGENTS.md", "required_fields": [ "Name", "Type", "Specification URL", "Storage type URL", "Interface URL", "Processes URL", "Registry ID", "Model ID", "Owner", "Version" ], "read_order": [ "Read AGENTS.md first and resolve Name, Type, Registry ID and Model ID to confirm which model and which adopting Dimension are in scope.", "Follow Specification URL to obtain the normative model definition, including scope, boundaries and the bundle, layer and finding structure.", "Follow Storage type URL to learn how the model is projected into the concrete store in use, whether that is a Git tree, a document collection, an MCP resource surface or a relational schema; treat this as projection detail, never as semantics.", "Follow Interface URL to learn the available read and write operations, their authentication and their scope granularity.", "Follow Processes URL to learn the governed processes - change proposal and approval, compatibility check, publication, deprecation, exception handling - before attempting any write.", "Only then read individual contract instances, resolving contract identifier plus version explicitly rather than relying on an implicit current version." ] } }, "coverage": { "claim": "The merged model covers the decision and operating surface of a governed data schema / data contract as evidenced by JSON Schema 2020-12 (core + validation), Apache Avro 1.12.0, SHACL 2017 Recommendation, ODCS v3.1.0, OpenAPI 3.1.1 Schema Object, W3C DCAT 3 with DCAT-AP 3.0.0 and PROV-O, RFC 3339, SemVer 2.0.0, Apache Iceberg evolution, OpenLineage and registry compatibility practice, extended with four Grok-sourced mechanism findings (dialect and vocabulary declaration, reference resolution and shape targeting, declared access roles, canonical form and fingerprints). This is not a universal theory of schema languages: geospatial encoding and data residency, the Protobuf/Thrift/Parquet/Arrow/XSD/GraphQL type and evolution families, streaming subject and tombstone semantics, and ISO/IEC 11179 clause-level structure remain outside the fetched evidence and are declared gaps rather than covered ground. No conformance to any cited standard is claimed.", "confidence": "medium", "checklist": [ { "dimension": "identity", "status": "covered", "notes": "Four competing identity mechanisms are distinguished and prioritised: master-system contract id, governed canonical URI or IRI, registry subject plus schema id, and content fingerprint. Fingerprints and versions are explicitly excluded as standalone identifiers." }, { "dimension": "lifecycle", "status": "covered", "notes": "Status is required by ODCS; permitted values, transitions, transition authority, effective instants, deprecation, sunset and retirement are separately modelled, with legacy data treatment after retirement addressed." }, { "dimension": "relationships", "status": "covered", "notes": "Covers keys, uniqueness and ODCS v3.1.0 relationships including composite and nested references, plus contract-to-dataset conformance links, consumer registrations and twelve composition links to sibling models." }, { "dimension": "temporal", "status": "covered", "notes": "RFC 3339 with mandatory seconds and explicit offset is applied throughout; event time is separated from observation and ingestion time; sunset, notice period, update frequency and temporal resolution are all represented." }, { "dimension": "provenance", "status": "covered", "notes": "PROV-O relations distinguish authored from inferred from derived contracts, with generating activity, responsible agent, inputs used and revision links, plus derivation links on projections to other schema languages." }, { "dimension": "ownership", "status": "covered", "notes": "Accountable owner, steward, approval authority, delegation and vacancy fallback are modelled as references to a party master system rather than as embedded names." }, { "dimension": "validation", "status": "covered", "notes": "Constraint enforcement class (assertion, annotation, documentation only) is made explicit, following the JSON Schema format-annotation versus format-assertion split, and validation outcomes use SHACL report and JSON Schema output-format semantics." }, { "dimension": "access", "status": "covered", "notes": "Default read-open, write-restricted rule with scoped exceptions for classification schedules, validation reports that may echo data values, and binding descriptors; connection secrets are excluded from the model entirely." }, { "dimension": "retention and deletion", "status": "covered", "notes": "Retention is addressed at three levels: the declared retention obligation for described data, retention of evidence artefacts, and the rule that published versions are never deleted. Execution of data deletion is explicitly delegated to the dataset and records-management models." }, { "dimension": "interoperability", "status": "covered", "notes": "Cross-language alignment with recorded fidelity loss, jurisdictional profile conformance with provider and receiver obligations distinguished, and an explicit conflict-precedence question." }, { "dimension": "compatibility and evolution", "status": "covered", "notes": "Seven compatibility modes, transitive checking depth, deployment upgrade order, Avro schema resolution with defaults, aliases and type promotion, and Iceberg stable column identifiers are all represented as distinct mechanisms." }, { "dimension": "semantics and vocabulary binding", "status": "covered", "notes": "Authoritative definitions, value domains and code list version pinning are covered, with ISO/IEC 11179 registration constructs cited as an alignment only, since the standard text is paywalled." }, { "dimension": "measurement and quality", "status": "covered", "notes": "ODCS rule types, seven dimensions, eight comparison operators, units, severity, business impact and schedule are covered as declarations; measured results are deliberately assigned to the observation sibling." }, { "dimension": "authority and approval", "status": "covered", "notes": "Approval authority by change severity, delegation, quorum, notice period, exception granting and expiry are all modelled as governed decisions with recorded evidence." }, { "dimension": "spatial and data residency", "status": "gap", "notes": "Server binding captures environment and location loosely, but no consulted primary source defines a normative residency constraint expression for data contracts. Residency is asked about but must be resolved by a jurisdiction or hosting sibling model; treating the current coverage as sufficient would be an overclaim." } ], "known_omissions": [ "ISO/IEC 11179-3 and any ISO data quality standard were verified only at catalogue-record level because the full texts are paywalled. No clause-level conformance claim is made and any structure resting solely on ISO citation should be treated as an alignment hypothesis.", "Protocol Buffers evolution rules (reserved field numbers, the semantics of removing a field number) were not fetched from a primary source in this pass, so the compatibility layer is grounded in Avro and registry practice rather than in all three common wire formats.", "Streaming-specific concerns such as key schema versus value schema, tombstone records and per-partition ordering guarantees are only partially represented through the registry subject concept.", "Machine-learning feature contracts, embedding dimensionality and model input schemas are not separately addressed; they are plausible extensions but no primary source consulted here treats them as data-contract constructs.", "Cost, pricing and chargeback sections present in ODCS are deliberately pushed to a data product sibling and are therefore not elaborated here.", "Semantic drift detection - the case where structure is unchanged but meaning has shifted - is asked about under semantic divergence but has no primary-source mechanism behind it.", "W3C XML Schema, RELAX NG, Protocol Buffers, Apache Thrift, GraphQL SDL, LinkML, FHIR StructureDefinition, Parquet and Arrow type systems were not fetched as primary sources and are not modelled as canonical.", "SHACL 1.2 Core is a Working Draft as of 2026 and is not treated as replacing the 2017 Recommendation.", "ODCS team, infrastructure, pricing and support-channel sections were not independently fetched; team rosters and servers remain out of scope or gaps.", "ODCS v3.2 and AI-oriented contract features are in progress and lack a frozen primary specification.", "Multi-party negotiation, cryptographic signing of contracts, and schema-registry product APIs (for example Confluent subject compatibility names) lack primary support here.", "Geometry, CRS and raster schemas are omitted beyond noting the gap." ], "conflicts": [ "The Data Contract Specification v1.2.1 is deprecated in favour of ODCS v3.1.0 with support stated only through end of 2026, yet both are in active production use with incompatible top-level structures. Deployments must state which is normative rather than treating them as interchangeable.", "ODCS bundles pricing, support, team and service levels into the contract, while the Data Contract Specification separates terms from servicelevels and DCAT keeps commercial concerns outside the vocabulary entirely. The packaging boundary is genuinely unsettled and this model resolves it by composition rather than by asserting one is correct.", "JSON Schema treats format as an annotation by default under the format-annotation vocabulary, whereas most practitioners assume a declared format is validated. A contract that declares formats without declaring the format-assertion vocabulary is weaker than it appears.", "Avro resolves fields by name with alias support, while Iceberg resolves columns by stable identifier. A contract projected across both cannot assume a single rename semantics, and the loss must be recorded rather than smoothed over.", "Registry compatibility modes are syntactic. A change can pass a BACKWARD check and still break consumers semantically - for example redefining the meaning of an existing code value - so syntactic pass is necessary but not sufficient evidence of non-breaking change.", "ODCS marks name as optional while requiring id, which is defensible for machines but conflicts with catalogue profiles such as DCAT-AP that require a title for a published resource.", "JSON Schema is an open-world constraint system (keywords add restrictions; missing keywords do not fail; type is not implied). Avro is a closed data-definition language with required fields at write time and positional binary encoding. Treating them as the same evolution model is incorrect.", "ODCS and OpenAPI companion JSON Schemas are explicitly non-authoritative if they disagree with the standard text.", "JSON Schema $id is a URI that need not be dereferenceable; ODCS id is a UUID-like unique key; Avro identity is a fullname. These are alignments, not one identifier system.", "JSON Schema format is annotation by default; requiring the format-assertion vocabulary changes interoperability.", "The prior Data Contract Specification is deprecated in favour of ODCS 3.1; do not claim dual-standard conformance.", "OpenAPI 3.0 nullable versus 3.1 type arrays is a dialect break inside the Schema Object family.", "SHACL closed shapes and JSON Schema additionalProperties/unevaluatedProperties implement similar intent with different defaults and path semantics." ], "regional_assumptions": [ "DCAT-AP 3.0.0 obligations, including its mandatory controlled vocabularies and the provider versus receiver conformance split, apply to European public-sector data portals and are not assumed to bind elsewhere.", "No specific data protection regime is assumed. The model carries classification, personal-data flags, retention statements and residency questions as declarations; which regime supplies the legal basis is a Dimension-level configuration, not a property of this model.", "Sector-specific schema regimes - clinical, financial reporting, geospatial - were not consulted and may impose mandatory elements this model treats as optional.", "The compatibility vocabulary is grounded in one widely deployed registry implementation. Other registries use different mode names and defaults, so the mode value must always be read from the version rather than assumed.", "RFC 3339 / ISO 8601 timestamps with explicit offsets are the interchange profile; ODCS examples include named timezones such as Australia/Sydney which must be reduced to offset at the event boundary.", "Classification values (public, restricted, confidential) and IAM role names are organisation-specific code lists, not a global taxonomy.", "SQL quality rules are dialect-specific to the target engine; no translation service is provided by ODCS.", "Retention SLAs may be driven by regional law (for example GDPR storage limitation) but this model records the contracted period, not the legal instrument.", "ECMA-262 regular-expression interoperability limits apply to JSON Schema and ODCS pattern fields." ], "adversarial_checks": [ "Counterexample sought for treating schema and data contract as one model: a bare Avro schema in a registry has no owner, terms or service levels, yet is operationally binding. The model handles this by making agreement-layer findings optional in content while keeping identity, structure and compatibility mandatory - so the narrow case is a valid instance, not a violation.", "Attempted overreach rejected: an early structure included quality measurement results and column-level lineage as findings. Both were removed because OpenLineage places them on run events as observations, and holding them here would have made the contract mutable on every pipeline execution.", "Tested whether version could serve as identity. It cannot: Semantic Versioning constrains ordering and immutability but two contracts can share a version string, and a fingerprint proves content equality without naming the thing. This is why identity priority names the master-system identifier first and excludes dates and fingerprints.", "Tested the claim that compatibility checking is sufficient for safe change. It is not: syntactic modes cannot detect a redefinition of an existing property's meaning, so a semantic-divergence question and a mandatory impact assessment against registered consumers were added rather than relying on the automated gate.", "Tested whether the model duplicates the parent dataset model. The overlap is exactly one link - conformance - and catalogue discovery metadata was deliberately excluded, so the boundary holds. The riskier overlap is with a data product model over pricing and support, which is recorded as an unresolved packaging conflict rather than silently resolved.", "Checked for a finding with no artefact and no honest reason. Three findings are inline-only - governed subject binding, encoding conventions and cross-field constraints - and in each case the rationale is that materialising a separate artefact would split one logical definition across two stores and create drift with no retrieval benefit.", "Would a date or filename be accepted as the contract identifier? Rejected: identity priority forbids dates as identifiers and prefers master-system keys.", "Could an agent claim Avro backward compatibility while publishing a JSON Schema that lifts a constraint? Flagged as a recorded conflict, not allowed as silent equivalence.", "Could YAML versus JSON serialisation be treated as a semantic change? Rejected: storage format is a projection.", "Could companion JSON Schema bugs override ODCS or OpenAPI text? Rejected: the standard text takes precedence.", "Could SHACL 1.2 WD features be required as if they were 2017 Rec? Marked as an omission; processors must declare the Rec profile.", "Could quality rowCount of a particular load be stored as schema structure? Rejected: promised rules live here, observed dataset measures live in WM-DAT-001." ] }, "researchAdjudication": { "providerMode": "dual-provider", "activeProviders": [ "claude", "grok" ], "waivedProviders": [], "providerPolicy": {}, "boundaryDecision": { "entry_kind": "entity", "status": "accepted", "rationale": "Both providers independently landed on entity, and the artefact behaves as one: it carries its own identity, version designation, status, accountable owner and lifecycle independently of any execution or observation, and it persists across the runs that reference it. The harder boundary question - whether a bare registry schema and a full producer-consumer contract are one model or two - is resolved as one model with optional agreement content, which is exactly the resolution Claude reached under adversarial test (a bare Avro schema in a registry has no owner, terms or service levels yet is operationally binding, so it is a valid sparse instance rather than a boundary violation). Splitting would duplicate identity, structure, constraint and compatibility machinery across two models whose only difference is which optional sections are populated." }, "decisions": [ { "concept": "Base provider selection", "disposition": "Claude as base", "rationale": "Claude resolves the boundary that actually causes overreach in this domain - declaration versus measurement - across three neighbours (quality observation, lineage run events, data product packaging), and carries whole governed surfaces that Grok lacks entirely: change proposal and approval, deprecation and sunset, contract provenance, registry publication and profile conformance. It also justifies each of its three inline-only findings rather than materialising an artefact per finding. Size was not the deciding factor; boundary completeness was." }, { "concept": "Entry kind", "disposition": "entity, accepted", "rationale": "Both providers independently classified this as an entity and the artefact has its own identity, version, status, owner and lifecycle persisting independently of any run or observation. No reclassification is warranted." }, { "concept": "Single model for bare schema and full data contract", "disposition": "Kept as one model, not split", "rationale": "A registry-held Avro schema with no owner, terms or service levels is a sparse instance of the same entity rather than a different kind of thing. Splitting would duplicate identity, structure, constraint and compatibility machinery across two models differing only in which optional sections are populated." }, { "concept": "Dialect, vocabulary and kind declaration", "disposition": "Accepted from Grok into l-identity-scope", "rationale": "Base has one dialect question and no vocabulary mechanism. The $vocabulary required-versus-optional rule, processor refusal on unknown required vocabularies, and the companion-schema-versus-standard-text authority rule are load-bearing and evidence-backed in JSON Schema core, ODCS and OpenAPI." }, { "concept": "Reference resolution and SHACL shape targeting", "disposition": "Accepted from Grok into l-structural-definition", "rationale": "Which nodes a shape targets, and how $ref, $dynamicRef, $defs and Avro fullnames resolve before evaluation, cannot be derived from the base's object and property structure. The unresolved-reference failure mode is a real operational exception the base never asks about." }, { "concept": "Contract-declared consumer roles and access mode", "disposition": "Accepted from Grok into l-parties-obligations, declaration-only", "rationale": "ODCS roles with access mode and a two-level approver chain, plus JSON Schema readOnly and writeOnly, are declarations the contract carries. They stay inside the base boundary that excludes enforcement, authentication and entitlement grants, and readOnly/writeOnly has no base counterpart." }, { "concept": "Canonical form and content fingerprint", "disposition": "Accepted from Grok into l-compatibility-policy, canonicalization half only", "rationale": "Parsing Canonical Form is the operative equality test for whether two schemas are the same for reading, and the base only names fingerprints as an identity option without the mechanism. The alignment half of the Grok finding is dropped because f-standard-alignment-mapping already owns it." }, { "concept": "Grok quality-rules finding", "disposition": "Rejected as duplicative", "rationale": "Base f-quality-rule-declaration already covers the four ODCS rule types, seven dimensions, comparison operators, units, severity, businessImpact and schedule, and additionally forces the consequence question. Adding a second quality finding would fragment one rule inventory across two layers." }, { "concept": "Grok sla-and-retention finding", "disposition": "Rejected as duplicative; enrichment deferred", "rationale": "Base f-service-levels-support occupies the same slot with availability, latency, freshness, retention, measurement point and support channel. The genuinely additional ODCS slaProperties vocabulary - timeToDetect, timeToNotify, timeToRepair and the regulatory/analytics/operational driver - is description-level enrichment of the existing finding, not new structure, and is recorded as deferred rather than accepted as a node." }, { "concept": "Grok data-element-concepts-and-classification finding", "disposition": "Rejected as duplicative", "rationale": "Split across base f-term-value-domain-binding (data-element concept, value domain, ISO 11179 administered item, authoritative definitions) and f-classification-privacy-terms (classification, criticalDataElement, encryptedName, personal-data basis). Nothing material remains once both are honoured." }, { "concept": "Grok emit-conformance-report function", "disposition": "Rejected as overlapping", "rationale": "Aggregating identity, dialect, validation results, quality outcomes and compatibility status is a reporting projection over outputs that fn-validate-instance, fn-evaluate-quality-rules and fn-check-compatibility already produce. Preferring rejection over a weakly separated function." }, { "concept": "Grok retire-or-deactivate function", "disposition": "Rejected; scope nuance deferred", "rationale": "Base fn-deprecate-and-sunset covers the governed retirement path including successor reference and consumer notification. The one genuine addition - that deprecation may be scoped to a single property or shape (JSON Schema deprecated, SHACL sh:deactivated) rather than the whole contract - is a question-level gap under f-deprecation-and-sunset, not a second function." }, { "concept": "Declaration versus measurement boundary", "disposition": "Retained from base, reinforced by Grok", "rationale": "Both providers independently rejected holding observed row counts, run-level quality results and column lineage in this model. Grok's adversarial check reaches the same conclusion as Claude's, which raises confidence that this boundary is correct rather than merely convenient." }, { "concept": "Data product packaging overlap", "disposition": "Composed by reference; conflict recorded, not resolved", "rationale": "ODCS bundles pricing, support, team and SLA into the contract while other standards separate them, and Grok reports the dataProduct field was deprecated in v3.1.0. The packaging boundary is genuinely unsettled, so it is carried as a recorded conflict rather than silently decided in the synthesized model." }, { "concept": "Comparison matcher output", "disposition": "Used only as a candidate list, not as evidence", "rationale": "Several reported layer matches are spurious (type representation matched to SLA and retention at 0.5, parties and obligations matched to concepts and classification at 0.52). Every acceptance and rejection here was decided on the finding text and its cited sources, not on the similarity score." }, { "concept": "Spatial encoding and data residency", "disposition": "Retained as a declared gap in both providers", "rationale": "Neither pack fetched a primary source defining geometry, CRS or a normative residency constraint expression; both mark it a gap. It must be published as a gap, and coverage for this dimension must not be asserted." }, { "concept": "Source register merge", "disposition": "Union of both registers, with repinning", "rationale": "The additions bring OpenAPI 3.1.1 and ISO/IEC 11179-31:2023 into the merged register, and Claude's three ODCS 'latest' URLs must be repinned to the immutable v3.1.0 path Grok used, since 'latest' silently drifts and would invalidate every version-specific claim resting on it." }, { "concept": "datacontract.com as supporting evidence", "disposition": "Excluded as sole support for any node", "rationale": "It is the only non-primary, tier-4 source in either pack. It may corroborate the ODCS-supersedes-DCS narrative but no accepted finding may rest on it alone; the accepted canonicalization finding is grounded in Avro, JSON Schema and OpenAPI instead." } ], "publicationHolds": [ "Live-URL and version-pin verification for the full merged source register is outstanding. Claude's three ODCS citations use 'latest' URLs annotated v3.1.0 while Grok cites the immutable v3.1.0 path; all ODCS references must be repinned to the versioned URL and refetched before publication, and the newly introduced OpenAPI 3.1.1 and ISO/IEC 11179-31:2023 entries must be fetch-verified and tier-assigned.", "Direct contradiction about ODCS v3.1.0 field status: Claude's f-governed-subject describes the governed subject as expressed through domain, dataProduct and tenant, while Grok states v3.1.0 deprecated the dataProduct field. This does not block a research draft, but f-governed-subject must not be published naming dataProduct as a live binding mechanism until the v3.1.0 text is reread.", "ISO/IEC 11179-3:2023 and 11179-31:2023 were verified only at catalogue-record level because the full texts are paywalled. Every 11179-derived construct (administered item, data element concept, conceptual domain, value domain, registration authority, registration status) must be published as an alignment hypothesis with no clause-level conformance claim.", "Domain-profile validation is incomplete. The model has been exercised against a generic enterprise profile and the European public-sector profile (DCAT-AP 3.0.0) only. It must be run against at least one regulated sector profile - clinical, financial reporting or geospatial - before any multi-profile coverage claim, since such regimes may mandate elements this model treats as optional.", "The spatial and data-residency dimension is a declared gap in both providers. Publication must state the gap explicitly and must not present server and environment binding as satisfying residency coverage.", "The accepted f-declared-access-roles finding must be reviewed at publication to confirm it reads as declaration only. If it drifts into entitlement grants, authentication or key management it breaches the base out-of-scope statement and must be cut back rather than published." ], "deferredResearch": [ "Protocol Buffers reserved field numbers and removal semantics, Apache Thrift, W3C XML Schema, RELAX NG, GraphQL SDL, LinkML, FHIR StructureDefinition, Parquet and Arrow type systems were not fetched from primary sources by either provider, so the compatibility and type layers rest on Avro plus one registry vendor's practice rather than on the full wire-format landscape.", "Geospatial and residency evidence: GeoJSON, OGC Simple Features, CRS declaration conventions, and any normative expression of a data-residency constraint inside a data contract. Both providers flagged this as a gap and neither fetched a source.", "Streaming-specific semantics: key schema versus value schema, tombstone records, subject naming strategies and per-partition ordering guarantees are only partially reachable through the registry subject concept, and the Confluent subject-compatibility API was not verified as a primary source.", "SHACL 1.2 Core status tracking. Grok records it as a Working Draft as of 2026 while the model is grounded in the 2017 Recommendation; the normative profile must be reconfirmed at publication time and processors required to declare which profile they implement.", "ODCS v3.2 and its AI-oriented contract features have no frozen specification. Recheck before publishing so the model is not pinned to a version about to be superseded, and resolve the dataProduct field question in the same pass.", "Mechanism gaps with no primary source behind them: semantic drift detection where structure is unchanged but meaning has shifted, cryptographic signing of contracts, and multi-party contract negotiation. Each is asked about in one or both packs but supported by no fetched specification.", "ODCS slaProperties detail deferred from the rejected Grok SLA finding - timeToDetect, timeToNotify, timeToRepair, generalAvailability, endOfSupport, endOfLife and the regulatory/analytics/operational driver - should be reconsidered as description-level enrichment of f-service-levels-support once the ODCS text is refetched at the pinned version." ] }, "statistics": { "sources": 24, "bundles": 6, "layers": 16, "findings": 31, "questions": 126, "artifacts": 28, "functions": 11 } }