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 Atomic Booleans.
  • Strings can be many datatypes, including String, Markdown, Date or other.
  • Nested Objects are Nested Resources. A Nested Resource can either be an Anonymous Resource (without an @id field) or a regular Resource.
  • 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/properties/shortname": "description"

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).