HyperCat Developer

# HyperCat

HyperCat is an open, lightweight JSON-based hypermedia catalogue format for exposing collections of URIs. Each HyperCat catalogue may expose any number of URIs, each with any number of RDF-like triple statements about it. HyperCat is simple to work with and allows developers to publish linked-data descriptions of resources.

HyperCat is designed for exposing information about IoT assets over the web. It allows a server to provide a set of resources to a client, each with a set of semantic annotations. Implementers are free to choose or invent any set of annotations to suit their needs. A set of best practices and tools are currently under development. Where implementers choose similar or overlapping semantics, the possibilities for interoperability are increased.

## HyperCat Consortium

As of April 2015, HyperCat 2.0 is being developed by a broad consortium of companies. See http://hypercat.io for more information.

## Video introductions to HyperCat

- https://www.youtube.com/watch?v=xe7WWCtEBUE
 - https://www.youtube.com/watch?v=6Ps8iEGRi1U

# Developer Community

## Mailing list

Public discussion of HyperCat takes place on the mailing list.

http://groups.google.com/a/1248.io/d/forum/hypercat

# Specification

[HyperCat 1.1 Specification](spec1.1.pdf)

# Implementations

## Language bindings

The HyperCat specification has been used in various tools and implemented in several languages.

For a summary see: https://github.com/hypercatiot

### Node.js

ARM R&D have contributed a Node.js module for manipulating HyperCat documents:

https://github.com/HyperCatIoT/node-hypercat

### Java

AlertMe have contributed a Java library for manipulating HyperCat documents:

https://github.com/HyperCatIoT/hypercat-java

### Python

1248 have contributed a Python library for manipulating HyperCat documents:

https://github.com/HyperCatIoT/python-tools

### PHP

SenseTecnic have contributed a PHP library or manipulating HyperCat documents:

https://github.com/HyperCatIoT/hypercat-php

## Tools

### Pathfinder

Pathfinder is a reference standalone HyperCat 1.1 server implementing the API

https://github.com/HyperCatIoT/pathfinder

### cat-server

cat-server is a simple standalone catalogue server

https://github.com/HyperCatIoT/cat-server

# Who is using HyperCat

HyperCat was developed to solve a real need for interoperability amongst 8 consortia:

- DISTANCE (Internet of Schools Things) includes ScienceScope, Intel, Xively, Explorer HQ, Stakeholder Design, University of Birmingham’s Urban Climate Laboratory, UCL Centre for Advanced Spatial Analysis, and The Open University Department of Computing
 - EyeHub includes Flexeye, Open Data Institute, Surrey University, IBM, Guildford Borough Council
 - IoTBay: An Interoperability Hub for IoT Services (IBS), includes SH&BA, EDF, IBM, Westminster City Council, BRE
 - i-MOVE (Internet of Moving Objects and Vehicles Ecosystem) includes Aimes Grid Services, BT, Traak, Avanti, Placr, Merseyside Transport
 - International Airport includes LivingPlanIT, London City Airport, Milligan Retail, Critical Software, AppSherpas, HWC, CrowdVision, and ECM
 - OpenIoT includes 1248.io, ARM, AlertMe, Enlight, Intellisense.io and Badger Pass
 - Smart Streets includes InTouch, Carillion, BalfourBeatty, Amey, Lancaster University
 - Stride (Smart Transport IoT Data Ecosystem) includes BT, Aimes, Ctrl-Shift, University of Cambridge, Dartt Ltd

The work was funded by the UK’s Technology Strategy Board https://connect.innovateuk.org/web/internet-of-things-ecosystem-demonstrator/article-view/-/blogs/the-list-of-8-internet-of-things-clusters

# Examples of using HyperCat

## HyperCat and SenML

HyperCat can point at any resource with a URL or URI. One common resource type (as used by the HyperCat Phase1 OpenIoT cluster) is SenML for representing time-series sensor data.

### SenML

SenML is a media type for representing simple sensor measurements and device parameters.
Representations are available for XML, EXI (Efficient XML Interchange) and JSON.
SenML is defined by http://tools.ietf.org/html/draft-jennings-senml-10

This examples uses just the JSON representation, `application/senml+json`.

Every valid SenML document is a JSON object with an array of event objects.

{
      "e": [
      ]
    }

Each event object contains a name `n`, a value `v` and an optional timestamp `t` in seconds since 01/01/1970 (UNIX epoch).
Events may also contain a units `u` declaration.

Documents may contain a single event with no timestamp (considered to be a "live" value)

Here, our `n` value is a URI giving a unique identifier for this sensor and parameter. This is optional.

{
      "e": [
        { "n": "http://example.org/sensor1/temperature", "v":22.5 }
      ]
    }

Documents may contain declarations of units according to the units registry in the SenML specification.

{
      "e": [
        { "n": "http://example.org/sensor1/temperature", "u": "Cel", "v":22.5 }
      ]
    }

Documents may contain single or multiple timestamped events

{
      "e": [
        { "n": "http://example.org/sensor1/temperature", "u": "Cel", "t": 1234, "v":22.5 },
        { "n": "http://example.org/sensor1/temperature", "u": "Cel", "t": 1235, "v":22.8 },
        { "n": "http://example.org/sensor1/temperature", "u": "Cel", "t": 1236, "v":22.2 }
      ]
    }

Or, events for multiple resources

{
      "e": [
        { "n": "http://example.org/sensor1/temperature", "u": "Cel", "t": 1234, "v":22.5 },
        { "n": "http://example.org/sensor1/light", "u": "lm", "t": 1235, "v":135 },
        { "n": "http://example.org/sensor2/acidity", "u": "pH", "t": 1235, "v":7 }
      ]
    }

To shorten documents and improve readability, an optional base name (`bn`) may be given to be used as a prefix for all resource names. The following two documents are equivalent

{
      "e": [
        { "n": "http://example.org/sensor1/temperature", "u": "Cel", "t": 1234, "v":22.5 },
        { "n": "http://example.org/sensor1/light", "u": "lm", "t": 1235, "v":135 }
      ]
    }

{
      "e": [
        { "n": "temperature", "u": "Cel", "t": 1234, "v":22.5 },
        { "n": "light", "u": "lm", "t": 1235, "v":135 }
      ],
      "bn": "http://example.org/sensor1/"
    }

To shorten documents and improve readability, an optional base time may be given. All times `t` are deltas from the base time (`bt`). The following two documents are equivalent

{
      "e": [
        { "n": "temperature", "u": "Cel", "t": 0, "v":22.5 },
        { "n": "light", "u": "lm", "t": 1, "v":135 }
      ],
      "bn": "http://example.org/sensor1/",
      "bt": 1234
    }

#### SenML with HyperCat

HyperCat is a file format and API designed for discovery of resources by web clients.
Although data can be carried both by SenML resources and in HyperCat catalogues themselves, as a general guide - more static data (metadata) about assets should be in catalogues while sensor readings and rapidly changing values should be in SenML or other resources.

For example, a streetlight is (relatively) immobile so its geographic position should be carried in HyperCat metadata. However, its live power consumption is constantly varying over time and should be provided in a resource pointed to by the catalogue, such as SenML.

Conversely, a vehicle’s geographic position is constantly varying so should be carried in a resource, such as SenML. The license number, make and model of the vehicle could be carried in HyperCat metadata.

When SenML documents are listed in HyperCat, they use the metadata relation

{"rel":"urn:X-tsbiot:rels:isContentType","val":"application/senml+json"}

When listing SenML resources in HyperCat, the HyperCat `href` link should point to the URL of a SenML document.

Individual resources in the SenML document may be named such that they are prefixed by the SenML document’s URL, either manually or by using the `bn` attribute. A data crawler is then able to relate the two from their paths.

Here follows an example catalogue and SenML document:

{
        "item-metadata":[
            {
                "rel":"urn:X-tsbiot:rels:isContentType",
                "val":"application/vnd.tsbiot.catalogue+json"
            },
            {
                "rel":"urn:X-tsbiot:rels:hasDescription:en",
                "val":"Sensor example"
            }
        ],
        "items":[
            {
                "href":"https://example.org/sensor1",
                "i-object-metadata":[
                    {
                        "rel":"urn:X-tsbiot:rels:isContentType",
                        "val":"application/senml+json"
                    },
                    {
                        "rel":"urn:X-tsbiot:rels:hasDescription:en",
                        "val":"Sensor number one"
                    },
                    {
                        "rel":"http://www.w3.org/2003/01/geo/wgs84_pos#long",
                        "val":"-0.57"
                    },
                    {
                        "rel":"http://www.w3.org/2003/01/geo/wgs84_pos#lat",
                        "val":"51.23"
                    }
                ]
            }
        ]
    }

{
        "e":[
            {"n":"temperature", "t":12345, "v":22.5, "u":"Cel"},
            {"n":"temperature", "t":12346, "v":22.7, "u":"Cel"},
            {"n":"temperature", "t":12347, "v":22.4, "u":"Cel"},
            {"n":"power", "t":12345, "v":100, "u":"W"}
        ],
        "bn":"https://example.org/sensor1/"
    }