-
Notifications
You must be signed in to change notification settings - Fork 16
/
draft-toomim-httpbis-linked-json-00.txt
225 lines (148 loc) · 7.46 KB
/
draft-toomim-httpbis-linked-json-00.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
Internet-Draft M. Toomim
Expires: Mar 8, 2020 Invisible College
Intended status: Proposed Standard B. Bellomy
Invisible College
Aug 2, 2020
Linked JSON
draft-toomim-httpbis-linked-json-00
Abstract
Linked JSON is an extension to JSON that defines a new datatype: a
"Link". A Link has a URI, and may have metadata.
Links allow JSON objects to compose across websites, supporting
transclusion. Optional metadata on links can be used to specify a
specific version or sub-slice of data to link to.
Status of this Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts. The list of current Internet-Drafts is at
http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
https://www.ietf.org/1id-abstracts.html
The list of Internet-Draft Shadow Directories can be accessed at
https://www.ietf.org/shadow.html
Table of Contents
1. Introduction ....................................................4
2. Related Work ....................................................4
3. Resolution ..........................................,...........4
4. Media Type ..........................................,...........5
5. IANA Considerations .............................................5
6. Security Considerations .........................................5
7. Conventions .....................................................6
8. Copyright Notice ................................................6
9. References ......................................................6
9.1. Normative References .......................................6
9.2. Informative References .....................................6
1. Introduction
JSON documents often include URIs, or references to other documents,
as strings. It is often useful to distinguish which strings actually
represent URIs, for example, to fetch and include the contents of
links, or to translate relative to absolute URIs.
Linked JSON is an extension of JSON that adds a Link datatype, so that
URIs can be distinguished from ordinary strings.
1.1. Syntax
A Link is encoded as a JSON object with a field named "link":
{ "link": "/david-macaulay" }
Any object with a field named "link" is interpreted as a Link. The
value of the link field MUST be a string containing a URI [RFC3986].
Links MAY be embedded within arbitrary JSON:
{
"book-name": "The way things work",
"image" { "link": "/the-way-things-work.jpg" },
"author": { "link": "/david-macaulay" }
}
1.2. Escaping
To encode a field named "link" *without* creating a Link, prefix the
field with an underscore:
{ "_link": "this is not a link" }
To encode "_link", prefix it with two underscores: "__link". To
encode "__link", use "___link", and so on.
1.3. Metadata
Links MAY specify metadata on other fields of the JSON object.
For instance, a "version" field could be used to specify a specific
version to link to:
{
"message": "Hey guys! I just published a new draft!",
"attachment: {
"link": "/books/the-way-things-work",
"version": "4.0.5"
}
}
The metadata in [RFC8288] could also be expressed.
Or a GraphQL [GRAPHQL] query:
{ "link": "/foo", "range": "(bar:9)[3,4]" }
2. Related Work
See [MNOT] for a survey of related work. Linked JSON is most similar
to [JSONREF], but has the following differences:
- It names the special field "link" instead of "$ref".
- It provides an escape hatch for when users need to encode the
string "link".
- It allows metadata to be specified on links.
- The contents of a link need not be JSON.
This enables software to automatically differentiate Links from
strings. Software could then automatically fetch, cache, and
transclude the author object into the book object, for instance, or
transform the relative link to absolute.
JSON-LD [JSONLD] also supports linking in JSON, but requires a number
of other features to be implemented as well. Linked JSON is lighter
and easier to implement for the specific purpose of linking JSON.
(Todo: compare with HAL, Siren, JSON:API, and Collection+JSON as
described at https://github.com/badgateway/ketting)
3. Resolution
Resolution of a Link SHOULD yield the referenced value.
If the URI contained in the JSON Reference value is a relative URI,
then the base URI resolution MUST be calculated according to
[RFC3986], Section 5.2. Resolution is performed relative to the
referring document.
4. Media Type
Linked JSON resources MAY use the media type
"application/linked-json".
5. IANA Considerations
XXX fill this in.
6. Security Considerations
XXX fill this in.
7. Conventions
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119].
8. Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
9. References
9.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005.
9.2. Informative References
[RFC8288] M. Nottingham, "Web Linking", RFC 8288, October 2017.
[GRAPHQL] Facebook, "GraphQL", June 2018.
[MNOT] Nottingham, M., "Linking in JSON", November 2011.
[JSONREF] Bryan, P., and K. Zyp, "JSON Reference", September 2012.
[JSONLD] Sporny, M., Longley, D., Kellogg, G., Lanthaler, M., and
N. Lindström, "JSON-LD", January 2014.
Author's Address
For more information, the author of this document are best contacted
via Internet mail:
Michael Toomim
Invisible College, Berkeley
2053 Berkeley Way
Berkeley, CA 94704
EMail: [email protected]
Web: https://invisible.college/@toomim