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: toomim@gmail.com Web: https://invisible.college/@toomim Bryn Bellomy Invisible College, Berkeley 2053 Berkeley Way Berkeley, CA 94704 EMail: bryn@signals.io Web: https://invisible.college/@bryn