Skip to content

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 unit on 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_cases and do_not: what the data is fit for, and the mistakes to avoid.
  • per, unit_from and use_instead on columns.
  • Schema history: aliases (with until), removed_columns, removed_datasets and not_exported. See Schema changes.
  • The card: the short page an agent reads, and the citation form a report can quote.

Planned

  • Column types. A type field taking ODCS logicalType values (string, integer, number, boolean, date, timestamp, ...) and a physical_type taking Apache Arrow type names, both filled from the data. They map one to one to ODCS logicalType and physicalType.
  • Generating whole ODCS and Ossie files from the declarations. Not part of this version; see Status.