JSON-AD: The Atomic Data serialization format

JSON-AD is the default serialization format for Atomic Data. It is what the current Rust and Typescript / React implementation use to communicate. It is a JSON with a lot of links in it and the following rules:

  • Every Object is a Resource.
  • Every Key is a Property URL.
  • The @id field is special: it defines the Subject of the Resource.
  • JSON arrays are mapped to Resource Arrays
  • Numbers can be Integers, Timestamps or Floats.
  • JSON booleans map to Booleans.
  • JSON strings can be many datatypes, including String, Markdown, Date or other.
  • Nested JSON Objects are Nested Resources. A Nested Resource can either be anonymous (without an @id subject) or a regular Nested Resource with an @id subject.
  • When you want to describe multiple Resources in one JSON-AD document, use an array as the root item.

Let's look at an example JSON-AD Resource:

{
  "@id": "https://atomicdata.dev/properties/description",
  "https://atomicdata.dev/properties/datatype": "https://atomicdata.dev/datatypes/markdown",
  "https://atomicdata.dev/properties/description": "A textual description of something. When making a description, make sure that the first few words tell the most important part. Give examples. Since the text supports markdown, you're free to use links and more.",
  "https://atomicdata.dev/properties/isA": [
    "https://atomicdata.dev/classes/Property"
  ],
  "https://atomicdata.dev/properties/shortname": "description"
}

JSON-AD Parsers, serializers and other libraries

  • Typescript / Javacript: @tomic/lib JSON-AD parser + in-memory store. Works with @tomic/react for rendering Atomic Data in React.
  • Rust: atomic_lib has a JSON-AD parser / serializer (and does a lot more).

Canonicalized JSON-AD

When you need deterministic serialization of Atomic Data (e.g. when calculating a cryptographic hash or signature, used in Atomic Commits), you can use the following procedure:

  1. Serialize your Resource to JSON-AD
  2. Do not include empty objects, empty arrays or null values.
  3. All keys are sorted alphabetically (lexicographically) - both in the root object, as in any nested objects.
  4. The JSON-AD is minified: no newlines, no spaces.

The last two steps of this process is more formally defined by the JSON Canonicalization Scheme (JCS, rfc8785).