idnits 2.17.1 draft-pot-json-link-01.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 : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The abstract seems to contain references ([RFC8259], [RFC8288]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 100: '... MUST be used as the default link co...' RFC 2119 keyword, line 107: '... this specification MAY override this....' RFC 2119 keyword, line 129: '... appearing on a link MUST ignore them....' RFC 2119 keyword, line 143: '...set of links in a document, SHOULD use...' RFC 2119 keyword, line 165: '...is specification SHOULD use a top-leve...' (1 more instance...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (January 09, 2020) is 1569 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) No issues found here. Summary: 3 errors (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Pot 3 Internet-Draft 4 Intended status: Standards Track G. Sullice 5 Expires: July 12, 2020 Acquia, Inc. 6 January 09, 2020 8 JSON serialization for Web Linking 9 draft-pot-json-link-01 11 Abstract 13 This specification defines a serialization of Web Linking [RFC8288] 14 in the JSON [RFC8259] format. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at https://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on July 12, 2020. 33 Copyright Notice 35 Copyright (c) 2020 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (https://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 1. Introduction 50 There are many JSON-based standards and formats that require the need 51 to express a link. Examples can be found in [draft-kelly-json-hal], 52 [JSON-API], [WEBTHING], [draft-nottingham-json-home], 53 [COLLECTIONJSON], [SIREN] and many others. 55 Because there hasn't been an accepted reference for serializing Web 56 Links in JSON, it's typical for authors of new formats to invent 57 their own. This has resulted in many minor differences between 58 serializations, making it difficult to write generic parsers. 60 This document is an attempt to define a standard JSON serialization 61 for Web linking. A primary goal is to define a format that's 62 relatively uncontroversial and similar to existing serializations. 64 Furthermore, this specification defines an optional format for groups 65 of links and a recommendation for defining document-wide links. 67 2. Format 69 2.1. The link object. 71 A link will be encoded as a JSON [RFC8259] object. The object might 72 support the properties from the following chapters, but only "rel" 73 and "href" are required. 75 2.1.1. rel 77 The "rel" property refers to Section 3.3 of [RFC8288]. The "rel" 78 property must be a string. 80 There is no support to encode multiple relation types for a single 81 link. To encode multiple relation types, the link must appear 82 multiple times in the document. 84 2.1.2. href 86 The "href" property refers to the Link Target, defined in Section 3.1 87 of [RFC8288]. 89 The property is required and must be specified as a string. 91 2.1.3. anchor 93 The "anchor" attribute is defined in Section 3.2 of [RFC8288]. This 94 specification alters the behavior of anchor. By default, if anchor 95 is not specified the link context is considered to be the URL of the 96 representation it is associated with. 98 If the link appears alongside a link with the 'self' relation type 99 (for example in Section 2.2 of links, the target of the self link 100 MUST be used as the default link context, unless the anchor attribute 101 is defined. 103 If the link is not part of a list of links that has a link relation 104 of type 'self', the default behavior is to use the URL of the 105 representation it's associated with. 107 However, implementors of this specification MAY override this. 108 Because JSON links may have deeper contextual meaning depending on 109 where it appears in the document. 111 2.1.4. Other attributes 113 The link object may also encode the "hreflang", "media", "type" 114 attributes. These properties are all defined in Section 3.4.1 of 115 [RFC8288]. In their JSON serialization they are all optional, and 116 must be encoded as a string. 118 Section 3.4.1 also defines a "title*" attribute, which may contain an 119 alternative encoding for the "title" attribute. 121 JSON only supports UTF-8 encoding. As such, it is not needed to make 122 this distinction. The link title is always encoded using the "title" 123 property. 125 2.1.5. Extension Attributes 127 Similar to [RFC8288], other documents may define new target 128 attributes for links. Parsers that don't understand any attributes 129 appearing on a link MUST ignore them. 131 2.1.6. Example 133 This section is non-normative. 135 { 136 "href": "https://evertpot.com/", 137 "rel": "author", 138 "title": "Evert Pot" 139 } 141 2.2. Lists of links 143 Authors that wish to encode a set of links in a document, SHOULD use 144 an array of links. 146 2.2.1. Example 148 This section is non-normative. 150 [ 151 { 152 "href": "https://evertpot.com/", 153 "rel": "author", 154 "title": "Evert Pot" 155 }, 156 { 157 "href": "https://test.example/", 158 "rel": "self" 159 } 160 } 162 2.3. Document-level links 164 If a JSON representation wants to define document-level links, 165 implementors of this specification SHOULD use a top-level "links" 166 property to define these. 168 The "links" property contains a list of links. 170 The links appearing in this list are considered semantically 171 equivalent to the links appear in the "Link" header, as defined in 172 Section 3.5 of [RFC8288]. 174 Implementors of this specification MAY make an effort to expose links 175 from the HTTP Link header and the document-level links via a unified 176 interface. 178 2.3.1. Example 180 This section is non-normative. 182 { 183 "links": [ 184 { 185 "href": "https://evertpot.com/", 186 "rel": "author", 187 "title": "Evert Pot" 188 }, 189 { 190 "href": "https://test.example/", 191 "rel": "self" 192 } 193 ] 194 } 196 3. IANA considerations 198 We would like to register the 'application/links+json' media-type for 199 documents wishing to implement this spec. 201 TBD? 203 4. References 205 4.1. Normative References 207 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 208 Interchange Format", STD 90, RFC 8259, 209 DOI 10.17487/RFC8259, December 2017, 210 . 212 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 213 DOI 10.17487/RFC8288, October 2017, 214 . 216 4.2. Informative References 218 [COLLECTIONJSON] 219 Mike Amundsen, ., "Collection+JSON", n.d., 220 . 222 [draft-kelly-json-hal] 223 Kelly, M., "JSON Hypertext A:wpplication Language", n.d., 224 . 226 [draft-nottingham-json-home] 227 Nottingham, M., "Home Documents for HTTP APIs", n.d., 228 . 230 [JSON-API] 231 "JSON:API", n.d., . 233 [SIREN] Kevin Swiber, ., "Siren: a hypermedia specification for 234 representing entities", n.d., 235 . 237 [WEBTHING] 238 Ben Francis, ., "Web Thing API", n.d., 239 . 241 Appendix A. Typescript definitions 243 type Link = { 244 href: string, 245 rel: string, 246 anchor?: string, 247 hreflang?: string, 248 media?: string, 249 type?: string, 250 } 252 type LinkSet = Link[]; 254 type DocumentLinks = { 255 links: LinkSet 256 } 258 Appendix B. JSON-SCHEMA definitions 260 B.1. Link 261 { 262 "$schema": "http://json-schema.org/draft-07/schema#", 263 "$id": "...", 264 "type": "object", 265 "additionalProperties": true, 266 "required": [ 267 "href", 268 "rel" 269 ], 270 "properties": { 271 "href": { 272 "type": "string", 273 "format":"uri-reference" 274 }, 275 "rel": { 276 "type": "string", 277 }, 278 "title": { 279 "type": "string" 280 }, 281 "type": { 282 "type": "string" 283 }, 284 "hreflang": { 285 "type": "string", 286 }, 287 "media": { 288 "type": "string" 289 } 290 } 291 } 293 Appendix C. Changelog 295 C.1. Changes since -?? 297 Authors' Addresses 299 Evert Pot 301 Email: me@evertpot.com 302 URI: https://evertpot.com/ 303 Gabriel Sullice 304 Acquia, Inc. 306 Email: gabriel@sullice.com 307 URI: https://sullice.com