Thing-to-Thing Research Group M. Koster
Internet-Draft SmartThings
Intended status: Experimental July 29, 2016
Expires: January 30, 2017

Media Types for Hypertext Sensor Markup


The scale and scope of the worldwide web has been in part driven by the availability of HTML as a common serialization, data model, and interaction model for structured resources on the web. By contrast, the general use of appropriate hypermedia techniques for machine interfaces has been limited by the lack of a common markup format for serialization and exchange of structured machine resources and sensor/actuator data which includes or embeds standardized hypermedia controls. The IRTF Thing to Thing Research Group [T2TRG] has a charter to investigate the use of REST design style [REST]for machine interactions. The W3C Web of Things Interest Group [W3C-WoT] are investigating abstract hypermedia controls and interaction models for machines. Machine optimized content formats exist for web links [RFC5988] [RFC6690] and for data items [I-D.ietf-core-senml].

Structured data which contains both links and items is known as the collection pattern. This draft describes media types for representation of machine resources structured as collections. A simple, reusable data model is described with a representation format, using a well known set of keywords to expose hypermedia controls, which inform clients how to perform state transfer operations on resources. The underlying assumptions regarding transfer layer processing are specified in this document. The HSML media type described in this document is compatible with SenML and CoRE Link-format by reusing the keyword identifiers and element structures from these content formats. Representations of HSML document content may be obtained in CoRE Link-Format and SenML content formats.

Status of This Memo

This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at

Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."

This Internet-Draft will expire on January 30, 2017.

Copyright Notice

Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents ( in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License.

Table of Contents

1. Scope of this document

This is a broadly scoped document which specifies representation formats, data models, interaction models, transfer mapping, URI processing, and design pattern extensions including actions and monitors.

The features listed above and new features may be specified and extended as needed in other documents which refer to this document.

2. Overview and Use Case Requirements

Use case requirements include the following.

A standardized way to expose self-describing resource representations using embedded hyperlinks and link annotations.

A standardized way of organizing and interacting with resource instances using hypermedia controls such as links and forms.

A standardized encapsulation of resources for modeling things, capabilities, groups, indices, and other common structures.

3. Data Model and Interaction Model

The HSML data model consists of collections containing links which point to items. An instance of a collection is a resource and is identified by a URI.

Links are standard web links as in [RFC5988] or [RFC6690]. Items are identified by links in collections.

Links in a collection may point to items within the context of the collection or they may point to items external to the collection, on the same server or on other servers.

Items are data elements, either within the context the collection, or outide the context of the collection. An instance of an item is a resource and is identified by a URI.

An Item may only be in the context of one collection, but may be identified by any number of links in any number of collections.

Items in the collection that use an HSML compatible data model, for example SenML, see [I-D.ietf-core-senml], may be embedded in the collection and transferred either along with the links or separately from links.

3.1. Informative Representation Examples

JSON formatted examples are used in this document to illustrate normative and informative concepts. Representations in other formats may be derived from the JSON representations. For example, compact binary mappings may be defined using available models.

3.2. Links

Links follow the specifications in [RFC5988] and [RFC6690] with extensions to implement actions and monitors as described in this document and any referencing extension documents.

HSML Links may be stored in Resource Directories for discovery using CoRE Resource Directory [I-D.ietf-core-resource-directory].

3.3. Collections

Collections contain one or more links and extended links, and may contain data items referred to by the links. A representation of a collection may contain both links and data items, plus any extended links such as action forms.

3.4. Link Embedding

Link embedding enables the transfer of one or more items in a collection using a single transfer operation. This document describes two types of link embedding for items in the collection. Batch link embedding allows one or more resource instances (item) to each contribute part of an aggregate (collection) representation. Group link embedding allows a particular operation to be repeated for each member (item) of a group (collection).

3.4.1. Batch operations on multiple items in a collection

A collection of items enables operations on more than one item at a time by exposing a structured a representation of multiple resources in the collection.

Applications may select resources by using URI parameters, and transfer representations of multiple named resources using the HSML or SenML multi-item formats.

3.4.2. Collective operation on groups of linked resources

Resource links in the collection may specify group transfer semantics, where transfer operations are routed to each resource in the collection specified by a group link. Group responses are aggregated using a multi-item format which identifies each item by URI.

4. Abstract Transfer Model

The HSML media type assumes a transfer model capable of interacting with representations using a simple CRUD model, allowing for basic life cycle operations on resources and collections.


Create an instance of a resource as specified using the payload as a constructor. Optionally return a reference to the created resource. Typically uses POST in CoAP [RFC7252] or HTTP, may use PUBLISH in pubsub protocols.

Obtain a representation of the selected resource. Typically uses GET in CoAP or HTTP, could use SUBSCRIBE with message retention in pubsub.

Replace or partially replace the representation of the selected resource. Typically uses PUT or PATCH in CoAP and HTTP, could use PUBLISH in pubsub in the frequent case that CREATE and UPDATE are not needed on the same resource.

Remove the representation of the selected resource. Typically uses DELETE in CoAP or HTTP. There is no natural mapping to pubsub if a remove operation is not provided.

Obtain a sequence of representations of the selected resource, indicating state updates which occur on the resource. Typically uses CoAP Observe, HTTP EventSource, MQTT SUBSCRIBE. OBSERVE is the transfer equivalent of performing a RETRIEVE on the resource immediately following each state change of the resource.

5. Collections

Collection representations in HSML include Base Elements, Link Elements, and Item Elements.

5.1. Base element

A base elements describes the context under which to interpret values embedded in subsequent items within the representation of a collection.

The base identifier element (bi) may contain an absolute URI or an absolute path reference from which to base relative references found in the links. It functions as a base URI embedded in content as per [RFC3986] Section 5.1.1

URI reference follows the definition in [RFC3986] Section 5.

The format of base elements are specified in [I-D.ietf-core-senml]. Figure 1 is an example of a base element.

      "bi": "/sensors/"

Figure 1: Example Base URI

Other base items from SenML are permissible, including base time (bt) and base value(bv). If additional senml base values are present, the client MUST interpret the items in the collection in the context of the applicable base elements. For example, if there is a “bv” or base value elment, all of the returned values from items in the collection MUST be added to the base value as per [I-D.ietf-core-senml].

5.2. Link element

A link element is a hyperlink based on the structure and syntax of [RFC6690] and [I-D.ietf-core-links-json]. An example link element is shown in Figure 2.