-
Notifications
You must be signed in to change notification settings - Fork 16
/
draft-toomim-httpbis-nelson-00.txt
287 lines (195 loc) · 9.21 KB
/
draft-toomim-httpbis-nelson-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
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
Internet-Draft M. Toomim
Expires: Mar 8, 2020 Invisible College
Intended status: Proposed Standard B. Bellomy
Invisible College
Nov 4, 2019
NelSON
draft-toomim-httpbis-nelson-00
Abstract
NelSON is "JSON that Ted Nelson would approve of."
NelSON is an extension to JSON where any region can be framed with a
URI and HTTP Metadata. Regions with the same URI refer to the same
content, and can be transcluded into other regions, with metadata
specifying how they connect.
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 ....................................................1
1.1. Syntax .....................................................2
1.2. Escaping ...................................................3
1.3. Metadata ...................................................4
2. Related Work ....................................................5
3. Resolution ..........................................,...........6
4. Media Type ..........................................,...........7
5. IANA Considerations .............................................8
6. Security Considerations .........................................9
7. Conventions ....................................................10
8. Copyright Notice ...............................................11
9. References .....................................................12
9.1. Normative References ......................................13
9.2. Informative References ....................................14
1. Introduction
NelSON is an extension of JSON where any object with a field named
"uri" is a special Hypermedia wrapper that can specify a URI link
for the region of JSON it wraps, as well as optional metadata:
{
"uri": "/this-ietf-spec",
"content-type": "text/plain",
"val": "NelSON is ..."
}
NelSON is valid JSON. A NelSON Hypermedia wrapper can be used to
insert a link inside JSON. For instance, in the JSON for a book, one
might include a link to the author:
{
"book-name": "The way things work",
"author": { "uri": "/david-macaulay" },
"image" {
"uri": "/the-way-things-work.jpg",
"content-type": "image/png"
}
}
In addition to the specially-interpreted "uri" field, the NelSON
wrapper may also contain an optional "val" field. The presence and
contents of these two fields leads to three distinct permutations:
o "uri" is non-null, "val" is absent:
{
"uri": "/this-ietf-spec",
"content-type": "text/plain"
}
The NelSON wrapper should be interpreted as a simple pointer to
another resource with optional metadata.
o "uri" is non-null, "val" is present:
{
"uri": "/this-ietf-spec",
"content-type": "text/plain",
"val": "NelSON is ..."
}
The NelSON wrapper should be interpreted as a simple pointer to
another resource with optional metadata. "val" contains a cached
copy of that resource that the consumer may ignore.
o "uri" is null, "val" is present:
{
"uri": null,
"content-type": "text/plain",
"val": "NelSON is ..."
}
"val" should be interpreted as the resource itself, and the NelSON
wrapper should be interpreted as metadata applying to it.
If "uri" is JSON null, then the NelSON wrapper SHOULD have a "val"
field.
NelSON can be used to distinguish which strings in JSON actually
represent URIs, for example, to fetch and include the contents of
links, or to translate relative to absolute URIs.
1.1. Syntax
A NelSON Hypermedia wrapper is encoded as a JSON object with a field
named "uri":
{ "uri": "/david-macaulay" }
Any object with a field named "uri" is interpreted as a wrapper. The
value of the uri field MUST be either a string containing a URI
[RFC3986], or JSON null.
1.2. Escape Syntax
To include an actual object with a field "uri", you must escape the
field with an underscore:
{ "_uri": "foo" }
A field named "_uri" is escaped as "__uri", 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", "slice": "(bar:9)[3,4]" }
2. Related Work
A number of related formats are surveyed in [MNOT].
This draft borrows from [JSONREF], but makes the following changes:
- It names the special field "uri" instead of "$ref".
- It provides an escape hatch for when users need to encode the
string "uri".
- 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 bundles a number
of other features as well, making it more difficult to implement.
3. Resolution
Resolution of a Link SHOULD yield the referenced value.
If the URI contained in the link 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.
XXX https://tools.ietf.org/html/draft-ucarion-json-schema-language-02
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
Bryn Bellomy
Invisible College, Berkeley
2053 Berkeley Way
Berkeley, CA 94704
EMail: [email protected]
Web: https://invisible.college/@bryn