Crate odcs 

Reference implementation of the Open Data Contract Standard (ODCS).

This is a reference implementation — not the normative ODCS specification. The upstream standard is maintained at bitol-io/open-data-contract-standard.

User documentation

• Getting started
• API decision guide
• CLI reference
• API stability policy

Pipeline

ODCS Document → Parser → Canonical Object Model → Validator → Diagnostics

Stable API

Use root re-exports only (parse, validate, parse_and_validate, DataContract, ContractSet, Registry, diff, …). Internal modules (parser, validation, model, …) are #[doc(hidden)] and not semver-stable. See the public API guide.

Error handling

• parse / parse_and_validate — return DiagnosticReport (validation) or embed parse diagnostics in ParseResult
• parse_file / DataContract::from_file — return miette::Result for I/O errors
• ParseResult::into_contract / parse_strict — Result<DataContract, DiagnosticReport> after parse and validation

Match on diagnostic codes and object_ref, not message text.

Example

use odcs::{parse, validate, DocumentFormat};

let yaml = br#"
version: "1.0.0"
apiVersion: "v3.1.0"
kind: "DataContract"
id: "example"
status: "draft"
"#;

let result = parse(yaml, DocumentFormat::Yaml);
let contract = result.contract.expect("parse succeeded");
let report = validate(&contract);
assert!(report.is_valid());

Re-exports

pub use compatibility::diff;

pub use compatibility::ChangeKind;

pub use compatibility::CompatibilityChange;

pub use compatibility::CompatibilityReport;

pub use contract_set::load_set;

pub use contract_set::load_set_with_registry;

pub use contract_set::parse_and_validate_set;

pub use contract_set::parse_and_validate_set_with_registry;

pub use contract_set::validate_set;

pub use contract_set::ContractSet;

Modules

cli

Command-line interface.

codes

Standardized odcs: diagnostic identifiers.

compatibility

Contract compatibility analysis.

contract_set

Cross-file contract loading and validation.

Structs

DataContract

An ODCS Data Contract — the canonical root object.

Diagnostic

A spec-level diagnostic record.

DiagnosticReport

Collection of diagnostics produced during parsing or validation.

ParseResult

Result of parsing an ODCS document.

Registry

Local contract registry backed by .odcs/registry.json.

RegistryEntry

A single contract entry in a local registry index.

Enums

DiagnosticCategory

Standard diagnostic category.

DiagnosticStage

Originating processing stage.

DocumentFormat

Supported ODCS document serialization formats.

Severity

Diagnostic severity.

ValidationPhase

Validation phases for ODCS documents.

Constants

MAX_PARSE_BYTES

Maximum document size accepted by parse_file (16 MiB).

UPSTREAM_SPEC_VERSION

Upstream ODCS specification version this crate targets.

Functions

index_and_save_registry

Scan a directory and write <dir>/.odcs/registry.json.

index_registry

Scan a directory recursively and build a registry index in memory.

inspect_contract

Returns a short human-readable contract summary.

load_registry

Load a registry from <dir>/.odcs/registry.json.

parse

Parse an ODCS document from bytes.

parse_and_validate

Parse and validate an ODCS document in one step.

parse_file

Parse an ODCS document from a file path.

parse_json

Parse JSON bytes into an ODCS contract.

parse_strict

Parse and validate an ODCS document, returning an error report on failure.

parse_yaml

Parse YAML bytes into an ODCS contract.

validate

Validate a parsed data contract (Rust pipeline + JSON Schema).

validate_with_contract_index

Validate a parsed data contract with optional cross-file reference index.

Type Aliases

ValidationReport

Alias aligned with implementation guides.