]> Universität Bremen TZI

Postfach 330440 Bremen D-28359 Germany +49-421-218-63921 cabo@tzi.org

Applications T2TRG Internet-Draft The Semantic Definition Format (SDF) is a format for domain experts to use in the creation and maintenance of data and interaction models that describe Things, i.e., physical objects that are available for interaction over a network. It was created as a common language for use in the development of the One Data Model liaison organization (OneDM) definitions. Tools convert this format to database formats and other serializations as needed. The SDF format is mainly intended for interchange between machine generation and machine processing. However, there is often a need for humans to look at and edit SDF models. Similar to the way Relax-NG as defined in ISO/IEC 19757-2 has an XML-based format and a compact format (its Annex C), this specification defines a compact format to go along SDF's JSON-based format. The present version of this document is mostly a proof of concept; it received positive initial feedback on the approach taken and is awaiting completion of the initial implementation. About This Document Status information for this document may be found at . Discussion of this document takes place on the A Semantic Definition Format for Data and Interactions of Things (asdf) Working Group mailing list (), which is archived at . Subscribe at .

Introduction The Semantic Definition Format (SDF, ) is a format for domain experts to use in the creation and maintenance of data and interaction models that describe Things, i.e., physical objects that are available for interaction over a network. It was created as a common language for use in the development of the One Data Model liaison organization (OneDM) definitions. Tools convert this format to database formats and other serializations as needed. The SDF format is mainly intended for interchange between machine generation and machine processing. However, there is often a need for humans to look at and edit SDF models. Similar to the way Relax-NG as defined in has an XML-based format and a compact format (its Annex C), this specification defines a compact format to go along SDF's JSON-based format. The intention is to be able to bidirectionally translate between compact and JSON form, without appreciable semantic losses. This will allow viewing SDF in compact form, apply edits if needed, and then continuing processing it in JSON form. As a limitation of this approach, it will be difficult to always recreate the order of map entries (members of JSON objects) in the JSON form; this order is essentially arbitrary as maps (JSON objects) in JSON are unordered. (In the long run, it may be useful to define a canonical presentation order in the SDF specification or here.) An initial prototype of a converter from compact form to JSON form was constructed during the ASDF/WISHI hackathon preceding IETF110. A more complete, bidirectionally operating version of this tool is planned for release soon.

Overview The SDF compact format is a YAML file ; a good part of the work needed for a compact representation is already done by the increased user-friendliness of YAML over JSON. In addition, all the sections defined with named<...> in the CDDL definition of SDF have been compacted into map entries with space-separated keys, giving the kind first and the name next. This saves the need for another level of hierarchy and reminds the reader of the kind of item being specified. The map key description is replaced by :, which also is rendered in the most compact form possible in YAML. The dataqualities readable, writable, and observable, together with optionality, are compressed into a four-character map key: The first three are translated into rwo when set (default in SDF) and into --- when not set. The fourth character is ? for optional and ! for required. The value of this abbreviated key is a CDDL rendition of the attributes defined in the jsonschema production in . To further reduce noise, a top-level array production in the CDDL can be represented as an array in the YAML (i.e., does not require additional quotes).

Example Definition is an SDF-compact representation of a slightly modified copy of the sdfobject-cadence.sdf.json model found at the time of writing in OneDM's SDF playground. (This example was chosen more or less randomly; better examples can probably be found. The modification is the addition of a unit quality.)

Example SDF model in SDF compact form

The result of automatically converting this YAML file using the prototype sdfc tool back into the JSON form of SDF is given in . Except for the unit addition, it is semantically identical to the sdfobject-cadence.sdf.json. Differences are visible in the order of map entries (members in JSON objects); a future version of the sdfc tool could attempt to preserve more of this order, even though the order does not carry semantics, neither in the JSON form nor in the compact form.

IANA Considerations This document does not make any requests of IANA.

Security Considerations The security considerations of apply. Additional security considerations arise as in all alternative representation forms for a formal description technique. (Security considerations are given for RELAX-NG compact form in , Annex C.7 (Media type registration template for the RELAX NG Compact Syntax); these actually apply to SDF in general. A more detailed discussion of the consequences of using dereferenceable identifiers can be found in the penultimate paragraph of Section Security Considerations of .)

References Normative References This document proposes a notational convention to express Concise Binary Object Representation (CBOR) data structures (RFC 7049). Its main goal is to provide an easy and unambiguous way to express structures for protocol messages and data formats that use CBOR or JSON. The Semantic Definition Format (SDF) is a format for domain experts to use in the creation and maintenance of data and interaction models that describe Things, i.e., physical objects that are available for interaction over a network. An SDF specification describes definitions of SDF Objects/SDF Things and their associated interactions (Events, Actions, and Properties), as well as the Data types for the information exchanged in those interactions. Tools convert this format to database formats and other serializations as needed. Informative References ISO/IEC This specification is also publicly available at https://standards.iso.org/ittf/PubliclyAvailableStandards/c052348_ISO_IEC_19757-2_2008(E).zip. This document defines two strategies for handling long lines in width-bounded text content. One strategy, called the "single backslash" strategy, is based on the historical use of a single backslash ('\') character to indicate where line-folding has occurred, with the continuation occurring with the first character that is not a space character (' ') on the next line. The second strategy, called the "double backslash" strategy, extends the first strategy by adding a second backslash character to identify where the continuation begins and is thereby able to handle cases not supported by the first strategy. Both strategies use a self-describing header enabling automated reconstitution of the original content.

Example in SDF JSON format This appendix shows the result of automatically converting into the JSON form of SDF. It was produced using the prototype sdfc tool. Note that JSON was not designed to enable JSON texts to always fit into the confines of the RFC format; the presentation here employs line wrapping, which is of course not visible in the actual JSON text for the example presented in .

Example SDF model in JSON text form, line-wrapped

Acknowledgements The idea for this draft originated at the IETF110 ASDF/WISHI hackathon. The author would like to thank the attendees for initial feedback.