| Thing-to-Thing Research Group | M. Koster |
| Internet-Draft | SmartThings |
| Intended status: Experimental | March 13, 2017 |
| Expires: September 14, 2017 |
Media Types for Hypertext Sensor Markup
draft-koster-t2trg-hsml-01
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 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.
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 http://datatracker.ietf.org/drafts/current/.
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 September 14, 2017.
Copyright (c) 2017 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 (http://trustee.ietf.org/license-info) 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.
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.
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.
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.
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.
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].
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.
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).
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.
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.
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.
Collection representations in HSML include Base Elements, Link Elements, and Item Elements.
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].
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.
{
"href": "temp",
"rt": "some.sensor.temp"
}
Figure 2: Example Link Element
An item element in a collection is a data element that is referenced by a link in the collection.
Items in the collection are indicated by hyperlink references (“href”) that serve as selection variables for matching to URI parameters and resource names (“n”)in multi-resource representataions. Reference resolution should use the rules defined in [RFC3986].
Items may be embedded in the collection, they may be subresources of the collection, or they may be items in other collections referenced by links in the collection. An example item element is shown in Figure 3
{
"n": "temp",
"v": 27
}
Figure 3: Example Item Element
Items may be stored as simple sets of key-value pairs in the context of the collection. Links about these items may be obtained from the collection that contains them.
[
{
"bi": "/sensors/"
},
{
"href": "temp",
"rel": "item"
},
{
"href": "humid",
"rel": "item"
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
Figure 4: Items Embedded in a Collection
Alternatively, items themselves may be stored as single-item collections, pointed to by links in another collection. Items stored as collections may contain an item with a zero length href and name, and a self link for the item as shown in the collection representation of the item in Figure 5. Items stored in this way may be augmented by adding additional resources and link content to the collection. Items stored as collections may offer link format and collection format representations.
base collection:
[
{
"bi": "/sensors/"
},
{
"href": "temp/"
},
{
"href": "humid/"
}
]
"temp" item:
[
{
"bi": "/sensors/temp/"
},
{
"href": "", //may be elided
"rel": ["self","item"]
},
{
"n": "", //may be elided
"v": 27
}
]
"humid" item:
[
{
"bi": "/sensors/humid/"
},
{
"rel": ["self","item"]
},
{
"v": 50
}
]
Figure 5: Items as Separate Collections
Items embedded in collections, and items linked and stored as separate collections, will all be returned using the item representation format as shown in Figure 6. A client interacting with the items representation of the example collection at /sensors/ would not need to understand the difference between embedded items and linked items that exposed similar content.
[
{
"bi": "/sensors/"
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
Figure 6: Example Items Representation
The HSML media type includes multiple content types and interface types [I-D.ietf-core-interfaces] to enable the client to select representations that optimize communication for the workflow. Representation formats include links and items together (collection formats), links alone (link formats), or items alone (item formats).
Link formats are useful for discovery workflow, item formats are useful for interaction with resource state machines, and link+item formats are useful for constructing and modifying resource instances.
In addition to HSML native formats, standard CoRE Link-Format [RFC6690] and SenML formats [I-D.ietf-core-senml] may be exposed.
Figure 7 shows an example document in hsml+json format. This example contains a base element, three link elements, and two item elements.
RETRIEVE /sensors/ accept=application/hsml+json
or
RETRIEVE /sensors/ accept=application/hsml.collection+json
or
RETRIEVE /sensors/
accept=application/hsml+json?if=hsml.collection
Response Payload:
[
{
"bi": "/sensors/"
},
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": "some.sensor.temp"
},
{
"href": "humid",
"rt": "some.sensor.humid"
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
Figure 7: Example Collection Format
The HSML media type defines content formats and corresponding CoRE Interface Types that may select partial representations of the resource for interaction.
Collection formats as shown in Figure 7 expose all of the elements of a resource, including items, links, and link extensions.
Link content formats, when used in an “accept” option or “content-type” option in a transfer header, or when selected by the “if=hsml.link” URI parameter, will select the link elements in the collection for interaction as in Figure 8.
RETRIEVE /sensors/ accept=application/hsml.link+json
or
RETRIEVE /sensors/ accept=application/hsml+json?if=hsml.link
Response Payload:
[
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": "some.sensor.temp"
},
{
"href": "humid",
"rt": "some.sensor.humid"
}
]
Figure 8: Example Lnk Format
CoRE link-format content formats, for example application/link-format+json, select RFC6690 compliant links, and may not include representations of extended links (rel=action, rel=monitor).
Item content formats, when used in an “accept” option or “content-type” option in a transfer header, or when selected by the “if=hsml.item” URI parameter, will select the item elements in the collection for interaction as in Figure 9.
RETRIEVE /sensors/ accept=application/hsml.item+json
or
RETRIEVE /sensors/ accept=application/hsml+json?if=hsml.item
Response Payload:
[
{
"bi": "/sensors/"
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
Figure 9: Example Item Format
URI Parameters for matching link attributes and relations may be used to select items when item representations are being specified using either content-format (accept) or interface parameters (if=). For example:
RETRIEVE /sensors/?if=hsml.item&rt=some.sensor.temp
Response Payload:
[
{
"bi": "/sensors/"
},
{
"n": "temp",
"v": 27
}
]
Figure 10: Item Selection Using Link Parameter
SenML content formats select data records and return SenML compliant resource names. “bn” may optionally be returned when compliant resource names “n” may be resolved through simple string concatenation as per [I-D.ietf-core-senml].
The HSML media type defines URI reference processing and URI Query processing but does not in general define fragment (#) references in URIs.
If fragment references are provided in a particular transfer implementation, they should be used to select single items in collections in accordance with current practice.
The path part of the URI reference used to indicate HSML resources may be used as a reference to a collection or to an item in a collection. Collection references should contain the trailing slash character “/” in accordance with [RFC3986]. Server implementations should return links to collections with the trailing “/”, and should attempt to accept references to collections without the trailing “/” if such references can be used to construct unambiguous references.
References to items in a collection should not contain the trailing “/” character. Servers should return items in response to references that do not contain the trailing “/” character, and should attempt to accept references to items in collections with the trailing “/” if such references can be used to construct unambiguous references.
URI references may be routed to collections in the order in which path segments appear in the reference, from left to right reading the path string, separated by “/” characters.
URI references may alternatively be routed as opaque strings to resources. In this case, the resolution of relative references to items in a collection should be possible by concatenating the relative reference to the context URI of the collection. Note that this may enforce certain naming conventions such as the trailing slash in practice.
URI Parameters, typically mapped as query parameters in HTTP and CoAP, are used for selecting resources, selecting partial representations, and otherwise modifying aspects of the expected or included representation. In this way, they may be considered part of the URI, since they help identify a unique representation to be transferred.
URI Parameters may be used to select resources in a collection for transfer. This is done using the common parameter matching rules specified in [RFC6690].
Resource selection is performed based on matching URI Parameters with Link Parameters of all links in the collection which are exposed by the indicated media type and interface type. URI Parameters listed in Section 10.2 are excluded from the matching process.
The target resource selection depends on the content-format specified in the request or the interface type specified in the URI parameters.
The collection content-formats or interface types select all links and items in the collection, including link extensions. URI parameters included in the request should be matched against link parameters for selecting links and associated items.
The link content formats or interface types select all links in the collection. URI parameters included in the request should be matched against link parameters for link selection.
The item content formats or interface types select all items in the collection. URI parameters included in the request should be matched against link parameters associated with items in the collection for item selection as shown in Figure 10.
When the reference of a request targets a collection resource, using a collection format, the representation may contain both links and items. It is implied that operations using this format will interact with both links and items. The collection format is indicated by using a collection content type in the accept or content-type header, or by specifying a collection interface type e.g. if=hsml.collection.
Retrieve returns a representation of selected elements, consisting of a list of elements in the collection, including base element, links, and optionally representations of items, as shown in Figure 11. Elements may include link extenstions, for example action links and monitor links.
RETRIEVE /sensors/ accept=application/hsml.collection+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": "some.sensor.temp"
},
{
"href": "humid",
"rt": "some.sensor.humid"
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
Figure 11: Retrieve Collection
Update replaces all selected elements in the collection with elements included in the payload. Update operations may include replace (PUT) and partial update (PATCH) oprations where supported in the transfer protocol. The server response should indicate that the resource was Changed.
UPDATE /sensors/?href=temp
content-type=application/hsml.collection+json
Payload:
[
{
"rt": ["some.sensor.temp", "some.other.type"]
}
]
Response: Changed
RETRIEVE /sensors/ accept=application/hsml.collection+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": ["some.sensor.temp", "some.other.type"]
},
{
"href": "humid",
"rt": "some.sensor.humid"
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
Figure 12: Update Item in Collection
Create adds elements to a collection, including links and items, where the elements are specified by representations included in the payload. Hints and directives about the created resource may be included in the payload as link parameters, for example a value for href, specifying the location of the created resource. The server is expected to return the location of created resource instances to the client in a header or other response parameter. For example, the “Location” option in CoAP or “Location” header in HTTP should be used to identify the created resource. The server response should indicate that a resource was Created.
CREATE /sensors/ content-type=application/hsml.collection+json
Payload:
[
{
"href": "barometer",
"rt": "some.sensor.mbar"
},
{
"n": "barometer",
"v": 993
}
]
Response: Created
Location: "barometer"
RETRIEVE /sensors/ accept=application/hsml.collection+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "barometer",
"rt": "some.sensor.mbar"
},
{
"href": "temp",
"rt": ["some.sensor.temp", "some.other.type"]
},
{
"href": "humid",
"rt": "some.sensor.humid"
},
{
"n": "barometer",
"v": 993
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
Figure 13: Create Item in Collection
Delete removes selected elements from the collection. If no elements are selected, delete removes the entire collection. The server response should indicate that the resource was Deleted.
DELETE /sensors/?href=barometer
Response: Deleted
RETRIEVE /sensors/ accept=application/hsml.collection+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": ["some.sensor.temp", "some.other.type"]
},
{
"href": "humid",
"rt": "some.sensor.humid"
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
Figure 14: Delete Item in Collection
When a collection is referenced and the link format is indicated, using a link content format in the header or specifying a link interface type, e.g. if=hsml.link, it is expected that the request will interact with the links in the collection.
Retrieve returns a list containing selected links, as shown in Figure 15.
RETRIEVE /sensors/ accept=application/hsml.link+json
Response Payload:
[
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": ["some.sensor.temp", "some.other.type"]
},
{
"href": "humid",
"rt": "some.sensor.humid"
}
]
RETRIEVE /sensors/?rt=some.sensor.temp
accept=application/hsml.link+json
Response Payload:
[
{
"href": "temp",
"rt": ["some.sensor.temp", "some.other.type"]
}
]
Figure 15: Retrieve Links
Update modifies selected links, replacing link elements with elements included in the payload. Update operations may include replace (PUT) and partial update (PATCH) oprations where supported in the transfer protocol. The server response should indicate that the resource was Changed.
UPDATE /sensors/?href=temp
content-type=application/hsml.link+json
Payload:
[
{
"rt": "some.sensor.temp"
}
]
RETRIEVE /sensors/ accept=application/hsml.link+json
Response Payload:
[
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": "some.sensor.temp",
},
{
"href": "humid",
"rt": "some.sensor.humid"
}
]
Figure 16: Update Links
Create adds links to the collection, where the links are included in the payload. The server response should indicate that the resource was Changed.
CREATE /sensors/ content-type=application/hsml.link+json
Payload:
[
{
"href": "/sensor-group/"
}
]
Response: Changed
RETRIEVE /sensors/ accept=application/hsml.link+json
Response Payload:
[
{
"href": "/sensor-group/"
},
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": "some.sensor.temp",
},
{
"href": "humid",
"rt": "some.sensor.humid"
}
]
Figure 17: Create Links
Delete removes selected links from the collection. The server response should indicate that the resource was Changed. If links point to items in the context of the collection, either remove the items as well as the links, or leave the collection as is and return a method error (Method Not Allowed).
DELETE /sensors/?href=sensor-group
Response: Changed
RETRIEVE /sensors/ accept=application/hsml.link+json
Response Payload:
[
{
"anchor": "/sensors/",
"rel": ["self", "index"]
},
{
"href": "temp",
"rt": "some.sensor.temp",
},
{
"href": "humid",
"rt": "some.sensor.humid"
}
]
Figure 18: Delete Links
Whan a collection is referenced and the item format is indicated, either by including an item content type in the request header or using an item interface type, e.g. if=hsml.item, it is expected that the request will interact with the items in a collection.
Specifying item interaction with a collection invokes the link embedding operations.
Collective operations on items in collections are invoked by using the URI of the collections, along with URI parameters, to select one or more items in the collection.
Items which are compatible with the HSML item format may be returned with multiple items embedded in a single representation.
Retrieve returns a list containing a base element and a composite representation of the selected items as shown in Figure 19.
RETRIEVE /sensors/ accept=application/hsml.item+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"n": "temp",
"v": 27
},
{
"n": "humid",
"v": 50
}
]
RETRIEVE /sensors/?href=temp
accept=application/hsml.item+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"n": "temp",
"v": 27
}
]
Figure 19: Retrieve Items
Update modifies selected items, replacing items in the collection with items included in the payload which match by name “n” value. Update operations may include replace (PUT) and partial update (PATCH) oprations where supported in the transfer protocol. The server response should indicate that the resource was Changed.
UPDATE /sensors/ content-type=application/hsml.item+json
Payload:
[
{
"n": "temp",
"v": 30
}
]
Response: Changed
RETRIEVE /sensors/ accept=application/hsml.item+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"n": "temp",
"v": 30
},
{
"n": "humid",
"v": 50
}
]
Figure 20: Update Items
Create adds new items to the collection along with system-constructed links. Link content is determined by the resource type or traits defined by application semantics. Server is expected to return the location of created resource instances to the client in a header or other response parameter. For example, the “Location” option in CoAP or “Location” header in HTTP should be used to identify the created resource. THe server response should indicate that a resource was Created.
CREATE /sensors/ content-type=application/hsml.item+json
Payload:
[
{
"n": "barometer",
"v": 1002
}
]
Response: Created
RETRIEVE /sensors/ accept=application/hsml.item+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"n": "temp",
"v": 30
},
{
"n": "barometer",
"v": 1002
},
{
"n": "humid",
"v": 50
}
]
Figure 21: Create Items
Delete removes selected items and corresponding links from the collection. The server response should indicate that the resource was Deleted. If no items are selected, return a not found error.
DELETE /sensors/?href=barometer
Response: Deleted
RETRIEVE /sensors/ accept=application/hsml.item+json
Response Payload:
[
{
"bi": "/sensors/"
},
{
"n": "temp",
"v": 30
},
{
"n": "humid",
"v": 50
}
]
Figure 22: Delete Items
When the URI of a reference points to an item in a collection, it is expected that the request will interact with a single item.
Retrieve returns a representation of the item in the content type according to the accept option of the RETRIEVE request, or using a system defined content-format if there is no accept option provided.
RETRIEVE /sensors/temp accept=text/plain
Response Payload:
30
Figure 23: Retrieve One Item
Update replaces the resource state with the state defined in the supplied representation according to the content-type or ct option. Update operations may include replace (PUT) and partial update (PATCH) oprations where supported in the transfer protocol. The server response should indicate that the resource was Changed.
UPDATE /sensors/temp content-type=text/plain
Payload:
33
RETRIEVE /sensors/temp accept=text/plain
Response Payload:
33
Figure 24: Update One Item
Not Defined, application dependent.
Delete removes any links to the item from the collection, and removes the item. If the item is stored as a collection, delete removes the collection. The server response should indicate that the resource was Deleted.
DELETE /sensors/temp
RETRIEVE /sensors/temp accept=text/plain
Response: Not Found
Figure 25: Delete One Item
Group transfer operations are provided by collections that contain links with the “grp” relation value.
Transfer operations which specify the collection URI as target and use the item content format are routed to the resolved URI of each link in the collection that contains the “grp” relation.
URI Parameters used for resource selection and matching are sent to the target URIs of all links that contain the “grp” relation.
Responses from the selected group resources are aggregated and by default returned as a single response. The group response SHOULD be returned as an outer array where such representation is available, for example a JSON array which contains elements consisting of SenML responses.
Optionally, a chunked response may be specified, if provided by the transfer implementation, in which the response from each group member is returned individually within a sequence of responses.
The return code should be based on successful responses from link targets. An implementation of a group collection may choose to allow some rejected responses from link targets, depending on the composition of the link targets. A group may not be required to be composed of link targets that always accept all requests; this is at the discretion of the resource designer.
No mechanism is provided in this document to enable a client to inspect the separate return codes from each group link target resource. Multiple transfer headers may be supplied in some representations, or mapped to metadata in others.
The following examples assume the prior example from Figure 5 indexed by a group collection as in Figure 26.
RETRIEVE /sensor-group/ accept=application/hsml.collection+json
Response Payload:
[
{
"bi": "/sensor-group/"
},
{
"anchor": "/sensor-group/",
"rel": ["self", "index"]
},
{
"href": "/sensors/temp/",
"rel": "grp"
},
{
"href": "/sensors/humid/",
"rel": "grp"
}
]
Figure 26: Example Group Collection
Retrieve requests are routed to each link in the collection that contains the “grp” relation. The response from each link target is returned as an element in an array representation.
RETRIEVE /sensor-group/ accept=application/hsml.item+json
Response Payload:
[
[
{
"bi": "/sensors/temp/"
},
{
"v": 33
}
],
[
{
"bi": "/sensors/humid/"
},
{
"v": 41
}
]
]
Figure 27: Group Retrieve
Update requests are routed to each link in the collection that contains the “grp” relation. The target resource of each group link processes the request, including URI parameters and content format. The result code returned should indicate that the resource is Changed if any resource state may have been updated.
UPDATE /sensor-group/ content-type=application/hsml.item+json
Payload:
[
{
"v": 0
}
]
Response: Changed
RETRIEVE /sensor-group/ accept=application/hsml.item+json
Response Payload:
[
[
{
"bi": "/sensors/temp/"
},
{
"v": 0
}
],
[
{
"bi": "/sensors/humid/"
},
{
"v": 0
}
]
]
Figure 28: Group Update
Create requests are routed to each link in the collection that contains the “grp” relation. In the example shown in Figure 29, an additional named resource is being created within each (collection type) item to hold a location value for that item. The result code should indicate that a resource was Created if any resource was created as a result of the create operation.
CREATE /sensor-group/ content-type=application/hsml.item+json
Payload:
[
{
"n": "location",
"vs": "living room"
}
]
Response: Created
RETRIEVE /sensor-group/ accept=application/hsml.item+json
Response Payload:
[
[
{
"bi": "/sensors/temp/"
},
{
"v": 0
},
{
"n": "location",
"vs": "living room"
}
],
[
{
"bi": "/sensors/humid/"
},
{
"v": 0
},
{
"n": "location",
"vs": "living room"
}
]
]
Figure 29: Group Create
Delete requests are routed to each link in the collection that contains the “grp” relation. In the example shown in Figure 30, the URI parameter ?href=location selects the resource at the relative URI reference “location” at each group link target for delete. The result code should indicate that a resource was Deleted if any resource was deleted as a result of the delete operation.
DELETE /sensor-group/?href=location
Response: Deleted
RETRIEVE /sensor-group/ accept=application/hsml.item+json
Response Payload:
[
[
{
"bi": "/sensors/temp/"
},
{
"v": 0
}
],
[
{
"bi": "/sensors/humid/"
},
{
"v": 0
}
]
]
Figure 30: Group Delete
Actions are hypermedia controls, indicated by a rel=action value in a link, used to construct transfer operations that change the state of resources. The use roughly follows the use of forms in HTML [RFC1866], with semantics more consistent with links. See Section 10.5 for more information.
An example Action element is shown in Figure 31.
{
"rel": "action",
"type": "st.on",
"href": "switchcommand",
"method": "create",
"accept": "text/plain",
"schema": {"type": "string", "enum": ["on"]}
}
{
"rel": "action",
"type": "st.off",
"href": "switchcommand",
"method": "create",
"accept": "text/plain",
"schema": {"enum": ["off"]}
}
Figure 31: Example Action Element
These Action elements inform the client that to perform a type “st.on” or “st.off” action on the context resource, perform a CREATE method on the “switchcommand” URI relative to the context URI, using the text/plain content type, with a payload as defined by the “schema” parameter. This example uses a free-form fragment of JSON-Schema language to differentiate, by action payloads, the “st.on” and “st.off” actions, which are mapped to the same URI and method.
Link Bindings and Monitors are hypermedia controls, indicated by a rel=boundto or rel=monitor value in a link, used to construct transfer operations that consume or expose state changes of resources. A monitor invokes a state transfer operation from the link context to a target resource. A Link Binding follows the semantics defined in [I-D.groves-core-dynlink], and invokes a state transfer in the opposite direction, that is from the link target to the link context.
Monitors use the IANA registered link relation “monitor”, defined in [RFC5989]. Link Bindings use the link relation type “boundto”, defined in [I-D.groves-core-dynlink].
Monitors have a set of accept parameters that indicate how the context resource is being observed, a set of filter parameters that indicate the conditions for generating a state change in the monitor, and a set of target parameters that indicate how state changes are to be applied to the monitor resource. See Section 10.6 for more information.
An example Monitor element is shown in Figure 32.
{
"rel": "monitor",
"href": "tank-level-events",
"content-type": "application/senml+json",
"transfer-method": "create",
"pmin": 600,
"pmax": 3600,
"nbul": 20,
"nbll": 80
}
Figure 32: Example Monitor Element
This Monitor element defines a monitor resource at the “tank-level-events” URI relative to the context URI, which OBSERVEs the context URI, and updates the “tank-level-events” resource using the CREATE method to add JSON items to the collection, according to the given conditional parameters no more frequently than once every 600 seconds, at least once every 3600 seconds, when the reading is in the notification band, which has a lower limit of 80 and wraps around zero to an upper limit of 20. This has the effect of defining a low level alert notification and high level alert notification.
This section defines the common reserved identifiers that are expected to be processed by implementations of HSML clients and servers. There are many more relation types and link parameters defined and registered with IANA. Implementations should not restrict processing to the keywords identified in this document; they should accept all IANA registered keywords as valid identifiers.
Many of the keywords listed are defined in other RFCs and IETF documents. This document does not redefine any existing keywords. Where a definition exists, the existing definition will be used. Where multiple conflicting definitions exist, this document will indicate the required definition.
New definitions are summarized in Section 11.
Identifiers in representations using the HSML media types are assumed to use the default namespace defined in Section 10 of this document. An identifier that does not containan explicit namespace identifier is assumed to be in the default namespace.
For example, if the identifier “method” is encountered and it doesn’t resolve to an IANA registered parameter (reg-parameter in [RFC5988]) resolution should be attempted using the definition of “method” in this document.
The following URI Parameters are used to filter representations according to specific processing rules and should not be used to attempt to match link parameters.
The following keywords are reserved for use in an HSML serialization to indicate elements of a web link
The following keywords are reserved for use in a HSML serialization to indicate types of link relations, and are used for values of “rel”.
The following keywords are reserved for use in a HSML serialization to indicate types of link attributes
The following keywords are reserved for use in a HSML serialization to indicate elements within the serialization. Some of these are defined in [I-D.ietf-core-senml].
The following keywords are reserved for use in a HSML serialization to indicate values of link attributes
Type
Subtypes
Media type strings
(subject to Structured Syntax encoding rules TBD)
The following should be registered in the CoRE dynamic linking draft [I-D.groves-core-dynlink].
These definitions may use the default namespace and do not need to be registered with IANA
Collection representations are resource state encapsulations and may be transmitted and stored as signed objects in order to protect the integrity of data and metadata, including time and embedded access control information.
The collection may include time stamps (bt and t) that are signed with the object data and metadata.
The collection representation may include embedded access control information, also signed with the metadata, that can instruct the server to enforce a particular access policy for transfer requests.
Representations submitted to a server to update the state of a resource (UPDATE, CREATE, DELETE) may also contain embedded signed assertions which may be used by the server to decide whether to apply or reject the update.
Object signing and encryption SHOULD use the mechanisms specified in IETF documents for secure JSON Objects [RFC7516] and CBOR Objects [I-D.ietf-cose-msg] [I-D.selander-ace-object-security].
| [I-D.groves-core-dynlink] | Shelby, Z., Vial, M., Koster, M. and C. Groves, "Dynamic Resource Linking for Constrained RESTful Environments", Internet-Draft draft-groves-core-dynlink-00, July 2016. |
| [I-D.ietf-core-interfaces] | Shelby, Z., Vial, M., Koster, M. and C. Groves, "Reusable Interface Definitions for Constrained RESTful Environments", Internet-Draft draft-ietf-core-interfaces-08, February 2017. |
| [I-D.ietf-core-links-json] | Li, K., Rahman, A. and C. Bormann, "Representing CoRE Formats in JSON and CBOR", Internet-Draft draft-ietf-core-links-json-06, July 2016. |
| [I-D.ietf-core-resource-directory] | Shelby, Z., Koster, M., Bormann, C. and P. Stok, "CoRE Resource Directory", Internet-Draft draft-ietf-core-resource-directory-09, October 2016. |
| [I-D.ietf-core-senml] | Jennings, C., Shelby, Z., Arkko, J., Keranen, A. and C. Bormann, "Media Types for Sensor Measurement Lists (SenML)", Internet-Draft draft-ietf-core-senml-05, March 2017. |
| [I-D.ietf-cose-msg] | Schaad, J., "CBOR Object Signing and Encryption (COSE)", Internet-Draft draft-ietf-cose-msg-24, November 2016. |
| [I-D.selander-ace-object-security] | Selander, G., Mattsson, J., Palombini, F. and L. Seitz, "Object Security of CoAP (OSCOAP)", Internet-Draft draft-selander-ace-object-security-06, October 2016. |
| [REST] | Fielding, R., "Architectural Styles and the Design of Network-based Software Architectures", Ph.D. Dissertation, University of California, Irvine, 2000. |
| [RFC1866] | Berners-Lee, T. and D. Connolly, "Hypertext Markup Language - 2.0", RFC 1866, DOI 10.17487/RFC1866, November 1995. |
| [RFC3986] | Berners-Lee, T., Fielding, R. and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, January 2005. |
| [RFC5988] | Nottingham, M., "Web Linking", RFC 5988, DOI 10.17487/RFC5988, October 2010. |
| [RFC5989] | Roach, A., "A SIP Event Package for Subscribing to Changes to an HTTP Resource", RFC 5989, DOI 10.17487/RFC5989, October 2010. |
| [RFC6690] | Shelby, Z., "Constrained RESTful Environments (CoRE) Link Format", RFC 6690, DOI 10.17487/RFC6690, August 2012. |
| [RFC7252] | Shelby, Z., Hartke, K. and C. Bormann, "The Constrained Application Protocol (CoAP)", RFC 7252, DOI 10.17487/RFC7252, June 2014. |
| [RFC7516] | Jones, M. and J. Hildebrand, "JSON Web Encryption (JWE)", RFC 7516, DOI 10.17487/RFC7516, May 2015. |
| [T2TRG] | IRTF, ., "IRTF Thing to Thing Research Group", 2016. |
| [W3C-WoT] | WoT IG, ., "W3C Web of Things Interest Group", 2016. |