idnits 2.17.1 draft-bormann-core-links-json-00.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 seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document date (February 14, 2012) is 4454 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) == Unused Reference: 'I-D.ietf-core-coap' is defined on line 220, but no explicit reference was found in the text == Outdated reference: A later version (-14) exists of draft-ietf-core-link-format-11 ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) ** Obsolete normative reference: RFC 5988 (Obsoleted by RFC 8288) == Outdated reference: A later version (-18) exists of draft-ietf-core-coap-08 == Outdated reference: A later version (-03) exists of draft-pbryan-zyp-json-ref-01 Summary: 2 errors (**), 0 flaws (~~), 6 warnings (==), 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 February 14, 2012 5 Expires: August 17, 2012 7 Representing CoRE Link Collections in JSON 8 draft-bormann-core-links-json-00 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 (I-D.ietf-core-link-format). 16 Outside of constrained environments, it may be useful to represent 17 these collections of Web links in JSON format (RFC4627). 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 August 17, 2012. 39 Copyright Notice 41 Copyright (c) 2012 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 . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 1.1. Objectives . . . . . . . . . . . . . . . . . . . . . . . . 3 58 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 59 2. Web Links in JSON . . . . . . . . . . . . . . . . . . . . . . 5 60 2.1. Examples . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 3. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 62 4. Security Considerations . . . . . . . . . . . . . . . . . . . 8 63 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 64 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 10 65 6.1. Normative References . . . . . . . . . . . . . . . . . . . 10 66 6.2. Informative References . . . . . . . . . . . . . . . . . . 10 67 Appendix A. Implementation . . . . . . . . . . . . . . . . . . . 11 68 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12 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 [I-D.ietf-core-link-format] 76 to enable resource discovery. 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 [RFC4627]. 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 (TBD: Convert the shopping list into plaintext) 97 o Canonical mapping 99 * lossless round-tripping 101 * but not trying for bit-preserving (DER-style) round-tripping 103 o The simplest thing that could possibly work 105 * Do not cater for RFC 5988 complications caused by HTTP header 106 character set issues [RFC2047] 108 o Consider other work that has links in JSON, e.g.: JSON-LD, JSON- 109 Reference [I-D.pbryan-zyp-json-ref] 111 * Do not introduce unmotivated differences 113 1.2. Terminology 115 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 116 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 117 document are to be interpreted as described in RFC 2119, BCP 14 119 [RFC2119]. 121 2. Web Links in JSON 123 The objective of the JSON mapping defined in this document is to 124 contain information of the formats specified in [RFC5988] and 125 [I-D.ietf-core-link-format]. This specification therefore uses the 126 names of the ABNF productions used in those documents. 128 An application/link-format document is a collection of web links 129 ("link-value"), each of which is a collection of attributes 130 ("link-param") applied to a "URI-Reference". 132 We straightforwardly map: 134 o the outer collection to an array of links 136 o each link to a JSON object. 138 In the object representing a "link-value", each target attribute or 139 other parameter ("link-param") is represented by a JSON name/value 140 pair (member). The name is a string representation of the parameter 141 or attribute name (as in "parmname"), the value is a string 142 representation of the parameter or attribute value ("ptoken" or 143 "quoted-string"). "quoted-string" productions are parsed (i.e, the 144 backslash constructions evaluated) as defined in 145 [I-D.ietf-core-link-format] and its referenced documents, before 146 placing them in JSON strings (where they may gain back additional 147 decorations such as backslashes as defined in [RFC4627]). 149 If a Link attribute ("parmname") is present more than once in a 150 "link-value", its values are then represented as a JSON array of JSON 151 string values; this array becomes the value of the JSON name/value 152 pair where the attribute name is the JSON name. Attributes occurring 153 just once MUST NOT be represented as JSON arrays but MUST be directly 154 represented as JSON strings. 156 The URI-Reference is represented as a name/value pair with the name 157 "uri" and the URI-Reference as the value. (Rationale: While this 158 does preempt "uri" as an attribute name, this usage is consistent 159 with the use of "uri" in link-format query filtering 160 [I-D.ietf-core-link-format]). 162 (TBD: Should be do something special with the "hosts" relation? 163 Should we include an anchor where the link-format does not explicitly 164 set one?) 166 2.1. Examples 168 ;rt="index";title="Sensor Index", 169 ;rt="TemperatureC";if="sensor", 170 ;rt="LightLux";if="sensor", 171 ;anchor="/sensors/temp" 172 ;rel="describedby", 173 ;anchor="/sensors/temp";rel="alternate" 175 Figure 1: Example from page 13 of [I-D.ietf-core-link-format] 177 becomes 179 " [{"uri":"/sensors","rt":"index","title":"Sensor Index"},{"uri":"/se 180 nsors/temp","rt":"TemperatureC","if":"sensor"},{"uri":"/sensors/light 181 ","rt":"LightLux","if":"sensor"},{"uri":"http://www.example.com/senso 182 rs/t123","anchor":"/sensors/temp","rel":"describedby"},{"uri":"/t","a 183 nchor":"/sensors/temp","rel":"alternate"}] " 185 (More examples to be added.) 187 3. IANA Considerations 189 (TBD. All the Media Type boilerplate, too, for:) 191 application/link-format+json 193 4. Security Considerations 195 (TBD.) 197 5. Acknowledgements 199 (TBD.) 201 6. References 203 6.1. Normative References 205 [I-D.ietf-core-link-format] 206 Shelby, Z., "CoRE Link Format", 207 draft-ietf-core-link-format-11 (work in progress), 208 January 2012. 210 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 211 Requirement Levels", BCP 14, RFC 2119, March 1997. 213 [RFC4627] Crockford, D., "The application/json Media Type for 214 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 216 [RFC5988] Nottingham, M., "Web Linking", RFC 5988, October 2010. 218 6.2. Informative References 220 [I-D.ietf-core-coap] 221 Shelby, Z., Hartke, K., Bormann, C., and B. Frank, 222 "Constrained Application Protocol (CoAP)", 223 draft-ietf-core-coap-08 (work in progress), October 2011. 225 [I-D.pbryan-zyp-json-ref] 226 Bryan, P. and K. Zyp, "JSON Reference", 227 draft-pbryan-zyp-json-ref-01 (work in progress), 228 November 2011. 230 [MNOT11] Nottingham, M., "Linking in JSON", November 2011, 231 . 233 [RFC2047] Moore, K., "MIME (Multipurpose Internet Mail Extensions) 234 Part Three: Message Header Extensions for Non-ASCII Text", 235 RFC 2047, November 1996. 237 Appendix A. Implementation 239 This appendix provides a simple reference implementation of the 240 mapping between CoRE link format and Links-in-JSON. 242 (TBD.) 244 Author's Address 246 Carsten Bormann 247 Universitaet Bremen TZI 248 Postfach 330440 249 Bremen D-28359 250 Germany 252 Phone: +49-421-218-63921 253 Fax: +49-421-218-7000 254 Email: cabo@tzi.org