Introducing JSON-LD
In my last blog post, I talked about embedding linked data in web pages using RDFa or JSON-LD. In this blog post, I'll shift gears a bit and talk about producing linked data that's in the JSON-LD serialization.
What's JSON-LD?
JSON (JavaScript Object Notation) is a commonly used, light-weight format for data interchange. JSON-LD is the JSON serialization of linked data.
JSON-LD is especially versatile in that it can appear in four different forms: expanded, compacted, flattened or framed. The form(s) your service supports may depend on what sorts of client applications you expect to serve and what your resource’s environment can provide to produce JSON-LD serializations.
Expanded JSON-LD
A key concept in JSON-LD is “context”. The context of a JSON-LD representation provides mappings from JSON to an RDF model. For example, the context can define that the JSON property “name” should be interpreted as representing the RDF model defined at http://xmlns.com/foaf/0.1/name.
The expanded form of JSON-LD takes the context information and applies it to all IRIs (International Resource Identifiers), RDF types, and values so that a separate “@context” JSON-LD node isn’t necessary.
Compact JSON-LD
In the compact form, a JSON “@context” node defines the relationships of JSON properties and corresponding RDF model IRIs and shortens the IRIs and JSON-LD values to simple values, such as strings or numbers, when referenced in the graph. This can make the document easier for a human to read and simpler to work with.
Flattened JSON-LD
In the flattened form, all properties of a node and flattened and converted into a single JSON “@graph” object and any blank nodes are labelled with identifiers. Because the flattening processes ensures the data is a particular shape, it can simplify the code that parses the JSON-LD.
Framed JSON-LD
Framing applies a particular layout to the RDF graph, based on a “frame” provided by a developer. For example, the frame could identify the RDF “@type” as a “book.” The result is a graph that is object-oriented and consistently formatted the same way.
Producing JSON-LD
A service providing JSON-LD-formatted data expects the media type “application/ld+json” via the HTTP Accept header. Services can also support clients sending an optional “profile” parameter to specify the preferred format of the returned data: expanded, compact or flattened. If the profile parameter isn't supported by the service or isn't specified, then the service will return the available JSON-LD representation. Each of these permutations is valid JSON-LD that is readable by libraries capable of parsing linked data.
However, some of the JSON-LD formats are easier to parse as more traditional object-oriented JSON and more readable to humans. If you visit the JSON-LD playground, you can see this in action. Compare the expanded and flattened views of the Person example. You will see they look quite different from one another.
Why does this matter, especially if everything is semantically equivalent? Let's take a closer look at two different JSON-LD renderings of a bibliographic record from WorldCat.
The first example is a compact view: http://experiment.worldcat.org/oclc/41266045.jsonld.
The second example is a framed view that uses the Information Resource type for the frame: http://www.oclc.org/content/dam/developer-network/web-services/WorldCatDiscovery/Bib-Book.json.
For a client used to parsing traditional object-oriented JSON, the framed second example is probably going to be easier to work with, and it is also easier for a human to read and understand the semantics of the document. This example has had framing applied to it specifically to meet these use cases.
JSON-LD and Web Syndication
Google's documentation indicates that it will read data embedded in webpages via microdata, microformats, RDFa or JSON-LD. This means JSON-LD is a viable alternative to RDFa for search engines harvesting linked data. This can be done via two methods:
- Using script tag and inline JSON-LD
- Using a script tag to link to a separate JSON-LD file
Our previous post on “Embedded Linked Data in Webpages” covers these two options in much greater detail.
JSON-LD in OCLC's Web Services and Linked Data
JSON-LD is available in the linked data for WorldCat and WorldCat Works. This linked data only makes a compacted, unframed form of JSON-LD available. JSON-LD is also one of the serializations supported by the WorldCat Discovery API.
The WorldCat Discovery API supports two forms of JSON-LD. The first form of JSON-LD that it supports is compacted and unframed, just like the open linked data OCLC makes available. The second form available in the WorldCat Discovery API is a flattened, framed form. When we were building the WorldCat Discovery API, we knew we wanted to make the data available to clients who might want to parse it using traditional JavaScript methods. So, we created a frame that structured the JSON-LD like a traditional object-oriented JSON document. The result is that I can use the following syntax to get the title of the book.
book['@graph']['schema:about']['schema:title']
We also chose to make the framed form of the JSON-LD available via content negotiation for the application/json media type. By doing this, we are signaling to developers using the service that what is being returned is JSON structured in a fashion that they are used to consuming.
Pitfalls of Framed JSON-LD
The choice to provide framed JSON-LD does have some downsides, though. Any entity within the graph that is repeated is only fully referenced in the flattened, framed JSON-LD. This behavior is most evident when viewing an autobiographic work, such as "The autobiography of Benjamin Franklin, 1706-1757". In the example below, you can see that the entity representing Benjamin Franklin is both a schema:creator and a schema:about. However, Benjamin Franklin’s full details only appear in one place in the framed JSON-LD. This is problematic for someone using the data in an object-oriented manner rather than treating it as a graph.
Example
{
"@graph": [
{
"@id": "http://www.worldcat.org/title/-/oclc/573925533",
"@type": [
"http://www.w3.org/2006/gen/ont#ContentTypeGenericResource",
"http://www.w3.org/2006/gen/ont#InformationResource"
],
"void:inDataset": {
"@id": "http://purl.oclc.org/dataset/WorldCat"
},
"schema:about": {
"@id": "http://www.worldcat.org/oclc/573925533",
"@type": [
"schema:Book",
"schema:CreativeWork",
"schema:MediaObject"
],
"schema:name": {
"@language": "en",
"@value": "The autobiography of Benjamin Franklin, 1706-1757"
},
"schema:about": [
{
"@id": "http://viaf.org/viaf/56609913",
"@type": "schema:Person",
"schema:birthDate": "1706",
"schema:deathDate": "1790",
"schema:familyName": "Franklin",
"schema:givenName": "Benjamin",
"schema:name": "Benjamin Franklin"
}
],
"schema:creator": {
"@id": "http://viaf.org/viaf/56609913"
}
}
}
]
}
When deciding which permutations of JSON-LD to produce, you will want to consider a number of factors including:
- Familiarity of your consuming clients with linked data
- Whether or not the original data is stored in a graph format
- Expectation of human readability
- Data within your dataset that might mimic the "autobiography" problem
- Whether or not you have an existing JSON API
- How important syndication of content for search engines is
All of these factors should be considered when making decisions regarding producing JSON-LD. In our next post, we'll discuss how using the JSON-LD serialization can lower the barrier to publishing linked data by allowing an existing JSON-based API to be retrofitted to become linked data.
-
Karen Coombs
Senior Product Analyst