HyperCat FAQ (Frequently Asked Questions)

A publically editable, community-moderated forum. To edit, just log in using the link at the bottom of the page then click an “edit” link.

What's HyperCat? Who's involved? How do I join?

HyperCat is designed for exposing information about IoT assets over the web. Specifically, it provides as standard way for any client to discover resources that it understands on any server - without a human having to write code (which is otherwise the bottleneck to growing an ecosystem of IoT clients and services).

For a high-level overview, with introductory videos, a list of companies with HyperCat-compliant products, and to join the consortium, visit

A bit more technical

HyperCat 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 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.

Who controls HyperCat?

HyperCat is an open specification, released under permission open-source terms for all to use, and contributed to by the community. The HyperCat foundation holds ownership of the HyperCat trademark and copyright, and manages the ongoing development of the specification.

How do I make my service HyperCat-compliant?

To make your IoT web service/hub HyperCat compliant is very easy. It can be done in 15 minutes. The absolute minimum you must do is to provide a /cat URL

which clients can HTTP GET. This document should be a HyperCat containing information about some of the resources offered by your service.

An example static HyperCat can be found here

Each of the items is a URL of something provided by your service, each of the rel/val pairs provide some extra information about the resource. For more info, have a look here for a short tutorial.

Once you have a HyperCat, there are a range of optional extensions you can provide to support search, editing and so on. But, none of these are mandatory to be HyperCat compliant.

Where can I find the technical specification?

The current draft specification is at version 3.00 and can be found here. It is released under a permissive open-source license.

This draft has been used as the basis for a BSI PAS (will be PAS 212) to be released in early 2016.

HyperCat clients and servers written to older 1.x versions of the specification can become compliant with a simple global search-and-replace of a few field names.

Open source code to use/copy?

Are there any Case Studies about using HyperCat?

In Phase 1 of the HyperCat work (2013-2014), participants of one of the 8 clusters (OpenIoT, lead by ARM) put together some case studies to demonstrate the value of HyperCat to them.

HyperCat security

Does HyperCat support security?

Yes, HyperCat provides mechanisms for:

  • File transfer of HyperCat documents: HTTPS with pre-agreed basic-auth credentials. This is minimal, sufficient for simple use and not overly prescriptive. Users are free to use other mechanisms to agree credentials or secure the transport of HyperCat documents.
  • Digitally signing catalogues and items within them. When complete, this functionality will allow confidence over the provenance of catalogue items.
  • Tagging resources with license and access control metadata, giving a client clues as to the use of resources they find.

The HyperCat approach is to agree and codify where we can, and to remain flexible and open to innovation. Security is a huge topic and we have hopefully left the door open for innovative and interesting solutions to be integrated with HyperCat.

Where does HyperCat security start and stop?

Each HyperCat is simply a catalogue of pointers to Resources, plus metadata to mark-up each Resource (think of it as a web page containing hyperlinks to other web pages, structured so that machines can read it). It is common for a HyperCat to “contain” (point to) other HyperCats, so a machine or human can browse from one catalogue to another before it finds the Resource it's looking for.

HyperCat has a simple security model - whenever a client requests a HyperCat it can present a key (using Basic Auth). What that key “means” is entirely up to the HyperCat server. A key might give access to the whole catalogue, or might give just access to certain parts of it, or change what metadata is visible, or allowing writing into the catalogue, or be a one-time token etc. The important point is that the purpose of the key is to protect access to that catalogue, not to the resources that it points to.

So HyperCat security doesn't protect edge Resources?

No. Let's illustrate with a concrete example: A client reads the root HyperCat catalogue of Hoover Dam Enterprises Inc. and because it presented the correct key it sees a list of Resources, most of which are links to sub-HyperCats listing different subsystems such as dam controls, water level monitors, environmental audits etc. By browsing through the catalogues (presenting the correct keys each time), the client eventually ends-up at a resource which opens a sluice gate. The client then takes a copy of the URI of that resource and sends it to someone malicious. That edge Resource, the sluice gate, is just an object on the Web. It's security model has nothing to do with HyperCat, and it is as secure, or insecure, as it makes itself. One should not rely on “security through obscurity” in HyperCat, any more than on the Web.

How do I find all the HyperCats?

I'd like a jumping-off point where, as a human browsing, or a machine exhaustively crawling, I can start to index all HyperCats

There is no one “root” HyperCat, any more than there is a single global “root” Web page. Because HyperCats often point to other HyperCats, and there is a standard metadata tag to identify such child HyperCats, given any starting point, a machine can exhaustively crawl the graph of all connected HyperCats. Indeed several companies including 1248, ARM, BT and IBM have built prototype HyperCat interactive browsers and automated crawlers that do just that. And a natural way to present the results is in … a HyperCat.

But that doesn't guarantee that there won't be other isolated HyperCat graphs, unconnected to the catalogues you know about. So, as with the Web, the general solution to this problem is search engines. This is complicated by the fact that much of the data in today's HyperCats is not public, so it is not possible for one engine to index everything, because it doesn't have the keys to everything. For this reason, it is worthwhile to make _something_ public in every HyperCat, just so it can be found by search engines, so that people/machines can then ask you for permission to explore further. Think of it as advertising.

The top-level HyperCat for any service supporting HyperCat should generally be found at


What metadata should I use?

HyperCat specifies a minimal set of mandatory metadata to identify itself as a HyperCat. For a HyperCat to be useful, it needs to also include other metadata, describing itself and the items within it. Each piece of metadata is a “rel/val” pair. So what should the rels be?

For a client to be able to discover things it understands in any HyperCat, the client and the server need to agree on what to call things, i.e. what metadata “rel”s labels use in the HyperCat. This is the world of academic-sounding subjects like Semantics, Taxonomies, Ontologies and Schemas. But don't be put off, it's conceptually simple - it's just about agreeing what to call things. If a server has some temperatures and the client understands temperatures, then they should in principle be interoperable. But if in practice the server labels its temperature “degrees” and the client is expects temperature to be labelled “Celsius”, then there is no interoperability.

HyperCat intentionally enforces no rules about metadata naming. It is just the sandpit within which this tough problem can be wrestled over, out in the open, driven by market forces. If company A and company B want to build systems that work together, they will have to pick a common ontology. There are thousands of ontologies out there: some for describing very common things (such as geolocation) and some for describing very specific concepts of interest only to a small number of vertical companies (e.g. vibration). Some are kitchen-sink ontologies, seeking to include labels for everything (a tall order), whilst others are minimalist, just describing one thing. A large ontology can be build from lots of little ones - quite a sensible approach in fact.

HyperCat's cunning twist on metadata is that a 'rel' is a pointer to a naming scheme rather than a literal name, which provides a powerful incentive to point to existing schemes rather than invent your own. Of course, you can still create your own schemes and point to them, but generally you're much better off choosing an existing one if you possibly can. By thus leveraging the URL namespace to guarantee uniqueness, HyperCat helps everyone call a spade a spade and thus converge on common ontologies more quickly. If your client doesn't “just work” with a HyperCat, at least a developer can immediately identify why (by seeing what rels the HyperCat is using). By adding support for those rels, the client is now upgraded to work with anyone else also using that rel. Companies that work in similar sectors will tend to converge to using similar rels, either in some top-down process of defining one ontology to rule them all, or in a bottom-up process of picking one name here, another there, until a commmon ontology (or “folksonomy”) emerges.

What if I need something that HyperCat doesn't support?

HyperCat is extremely extensible: you are free to add any metadata tags you like to either the catalogue or its items, as long as the rel doesn't collide with the few defined in the specification. So you can use whatever schemas you like - ones specific to your industry, or very general ones. You are also free to build new mechanisms around and on top of HyperCat to add functionality to it - the required core of HyperCat is intentionally minimal so there's plenty of room to extend it in new directions.

If you believe that the community as a whole would benefit from adopting some new tag or mechanism that you've invented, then the process is to: 1) Write a proposal, in a form similar to an IETF RFC (Example) and then canvas opinion and support on the HyperCat mailing list for adoption into the next version of the spec.

Does HyperCat support paging?

The topic of Paging includes:

  • Server-driven paging: The ability for a HyperCat server to return a well-formed catalogue, but one which contains only some of the items requested. This could be in response to a GET of the whole catalogue, or a search query. This may be necessary if the server knows that the full catalogue is huge and so the cost of returning it is too large. In this case it's important that the client knows it has received only a partial catalogue, and knows how to access subsequent pages. This is analogous to how Google returns paged search results.
  • Client-driven paging: The ability for a HyperCat client to limit the number of responses in a catalogue. For example if it is a resource-constrained client (e.g. Arduino), or has a UI which can fit only e.g. 10 items. This is analogous to the LIMIT parameter in SQL.

The 3.0 specification does not support paging, but of course anyone is free to extend it. A well-drafted RFC exists here, supporting optional server-driven paging. Written by Sam Mulube of Thingful, this is already implemented and in use, and may be included in a future version of the specification.

How is HyperCat different from X?


There are many other interface description approaches out there (WSDL for SOAP type services, WADL aimed at Restful services). So what was the driver to create something new rather than to adapt something existing? i.e. why are IoT apps / data “special” vs the rest of the web?

HyperCat was shaped by the real-world needs of the companies involved. The participants had strong leanings towards JSON and RESTful APIs, rejecting XML, SOAP and WSDL as were seen as too complex for web developers to easily adopt. With HyperCat, the barrier to entry is very low. Existing web data hubs can add a catalogue of resources, choosing metadata as the developer sees fit.

HyperCat provides a mechanism to expose a list of URIs with RDF-triple style assertions about each one. This is not specific to IoT. However, on top of the defined format (and API), we are developing sets of domain specific metadata (ontologies) for use by different verticals. Those are specific to IoT. Because HyperCat is based on the popular RDF object-subject-predicate model and uses URIs, the metadata used can be cherry picked from existing semantic web ontologies or freely defined by developers according to need.

WADL and WSDL are interface description languages, they allow for the specification of a rigid contract for server and client to follow. This model works fine where both ends are under developer control. But, in a web world, where devices and services are constantly evolving, it’s important that nodes can probe each other to discover commonality, then make a best attempt at interoperability. HyperCat achieves this by encouraging the use of hypermedia types and links to describe data formats and state changes in the HATEOAS REST style.

Here is a brief introduction to the HATEOAS REST constraint in web APIs.

Does HyperCat allow relative Metadata paths?

Yes, the HyperCat spec allows hrefs to be server-relative and path relative, following normal Web URI conventions (RFC1808). This can be hugely convenient, because when part of a HyperCat is being created its creator (a human, a machine or data) may not know where that HyperCat fragment will end-up being served from - and indeed that might change, and it might be served from multiple places. Imagine a 1-million-entry hierarchical HyperCat tree being served from and now you want to serve it from - you don't want to have to change vast numbers of absolute URLs embedded within the catalogue. HyperCat graphs don't have to be organised as hierarchical trees like directories, but they often are, so relative paths can be extremely useful.

Relative paths refresher

Examples for illustration:

  • Absolute path: “” (begins with http: or similar, and includes the ”//”)
  • Server-relative path: ”/devices” (begins with a ”/” so starts at the root of the current server)
  • Path-relative: “fred” (doesn't begin with ”/”, so is relative to the hypercat it's within)

In paths ”.” means the current directory and ”..” means the parent directory (i.e. strip the trailing characters to the last ”/”).

So “fred/joe/../bob” is equivalent to “fred/bob”.

Relative paths in a HyperCat

HyperCat allows relative paths everywhere: in resource pointers (item hrefs), in metadata refs and in metadata vals. In all cases, these relative URLs are relative to the root URL from which the HyperCat itself was sereved (and not, for example, to the href of an item).

So in a HyperCat served from, metadata {rel=“http://X, val=“http:bar”} means that the val is pointing at

Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution 3.0 Unported