A standardized JSON-schema to represent any Cardano-related objects. The schema covers objects found in blocks and transactions, from the Byron era onward.
| schema | format |
|---|---|
| Raw schema | JSON |
| Rendered schema | HTML |
The schema from this repository is the result of several years of experience dealing with Cardano objects and collecting feedback from builders through tools like Ogmios. It is opinionated in a few ways, with choices that could be summarized as follows:
-
The schema and its sub-schemas try to be era-independent. That is, it tries to blend together objects from multiple Cardano era into one unified model. This is only reasonable because efforts are done for each Cardano upgrades to keep objects as backward and forward-compatible as possible. Transactions are divided into fields which are most entirely optional. While only later era may instantiate transactions carrying all fields, the schema still only describes one transaction model.
-
The previous point implies some transformations and divergence compared to what one would expect from the binary format. For example, there's no MIR certificates in the schema. They are mapped to treasury withdrawal governance actions. These transformations are meant to reduce the cognitive load that comes with undertanding the schema and dealing with evolutions of the chain. The schema present a final view on Cardano's objects, and thus make accomodations where needed.
-
There are few exceptions, but most exclusively around the Byron era. This is because the Byron era simply is too different that some schema couldn't be unified without bringing extreme awkwardness.
-
The schema is consistent in its naming. Things that represent the same concept are named the same. And things that represent different concept are named differently. This is true also between the Byron era and the others. So it is reasonable for one to expect the same sub-schema given a field name.
-
We avoid as much as possible key/value objects with arbitrary key unless they bring a real cost-saving benefit (e.g. for assets). Instead, we prefer lists with inlined fields. This is because of two main reasons: such dictionnaries are usually ordered and JSON parsers do not usually preserve this ordering; and it makes parsing and processing of those datasets sometimes more cumbersome. Lists are much more universal.
-
As a means to keep the schema self-documented, we keep names full and avoid abbreviations. No
tx,pp,vk,pkhor other acronyms either. The point of such schema isn't to be as compact as possible; If you need this, use a proper binary format (CBOR would be the only sensible choice given Cardano's landscape). -
We use discriminated unions consistently where it is needed. That is, no object shall be ambiguous to parse and objects that represent sum-types shall always have a field to discriminate on.
-
Few integer values in the schema are unbounded (no
maximumnorminimum). These are not oversight, but actual quantity that can grow unbounded, in particular when aggregated. Parsers are expected to use big numbers or equivalent for dealing with such unbounded quantities.
