Open Derivation Spec
The schema is the standard. Implementations just validate against it.
elbi’s SDK validates every derivation against a public JSON Schema — the same document any other implementation validates against. Open spec, no lock-in.
§ 01 · Authoritative
The schema decides. The prose explains.
derivation.schema.json is a JSON Schema 2020-12 document. Where prose and schema disagree, the schema wins — the SDK loads it as data instead of hand-mirroring its rules in Python.
"The bundled copy in the package is asserted byte-identical to the canonical spec/ file by a test, so the two cannot drift."
{
"specVersion": "1.0",
"kind": "Derivation",
"name": "churn_risk",
"description": "Per-customer churn-risk scores derived from recent sales activity.",
"inputs": {
"sales": { "kind": "dataset", "ref": "sales" }
},
"serve": {
"format": "table",
"title": "Churn risk",
"columns": ["customer_id", "risk"],
"maxRows": 50
}
}A manifest — the declarative serialization of a derivation. Any SDK that authors derivations MUST be able to emit one that validates.
§ 02 · Certification, in the schema
“Agent-proposed” and “certified” aren’t marketing words. They’re enum values.
Every manifest carries origin (human | agent) and status (proposed | certified). The schema’s own description of status is the whole trust boundary:
“Only ‘certified’ derivations may be served to agents; ‘proposed’ ones await review.”
derivation.schema.json
Before review
{
"name": "revenue_by_region",
"origin": "agent",
"status": "proposed",
"serve": { "format": "table" }
}Default — awaits nothing further
{
"name": "churn_risk",
"origin": "human",
"status": "certified"
}Both fields default: origin to human, status to certified. An agent proposing one is what flips both.
§ 03 · Versioned like a standard
Not tied to any one SDK release.
ODS moves on its own SemVer line — specVersion, as MAJOR.MINOR. An SDK must reject an unsupported major version, and accept any minor version at or below its own.
- MAJOR
Backward-incompatible: a field removed or renamed, a constraint tightened so a previously valid manifest fails.
- MINOR
Backward-compatible: a new optional field, a new serve format, a relaxed constraint.
- PATCH
Editorial only — prose or example fixes that don't change validation. Never reflected in specVersion.
A conformance suite of valid/invalid fixtures — the executable definition of the standard — runs in CI. Any implementation can run it.
§ 04 · Deliberately not over-built
It stays in the SDK’s repo — for now, on purpose.
“The spec stays here until there is a second-language SDK, external implementers filing spec issues, or a foundation home. Splitting earlier signals theater, not openness.”
spec/README.md
The spec is Apache-2.0, same as the SDK — read it, fork it, validate against it independently. No permission needed.
Check it yourself
Validate a manifest yourself.
import elbi; elbi.validate_manifest(my_manifest) raises SpecValidationError if it doesn't conform — the same check the SDK runs before anything serves.