Related standards¶
The spec is a thin layer. Where an open standard already says something well, the file uses it as is: its codes, its field names, or a field-by-field mapping. The spec adds only what those standards have no place for: dated, checkable facts about the data, with an as-of date per source and a citation id.
Which element comes from where¶
| Element in the file | Standard | How the spec uses it |
|---|---|---|
| The file format | YAML 1.2 | The file is plain YAML. |
| Validating the file | JSON Schema | A published schema (schema/ai-ready-data-declarations-v1.json) checks keys and value types. |
Column unit |
UCUM | Codes used as is, plus three aliases (decimal, pct, bp). See Units. |
Column and pricing currency |
ISO 4217 | Three-letter codes used as is (USD, EUR). |
Pricing plans (pricing) |
ODPS 4.1 | Same field names in snake_case, same unit values. Mapped field by field. |
| One contract price | ODCS v3 | The first qualifying plan maps to the contract's price. |
relationships |
Apache Ossie | Same shape and field names (from, to, from_columns, to_columns, ai_context). |
x- extension keys |
The x- convention of OpenAPI |
Any key starting with x- is allowed and kept verbatim. See Extensions. |
grain |
The "grain" of dimensional modelling (Kimball) | The idea, not a format: the columns that make one row unique. |
Field-by-field tables for ODCS, ODPS and Ossie are on Mappings.
What each standard is for, and where it stops¶
- ODCS (Open Data Contract Standard, Bitol, Linux Foundation) describes a data contract: schema, quality rules, service levels, owners, servers, price. The spec does not repeat a contract. It maps one price to it today.
- ODPS (Open Data Product Specification) describes a data product for a marketplace, including pricing plans. The spec reuses its pricing plans so a vendor writes prices once.
- Apache Ossie describes semantic models: entities, measures and relationships between tables. The spec reuses its relationship shape so joins read the same in both.
- UCUM defines unit codes with a grammar (prefixes, multiply and divide, annotations), so a unit can be checked instead of guessed. The spec takes the codes and adds no units of its own beyond three aliases.
- ISO 4217 defines currency codes. Money is kept out of
uniton purpose, as in most finance data.
What the spec adds¶
None of the standards above has a place for these, and they are the reason the spec exists:
dates_asof: an as-of date per source, so a reader can tell which release each number comes from.facts: dated statements about the data, each with a status, a severity, an expiry and a citation id, optionally re-tested by a probe on every build.use_casesanddo_not: what the data is fit for, and the mistakes to avoid.per,unit_fromanduse_insteadon columns.- Schema history:
aliases(withuntil),removed_columns,removed_datasetsandnot_exported. See Schema changes. - The card: the short page an agent reads, and the citation form a report can quote.
Planned¶
- Column types. A
typefield taking ODCSlogicalTypevalues (string,integer,number,boolean,date,timestamp, ...) and aphysical_typetaking Apache Arrow type names, both filled from the data. They map one to one to ODCSlogicalTypeandphysicalType. - Generating whole ODCS and Ossie files from the declarations. Not part of this version; see Status.