Media Types for FETCH & PATCH with Sensor Measurement Lists (SenML)
draft-keranen-core-senml-fetch-00

Network Working Group                                         A. Keranen
Internet-Draft                                                  Ericsson
Intended status: Standards Track                              M. Mohajer
Expires: September 6, 2018                                     u-blox UK
                                                           March 5, 2018

  Media Types for FETCH & PATCH with Sensor Measurement Lists (SenML)
                   draft-keranen-core-senml-fetch-00

Abstract

   The Sensor Measurement Lists (SenML) media type and data model can be
   used to send collections of resources, such as batches of sensor data
   or configuration parameters.  The CoAP PATCH and FETCH methods enable
   accessing and updating parts of a resource or multiple resources with
   one request.  This document defines two new media types that can be
   used with the CoAP PATCH and FETCH methods for resources represented
   with the SenML data model.

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

   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 6, 2018.

Copyright Notice

   Copyright (c) 2018 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

Keranen & Mohajer       Expires September 6, 2018               [Page 1]
Internet-Draft  Media Types for FETCH & PATCH with SenML      March 2018

   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.  Introduction  . . . . . . . . . . . . . . . . . . . . . . . .   2
   2.  Terminology . . . . . . . . . . . . . . . . . . . . . . . . .   3
   3.  Media Type Definitions  . . . . . . . . . . . . . . . . . . .   3
     3.1.  SenML FETCH Media Type  . . . . . . . . . . . . . . . . .   3
       3.1.1.  Wild Card Selectors . . . . . . . . . . . . . . . . .   4
     3.2.  SenML PATCH Media Type  . . . . . . . . . . . . . . . . .   5
   4.  Security Considerations . . . . . . . . . . . . . . . . . . .   5
   5.  IANA Considerations . . . . . . . . . . . . . . . . . . . . .   6
     5.1.  CoAP Content-Format Registration  . . . . . . . . . . . .   6
     5.2.  senml-fetch+json Media Type . . . . . . . . . . . . . . .   6
     5.3.  senml-patch+json Media Type . . . . . . . . . . . . . . .   7
   6.  Acknowledgements  . . . . . . . . . . . . . . . . . . . . . .   7
   7.  References  . . . . . . . . . . . . . . . . . . . . . . . . .   7
     7.1.  Normative References  . . . . . . . . . . . . . . . . . .   7
     7.2.  Informative References  . . . . . . . . . . . . . . . . .   8
   Authors' Addresses  . . . . . . . . . . . . . . . . . . . . . . .   8

1.  Introduction

   The Sensor Measurement Lists (SenML) media type [I-D.ietf-core-senml]
   and data model can be used to transmit collections of resources, such
   as batches of sensor data or configuration parameters.

   Example of a SenML collection is shown below:

   [
    {"bn":"2001:db8::2/3306/0/", "n":"5850", "vb":true},
    {"n":"5851", "v":42},
    {"n":"5750", "vs":"Ceiling light"}
   ]

   Here three resources "3306/0/5850", "3306/0/5851", and "3306/0/5750",
   of an IPSO dimmable light smart object [IPSO] are represented using a
   single SenML Pack with three SenML Records.  All resources share the
   same base name "2001:db8::2/3306/0/", hence full names for resources
   are "2001:db8::2/3306/0/5850", etc.

   The CoAP [RFC7252] PATCH and FETCH methods [RFC8132] enable accessing
   and updating parts of a resource or multiple resources with one
   request.

Keranen & Mohajer       Expires September 6, 2018               [Page 2]
Internet-Draft  Media Types for FETCH & PATCH with SenML      March 2018

   This document defines two new media types that can be used with the
   CoAP PATCH and FETCH methods with resources represented with the
   SenML data model.

2.  Terminology

   The key words 'MUST', 'MUST NOT', 'REQUIRED', 'SHALL', 'SHALL NOT',
   'SHOULD', 'SHOULD NOT', 'RECOMMENDED', 'MAY', and 'OPTIONAL' in this
   specification are to be interpreted as described in [RFC2119].

   Readers should also be familiar with the terms and concepts discussed
   in [RFC8132] and [I-D.ietf-core-senml].  Also the following terms are
   used in this document:

   FETCH Record:  One set of parameters that is used to match SenML
      Record(s).  Presented using the SenML data model with extensions
      defined in this document.

   FETCH Pack:  One or more FETCH Records in an array structure.

   PATCH Record:  One set of parameters similar to FETCH Record but
      contains also instructions on how to change existing SenML
      Pack(s).

   PATCH Pack:  One or more PATCH Records in an array structure.

3.  Media Type Definitions

   The FETCH and PATCH media types for SenML are both modeled as
   extensions to the SenML media type to enable re-use of existing SenML
   parsers and generators, in particular on constrained devices.  Unless
   mentioned otherwise, FETCH and PATCH Packs are constructed with the
   same rules and constraints as SenML Packs.

3.1.  SenML FETCH Media Type

   The FETCH media type is used to select and return parts of one or
   more SenML Packs.  The SenML records are selected by giving the
   name(s) of the resources using the SenML "name" and/or "base name"
   Fields.  The same rules for concatenating the name and base name
   Fields apply as for SenML Packs.

   For example, to select resources "5850" and "5851" from the example
   in Section 1, the following FETCH Pack can be used:

Keranen & Mohajer       Expires September 6, 2018               [Page 3]
Internet-Draft  Media Types for FETCH & PATCH with SenML      March 2018

   [
    {"bn":"2001:db8::2/3306/0/", "n":"5850"},
    {"n":"5851"}
   ]

   The result to a FETCH request with the example above would be:

   [
    {"bn":"2001:db8::2/3306/0/", "n":"5850", "vb":true},
    {"n":"5851", "v":42},
   ]

   When SenML records contain also time values, a name may no longer
   uniquely identify a single record.  When no time is given in a FETCH
   Record, all SenML Records with the given name are be matched.  When
   time is given in the FETCH Record, only a SenML Record (if any) with
   equal time value is matched.

3.1.1.  Wild Card Selectors

   Multiple SenML Records can be chosen simply by listing all names, and
   potentially times, in separate FETCH Records.  However, for
   efficiency, also wild card operations for selecting multiple SenML
   records with a single FETCH Record MAY be supported.

   Implementations that do not support wild card operations MUST return
   4.00 "Bad Request" when receiving a request with wild cards.

   TBD: better response code than 400?

   The format for SenML wild card operations is for further study.  This
   section proposes one possible format for discussion.

   SenML names are often split to multiple segments using the "/" and/or
   ":" characters.  For example, "3306/0/5850" contains three segments:
   "3306", "0", and "5850".

   A new SenML Field, FETCH filter ("ff"), is defined for use with wild
   card operations.  The filter expression is concatenated to the base
   name like the name field.  The filter can contain asterisk ("*")
   characters that are used to match any set of characters within a
   SenML name until the next segment separator ("/" or ":").

   TBD: more formal specification of matching rules

   For example, the filter expression "3306/0/*" together with the base
   name "2001:db8::2/" would match all three Records in the example
   SenML Pack from Section 1.

Keranen & Mohajer       Expires September 6, 2018               [Page 4]
Internet-Draft  Media Types for FETCH & PATCH with SenML      March 2018

   Note that the "*" character is not a valid character in SenML names.

   The "n" and "ff" Fields MUST NOT be used together.

   Example of using the filter expression "3306/0/*" in a FETCH Pack is
   shown below:

   [
    {"bn":"2001:db8::2/", "ff":"3306/0/*"}
   ]

   Similarly, when used with the same base name, the filter expression
   "*/0/*" would match all the three Records and the filter expression
   "*/0/5850" would match only the Record with name "5850".

3.2.  SenML PATCH Media Type

   The PATCH media type is used to change the values of SenML Records.
   The names and times of the Records are given in same way as for the
   FETCH media type but PATCH Packs can include also new values and
   other SenML Fields for the Records.

   For example, the following document could be given as PATCH payload
   to change/set values of two SenML Records for the example in
   Section 1:

   [
    {"bn":"2001:db8::2/3306/0/", "n":"5850", "vb":false},
    {"n":"5851", "v":10}
   ]

   If the request is successful, the resulting representation of the
   example SenML Pack would be as follows:

   [
    {"bn":"2001:db8::2/3306/0/", "n":"5850", "vb":false},
    {"n":"5851", "v":10},
    {"n":"5750", "vs":"Ceiling light"}
   ]

4.  Security Considerations

   TBD

Keranen & Mohajer       Expires September 6, 2018               [Page 5]
Internet-Draft  Media Types for FETCH & PATCH with SenML      March 2018

5.  IANA Considerations

   This document registers two new media types, one for the FETCH and
   one for the PATCH use, and CoAP Content-Format IDs for both media
   types.

5.1.  CoAP Content-Format Registration

   IANA is requested to assign CoAP Content-Format IDs for the SenML
   PATCH and FETCH media types in the "CoAP Content-Formats" sub-
   registry, within the "CoRE Parameters" registry [RFC7252].  All IDs
   are assigned from the "Expert Review" (0-255) range.  The assigned
   IDs are show in Table 1.

                  +------------------------------+-----+
                  | Media type                   | ID  |
                  +------------------------------+-----+
                  | application/senml-patch+json | TBD |
                  |                              |     |
                  | application/senml-fetch+json | TBD |
                  +------------------------------+-----+

                     Table 1: CoAP Content-Format IDs

5.2.  senml-fetch+json Media Type

   Type name: application

   Subtype name: senml-fetch+json

   Required parameters: none

   Optional parameters: none

   Encoding considerations: Must be encoded as using a subset of the
   encoding allowed in [RFC8259].  See RFC-AAAA for details.  This
   simplifies implementation of very simple system and does not impose
   any significant limitations as all this data is meant for machine to
   machine communications and is not meant to be human readable.

   Security considerations: See Section 4 of RFC-AAAA.

   Interoperability considerations: TBD

   Published specification: RFC-AAAA

   Applications that use this media type: Applications that use the
   SenML media type for resource representation.

Keranen & Mohajer       Expires September 6, 2018               [Page 6]
Internet-Draft  Media Types for FETCH & PATCH with SenML      March 2018

   Fragment identifier considerations: TBD

   Additional information:

   Magic number(s): none

   File extension(s): senml-fetch-json

   Windows Clipboard Name: "SenML fetch format"

   Macintosh file type code(s): none

   Macintosh Universal Type Identifier code: org.ietf.senml-fetch-json
   conforms to public.text

   Person & email address to contact for further information: Ari
   Keranen ari.keranen@ericsson.com

   Intended usage: COMMON

   Restrictions on usage: None

   Author: Ari Keranen ari.keranen@ericsson.com

   Change controller: IESG

5.3.  senml-patch+json Media Type

   TBD (similar to senml-fetch)

6.  Acknowledgements

   TBD

7.  References

7.1.  Normative References

   [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-13 (work in progress),
              March 2018.

   [RFC2119]  Bradner, S., "Key words for use in RFCs to Indicate
              Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/
              RFC2119, March 1997, <https://www.rfc-editor.org/info/
              rfc2119>.

Keranen & Mohajer       Expires September 6, 2018               [Page 7]
Internet-Draft  Media Types for FETCH & PATCH with SenML      March 2018

   [RFC7252]  Shelby, Z., Hartke, K., and C. Bormann, "The Constrained
              Application Protocol (CoAP)", RFC 7252, DOI 10.17487/
              RFC7252, June 2014, <https://www.rfc-editor.org/info/
              rfc7252>.

   [RFC8132]  van der Stok, P., Bormann, C., and A. Sehgal, "PATCH and
              FETCH Methods for the Constrained Application Protocol
              (CoAP)", RFC 8132, DOI 10.17487/RFC8132, April 2017,
              <https://www.rfc-editor.org/info/rfc8132>.

   [RFC8259]  Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
              Interchange Format", STD 90, RFC 8259, DOI 10.17487/
              RFC8259, December 2017, <https://www.rfc-editor.org/info/
              rfc8259>.

7.2.  Informative References

   [IPSO]     IPSO, "IP for Smart Objects - IPSO Objects", 2018,
              <https://github.com/IPSO-Alliance/pub>.

Authors' Addresses

   Ari Keranen
   Ericsson

   Email: ari.keranen@ericsson.com

   Mojan Mohajer
   u-blox UK

   Email: Mojan.Mohajer@u-blox.com

Keranen & Mohajer       Expires September 6, 2018               [Page 8]