HyperCat Overview

Toby Jaffey <toby@1248.io>

Catalogues and Resources

Servers provide catalogues of resources to
clients.
A catalogue is an array of URIs.

Resource Metadata
Each resource in the catalogue is annotated
with metadata (RDF-like triples)

Interoperability of Metadata
Using the same metadata annotations in
multiple catalogues creates points of
interoperability.

Client Model
Clients accumulate one or more catalogues into
a knowledge graph, then query that graph

HyperCat Format
HyperCat is designed to be easy to work with:
JSON
Flexible metadata model (triples)
URIs for everything
Served over HTTP/HTTPS

Empty Catalogue
Servers should serve a catalogue on http://hub.
com/cat
The catalogue is a JSON document with MIME type
application/vnd.tsbiot
{
"metadata":[
{
"rel":"urn:X-tsbiot:rels:isContentType",
"val":"application/vnd.tsbiot.catalogue+json"
},
{
"rel":"urn:X-tsbiot:rels:hasDescription:en",
"val":"Minimal empty catalogue"
}
],
"items":[]
}

(This is the minimum valid response, though it doesn't provide much interop potential...)

Bare Catalogue (minimal metadata)

Every item must have a URI and mandatory metadata
items
{
"metadata":[
{
"rel":"urn:X-tsbiot:rels:isContentType",
"val":"application/vnd.tsbiot.catalogue+json"
},
{
"rel":"urn:X-tsbiot:rels:hasDescription:en",
"val":"Bare catalogue"
}
],
"items":[
{
"href":"http://hub.com/resource1",
"metadata":[
{
"rel":"urn:X-tsbiot:rels:hasDescription:en" ,
"val":"The first resource"
}
]
},
{
"href":"http://hub.com/resource2",
"metadata":[
{
"rel":"urn:X-tsbiot:rels:hasDescription:en" ,
"val":"The second resource"
}
]
}
]

(An app client can now fetch a list of resources,

but still knows nothing about them)

Typed Catalogue
Annotate every item with a MIME type
{
"metadata":[
{
"rel":"urn:X-tsbiot:rels:isContentType",
"val":"application/vnd.tsbiot.catalogue+json"
},
{
"rel":"urn:X-tsbiot:rels:hasDescription:en",
"val":"Typed catalogue example"
}
],
"items":[
{
"href":"http://hub.com/resource1",
"metadata":[
{
"rel":"urn:X-tsbiot:rels:hasDescription:en",
"val":"Census data in CSV format"
},
{
"rel":"urn:X-tsbiot:rels:isContentType",
"val":"text/csv"
}
]
}
]
}

(An app client can now tell which resources it is

capable of consuming by format)

API Discovery
A catalogue can advertise API mechanisms using its
metadata
{
"metadata":[
{
"rel":"urn:X-tsbiot:rels:supportsSearch",
"val":"urn:X-tsbiot:search:simple"
},
...
],
"items":[...]
}

Accessing Resources
Resources are addressed by URL
The scheme, port and path tell a client how and where to
access a resource
http://server.com:80/path
https://server.com/path
mqtt://broker.com:1883/topic
coap://device.com/light