On Using JSON-LD to Create Evolvable RESTful Services

Markus Lanthaler 1, 2 Christian Gütl 1, 2

1 2
Institute for Information Systems and Computer Media School of Information Systems
Graz University of Technology Curtin University of Technology
Graz, Austria Perth, Australia
[email protected] [email protected]

ABSTRACT being solved, issues on how to integrate these hugely hetero-

As the amount of data and devices on the Web experiences geneous datasets into a scalable system become increasingly
exponential growth issues on how to integrate such hugely important. Reusing the Web’s underlying architectural style, i.e.,
heterogeneous components into a scalable system become increa- REST [1], has proven to be a viable solution to transform islands
singly important. REST has proven to be a viable solution for of data into an integrated Web of Data. It provides a set of archi-
such large-scale information systems. It provides a set of archi- tectural constraints that, when applied as a whole, result in a
tectural constraints that, when applied as a whole, result in bene- concrete system architecture that “emphasizes scalability of com-
fits in terms of loose coupling, maintainability, evolvability, and ponent interactions, generality of interfaces, independent
scalability. Unfortunately, some of REST’s constraints such as the deployment of components, and intermediary components to
ones that demand self-descriptive messages or require the use of reduce interaction latency, enforce security, and encapsulate
hypermedia as the engine of application state are rarely imple- legacy systems” [1].
mented correctly. This results in tightly coupled and thus brittle While some of REST’s constraints such as stateless interaction,
systems. To solve these and other issues, we present JSON-LD, a uniform interface, identification of resources, or manipulation of
community effort to standardize a media type targeted to resources through representations are well understood, others are
machine-to-machine communication with inherent hypermedia rarely implemented correctly; regardless of a service claiming to
support and rich semantics. Since JSON-LD is 100% compatible be RESTful or not. Primarily the constraints that demand self-
with traditional JSON, developers can continue to use their descriptive messages and require the use of hypermedia as the
existing tools and libraries. As we show in the paper, JSON-LD engine of application state are often ignored. Instead of creating
can be used to build truly RESTful services that, at the same time, specific media types, often, general media types with poor
integrate the exposed data into the Semantic Web. The required semantics are used which results in reduced visibility and requires
additional design costs are significantly outweighed by the out-of-band knowledge to process a message. Similarly, instead
achievable benefits in terms of loose coupling, evolvability, of including valid state transitions in the form of hyperlinks in
scalability, self-descriptiveness, and maintainability. responses sent from the server, such knowledge is often
documented out-of-band and consequently hardcoded into the
Categories and Subject Descriptors client. To solve these issues, there are basically three options.
H.3.4 [Information Storage and Retrieval]: Systems and
Software – Semantic Web, Web 2.0, World Wide Web (WWW). The first one, and often advocated as the cleanest solution, is to
H.4.3 [Information Systems Applications]: Communications create a new media type which specifies the application’s seman-
Applications – Internet. D.2.11 [Software]: Software Archi- tics and supports the required hypermedia controls to fulfill
tectures – Service-oriented architecture (SOA) REST’s hypermedia constraint. Unfortunately, this approach is
not as straightforward as it might seem at the first sight. On one
General Terms hand, it is not trivial to design a media type that is general enough
Design, Standardization for a broad range of applications, yet useful. On other hand it is
difficult to find broad acceptance for a media type that is just
Keywords usable in a very small application domain. Obviously, if the media
Web services; REST; Semantic Web; Linked Data; JSON-LD; type introduces a new serialization format, no existing client
Web of Things libraries can be used to parse representations. This then forces all
clients to implement parsers specifically designed for this new
1. INTRODUCTION media type. While such an approach might provide the best
The Internet has experienced exponential growth, yet, it is possible efficiency, it does not scale when the number of services
expected that in the near future the amount of data generated by or even just the number of entities using different media types in a
machines (e.g. sensors) will exceed that created by humans by single service increases. This is often criticized as media type
several orders of magnitude. While the lower-level technical explosion. In principle the same applies to media types that build
problems of connecting such a large number of machines are on top of existing media types. A common pattern is to add, e.g.,
a +xml suffix to the media type identifier to describe that it is
based on XML’s syntax. Even though this practice has been stan-
Copyright is held by the author/owner(s). dardized, at least for XML for more than a decade, some client
WS-REST 2012, April 2012, Lyon, France. libraries still do not understand it. Furthermore, this pattern cannot
Copyright 2012 ACM 978-1-4503-1190-8/12/04…$5.00 be used in content type negotiation. It can thus just be seen as a
hint to the developer to describe how to process such a repre- their misconceptions, while others are waiting for a killer appli-
sentation. The practice of defining specialized media types for cation making it a classical chicken-and-egg problem. Another
entities might also result in tighter coupled systems at the model common perception is that the Semantic Web is a disruptive
layer as it makes it convenient for developers to reuse them as an technology making it a show-stopper for enterprises needing to
application-level data model which is then shared among all sys- evolve their systems and build upon existing infrastructure
tem components (see [2] for an excellent discussion about the investments. This relies on the fact that RDF is traditionally triple-
different coupling facets). centric whereas most developers program their systems in an
entity centric (think object oriented) manner. Obviously, some
The second option is to extend an existing media type’s appli- developers are also just reluctant to use new technologies. There-
cation semantics with custom semantics. However, even though fore, to mitigate these problems, these “new” technologies have to
the Web is more than two decades old, surprisingly few media be introduced incrementally.
types exist that provide hypermedia support which goes beyond
pure “GET-links” that do not have any support for semantic The XML serialization format of RDF, RDF/XML [19], is a great
annotations. The reason for this is that it is hard to get consensus, example of this. While it has been around for over a decade with
and consequently support, for new processing mechanisms as very little uptake, RDFa [20] had gained a lot of momentum
provided by a media type. The Atom protocol suite ([3], [4]) recently. It uses the same underlying data model as RDF, but
defines media types which are among the most widely used for instead of creating a new serialization format, it is used as a
such an approach. Their main application domain is the syndi- semantic layer on top of the ubiquitous (X)HTML. This gives
cation and manipulation of feeds of articles or blog posts, but Web developers a way to easily add semantic annotations to
since Atom’s model has been specified general and extensible HTML documents. Since this makes it much easier for search
enough to support a broad range of applications, it is often used in engines to extract structured data from Web pages, they started to
other contexts as well; Microsoft’s OData [5], Google’s use it to improve their search algorithms and to present the results
GData [6], and our previous work SAPS [7] are just a few in a visually more appealing way which is a clear incentive for
examples. Such use beyond the original scenario is enabled by developers to annotate their Web pages. The recent introduction
allowing the semantic description of links in feeds as well as in of schema.org can therefore be seen a major step forward for the
entries. Technically this works by setting the rel attribute of the Semantic Web as it allows a broad range of data, ranging from
atom:link element to a custom value instead of using one of the events and recipes to products and people, to be annotated with a
specified values. If an IRI (Internationalized Resource Identifier) shared vocabulary which is understood by all major search
is used to denote such a link’s semantics, a developer can avoid engines. Unfortunately, a similar approach for machines talking to
name collisions and allow users to look its description up by each other via Web services is still missing. This is the gap that
simply dereferencing that IRI. JSON-LD, the approach we are presenting in this paper, is trying
to fill. It uses, similar to RDFa, an already successful syntax, i.e.,
Finally, the third option is to use a completely application- JSON, and adds a semantic layer on top of it.
agnostic media type that focuses on the presentation of raw data
and thus allowing the serialization syntax to be separated from the The remainder of this paper is organized as follows. In section 2
application semantics. XML and JSON are the most popular we give an overview of related work. Then, in section 3, we
media types of that class, but, since both have no inherent support present JSON-LD and its data model. Section 4 shows how
for hyperlinks, it is impossible to use them to build truly RESTful JSON-LD can be used to create evolvable RESTful services and
services without documenting out-of-band how hyperlinks are finally, section 5 concludes the paper and gives an overview of
represented. Traditionally, this was also true for RDF (in all its future work.
serialization formats) as the used IRIs were not meant to be de-
referenced – similar to namespace declarations in XML docu-
ments. This shortcoming, that prevented networking effects to
2. RELATED WORK
arise, was addressed by the introduction of the Linked Data According to ProgrammableWeb’s statistics [8], three out of four
principles [15] which demand dereferenceable HTTP IRIs that APIs are RESTful and roughly half of them use JSON as the data
return useful information. Unsurprisingly, the Semantic Web, or format. It is interesting to observe that some of the most used
Web of Data to avoid unnecessary misconceptions stemming from APIs such as, e.g., Facebook’s Graph API, Twitter’s Streaming
the historically AI-heavy term “Semantic Web”, gained huge API, or Foursquare’s API are now JSON-only. One of the reasons
traction from this initiative. why JSON overtook XML as the primary data format in Web
APIs might be the inherent impedance mismatch between XML
Since the Linked Data principles align well with the REST archi- and object oriented programming constructs (the so called O/X
tectural style (see [17] for an extensive analysis) it would just impedance mismatch) which often results in severe interope-
seem natural to combine their strengths. Nevertheless, the two rability problems. The fundamental problem is that the XML
remain largely separated in practice. Instead of providing Linked Schema language has a number of type system constructs which
Data via RESTful Web services, current efforts deploy centralistic simply do not exist in commonly used object oriented program-
SPARQL endpoints or upload static dumps of the data. This rarely ming languages such as, e.g., Java. This leads to interoperability
reflects the nature of the data, i.e., descriptions of interlinked problems because each program stack has its own way of mapping
resources. In our opinion this stems from the fact that average the various XSD type system constructs to objects in the target
Web developers fear to use Semantic Web technologies; a phe- platform’s programming language and vice versa. Recent exten-
nomenon we denoted as Semaphobia [18]. Developers are often sions for common languages such as Cω or LINQ (Language
overwhelmed by the (perceived) complexity or intimidated by the Integrated Query) for C# or E4X (ECMAScript for XML) for
AI-heavy history of the Semantic Web. The prevalent termi- JavaScript ease handling of XML enormously but are not always
nology, suffused with words such as Ontology, just seems to fuel available. In fact, XML was not even intended to be a generic
data-interchange format but designed as a lightweight subset of sentation will look to a JSON developer; an important aspect for
SGML to simplify electronic publishing in multiple media. the acceptance of such a format. Unfortunately, most of the
approaches fall short in this respect.
In contrast to XML, JSON, the JavaScript Object Notation, was
specifically designed as a lightweight, language-independent data- To overcome these and other shortcomings we introduced
interchange format that is easy to parse and generate. At the same SEREDASj [18] in previous work. It is a description language for
time it is much less complex than XML. But, this simplicity SEmantic REstful DAta Services and focuses on the description of
comes at a price. JSON has neither native hypermedia support, JSON resource representations and their interconnections. It also
nor does it support namespaces or semantic annotations. There allows these representations to be transformed to RDF. From
have been various proposals to solve these shortcomings and all of working with different developers, we found that the separation of
them have in common that they specify a set of reserved key- the description layer and the data is suboptimal as it effectively
words to express certain aspects such as, e.g., hyperlinks. creates a second layer of interconnected resources on top of the
data in JSON documents which increases the cognitive load on the
The most prominent examples of trying to add hypermedia sup- developer. It was difficult for developers to understand documents
port to JSON are probably JSON Schema [10] and it’s trimmed without at the same time looking at the SEREDASj description
down counterpart JSON Reference [11]. Both define a special document. Also, the syntax, which followed JSON Schema’s
keyword $ref to denote a hyperlink. While, as the name suggests, approach, was often considered to be too verbose.
JSON Schema puts that type information in a schema describing
the document, JSON Reference uses the $ref keyword directly After having worked for quite some time on SEREDASj and
within the document. It can thus be seen as a static serialization of having built several promising prototypes, we discovered the
the same type but it lacks support for semantic annotation to JSON-LD project. As it had almost the same goals we were trying
describe its relation to the current document (this is possible with to achieve and followed a very similar approach, we joined the,
JSON Schema). Two related solutions for this issue are HAL and back then, still small community. After understanding its goals
Collection+JSON, but in contrast to the previously mentioned and mindset we decided to discontinue our work on SEREDASj in
approaches which augment JSON, they represent a new media favor of JSON-LD as we believed we could achieve more in less
type on their own. HAL [12] uses the _links keyword instead of time by joining forces, instead of working on similar, yet different
$ref but instead of setting its value directly to the link’s target, an approaches competing to solve similar problems.
object whose keys are the link relations and whose values are the In spite of being a comparatively young project, JSON-LD has
link targets is used. It has also support to embed external already had a turbulent history. According to Manu Sporny [21],
resources within a representation. Often this is important as it the work was started internally at Digital Bazaar in March 2010.
allows applications to greatly decrease the number of required This was shortly before at the W3C RDF Next Steps Workshop
HTTP requests. Collection+JSON [13] is basically a JSON the desire of the community for a JSON-based RDF format was
version of the Atom protocol suite to manage simple lists of enti- found [22]. Consequently the RDF Working Group at W3C
ties. This media type not only specifies how links (which can be started working on a JSON-based RDF serialization on two fronts.
templated) are represented, but also how HTTP can be used to It decided to quickly standardize Talis’ triple-centric
manipulate the various representations. RDF/JSON [9] for RDF experts needing a JSON-based
Similar to the above described proposals, but with a different goal serialization and to incubate on JSON-LD for average Web devel-
in mind, various approaches have been presented to add semantic opers without RDF background. Unsurprisingly, this strategy soon
annotations or namespace support to JSON. These two aspects can ended in a general confusion as to the exact target group it is
be considered to be roughly the same as the idea of semantic attempting to address and what the outcome should be [21]; the
annotations is to define the semantics of a concept in a special group did not share a common vision. Finally, in August 2011
namespace to avoid collisions when the same terms are reused in Thomas Steiner, the appointed co-editor, pulled the “emergency
different documents. The different proposals can be classified into brake” [23] and the work in the RDF Working Group was
two groups based on whether namespaces are supposed to be stopped. Despite these happenings, we continued to work as part
dereferenceable or not. In the first group, where namespaces are of the JSON-LD community to improve the syntax and created a
just used to avoid collisions and are thus not expected to be de- W3C community group [24] instead of waiting for the RDF
Working Group to decide on how to proceed.
referenceable, often DNS-style names (com.example.
projects.namespacesInJSON) are used [14]; the syntactic
differences of the proposals are negligible. The second group of 3. JSON-LD
approaches assumes namespaces to be dereferenceable to be able JSON-LD is an attempt to create a simple method to not only
to retrieve further information about them. As such they are express Linked Data in JSON but also to add semantics to existing
mostly trying to create a JSON serialization format for RDF and JSON documents. It has been designed to be as simple as
thus offer much more functionality such as typing or inter- possible, very terse, and human readable. Furthermore, it was a
nationalization support. As part of their effort to standardize a goal to require as little effort as possible from developers to trans-
JSON serialization format for RDF, the RDF Working group form their plain old JSON to semantically rich JSON-LD. Conse-
already compared most of the existing approaches [16]; therefore quently, an entity-centric approach was followed whereas tradi-
we would like to refer the interested reader to that document for a tional Semantic Web technologies are usually triple-centric. While
detailed comparison. Summarized, it can be said that most of the the initial versions [25] of JSON-LD looked like a more or less
approaches create a new media type with specific processing direct translation of Turtle to JSON, the syntax was changed
mechanisms and that the main differences between them are dramatically in the latest versions and allows now data to be
whether they are triple- or entity-centric and the degree by which serialized in a way that is often indistinguishable from traditional
they rely on microsyntaxes. This determines how familiar a repre- JSON [26]. This is remarkable since JSON is used to serialize a
 1 {
2 "@context": {
3 "foaf": "http://xmlns.com/foaf/0.1/",
4 "title": "foaf:title",
5 "name": "foaf:name",
6 "homepage": {
7 "@id": "foaf:workplaceHomepage",
8 "@type": "@id"
9 }
10 },
11 "@id": "http://me.markus-lanthaler.com",
12 "@type": "foaf:Person",
13 "title": [
14 {"@value":"Dipl.Ing.", "@language":"de"},
15 {"@value":"MSc", "@language": "en"}
16 ],
Subject Object Subject and Value 17 "name": "Markus Lanthaler",
Object 18 "homepage": "http://www.tugraz.at/"
19 }

Figure 1. A Linked Data graph Listing 1. An exemplary JSON-LD document

directed graph that potentially contains cycles while its native data via an HTTP link header, provides a smooth upgrade path for
model is a tree. existing infrastructure as it allows most of the functionality with-
out having to change the contents of an existing document at all.
Figure 1 shows JSON-LD’s data model, a Linked Data graph.
Nodes in the graph are called subjects or objects and edges are Listing 1 contains a simple JSON-LD document that describes a
called properties (predicates in RDF). A subject is a node with at person based on the FOAF vocabulary [27]. First, a prefix for the
least one outgoing edge whereas an object is a node with at least FOAF vocabulary is defined (line 3) in the embedded context
one incoming edge. This implies that a node can be a subject and (lines 2-10) to abbreviate the long concept IRIs. Then, in
an object at the same time. To be unambiguously identifiable and lines 4-7, the three JSON properties title, name, and homepage
referenceable, a subject should be labeled with an IRI. This is not are mapped to concepts in the FOAF vocabulary. Additionally,
a strict requirement though; JSON-LD also supports unlabeled the value of the homepage property is specified to be of the type
nodes. Even though such nodes do not fulfill the requirements of @id, i.e., it is specified to be an IRI (line 8). Finally, in line 11, the
Linked Data, they are supported as they allow certain use cases person described in the document is unambiguously identified by
which require just locally referenceable data. The same applies to an IRI to make it possible to reference this person in other docu-
properties (edges): if they are labeled with an IRI they are refe- ments. The same mechanism allows JSON-LD documents con-
renceable from other documents and thus Linked Data; otherwise taining more information to be transcluded which enables clients
they are just traditional JSON properties that only have a meaning to discover new data by simply following those links; this
in the specific document they are used. The situation is slightly principle is known as Follow Your Nose [28]. By having all data
different for objects. If an object is labeled by an IRI, it is called semantically annotated as in the example, a machine client can be
an object; if it is labeled by something that is not an IRI, e.g. a programmed to “understand” that the document is about a person
number, it is denoted as a value, i.e., a literal in RDF. (line 12) and to figure out which properties specify the person’s
title (and in which language it is; lines 13-16), name (line 17) and
Given the reluctance of average Web developers to use semantic
the homepage of the organization it works for (line 18). A
technologies, huge efforts have been put into JSON-LD so that
JSON-LD publisher is free to choose between using terms that are
developers do not have to be knowledgeable about other semantic
mapped to concept IRIs in a vocabulary via a context as in the
Web technologies. All a developer needs to know is JSON and
example and using these IRIs directly in the document. Since this
two keywords (@context and @id) to use JSON-LD’s basic
flexibility results in variability that makes it more difficult to
functionality. Since JSON-LD is 100% compatible with plain old
JSON, developers can continue to use their existing tools and
libraries. This is especially important for enterprises as it allows 1 [ {
2 "@id": "http://me.markus-lanthaler.com",
them to add meaning to their JSON documents in a way that is not 3 "@type":"http://xmlns.com/foaf/0.1/Person",
disruptive to their operations and is transparent to their current 4 "http://xmlns.com/foaf/0.1/title": [
customers. At the same time JSON-LD is expressive enough to 5 {"@value":"Dipl.Ing.", "@language":"de"},
support all major RDF concepts. 6 {"@value":"MSc", "@language": "en"}
7 ],
The basic idea of JSON-LD is to create a description of the data in 8 "http://xmlns.com/foaf/0.1/name":
the form of a so called context. It links, similarly to SEREDASj 9 [ "Markus Lanthaler" ],
description documents, objects and their properties in a JSON 10 "http://xmlns.com/foaf/0.1/ ↵
document to concepts in an ontology. Furthermore, it allows workplaceHomepage":
values to be type-coerced and language tagged. A context can 11 [ { "@id": "http://www.tugraz.at/" } ]
12 } ]
either be directly embedded in a JSON-LD document or put into a
separate file and referenced from different documents. This, and
the fact that plain old JSON documents can reference a context Listing 2. The expanded form of the document in Listing 1
process the data, JSON-LD specifies two special document 1 @prefix rdf: <http://www.w3.org/1999/02/22-
forms: expanded and compacted. rdf-syntax-ns#> .
2 @prefix foaf: <http://xmlns.com/foaf/0.1/> .
The expanded form (Listing 2) is a JSON-LD document where all 3
terms and prefixes have been expanded into full IRIs and all type 4 <http://me.markus-lanthaler.com>
and language coercions are defined inline so that the context can 5 rdf:type foaf:Person ;
6 foaf:title
be eliminated from the document without losing any information.
7 "Dipl.Ing."@de ,
It can thus be seen as an explicit version of the document. To 8 "MSc"@en ;
assure that the resulting expanded document is easy to work with, 9 foaf:name "Markus Lanthaler" ;
also all properties that allow multiple values are converted to 10 foaf:workplaceHomepage
array form. This is necessary as different properties in a JSON-LD 11 <http://www.tugraz.at/> .
document might map to the same IRI that requires their values to
be merged. The more or less reverse process is compaction. It Listing 3. Triples extracted from Listing 1 converted to Turtle
takes a JSON-LD document and applies a user-specified context
to generate the most compact representation of a document, i.e.,
all full IRIs are translated to short terms (as specified in the transition table and the initial state to understand the communi-
supplied context) and all array values with a single entry are cation which is often not available or not practical. This also
unwrapped from that array form. Compacting Listing 2 with the makes it difficult or virtually impossible to recover from partial
context used in Listing 1 would result in a document equal to failures in such distributed systems.
Listing 1. Please note, however, that compaction is not always the To solve these issues and assure evolvability, the use of hyper-
exact inverse operation for expansion – it is, e.g., impossible to media is a core tenet of the REST architectural style. It refers to
split properties that have been merged to the same full IRI in the use of hypermedia controls in resource representations as a
expansion. Since expansion and compaction can be used together, way of navigating the state machine of an application. “A REST
applications can use them to harmonize data representations by API should be entered with no prior knowledge beyond the initial
translating between different contexts. For greater flexibility, URI (bookmark) and set of standardized media types. […] From
JSON-LD also defines a framing API method [29] which allows a that point on, all application state transitions must be driven by
developer to transform a document into a form that is convenient client selection of server-provided choices that are present in the
to process for a specific application. The developer defines a received representations or implied by the user’s manipulation of
frame, i.e., a template, which is then used to restructure the data those representations.” [30] While the human Web is unques-
contained in an arbitrary JSON-LD document into the desired tionably based on this type of interaction and state control-flow
form. This allows the developer to subsequently work with the where very little is known a priori, machine-to-machine commu-
framed document just as with any other JSON document which nication is often based on static contracts and out-of-band
means that usually all existing JSON tools and workflows can be knowledge resulting in tight coupling. Such approaches might
retained. work in the short term but are condemned to break in the long
Conversion of a JSON-LD document, especially one in the term since assumptions about server resources will break even-
expanded form, to RDF triples is straightforward. A subject, tually as resources evolve over time. Parastatidis et al. [31] define
which could also be used as an object in another triple, is defined the set of legal interactions necessary to achieve a specific,
by @id. All other JSON-LD properties are converted to application-dependent goal as the domain application protocol of
predicates. Finally, literal values are either taken directly from a a service. The protocol defines the interaction rules between the
property’s value, or created by taking the value of @value and different participants. Consequently, the application state is a
adding language (@language) and/or type information (@type). snapshot of the system at an instant in time. This coincides with
The example in Listing 1 could thus be converted to, e.g., a Turtle Fielding’s definition [1] of application state which defines it as the
document as shown in Listing 3. “pending requests, the topology of connected components (some
of which may be filtering buffered data), the active requests on
those connectors, the data flow of representations in response to
4. EVOLVABLE RESTFUL SERVICES those requests, and the processing of those representations as they
WITH JSON-LD are received by the user agent.” Accordingly, the overall system
As mentioned in the introduction, the Hypermedia as the Engine state consists of the application state and the server state. By using
of Application State (HATEOAS) constraint is one of the least the notion of a domain application protocol the phrase
understood constraints, and thus seldom implemented correctly. “hypermedia as the engine of application state” can now be
Annoyed by the fact that a lot of services claim to be RESTful explained as the use of hypermedia controls to advertise valid
regardless of violating the hypermedia constraint, Fielding [30] state transitions at runtime instead of agreeing on static contracts
made it very clear that hypermedia is a fundamental requirement at design time. Changes in the domain application protocol can
but since the term REST is so widely misused, there are efforts in thus be dynamically communicated to clients. This brings some of
the community to look for an alternative term, such as the human Web’s adaptivity to the Web of machines and allows
Hypermedia API, to denote truly RESTful services. the building of loosely coupled and evolvable systems. Rather
than requiring an understanding of a specific IRI structure, clients
A lot of systems, regardless of claiming to be RESTful, rely only need to understand the semantics or business context in
heavily on implicit state control-flow which is characteristic of the which a link appears [31].
RPC-style. The allowed messages and how they have to be inter-
preted depends on previously exchanged messages and thus in The creation of a truly RESTful service can be dramatically sim-
which implicit state the system is in. Third parties or interme- plified by the use of a well-defined, generic media type with
diaries trying to interpret the conversation need the full state inherent hypermedia support. Developers can then fully con-
Management Node process to be further streamlined as it enables the creation of
unit reusable client libraries.

GET / The core process to create a RESTful service would then be to

Access entry point to define and describe the application semantics. Every concept gets
explore service
assigned an IRI where the definition of that concept can be looked
GET /door up. Please note that this process is almost the same as the one
Retrieve door sensor data chosen by, e.g., Atom. The only difference is that instead of
requiring out-of-band knowledge to look up the link relation’s
PUT /door Register callback IRI, i.e., semantics, i.e., the knowledge about the IANA registry [32], the
subscribe to updates semantics can be directly accessed by simply dereferencing the
IRI. A developer could then go a step further and describe the
semantics in a machine processable way. It would, e.g., be
POST /callback possible to describe the allowed value range for a property by
Notify about sensor event using OWL [33], a standardized ontology. This would also make
it possible to automatically check the consistency of a domain
GET / application protocol and to generate human readable docu-
Entry point (cached) mentation from it. Clearly, this goes far beyond what is achievable
with the traditional definition of media types as the descriptions
GET /ac
Access air conditioner can be reasoned with by computer programs.
As a real-world proof of concept for the principles described in
PUT /ac this paper, we have designed and implemented a Web of Things
Switch off air conditioner
consisting of a central management unit and nodes equipped with
sensors and actuators. It clearly illustrates the way in which such a
distributed system can be modeled and implemented by using
Figure 2. Interaction between management unit and node JSON-LD and Semantic Web technologies. For example, assume
we have a node in each room with a door sensor and an air condi-
tioner connected to it. An application running on the management
centrate on defining the domain application protocol instead of
unit could then be programmed to turn the air conditioner off
having to design new media types which often are specializations
when the door is open.
of existing syntaxes. This can be compared to the omnipresence of
HTML and browsers in the human Web where such standar- Figure 2 illustrates how the management unit and the nodes would
dization is already well advanced. JSON-LD was specifically interact. First, the management unit would establish a connection
designed for such purposes. It has built-in support for domain to the node’s entry point. The response could contain a represen-
semantics yet its syntax is completely independent thereof. A tation as shown in Listing 4 (context defined externally for the
developer can thus use JSON-LD as a generic media type for a sake of brevity). In the next step, the application on the manage-
broad range of applications. If Semantic Web technologies, i.e., ment unit would choose which link to follow. Instead of having to
ontologies, are used to express the domain application protocol, it rely on type information (line 12), it would also be possible to
is possible to leverage the rich underlying model and existing create a more specific property than just sensors; this is a
tools for tasks such as data validation or even to make implicit decision the domain application protocol designer has to take.
knowledge explicit. This standardization allows the development Given that the application is interested in the door sensor, it would
dereference the link in line 11 and the node would return a repre-
sentation similar to the one shown in Listing 5. Finally, the
1 { management unit would add its own callback IRI to the list of
2 "@context": "http://api.com/dap.jsonld",
subscribers (lines 7-10). As soon as the reading of the sensor
3 "@id": "/",
4 "location": "http://api.com/room/48", changes, the node would notify all subscribers, which at this point
5 "sensors": [ includes the management unit. This would then trigger a process
6 { similar to the one just described, but this time, the management
7 "@id": "/temperature", unit would look up the air conditioner and update its represen-
8 "@type": "dap:TemperatureSensor" tation to turn it off.
9 },
10 {
11 "@id": "/door", 1 {
12 "@type": "dap:DoorSensor" 2 "@context": "http://api.com/dap.jsonld",
13 } 3 "@id": "/door",
14 ], 4 "@type": "dap:DoorSensor",
15 "actuators": [ 5 "node": "/",
16 { 6 "reading": "dap:closed",
17 "@id": "/ac", 7 "subscribers": [
18 "@type": "dap:AirConditioner" 8 "http://log.example.com/",
19 } 9 "http://accesscontrol.example.com/"
20 ] 10 ]
21 } 11 }
Listing 4. The node's “homepage” Listing 5. The door sensor data
 1 { follow the structure of how JSON is typically used by Web de-
2 "@context": "http://api.com/dap.jsonld", velopers. The syntax is 100% compatible with JSON and flexible
3 "@id": "/", enough to provide a smooth upgrade path for existing infra-
4 "location": "http://api.com/room/48",
5 "sensors": [ structure. This means that developers have to change neither their
6 { workflows nor their existing tools and programming libraries. We
7 "@id": "/temperature", hope this lowers the entry barrier to publish Linked Data in the
8 "@type": "dap:TemperatureSensor", form of RESTful services and results in a broader adoption of the
9 "reading": 32.5, underlying ideas and principles. The additional design costs are
10 "subscribers": [] significantly outweighed by the achievable benefits in terms of
11 }, loose coupling, evolvability, scalability, self-descriptiveness, and
12 {
13 "@id": "/door", maintainability. Our experiments in the context of a large-scale
14 "@type": "dap:DoorSensor", Web of Things project have delivered proofs that the presented
15 "reading": "dap:closed", approach is practical. In fact, JSON-LD could be a first step
16 "subscribers": [ toward standardizing semantic RESTful Web services and could
17 "http://log.example.com/", form the basis for various efforts that previously could not seem
18 "http://accesscontrol.example.com/" to find any common ground. By working with a community with
19 ] different backgrounds, we hope to be able to create a balanced
20 }
21 ], solution that builds on the efforts put into RDF in the last decade
22 "actuators": [ while having the potential to positively affect the Web as a whole.
23 { Given that JSON-LD is still a work in progress, we would like to
24 "@id": "/ac", take the chance to invite the interested reader to join the
25 "@type": "dap:AirConditioner", community at http://www.json-ld.org.
26 "status": "dap:off"
27 } As we have shown, JSON-LD itself is not a complete technology
28 ] stack – it needs ontologies to express domain semantics. In future
29 } work we would like to investigate how a lightweight ontology to
support a wide range of application domains could be modeled.
Listing 6. Optimization of Listing 4 with embedded resources Furthermore, we would like to explore various ideas to create
aiming to reduce the number of required HTTP requests smarter service clients.

While this seems overly chatty, it is worth noting that responses

can be cached and that the developer is free to optimize represen- 6. REFERENCES
tations to reduce the number of required roundtrips. For example, [1] R.T. Fielding, “Architectural styles and the design of
Listing 4 can be cached for long periods as it is not expected to network-based software architectures,” PhD dissertation,
change often. Alternatively, it could be heavily optimized to a Department of Information and Computer Science,
form similar to the one shown in Listing 6 where all the required University of California, Irvine, 2000.
data is directly embedded into the “homepage” instead of being [2] C. Pautasso and E. Wilde, “Why is the Web Loosely
transcluded; obviously this renders caching almost useless as the Coupled? A Multi-Faceted Metric for Service Design,” in
representation would change continuously. Such an optimization Proceedings of the 18th International Conference on World
can be compared to the use of image sprites or data URIs in Wide Web (WWW), 2009, pp. 911-920.
HTML pages to reduce the number of required HTTP requests.
Whilst it is completely acceptable for a service to make such [3] The Atom Syndication Format. [Online]. Available:
structural changes, semantic changes to the domain application http://tools.ietf.org/html/rfc4287.
protocol have to be carefully evaluated as they might change the [4] The Atom Publishing Protocol. [Online]. Available:
contract and break existing consumers relying on them. http://tools.ietf.org/html/rfc5023.
If OWL’s expressivity is used to describe the relationships [5] Open Data Protocol. [Online]. Available:
between different resources, much smarter clients can be built. It http://www.odata.org/.
is, e.g., possible to create a generic crawler which indexes all [6] Google Data Protocol. [Online]. Available:
available sensors; by leveraging OWL’s class hierarchy this http://code.google.com/apis/gdata/.
would also work for sensor types that are still unknown at design
time. Similarly, a logging service can be created that stores [7] M. Lanthaler and C. Gütl, “SAPS: Semantic AtomPub-based
reported sensor readings. It is enough if such a service under- Services,” in Proceedings of the 11th IEEE/IPSJ
stands which property contains the reading; it is not necessary that International Symposium on Applications and the Internet
it understands the reading itself. Such flexibility greatly contri- (SAINT), 2011, pp. 382-387.
butes to the extensibility and evolvability of a system. [8] T. Vitvar and J. Musser, “ProgrammableWeb.com: Statistics,
trends, and best practices,” Keynote of the Web APIs and
5. CONCLUSIONS AND FUTURE WORK Service Mashups Workshop at the European Conference on
Web Services, 2010.
In this paper we presented JSON-LD, a community effort to stan-
dardize Linked Data in JSON. In contrast to previous approaches, [9] RDF/JSON, Talis Systems Ltd., 2011. [Online]. Available:
great efforts have been made to keep the approach as simple as http://docs.api.talis.com/platform-api/output-types/rdf-json.
possible and to create a syntax that results in serializations that [Accessed: 15-Jan-2012].
[10] K. Zyp and G. Court, “JSON Schema”, 2010. [Online]. [22] I. Herman, “W3C Workshop — RDF Next Steps Workshop
Available: http://tools.ietf.org/html/draft-zyp-json- Report,” 2010. [Online]. Available:
schema-03. [Accessed: 18-Jan-2011]. http://www.w3.org/2009/12/rdf-ws/Report.html.
[11] P. Bryan and K. Zyp, “JSON Reference”, 2011. [Online]. [Accessed: 05-Aug-2010].
Available: http://tools.ietf.org/html/draft-pbryan-zyp-json- [23] T. Steiner, “JSON Emergency Brake,” RDF Working Group
ref-01. [Accessed: 20-Dec-2011]. mailing list, 2011. [Online]. Available:
[12] M. Kelly, “HAL - Hypertext Application Language”, 2011. http://lists.w3.org/Archives/Public/public-rdf-
[Online]. Available: http://stateless.co/hal_specification.html. wg/2011Aug/0131.html. [Accessed: 23-Aug-2011].
[Accessed: 20-Dec-2011]. [24] JSON for Linking Data Community Group, W3C Community
[13] M. Amundsen, “Collection+JSON - Document Format”, and Business Groups. [Online]. Available:
2011. [Online]. Available: http://amundsen.com/media- http://www.w3.org/community/json-ld/.
types/collection/format/. [Accessed: 24-Oct-2011]. [25] JSON-LD - Linked Data Expression in JSON, Unofficial
[14] Y. Goland, “Adding Namespaces to JSON”, 2006. [Online]. Draft 30 May 2010. [Online]. Available: http://json-
Available: http://www.goland.org/jsonnamespace/. ld.org/spec/ED/json-ld-syntax/20100529/.
[Accessed: 05-Jan-2012]. [26] JSON-LD Syntax 1.0, Unofficial Draft 26 April 2012.
[15] T. Berners-Lee, “Linked Data,” Design Issues for the World [Online]. Available: http://json-ld.org/spec/ED/json-ld-
Wide Web, 2006. [Online]. Available: syntax/20120426/.
http://www.w3.org/DesignIssues/LinkedData.html. [27] D. Brickley and L. Miller, FOAF Vocabulary Specification
[Accessed: 06-Jun-2010]. 0.98. 2010. [Online]. Available: http://xmlns.com/foaf/spec/.
[16] RDF Working Group, “JSON Serializations by Example”, [Accessed: 17-Jan-2011].
2011. [Online]. Available: http://www.w3.org/2011/rdf- [28] L. Dodds and I. Davis, Linked Data Patterns - A pattern
wg/wiki/JSON-Serialization-Examples. catalogue for modelling, publishing, and consuming Linked
[Accessed: 28-Jul-2011]. Data, 2011, pp. 44-55. [Online]. Available:
[17] K. R. Page, D. C. De Roure, and K. Martinez, “REST and http://patterns.dataincubator.org/book/linked-data-
Linked Data: a match made for domain driven patterns.pdf. [Accessed: 07-Oct-2011].
development?” in Proceedings of the 2nd International [29] The JSON-LD API 1.0, Unofficial Draft 26 April 2012.
Workshop on RESTful Design (WS-REST), 2011, pp. 22-25. [Online]. Available: http://json-ld.org/spec/ED/json-ld-
[18] M. Lanthaler and C. Gütl, “A Semantic Description api/20120426/.
Language for RESTful Data Services to Combat [30] R. T. Fielding, “REST APIs must be hypertext-driven,”
Semaphobia,” in Proceedings of the 2011 5th IEEE Untangled musings of Roy T. Fielding, 2008. [Online].
International Conference on Digital Ecosystems and Available: http://roy.gbiv.com/untangled/2008/rest-apis-
Technologies (DEST), 2011, pp. 47-53. must-be-hypertext-driven. [Accessed: 02-Jun-2010].
[19] RDF/XML Syntax Specification (Revised). [Online]. [31] S. Parastatidis, J. Webber, G. Silveira, and I. S. Robinson,
Available: http://www.w3.org/TR/2004/REC-rdf-syntax- “The Role of Hypermedia in Distributed System
grammar-20040210/. Development,” in Proceedings of the 1st International
[20] RDFa in XHTML: Syntax and Processing. [Online]. Workshop on RESTful Design (WS-REST), 2010, pp. 16-22.
Available: http://www.w3.org/TR/2008/REC-rdfa- [32] Link Relations, IANA. [Online]. Available:
syntax-20081014. http://www.iana.org/assignments/link-relations/link-
[21] M. Sporny, “Linked JSON: RDF for the Masses,” The relations.xml.
Beautiful, Tormented Machine, 2011. [Online]. Available: [33] OWL 2 Web Ontology Language. [Online]. Available:
http://manu.sporny.org/2011/linked-json/. http://www.w3.org/TR/2009/REC-owl2-primer-20091027/.
[Accessed: 28-Apr-2011].