Schemas and contracts are the durable, language-neutral vocabulary of a One system. They describe meaning independently of Rust layout, Python objects, wire codecs, database rows, UI state, or transport.
Bounded semantic data
A semantic type owns fields, variants, units, constraints, classifications, purposes, identity, nullability, and compatibility. Bounds are operational facts: they affect validation, allocation, frame admission, storage planning, fuzzing, redaction, and generated clients.
Physical representations remain separate. One semantic record may be realized as a Rust struct, TypeScript discriminated union, Python validated object, Protobuf message, row layout, columnar array, or WIT record.
Operations own more than signatures
An operation contract includes:
- nominal input, output, and recoverable domain faults;
- effect and state-impact semantics;
- deadline, cancellation, delivery, and idempotency obligations;
- authentication, authorization, capability, and data-policy requirements;
- streaming, backpressure, and compatibility behavior.
No executor, HTTP framework, database driver, or cloud type belongs in the semantic contract.
Domain faults are not invocation causes
| Channel | Examples |
|---|---|
| Domain fault | invalid order, insufficient stock, business rejection |
| Invocation cause | admission, cancellation, deadline, incompatibility, transport |
| Effect outcome | definitely aborted, committed, or outcome unknown |
| Defect | invariant violation, panic, corrupt provider output |
Keeping these separate lets a local call become remote without rewriting its business fault schema.
One Contract Schema
One Contract Schema (OCS) is the canonical, content-addressed contract package. It contains nominal schemas, operations, faults, effects, resources, services, capabilities, documentation, deprecation, and compatibility.
Rust, native One, TypeScript, Python, WIT, Protobuf, OpenAPI, and GraphQL are profile-governed projections. Every projection records exact, represented, shimmed, qualified, unsupported, and lossy dispositions.
Generated source is a disposable cache. Editing it cannot redefine the contract.
Compatibility is exact
Compatibility is checked at each real edge: stored state, active deployments, remote peers, generated clients, histories, and imported models. Similar names or shapes do not establish compatibility.
A mapping between owners is directional and destination-validated. A U64
cannot silently become a JavaScript number, and a remote typed failure cannot
collapse into an unchecked exception without an explicit loss disposition.
Canonical owner: Contracts.