idnits 2.17.1 draft-pot-json-link-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 : ---------------------------------------------------------------------------- ** 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 96: '... self link MUST be used as the defau...' RFC 2119 keyword, line 102: '... this specification MAY override this....' RFC 2119 keyword, line 124: '... appearing on a link MUST ignore them....' RFC 2119 keyword, line 159: '...is specification SHOULD use a top-leve...' RFC 2119 keyword, line 168: '...is specification MAY make an effort to...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (December 30, 2019) is 1579 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 December 30, 2019 4 Intended status: Standards Track 5 Expires: July 2, 2020 7 JSON serialization for Web Linking 8 draft-pot-json-link-00 10 Abstract 12 This specification defines a serialization of Web Linking [RFC8288] 13 in the JSON [RFC8259] format. 15 Status of This Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at https://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on July 2, 2020. 32 Copyright Notice 34 Copyright (c) 2019 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (https://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 1. Introduction 49 There are many JSON-based standards and formats that require the need 50 to express a link. Examples can be found in [draft-kelly-json-hal], 51 [JSON-API], [WEBTHING], [draft-nottingham-json-home], 52 [COLLECTIONJSON], [SIREN] and many others. 54 Typically when new formats requiring links are defined, there is no 55 common reference to build on. This often results in minor 56 differences between serializations making it difficult to write 57 generic parsers. 59 This document is an attempt to define a standard JSON serialization 60 for Web linking. A primary goal is to define a format that's 61 relatively uncontroversial and similar to existing serializations. 63 2. Format 65 2.1. The link object. 67 A link will be encoded as a JSON [RFC8259] object. The object might 68 support the properties from the following chapters, but only "rel" 69 and "href" are required. 71 2.1.1. rel 73 The "rel" property refers to Section 3.3 of [RFC8288]. The "rel" 74 property must be a string. 76 There is no support to encode multiple relation types for a single 77 link. To encode multiple relation types, the link must appear 78 multiple times in the document. 80 2.1.2. href 82 The "href" property refers to the Link Target, defined in Section 3.1 83 of [RFC8288]. 85 The property is required and must be specified as a string. 87 2.1.3. anchor 89 The "anchor" attribute is defined in Section 3.2 of [RFC8288]. This 90 specification alters the behavior of anchor. By default, if anchor 91 is not specified the link context is considered to be the URL of the 92 representation it is associated with. 94 If the link appears in a list of links (defined in Section 2.2), and 95 the list contains a link with relation type 'self', the target of the 96 self link MUST be used as the default link context. 98 If the link is not part of a list of links that has a link relation 99 of type 'self', the default behavior is to use the URL of the 100 representation it's associated with. 102 However, implementors of this specification MAY override this. 103 Because JSON links may have deeper contextual meaning depending on 104 where it appears in the document. 106 2.1.4. Other attributes 108 The link object may also encode the "hreflang", "media", "type" 109 attributes. These properties are all defined in Section 3.4.1 of 110 [RFC8288]. In their JSON serialization they are all optional, and 111 must be encoded as a string. 113 Section 3.4.1 also defines a "title*" attribute, which may contain an 114 alternative encoding for the "title" attribute. 116 JSON only supports UTF-8 encoding. As such, it is not needed to make 117 this distinction. The link title is always encoded using the "title" 118 property. 120 2.1.5. Extension Attributes 122 Similar to [RFC8288], other documents may define new target 123 attributes for links. Parsers that don't understand any attributes 124 appearing on a link MUST ignore them. 126 2.1.6. Example 128 This section is non-normative. 130 { 131 "href": "https://evertpot.com/", 132 "rel": "author", 133 "title": "Evert Pot" 134 } 136 2.2. Lists of links 138 A list of links defined as a JSON array of one or more link objects. 140 2.2.1. Example 142 This section is non-normative. 144 [ 145 { 146 "href": "https://evertpot.com/", 147 "rel": "author", 148 "title": "Evert Pot" 149 }, 150 { 151 "href": "https://test.example/", 152 "rel": "self" 153 } 154 } 156 2.3. Document-level links 158 If a JSON representation wants to define document-level links, 159 implementors of this specification SHOULD use a top-level "links" 160 property to define these. 162 The "links" property contains a list of links. 164 The links appearing in this list are considered semantically 165 equivalent to the links appear in the "Link" header, as defined in 166 Section 3.5 of [RFC8288]. 168 Implementors of this specification MAY make an effort to expose links 169 from the HTTP Link header and the document-level links via a unified 170 interface. 172 2.3.1. Example 174 This section is non-normative. 176 { 177 "links": [ 178 { 179 "href": "https://evertpot.com/", 180 "rel": "author", 181 "title": "Evert Pot" 182 }, 183 { 184 "href": "https://test.example/", 185 "rel": "self" 186 } 187 ] 188 } 190 3. IANA considerations 192 We would like to register the 'application/links+json' media-type for 193 documents wishing to implement this spec. 195 TBD? 197 4. References 199 4.1. Normative References 201 [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data 202 Interchange Format", STD 90, RFC 8259, 203 DOI 10.17487/RFC8259, December 2017, 204 . 206 [RFC8288] Nottingham, M., "Web Linking", RFC 8288, 207 DOI 10.17487/RFC8288, October 2017, 208 . 210 4.2. Informative References 212 [COLLECTIONJSON] 213 Mike Amundsen, ., "Collection+JSON", n.d., 214 . 216 [draft-kelly-json-hal] 217 Kelly, M., "JSON Hypertext A:wpplication Language", n.d., 218 . 220 [draft-nottingham-json-home] 221 Nottingham, M., "Home Documents for HTTP APIs", n.d., 222 . 224 [JSON-API] 225 "JSON:API", n.d., . 227 [SIREN] Kevin Swiber, ., "Siren: a hypermedia specification for 228 representing entities", n.d., 229 . 231 [WEBTHING] 232 Ben Francis, ., "Web Thing API", n.d., 233 . 235 Appendix A. Typescript definitions 237 type Link = { 238 href: string, 239 rel: string, 240 anchor?: string, 241 hreflang?: string, 242 media?: string, 243 type?: string, 244 } 246 type LinkSet = Link[]; 248 type DocumentLinks = { 249 links: LinkSet 250 } 252 Appendix B. JSON-SCHEMA definitions 254 TBD 256 Appendix C. Changelog 258 C.1. Changes since -?? 260 Author's Address 262 Evert Pot 264 Email: me@evertpot.com 265 URI: https://evertpot.com/