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 for the first version of the full mapping for the model is published as:

https://linked.art/ns/context/1/full.jsonld

Example

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.

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

{
  "@context": "https://linked.art/ns/context/1/full.jsonld", 
  "id": "https://linked.art/example/object/20", 
  "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/20/part/1", 
      "type": "PhysicalObject", 
      "label": "Canvas Support", 
      "classified_as": ["aat:300014844"], 
      "made_of": [{"id": "aat:300014078","type": "Material","label": "canvas"}]
    }
  ]
}

Raw | Playground | Raw Turtle | Styled Turtle

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:

• The resulting JSON must be valid Linked Open Data and valid JSON-LD. There are patterns that are valid in JSON that are not valid in JSON-LD, such as an array of arrays. The nested object structure in the JSON is a result of the graph of resources.
• The resulting JSON must be understandable by developers who are unfamiliar with both the model and RDF in general. If the target technical audience was developers who had the full suite of RDF tools at their disposal, then Turtle and SPARQL would likely be preferable. The serialization instead tries to make the content as accessible as the model will allow.
• The resulting JSON must be usable regardless of programming language or application environment to ensure the widest possible adoption and value. The context is designed to allow as many of conveniences as possible to be used, and to maximize the situations in which it can be used.

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

• The use of numbers in the class and properties runs counter to the understandable and usable principles.
• The use of - in the names of some classes and properties reduces usability, as it is not allowed as the name of a property in most programming languages.
• The use of the same name for a property, minus its number, is not possible in JSON-LD as the keys must map uniquely to a predicate.
• The use of underscores in class or property names is not common in Javascript or in RDF ontologies, which tend to prefer camelCase.

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

Context

The following patterns are used to create the JSON-LD keys from the CIDOC-CRM ontology:

• Remove the prefix numbers (Activity not E7_Activity)
• Remove dashes (has_timespan not has_time-span)
• Use upper CamelCase for classes (TransferOfCustody not Transfer_of_Custody)
• Use lower snake_case for properties (is_identified_by)
• Remove CRM namespace from classes and properties (Production not crm:Production)
• Remove @ symbols (id not @id)
• Remove is_, was_, has_ and had_ from the beginning of properties, as being inconsistently applied in the ontology and hard to remember (created not has_created ; compare destroyed)
• Rename properties with collisions, from furthest down the hierarchy first, with a first effort of adding the range's class to the predicate name, but preferring a human understandable term
• Include prefixes for commonly used ontologies (skos, schema, rdf) and vocabularies (aat, tgn, geonames)

The name collisions 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