DeepGraphs Specification

Hypermedia Extensive Rules and Affordances Service Description Language

  • Editor: Michael Petychakis, National Technical University of Athens
  • Created: Monday, October 26 2015
  • Updated: Friday, March 4 2016



DeepGraphs is a simple format that gives a consistent and easy way to hyperlink between resources in your API and describe the possible workflows that the developer has predicted and allows for this. By specifying a number of concepts commonly used in Web APIs, as well as it enables the creation of generic API clients.

Adopting DeepGraphs will make your API explorable, and its documentation easily discoverable from within the API itself. It will also enable all the DeepGraph clients to interact with it, while developers would have to configure them in a high level.

DeepGraphs is focusing on JSON-LD as it fits more natural to serialise the advanced rules that are going to be exchanged. Thus, all information could be encoded to RDF and treated accordingly.

Status of This Document

This document is merely a public working draft of a potential specification. It has no official standing of any kind and does not represent the support or consensus of any standards organisation.



This specification describes the conformance criteria for DeepGraphs API documentations and DeepGraphs clients. This criteria is relevant to authors, authoring tool implementers, and client implementers. All authoring guidelines, diagrams, examples, and notes in this specification are non-normative, as are all sections explicitly marked as non-normative. Everything else in this specification is normative.

The key words must, must not, required, shall, shall not, should, should not, recommended, not recommended, may, and optional in this specification have the meaning defined in RFC2119.

DeepGraphs at a glance

DeepGraphs aims to be a specification for the Internet of Things. Its main goal is to stand as an interoperability layer between server and client implementations. This will happen through a specification that takes into account most of the behaviour in today’s web and automate this.

Designing a new API

While designing a new DeepGraphs a API the developer has to bear in mind that first he needs to define a finite state machine of all the possible situations of the client server interaction. To describe the API, any Hypermedia standard will work to show the map of all the possible paths that the client has to follow. This finite state machine is going to be encoded in SWRL (maybe also RuleML is going to be supported in the future, or depending on the implementation).

Designing a new client

Clients are a little bit different to what has already been widely adopted in the web nowadays. Clients are generic reasoners that depending on their goals, they follow the paths according to the event driven reasoning that has been sent to them by the server. They actually in practice consume all the map by the Hypermedia API and also they have the rules provided as a compass on what to do next at every moment. Following this logic, DeepGraphs client could interact with several servers simultaneously or even implement combined transactions on those servers.

Using DeepGraphs


In this section we are going to describe into more detail about the core principles behind DeepGraphs Specification. If you would like to involve yourself deeper into the theory behind all this, you can read more at the Theoretical Background section or contact me directly.

DeepGraphs Model

The DeepGraphs conventions revolve around representing three simple concepts: Resources, Links and FSM.


The DeepGraphs conventions revolve around representing four simple concepts:

  • Affordances are classes representing the possible actions that an agent can actually execute against a digital resource. Thus, this class is a subclass of the union of hydra.
  • Processes is a property that defines that of the aforementioned defined property “affordances”, can be executed in parallel, and which ones need to be executed serially.
  • Constraints are actually the rules that describe the integrity constraints of the transactions and the steps of those transactions, meaning the FSM. Those FSM consist of the series of steps for all possible scenarios from each situation. Error Handling in unforeseen situations, is also described and included in this part of the document. Those are the core for synchronising multiple FSM clients.
  • Duration is actually a property for processes by it is explained here separately because it is really important and needs a specific focus. The web is a fragmented global space, meaning that a transaction that happens in one place, in a specific time zone will most probably have some parts of it executed in a distributed manner in some other places, some other time zones. So, if a request needs to be executed under specific time constraints, those changes dramatically due to this fragmentations as well as the time delays added to each receiver by the network latency. For this reason the notion of relative time was added in the HTTP 1.1 specification and each time reference we make is based on that one.

A series of steps All possible scenarios from each situation Error Handling in unforeseen situations

Hypermedia and Rules

Since this is the core proposition of the proposed specification we need to explain further why DeepGraphs are extending Hypermedia practices.

The Structure of a DeepGraph Document

Minimum valid document

A DeepGraph document must at least contain an empty resource.

An empty JSON object:



Finite State Machine

At the end of it, there is the Finite State Machine, in a SWRL format. This is recognised by ‘fsm’ tag. An empty such document will be like below.

“fsm”: {


For information into a more concrete example onto a whole DeepGraph document you can find here.

In  order to better understand the overall structure of a full example of FSM based on rules you can see some of the public examples of Fluent Editor below:



Here there are going to be two lists. Since the DeepGraphs is a specification both for designing servers and clients, we are going to keep a list for server implementations and one for clients.

Server Libraries

Client Libraries


Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s