Upstream Specification¶

ODCS Upstream Specification Policy¶

Document Status: Normative Repository Policy\ Applies To: odcs Rust Reference Implementation

Purpose¶

This document defines the authoritative upstream references that the odcs repository SHALL use when implementing the Open Data Contract Standard (ODCS).

The goal is to ensure that the Rust implementation remains aligned with the published ODCS specification while providing an idiomatic, high-quality Rust API.

Normative Upstream Sources¶

The following resources SHALL be treated as the authoritative sources for ODCS semantics.

1. Official GitHub Repository¶

https://github.com/bitol-io/open-data-contract-standard

Contains:

specification source
releases
changelog
governance
examples
JSON Schema
reference material

2. Official Documentation¶

https://bitol-io.github.io/open-data-contract-standard/

Provides the published human-readable specification.

3. Official JSON Schema¶

The JSON Schema published by the ODCS project SHALL be used as the behavioral parity target for structural validation.

Repository Policy¶

This repository SHALL maintain:

SPEC.md
Rust source code
examples
tests
conformance fixtures

SPEC.md is the implementation guide for this repository.

The upstream ODCS specification remains the normative standard.

If a conflict exists:

Follow the targeted upstream ODCS release.
Update SPEC.md.
Update tests.
Update implementation.

Version Target¶

Each release of this repository SHALL explicitly identify the supported upstream ODCS version.

Example:

ODCS 3.1.0
ODCS 3.2.0

The supported version SHALL appear in:

README.md
Cargo.toml metadata where appropriate
SPEC.md
release notes

Upstream example corpus (0.4.0)¶

Curated upstream examples are synced from bitol-io/open-data-contract-standard @ main into tests/fixtures/upstream/. See tests/fixtures/upstream/SOURCE.txt for the file list. Document version fields are preserved from upstream (typically 1.0.0).

Spec parity policy (0.4.0)¶

Default validate() runs the Rust semantic pipeline and JSON Schema validation against the pinned ODCS v3.1.0 schema in schema/odcs-v3.1.0.json.

Matches upstream JSON Schema¶

Root document properties and additionalProperties: false (via deny_unknown_fields on model types)
Enum constraints promoted to default validation (logicalType, quality.dimension, server type, relationship type)
Library quality DataQualityOperators oneOf
Server type-specific required fields (Snowflake, Kafka, PostgreSQL)
SLA description and scheduler fields

Intentional extensions (stricter than schema)¶

Documented deviations that remain in the Rust pipeline:

Extension	Behavior
Relationship shorthand resolution	Shorthand refs (`table.column`) must resolve to a known schema object and property in the same document
Composite endpoint length parity	Composite `from`/`to` arrays must have equal length
Library `rule` field	Deprecated `rule` alone is rejected; `metric` is required
`apiVersion` scope	Only `v3.1.0` accepted (schema allows older API versions)

Structural validation (0.7.0)¶

Cross-field rules enforced in src/validation/structural.rs (not covered by JSON Schema or single-section validators):

Rule	Behavior	Diagnostic
Unique `schema[].name`	Non-empty schema object names must be unique within `schema[]`	`odcs:invalid-schema`
`slaProperties[].element` → `schema[].name`	Each comma-separated token must reference an existing schema object name	`odcs:unresolved-reference`
`slaDefaultElement` → `schema[].name`	When set, must reference an existing schema object name (deprecated field; same element-path semantics as `slaProperties[].element`)	`odcs:unresolved-reference`
Unique `servers[].server`	Non-empty server identifiers must be unique within `servers[]`	`odcs:invalid-schema`

Not adopted: servers[].schema in server-type details is a database/catalog schema string (e.g. Snowflake "public"), not a reference to an ODCS schema[] object name.

Section semantics (0.8.0)¶

Business rules enforced in src/validation/sections.rs (beyond JSON Schema and emptiness checks in extensions.rs):

Rule	Behavior	Diagnostic
Unique `roles[].id`	Non-empty role ids must be unique within `roles[]`	`odcs:invalid-schema`
Support URL	When `support[].tool` is `slack`, `teams`, `discord`, `googlechat`, `ticket`, or `other`, `url` must be non-empty	`odcs:missing-required-field`
SLA scheduler pairing	When `slaProperties[].scheduler` is non-empty, `schedule` must be non-empty	`odcs:missing-required-field`
Pricing currency	When `price.priceAmount` is set, `price.priceCurrency` must be non-empty	`odcs:missing-required-field`
Pricing amount	`price.priceAmount` must not be negative	`odcs:invalid-schema`

Cross-file references (0.8.0)¶

Fully-qualified relationship endpoints ({contractId}/{schemaObject}/{property}) resolve against a loaded contract set indexed by root id. See docs/implementation/cross-file-references.md.

Behavior	Diagnostic
FQN resolves when referenced contract is included via `--dep`, `--include`, or `--registry`	(pass)
FQN does not resolve when referenced contract is omitted	`odcs:unresolved-reference`
Duplicate `id` within a loaded set	`odcs:invalid-schema`

Compatibility analysis (0.8.0)¶

Contract diff compares two parsed contracts and classifies changes as breaking, additive, deprecated, or unchanged. See src/compatibility/. CLI: odcs diff <old> <new>.

Local registry (0.9.0)¶

Filesystem registry for contract discovery and cross-file validation. See docs/implementation/registry.md.

Behavior	Notes
`odcs registry index <dir>`	Recursive scan; writes `<dir>/.odcs/registry.json`
`lookup(id)` / `lookup(id, version)`	In-memory lookup from index
`odcs validate --registry <dir>`	Loads index for FQN dependency resolution

Out of scope¶

Remote registry server (see docs/implementation/non-goals.md)

Synchronization Workflow¶

When a new upstream release is published:

Review the changelog.
Compare specification changes.
Compare JSON Schema changes.
Update SPEC.md.
Update Canonical Object Model.
Update validators.
Update diagnostics.
Update conformance tests.
Publish a new crate release.

Implementation Philosophy¶

This repository is not intended to replace the upstream specification.

Instead it provides:

the Rust reference implementation
idiomatic Rust APIs
deterministic validation
diagnostics
CLI tooling
Python bindings
conformance testing

while remaining faithful to the published ODCS standard.

Mapping Responsibilities¶

The implementation SHALL define a stable mapping from upstream ODCS concepts into Rust types.

Mapping includes:

Canonical Object Model
parsing
validation
diagnostics
compatibility
version handling

Implementation details MAY differ from the specification provided observable behavior remains equivalent.

Non-Goals¶

This repository SHALL NOT:

redefine ODCS semantics
invent incompatible extensions by default
diverge intentionally from the upstream specification
modify published JSON Schema behavior without documentation

Long-Term Vision¶

The long-term objective is to make this repository the canonical open-source Rust implementation of ODCS.

Future companion repositories are expected to include:

contractmodel
dtcs
dpcs

forming a cohesive contract-first data engineering ecosystem.