IHAN® Developer documentation

Data standards

« Back to index

To make data from different systems inter-operable, as well as to ensure clarity for developers on the platform, the data needs to be standardized. To help with this, data is "productized" - specified in the level of clear inputs and outputs, such as "when provide latitude and longitude, you get back the current weather".

These kinds of Data Product standards should be built by the experts from relevant industry in collaboration within the community around the platform, with some help from relevant experts to advice on how to build generic data standards.

One of the goals of a future phase in the project should be the setting up of an independent standards body to guide the standardization work, but at the early stages we need to work together and the project will be working to provide some of the initial standards required for the proof of concept stage.

How Data Standardization flows

The standards are built using a combination of two specification languages - OpenAPI 3.0 specification is used to define the inputs and outputs, as well as the related validation rules and other required technical specification for how to communicate with the Data Product APIs in practice. Additionally JSON-LD is used to add contextual information to the data - what the fields mean in practice.

The source for the standards is currently stored at github.com/digitalliving/standards/tree/master/draft/DataProducts, and if you need new ones added you should submit a Pull Request on GitHub from your fork.

As an example, the /Weather/Current/Metric Data Product's OpenAPI 3.0 spec and JSON-LD for the response are hosted there.

The OpenAPI 3.0 spec defines the raw communication protocol, how to call the APIs on the Product Gateway when requesting the data product, and what kind of responses you should expect. It can also be used to automatically generate client code, HTML documentation, and so on.

The JSON-LD standard itself is best explained by json-ld.org, but basically it works to augment the responses (potentially requests as well in the future), to provide them additional context.

As a simple example, take the typical response from /Weather/Current/Metric:

{
  "humidity": 75.0,
  "pressure": 1007.0,
  "rain": false,
  "temp": 6.3,
  "windSpeed": 5.7,
  "windDirection": 220.0
}

If we augment that with a reference to the .jsonld specification in its standards, it will look something like this:

{
  "@context": "https://raw.githubusercontent.com/digitalliving/standards/master/draft/DataProducts/Weather/Current/Metric.jsonld",
  "humidity": 75.0,
  "pressure": 1007.0,
  "rain": false,
  "temp": 6.3,
  "windSpeed": 5.7,
  "windDirection": 220.0
}

Now using that input on the JSON-LD Playground you will see how that gets parsed into references to the vocabularies defined in the JSON-LD file's saref and weather prefixes, as well as the various ways it can be transformed, visualized, or signed based on it. This can provide various extra capabilities for interoperability and a real world context that even machines can understand.

Example of a compacted payload:

{
  "https://vocabulary.lifeengine.io/Weather/#rain": false,
  "https://vocabulary.lifeengine.io/Weather/#windDirection": 220,
  "https://vocabulary.lifeengine.io/Weather/#windSpeed": 5.7,
  "https://w3id.org/saref#Humidity": 75,
  "https://w3id.org/saref#Pressure": 1007,
  "https://w3id.org/saref#Temperature": 6.3
}

When creating new specifications, you should strive to find existing vocabularies to refer to, but at this stage it might not be always possible. At the simplest a "vocabulary" is simply a webpage with an explanation on the given element in the JSON object, so e.g. windSpeed, and via the JSON-LD transformation the key windSpeed can be transformed to point to the vocabulary for a more in-depth explanation. This is why we've set up a temporary vocabulary that can be referenced in such cases at github.com/digitalliving/vocabulary, and the generated pages are hosted at vocabulary.lifeengine.io. So for an explanation on the windSpeed key, you would refer to vocabulary.lifeengine.io/Weather/#windSpeed.

Example vocabularies to refer to:

© 2020, IHAN® Project