JSON-LD Serialization

Table of Contents


Introduction

JSON-LD is a Linked Open Data serialization using the popular JSON (Javascript Object Notation) format that is convenient for both backend and browser based development. It is specified by the W3C as an official serialization. Continued development work happens in the JSON for Linking Data W3C Community Group.

The serialization for JSON-LD is friendly to developers through the use of context documents that specify the mapping between the key used in the json object and the RDF predicate used in the model. This abstraction allows the developer to work with existing patterns and frameworks, while the data is still managed as a graph underneath. This document describes the context used for CIDOC-CRM and other ontologies.

The context that provides the mapping of the terms used in the model is published as:

https://linked.art/ns/v1/linked-art.json

Examples

The examples throughout the documentation use the JSON-LD serialization. Each has a link to the raw JSON-LD, and to load it into the invaluable JSON-LD playground where you can explore the details. Instead of trying to describe all of the predicates and classes (for that just read the CIDOC-CRM specification), we present the models for the known use cases in an attempt to be more practical and results oriented. We strive for usability and familiarity for developers, and the examples aim to present best practices at the same time as being easy to follow.

An example of the JSON-LD serialization for a painting, that is made of watercolor on a canvas support:

{
  "@context": "https://linked.art/ns/v1/linked-art.json", 
  "id": "https://linked.art/example/object/23", 
  "type": "ManMadeObject", 
  "label": "Example Painting", 
  "classified_as": ["aat:300033618","aat:300133025"], 
  "made_of": [
    {"id": "aat:300015045","type": "Material","label": "watercolor"}
  ], 
  "part": [
    {
      "id": "https://linked.art/example/object/23/part/1", 
      "type": "ManMadeObject", 
      "label": "Canvas Support", 
      "classified_as": ["aat:300014844"], 
      "made_of": [{"id": "aat:300014078","type": "Material","label": "canvas"}]
    }
  ]
}

JSON-LD (Raw) | JSON-LD (Playground) | Turtle (Raw) | Turtle (Styled)

Context Design

The important part of the JSON-LD serialization is the shared context document. This context has some design constraints that it is useful to understand before looking at the data model and mapping from the ontology. In particular:

There are some challenges overlaid on these principles from the CIDOC-CRM ontology.

The context tries to manage all of these issues in a practical and programmatically accesible way from the ontology definition.

Context

The context implements the notion that if a property can ever have multiple values, then it must always be an array. In JSON-LD this is done with @container: @set on such properties, and you'll see many instances of this in the examples where a property has an array with a single object inside it.

The following process is used to create the JSON-LD keys from the CIDOC-CRM ontology:

The name collisions and consistency changes have been resolved as follows:

Property Key
P2 classified_as
P5 subState
P5i subState_of
P7i location_of
P12 involved
P14i carried_out
P20i specific_purpose_of
P28 transferred_custody_from
P29 transferred_custody_to
P29i acquired_custody_through
P32 technique
P33 specific_technique
P35i condition_identified_by
P37 assigned_identifier
P37i identifier_assigned_by
P42 assigned_type
P42i type_assigned_by
P45 made_of
P46 part
P46i part_of
P56 bears
P78 time_identified_by
P78i identifies_time
P86 temporally_within
P86i temporally_contains
P87 place_identified_by
P87i identifies_place
P89 spatially_within
P89i spatially_contains
P90 has_value
P106i composed_from
P107 member
P107i member_of
P131 actor_identified_by
P131i identifies_actor
P132 volume_overlaps_with
P133 distinct_from
P135i type_created_by
P140 assigned_to
P149 concept_identified_by
P149i identifies_concept
P151i participated_in_formation
P164i timespan_of_presence
P165i included_in