idnits 2.17.1 draft-ietf-core-links-json-02.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (July 04, 2014) is 3578 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) ** Obsolete normative reference: RFC 7159 (Obsoleted by RFC 8259) Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CoRE Working Group C. Bormann 3 Internet-Draft Universitaet Bremen TZI 4 Intended status: Standards Track July 04, 2014 5 Expires: January 5, 2015 7 Representing CoRE Link Collections in JSON 8 draft-ietf-core-links-json-02 10 Abstract 12 Web Linking (RFC5988) provides a way to represent links between Web 13 resources as well as the relations expressed by them and attributes 14 of such a link. In constrained networks, a collection of Web links 15 can be exchanged in the CoRE link format (RFC6690). Outside of 16 constrained environments, it may be useful to represent these 17 collections of Web links in JSON format (RFC7159). 19 This specification defines a common format for representing Web links 20 in JSON format. 22 Status of This Memo 24 This Internet-Draft is submitted in full conformance with the 25 provisions of BCP 78 and BCP 79. 27 Internet-Drafts are working documents of the Internet Engineering 28 Task Force (IETF). Note that other groups may also distribute 29 working documents as Internet-Drafts. The list of current Internet- 30 Drafts is at http://datatracker.ietf.org/drafts/current/. 32 Internet-Drafts are draft documents valid for a maximum of six months 33 and may be updated, replaced, or obsoleted by other documents at any 34 time. It is inappropriate to use Internet-Drafts as reference 35 material or to cite them other than as "work in progress." 37 This Internet-Draft will expire on January 5, 2015. 39 Copyright Notice 41 Copyright (c) 2014 IETF Trust and the persons identified as the 42 document authors. All rights reserved. 44 This document is subject to BCP 78 and the IETF Trust's Legal 45 Provisions Relating to IETF Documents 46 (http://trustee.ietf.org/license-info) in effect on the date of 47 publication of this document. Please review these documents 48 carefully, as they describe your rights and restrictions with respect 49 to this document. Code Components extracted from this document must 50 include Simplified BSD License text as described in Section 4.e of 51 the Trust Legal Provisions and are provided without warranty as 52 described in the Simplified BSD License. 54 Table of Contents 56 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 57 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Web Links in JSON . . . . . . . . . . . . . . . . . . . . . . 3 60 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . 4 61 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 5 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 6 63 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 6 64 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 6 65 6.1. Normative References . . . . . . . . . . . . . . . . . . 6 66 6.2. Informative References . . . . . . . . . . . . . . . . . 6 67 Appendix A. Implementation . . . . . . . . . . . . . . . . . . . 6 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 7 70 1. Introduction 72 Web Linking [RFC5988] provides a way to represent links between Web 73 resources as well as the relations expressed by them and attributes 74 of such a link. In constrained networks, a collection of Web links 75 can be exchanged in the CoRE link format [RFC6690] to enable resource 76 discovery, for instance by using the CoAP protocol [RFC7252]. 78 Outside of constrained environments, it may also be useful to 79 represent the same collections of Web links in the widely used JSON 80 format [RFC7159]. When converting between these two formats, as 81 usual, there are many little decisions that have to be made. If left 82 without guidance, it is likely that a number of slightly incompatible 83 dialects will emerge. 85 This specification defines a common format for representing CoRE Web 86 Linking in JSON format. 88 Note that there is a separate question on how to represent Web links 89 out of JSON documents, as discussed e.g. in [MNOT11]. While there 90 are good reasons to stay as compatible as possible to developments in 91 this area, the present specification is solving a different problem. 93 1.1. Objectives 95 This specification has been designed based on the following 96 objectives: 98 o Canonical mapping 100 * lossless round-tripping with [RFC6690] 102 * but not trying for bit-preserving (DER-style) round-tripping 104 o The simplest thing that could possibly work 106 * Do not cater for RFC 5988 complications caused by HTTP header 107 character set issues [RFC2047] 109 o Consider other work that has links in JSON, e.g.: JSON-LD, JSON- 110 Reference [I-D.pbryan-zyp-json-ref] 112 * Do not introduce unmotivated differences 114 1.2. Terminology 116 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 117 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 118 document are to be interpreted as described in [RFC2119] when they 119 appear in ALL CAPS. These words may also appear in this document in 120 lower case as plain English words, absent their normative meanings. 122 2. Web Links in JSON 124 The objective of the JSON mapping defined in this document is to 125 contain information of the formats specified in [RFC5988] and 126 [RFC6690]. This specification therefore uses the names of the ABNF 127 productions used in those documents. 129 An application/link-format document is a collection of web links 130 ("link-value"), each of which is a collection of attributes ("link- 131 param") applied to a "URI-Reference". 133 We straightforwardly map: 135 o the outer collection to an array of links 137 o each link to a JSON object. 139 In the object representing a "link-value", each target attribute or 140 other parameter ("link-param") is represented by a JSON name/value 141 pair (member). The name is a string representation of the parameter 142 or attribute name (as in "parmname"), the value is a string 143 representation of the parameter or attribute value ("ptoken" or 144 "quoted-string"). "quoted-string" productions are parsed (i.e, the 145 backslash constructions evaluated) as defined in [RFC6690] and its 146 referenced documents, before placing them in JSON strings (where they 147 may gain back additional decorations such as backslashes as defined 148 in [RFC7159]). 150 If a Link attribute ("parmname") is present more than once in a 151 "link-value", its values are then represented as a JSON array of JSON 152 string values; this array becomes the value of the JSON name/value 153 pair where the attribute name is the JSON name. Attributes occurring 154 just once MUST NOT be represented as JSON arrays but MUST be directly 155 represented as JSON strings. (Note that the most recent version of 156 link-format has cut down on the use of repeated parameter names; they 157 are still allowed by [RFC5988] though. No attempt has been made to 158 decode the possibly space-separated values for rt=, if=, and rel= 159 into JSON arrays.) 161 The URI-Reference is represented as a name/value pair with the name 162 "href" and the URI-Reference as the value. (Rationale: This usage is 163 consistent with the use of "href" as a query parameter for link- 164 format query filtering and with link-format reserving the link 165 parameter "href" specifically for this use [RFC6690]). 167 (TBD: Should we do something special with the "hosts" relation? 168 Should we include an anchor where the link-format does not explicitly 169 set one?) 171 2.1. Examples 173 ;ct=40;title="Sensor Index", 174 ;rt="temperature-c";if="sensor", 175 ;rt="light-lux";if="sensor", 176 ;anchor="/sensors/temp" 177 ;rel="describedby", 178 ;anchor="/sensors/temp";rel="alternate" 180 Figure 1: Example from page 15 of [RFC6690] 182 becomes 184 "[{"href":"/sensors","ct":"40","title":"Sensor Index"},{"href 185 ":"/sensors/temp","rt":"temperature-c","if":"sensor"},{"href 186 ":"/sensors/light","rt":"light- 187 lux","if":"sensor"},{"href":"http://www.example.com/sensors/ 188 t123","anchor":"/sensors/ 189 temp","rel":"describedby"},{"href":"/t","anchor":"/sensors/ 190 temp","rel":"alternate"}] " 192 (More examples to be added.) 194 3. IANA Considerations 196 This specification registers the following additional Internet Media 197 Types: 199 Type name: application 201 Subtype name: link-format+json 203 Required parameters: None 205 Optional parameters: None 207 Encoding considerations: Resources that use the "application/ 208 link-format+json" media type are required to conform to the 209 "application/json" Media Type and are therefore subject to the 210 same encoding considerations specified in Section 6 {{RFC7159}}. 212 Security considerations: As defined in this specification 214 Published specification: This specification. 216 Applications that use this media type: None currently known. 218 Additional information: 220 Magic number(s): N/A 222 File extension(s): N/A 224 Macintosh file type code(s): TEXT 226 Person & email address to contact for further information: 227 Carsten Bormann 229 Intended usage: COMMON 231 Change controller: IESG 233 4. Security Considerations 235 The security considerations of [RFC6690] apply. 237 (TBD.) 239 5. Acknowledgements 241 (TBD.) 243 6. References 245 6.1. Normative References 247 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 248 Requirement Levels", BCP 14, RFC 2119, March 1997. 250 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 252 [RFC6690] Shelby, Z., "Constrained RESTful Environments (CoRE) Link 253 Format", RFC 6690, August 2012. 255 [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data 256 Interchange Format", RFC 7159, March 2014. 258 6.2. Informative References 260 [I-D.pbryan-zyp-json-ref] 261 Bryan, P. and K. Zyp, "JSON Reference", draft-pbryan-zyp- 262 json-ref-03 (work in progress), September 2012. 264 [MNOT11] Nottingham, M., "Linking in JSON", November 2011, 265 . 267 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 268 Part Three: Message Header Extensions for Non-ASCII Text", 269 RFC 2047, November 1996. 271 [RFC7252] Shelby, Z., Hartke, K., and C. Bormann, "The Constrained 272 Application Protocol (CoAP)", RFC 7252, June 2014. 274 Appendix A. Implementation 276 This appendix provides a simple reference implementation of the 277 mapping between CoRE link format and Links-in-JSON. 279 (TBD - the reference implementation was used to create the above 280 examples, but I still have to clean it up for readability and paste 281 it in at 69 columns max.) 283 Author's Address 285 Carsten Bormann 286 Universitaet Bremen TZI 287 Postfach 330440 288 Bremen D-28359 289 Germany 291 Phone: +49-421-218-63921 292 Email: cabo@tzi.org