JSON-AD: The Atomic Data serialization format

Although you can use various serialization formats for Atomic Data, JSON-AD is the default and only required serialization format. It is what the current Rust and Typescript / React implementations use to communicate. It is designed to feel familiar to developers and to be easy and performant to parse and serialize. It is inspired by JSON-LD.

It is JSON with the additional constraint that the root data structure must either be a Named Resource (with an @id), or an Array containing Named Resources.

The mime type (for HTTP content negotiation) is application/ad+json (registration ongoing).

Named Resources

A named resource is a JSON Object that represents an Atomic Data resource. Each key represents a property, therefore each key must be a valid Property URL with the exception of the mandatory @id field. The @id field is special: it defines the Subject of the Resource. If you send an HTTP GET request there with an content-type: application/ad+json header, you should get the full JSON-AD resource.

The types of values allowed are determined by the datatype of the property.

• string, slug, markdown, uri and date datatype fields must be a string.
• integer, float and timestamp datatype fields must be a number.
• boolean datatype fields must be a boolean.
• atomic-url datatype fields must be either a string (url) or an object (nested resource).
• resource-array datatype fields must be an array of strings (must be a url) or objects (must be an nested resource).
• json datatype fields can be any valid JSON value.

Named Resources are only allowed in the following places:

• The root of the JSON-AD document.
• As an item in an array that is directly under the root of the JSON-AD document.

Example of a named resource in JSON-AD format:

{
  "@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"
}

Nested Resources

Nested resources are resources that do not have an @id field. It does have its own unique path, which can be used as its identifier.

Nested resources are only allowed in the following places:

• The value of a property with an atomic-url datatype.
• As an item in a resource-array property's array value.

In the example below is a named resource with the subject: https://example.com/arnold. The address property has an nested resource as its value, therefore the path of the nested resource is: https://example.com/arnold https://example.com/properties/address.

{
  "@id": "https://example.com/arnold",
  "https://example.com/properties/address": {
    "https://example.com/properties/firstLine": "Longstreet 22",
    "https://example.com/properties/city": "Watertown",
    "https://example.com/properties/country": "the Netherlands",
  }
}

Regular JSON

Properties with a json datatype can contain any valid JSON value. If any JSON-AD data is present in these values it will not be treated as JSON-AD, but as regular JSON.

Because these JSON values do not benefit from any of Atomic Data's features you should avoid using them unless your value is truly JSON data, for example when you need to store a config of some application.

JSON-AD Parsers, serializers and other libraries

• Typescript / Javacript: @tomic/lib JSON-AD parser + in-memory store.
• 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 are more formally defined by the JSON Canonicalization Scheme (JCS, rfc8785).

Interoperability with JSON and JSON-LD

Read more about this subject.