DeepGraphs Specification

Hypermedia Extensive Rules and Affordances Service Description Language

logo_full.png

  • Editor: Michael Petychakis, National Technical University of Athens
  • Created: Monday, October 26, 2015
  • Updated: Friday, January 21, 2018

 

Abstract

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 the 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 at a high level.

DeepGraphs is focusing on JSON-LD as it fits more natural to serialize 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 organization.

Introduction

Conformance

This specification describes the conformance criteria for DeepGraphs API documentation and DeepGraphs clients. This criterion 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 behavior in today’s web and automates this.

Designing a new API

While designing a new DeepGraphs an 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

Background

In this section, we are going to describe in 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.

Resources

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 synchronizing 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 fragmentation 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.

 

Negotiation

A major advancement of the methodology is the ability to negotiate. For more information visit here.

The Structure of a DeepGraph Document

Minimum valid document

A DeepGraph document must at least contain an empty resource.

An empty JSON object:

{}
Resources

{}
Links

{}
Finite State Machine

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

{
“fsm”: {
#Rules
}
}

Example

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:

  1. http://www.cognitum.eu/semantics/Examples/GoodRelations.aspx
  2. http://semanticweb.org/wiki/GoodRelations#Example
  3. http://www.cognitum.eu/semantics/Examples/FIBO.aspx#at_pco=smlwn-1.0&at_si=563f78ee4ba8a1d8&at_ab=-&at_pos=0&at_tot=1

Libraries

In this section, we aim to document the latest software developments around the specification.