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 Abstract 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. 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 http://datatracker.ietf.org/drafts/current/. Koster Expires September 14, 2017 [Page 1] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 Notice 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. Table of Contents 1. Scope of this document . . . . . . . . . . . . . . . . . . . 4 2. Overview and Use Case Requirements . . . . . . . . . . . . . 4 3. Data Model and Interaction Model . . . . . . . . . . . . . . 4 3.1. Informative Representation Examples . . . . . . . . . . . 5 3.2. Links . . . . . . . . . . . . . . . . . . . . . . . . . . 5 3.3. Collections . . . . . . . . . . . . . . . . . . . . . . . 5 3.4. Link Embedding . . . . . . . . . . . . . . . . . . . . . 5 3.4.1. Batch operations on multiple items in a collection . 6 3.4.2. Collective operation on groups of linked resources . 6 4. Abstract Transfer Model . . . . . . . . . . . . . . . . . . . 6 5. Collections . . . . . . . . . . . . . . . . . . . . . . . . . 7 5.1. Base element . . . . . . . . . . . . . . . . . . . . . . 7 5.2. Link element . . . . . . . . . . . . . . . . . . . . . . 7 5.3. Item element . . . . . . . . . . . . . . . . . . . . . . 8 5.3.1. Items embedded in the collection . . . . . . . . . . 8 5.3.2. Items stored as collections . . . . . . . . . . . . . 9 6. Representation Formats . . . . . . . . . . . . . . . . . . . 11 6.1. Example Serialization Formats . . . . . . . . . . . . . . 11 6.1.1. Collection Formats . . . . . . . . . . . . . . . . . 12 6.1.2. Link Formats . . . . . . . . . . . . . . . . . . . . 13 6.1.3. Item Formats . . . . . . . . . . . . . . . . . . . . 13 7. URI and Parameter Processing . . . . . . . . . . . . . . . . 15 7.1. URI Path Processing . . . . . . . . . . . . . . . . . . . 15 7.2. URI Parameter processing . . . . . . . . . . . . . . . . 15 Koster Expires September 14, 2017 [Page 2] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 7.2.1. Resource selection . . . . . . . . . . . . . . . . . 16 8. Transfer Model Mapping to Collections . . . . . . . . . . . . 16 8.1. Target Resource is Collection, Format is Collection . . . 16 8.1.1. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 16 8.1.2. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 17 8.1.3. CREATE . . . . . . . . . . . . . . . . . . . . . . . 18 8.1.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 20 8.2. Target Resource is Collection, Format is Link . . . . . . 21 8.2.1. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 21 8.2.2. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 21 8.2.3. CREATE . . . . . . . . . . . . . . . . . . . . . . . 22 8.2.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 23 8.3. Target Resource is Collection, Format is Item . . . . . . 24 8.3.1. Link Embedding Items . . . . . . . . . . . . . . . . 24 8.3.2. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 24 8.3.3. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 25 8.3.4. CREATE . . . . . . . . . . . . . . . . . . . . . . . 26 8.3.5. DELETE . . . . . . . . . . . . . . . . . . . . . . . 27 8.4. Target Resource is Item . . . . . . . . . . . . . . . . . 28 8.4.1. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 28 8.4.2. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 28 8.4.3. CREATE . . . . . . . . . . . . . . . . . . . . . . . 29 8.4.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 29 8.5. Groups . . . . . . . . . . . . . . . . . . . . . . . . . 29 8.5.1. RETRIEVE . . . . . . . . . . . . . . . . . . . . . . 30 8.5.2. UPDATE . . . . . . . . . . . . . . . . . . . . . . . 31 8.5.3. CREATE . . . . . . . . . . . . . . . . . . . . . . . 32 8.5.4. DELETE . . . . . . . . . . . . . . . . . . . . . . . 33 9. Link extensions . . . . . . . . . . . . . . . . . . . . . . . 34 9.1. Actions . . . . . . . . . . . . . . . . . . . . . . . . . 34 9.2. Link Bindings and Monitors . . . . . . . . . . . . . . . 35 10. Reserved Identifiers . . . . . . . . . . . . . . . . . . . . 36 10.1. Default namespace . . . . . . . . . . . . . . . . . . . 37 10.2. URI Processing Parameters . . . . . . . . . . . . . . . 37 10.3. Link Keywords . . . . . . . . . . . . . . . . . . . . . 37 10.3.1. Link Relation Types . . . . . . . . . . . . . . . . 38 10.3.2. Link Attribute Types . . . . . . . . . . . . . . . . 38 10.4. Item Keywords . . . . . . . . . . . . . . . . . . . . . 38 10.5. Link Parameters used in Actions . . . . . . . . . . . . 39 10.6. Link Parameters used in Link Bindings and Monitors . . . 40 10.7. Conditional Observe Parameters used in Monitors . . . . 41 10.8. Link Attribute Values . . . . . . . . . . . . . . . . . 41 11. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 42 11.1. Media Types . . . . . . . . . . . . . . . . . . . . . . 42 11.2. CoRE Parameters Content Formats . . . . . . . . . . . . 43 11.3. Link Parameters . . . . . . . . . . . . . . . . . . . . 43 11.4. Link Relation Types . . . . . . . . . . . . . . . . . . 44 11.5. New CoRE Interface Types . . . . . . . . . . . . . . . . 44 Koster Expires September 14, 2017 [Page 3] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 11.6. Transfer Layer Methods . . . . . . . . . . . . . . . . . 44 12. Security Considerations . . . . . . . . . . . . . . . . . . . 44 12.1. Object Signing . . . . . . . . . . . . . . . . . . . . . 44 12.2. Signed Embedded Time Stamps . . . . . . . . . . . . . . 44 12.3. Signed Embedded Access Control . . . . . . . . . . . . . 45 12.4. Secure State Updates . . . . . . . . . . . . . . . . . . 45 12.5. Object Signing and Encryption . . . . . . . . . . . . . 45 13. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 45 14. Informative References . . . . . . . . . . . . . . . . . . . 47 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 48 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. Koster Expires September 14, 2017 [Page 4] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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). Koster Expires September 14, 2017 [Page 5] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 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. RETRIEVE Obtain a representation of the selected resource. Typically uses GET in CoAP or HTTP, could use SUBSCRIBE with message retention in pubsub. UPDATE 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. DELETE 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. OBSERVE Koster Expires September 14, 2017 [Page 6] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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. Koster Expires September 14, 2017 [Page 7] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 { "href": "temp", "rt": "some.sensor.temp" } Figure 2: Example Link Element 5.3. Item 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 5.3.1. Items embedded in the collection 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. Koster Expires September 14, 2017 [Page 8] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 [ { "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 5.3.2. Items stored as collections 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. Koster Expires September 14, 2017 [Page 9] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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/ Koster Expires September 14, 2017 [Page 10] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 6. Representation Formats 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. 6.1. Example Serialization Formats Figure 7 shows an example document in hsml+json format. This example contains a base element, three link elements, and two item elements. Koster Expires September 14, 2017 [Page 11] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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. 6.1.1. Collection Formats Collection formats as shown in Figure 7 expose all of the elements of a resource, including items, links, and link extensions. Koster Expires September 14, 2017 [Page 12] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 6.1.2. Link Formats 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). 6.1.3. Item Formats 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. Koster Expires September 14, 2017 [Page 13] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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]. Koster Expires September 14, 2017 [Page 14] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 7. URI and Parameter Processing 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. 7.1. URI Path Processing 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. 7.2. URI Parameter processing 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. Koster Expires September 14, 2017 [Page 15] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 7.2.1. Resource selection 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. 8. Transfer Model Mapping to Collections 8.1. Target Resource is Collection, Format is Collection 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. 8.1.1. RETRIEVE 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. Koster Expires September 14, 2017 [Page 16] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.1.2. UPDATE 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. Koster Expires September 14, 2017 [Page 17] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.1.3. CREATE 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 Koster Expires September 14, 2017 [Page 18] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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", Koster Expires September 14, 2017 [Page 19] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 "v": 27 }, { "n": "humid", "v": 50 } ] Figure 13: Create Item in Collection 8.1.4. DELETE 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 Koster Expires September 14, 2017 [Page 20] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 8.2. Target Resource is Collection, Format is Link 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. 8.2.1. RETRIEVE 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 8.2.2. UPDATE 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 Koster Expires September 14, 2017 [Page 21] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.2.3. CREATE Create adds links to the collection, where the links are included in the payload. The server response should indicate that the resource was Changed. Koster Expires September 14, 2017 [Page 22] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.2.4. DELETE 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). Koster Expires September 14, 2017 [Page 23] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.3. Target Resource is Collection, Format is Item 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. 8.3.1. Link Embedding Items 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. 8.3.2. RETRIEVE Retrieve returns a list containing a base element and a composite representation of the selected items as shown in Figure 19. Koster Expires September 14, 2017 [Page 24] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.3.3. UPDATE 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. Koster Expires September 14, 2017 [Page 25] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.3.4. CREATE 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. Koster Expires September 14, 2017 [Page 26] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.3.5. DELETE 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. Koster Expires September 14, 2017 [Page 27] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.4. Target Resource is Item 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. 8.4.1. RETRIEVE 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 8.4.2. UPDATE 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. Koster Expires September 14, 2017 [Page 28] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 UPDATE /sensors/temp content-type=text/plain Payload: 33 RETRIEVE /sensors/temp accept=text/plain Response Payload: 33 Figure 24: Update One Item 8.4.3. CREATE Not Defined, application dependent. 8.4.4. DELETE 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 8.5. Groups 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. Koster Expires September 14, 2017 [Page 29] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.5.1. RETRIEVE 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. Koster Expires September 14, 2017 [Page 30] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 RETRIEVE /sensor-group/ accept=application/hsml.item+json Response Payload: [ [ { "bi": "/sensors/temp/" }, { "v": 33 } ], [ { "bi": "/sensors/humid/" }, { "v": 41 } ] ] Figure 27: Group Retrieve 8.5.2. UPDATE 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. Koster Expires September 14, 2017 [Page 31] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.5.3. CREATE 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. Koster Expires September 14, 2017 [Page 32] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 8.5.4. DELETE 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 Koster Expires September 14, 2017 [Page 33] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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 9. Link extensions 9.1. Actions 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. Koster Expires September 14, 2017 [Page 34] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 { "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. 9.2. Link Bindings and Monitors 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 Koster Expires September 14, 2017 [Page 35] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 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. 10. Reserved Identifiers 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. Koster Expires September 14, 2017 [Page 36] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 10.1. Default namespace 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. 10.2. URI Processing Parameters 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. "if" Interface type, used to select a partial representation of a collection "count" Indicates the number of items to be returned from the collection "start" Indicates the array index of the item in the collection to select as the first item to be returned "page" Page number, in units of count 10.3. Link Keywords The following keywords are reserved for use in an HSML serialization to indicate elements of a web link "anchor" Overrides the default resource context of the link "rel" Link relation type as defined in [RFC5988] and [RFC6690] "href" Target of a link reference. This may be a relative path reference in the collection, e.g. "currentValue" or an absolute path reference on the server, "/sensors/temp/currentValue", or an absulute URI, for example "https://example.com/sensors/temp/ currentValue" Koster Expires September 14, 2017 [Page 37] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 10.3.1. Link Relation Types The following keywords are reserved for use in a HSML serialization to indicate types of link relations, and are used for values of "rel". "self" Refers to the collection that contains the link "item" The link points to an item in the collection, indicating eligibility for collective interaction using link embedding as described in Section 3.4 and Section 8.3.1. "grp" The item the link points to is available for collective interaction through the collection URI according to group semantics described in Section 8.5. 10.3.2. Link Attribute Types The following keywords are reserved for use in a HSML serialization to indicate types of link attributes "rt" The resource type(s) of the item "u" Units of measure "ct" The CoAP content-format number(s) associated with the item "content-type" The media type string(s) associated with the item "obs" Presence of this attribute indicates that the associated resource is observable 10.4. Item Keywords 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]. "bi" Koster Expires September 14, 2017 [Page 38] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 The base URI of the collection, relative to the service location e.g. "/sensors/temp/" Thi sis a new definition for HSML "bt" The base time that corresponds to the encapsulated state of the collection "t" The time stamp that corresponds to the encapsulated state of the item in the collection, relative to the base time "bt" "n" The name or URI of the resource, relative to the base name or base URI "u" Units of measure "v" Number value "vb" Boolean value "vs" String value 10.5. Link Parameters used in Actions "anchor" May override the default context of an action "rel" Indicates that this control is an action when rel contains the value "action" "href" URI for mapping or invoking the action specified in the action control. "type" Additional indicator of the action being exposed, can be used with "rel" "method" Transfer method to use on a particular action "accept" Koster Expires September 14, 2017 [Page 39] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 The Content-Types or CoAP content-formats that are accepted on create and update methods "content-type" The media type string(s) that are exposed by retrieve and observe methods "ct" The CoAP content-format number(s) exposed "schema" Indicates the schema to use for constructing or interpreting transfer payloads, may be a literal value or a URI pointing to an instance of a schema 10.6. Link Parameters used in Link Bindings and Monitors "anchor" May override the context URI of a link binding or monitor with any observable resource "rel" Indicates that this control is a monitor when rel contains the value "monitor" or a link binding when rel contains the value "boundto" "href" The URI of the resource used to monitor context URI, where transfer operations will be sent. "accept" The media type string or CoAP content-format to request from the observed resource "content-type" The media type string to use in the transfer operation "ct" the CoAP content-format number to use in the transfer operation "accept-method" (HSML extension) Transfer method to use in request from the observed resource, default is OBSERVE "transfer-method" (HSML extension) Transfer method to use for notifications, default is UPDATE Koster Expires September 14, 2017 [Page 40] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 "accept-schema" (HSML extension) Schema to use in interpreting the observed resource payload, required if transfer-schema is used. "transfer-schema" (HSML extension) Schema to use in constructing the notification transfer payload, default is to transfer the accepted payload unmodified to the target resource. 10.7. Conditional Observe Parameters used in Monitors "pmin" Minimum time between notifications from a monitor "pmax" Maximum time between notifications from a monitor "gth" Value to match or exceed to determine notification condition "lth" Value to match or be less than to determine notification condition "st" Value change +/- from last report to determine notification condition "eq" Value to match, or change from, to determine notification condition "bmn" Defines a lower limit, at or above which notification is enabled "bmx" Defines an upper limit, at or below which notification is enabled "iv" Starts the notification state machine with an initial value 10.8. Link Attribute Values The following keywords are reserved for use in a HSML serialization to indicate values of link attributes "create" Transfer layer CREATE operation, value of "method" or "target- method" Koster Expires September 14, 2017 [Page 41] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 "retrieve" Transfer layer RETRIEVE operation, value of "method" or "accept- method" "update" Transfer layer UPDATE operation, value of "method" or "target- method" "delete" Transfer layer DELETE operation, value of "method" or "target- method" "observe" Transfer layer OBSERVE operation, value of "method" or "accept- method" 11. IANA Considerations 11.1. Media Types Type o application Subtypes o hsml o hsml.collection o hsml.link o hsml.item Media type strings o application/hsml o application/hsml.collection o application/hsml.link o application/hsml.item o application/hsml+json o application/hsml.collection+json Koster Expires September 14, 2017 [Page 42] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 o application/hsml.link+json o application/hsml.item+json 11.2. CoRE Parameters Content Formats (subject to Structured Syntax encoding rules TBD) o 22000 - application/hsml+json o 22001 - application/hsml.link+json o 22002 - application/hsml.item+json 11.3. Link Parameters o method o schema o content-type o ct o accept-method o transfer-method o accept-schema o transfer-schema The following should be registered in the CoRE dynamic linking draft [I-D.groves-core-dynlink]. o pmin o pmax o bmn o bmx o iv o lth o gth Koster Expires September 14, 2017 [Page 43] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 o st o eq 11.4. Link Relation Types o grp 11.5. New CoRE Interface Types o hsml.collection o hsml.item o hsml.link 11.6. Transfer Layer Methods These definitions may use the default namespace and do not need to be registered with IANA o create o retrieve o update o delete o observe 12. Security Considerations 12.1. Object Signing 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. 12.2. Signed Embedded Time Stamps The collection may include time stamps (bt and t) that are signed with the object data and metadata. Koster Expires September 14, 2017 [Page 44] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 12.3. Signed Embedded Access Control 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. 12.4. Secure State Updates 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. 12.5. Object Signing and Encryption 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]. 13. Terminology Client Having a client role in a REST operation, transmitting a request and receiving one or more responses. Server Having a server role in a REST operation, the origin of data items or proxy for the origin. A server is also an authority for a URI namespace [RFC3986]. Resource Server endpoint for a REST operation, identified by a URI [RFC3986] Representation An encoded form of the state of a resource. The encoding rules may be specified in a media type or content type. Clients and servers exchange representations of resources in order to effect application state changes [REST]. URI Uniform Resource Identifier, used to identify a resource in a link or as a reference [RFC3986] Reference An identifier used to select or identify a particular resource. References are constructed by clients to identify resources when Koster Expires September 14, 2017 [Page 45] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 interacting with servers. Servers match references in client requests against URIs of hosted resources. Media Type, also Content-Format, Content-Type A set of rules for encoding, transfer, and prosessing resource representations Hypermedia Design style which uses metadata in the form of hyperlinks to structure resources in relation to each other Collection A composite resource that contains links and optionally data items Link, also Hyperlink A metadata element as described in [RFC5988] and [RFC6690] that contains a pointer to and description of some data element. Item A data item pointed to by one or more links in one or more collections. Context The context of a link is the subject of the link or the enclosing scope. In this document the collection is the default context for links in the collection. Target The target of a link is the resource being pointed to or described. Links in a collection point to and describe items as link targets. Transfer Layer A set of predefined message types used to implement state transfer semantics, for example REST. Request A message sent from a client to a server identifying the resource, representation, and method to use for the interaction with the server. Response A message sent from a server to a client in response to a request, which communicates the state of the identified resource. Operation or Method Koster Expires September 14, 2017 [Page 46] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 The state transition type requested by the client for the server to perform on the identified resource. Indicated by the transfer layer method, for example, RETRIEVE, UPDATE, CREATE, DELETE. Pubsub A transfer layer semantic interface based on the publish-subscribe paradigm, allowing for asynchronous messages to be routed on demand. 14. Informative References [I-D.groves-core-dynlink] Shelby, Z., Vial, M., Koster, M., and C. Groves, "Dynamic Resource Linking for Constrained RESTful Environments", draft-groves-core-dynlink-00 (work in progress), July 2016. [I-D.ietf-core-interfaces] Shelby, Z., Vial, M., Koster, M., and C. Groves, "Reusable Interface Definitions for Constrained RESTful Environments", draft-ietf-core-interfaces-08 (work in progress), February 2017. [I-D.ietf-core-links-json] Li, K., Rahman, A., and C. Bormann, "Representing CoRE Formats in JSON and CBOR", draft-ietf-core-links-json-06 (work in progress), July 2016. [I-D.ietf-core-resource-directory] Shelby, Z., Koster, M., Bormann, C., and P. Stok, "CoRE Resource Directory", draft-ietf-core-resource-directory-09 (work in progress), 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)", draft-ietf-core-senml-05 (work in progress), March 2017. [I-D.ietf-cose-msg] Schaad, J., "CBOR Object Signing and Encryption (COSE)", draft-ietf-cose-msg-24 (work in progress), November 2016. [I-D.selander-ace-object-security] Selander, G., Mattsson, J., Palombini, F., and L. Seitz, "Object Security of CoAP (OSCOAP)", draft-selander-ace- object-security-06 (work in progress), October 2016. Koster Expires September 14, 2017 [Page 47] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 [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, . Author's Address Koster Expires September 14, 2017 [Page 48] Internet-Draft Media Types for Hypertext Sensor Markup March 2017 Michael Koster SmartThings 1281 Lawrence Station Road Sunnyvale 94089 USA Phone: +1-707-502-5136 Email: michael.koster@smartthings.com Koster Expires September 14, 2017 [Page 49]