draft-toomim-httpbis-linked-json-00.txt

Internet-Draft                                                 M. Toomim
Expires: Aug 8, 2026                                   Invisible College
Intended status: Proposed Standard                            B. Bellomy
                                                       Invisible College
                                                            Feb 12, 2026

                                 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, or to cache a
   pre-fetched result.



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"
       }
     }

   A "body" field can be used to include a cache of the resource, to
   save the client a round-trip when fetching it:

     {
       "link: "/post/1234",
       "body": {
         "title": "Hello world!",
         "body": "This is my first post!,
         "author": "Michael Toomim"
        }
      }

   Metadata fields can also express Link Relation Types, as defined in
   [RFC8288], or GraphQL [GRAPHQL] queries:

     { "link": "/post/234", "range": "{title, body, comments[0:5]}" }

   The meaning of particular fields can be standardized by registering
   with IANA, as specified in section 5.


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.  Also IPLD.)

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 use the media type
   "application/linked+json".

5.  IANA Considerations

   XXX fill this in.

5.1.  Linked JSON Field Registry

   The "Linked JSON Field Registry" defines the namespace for the
   version type names and refers to their corresponding specifications.
   The registry will be created and maintained at
   <http://www.iana.org/assignments/linked-json-fields>.

5.1.1.  Procedure

   Registration of a Linked JSON Field MUST include the following
   fields:

     - Type name
     - Required parameters
     - Optional parameters
     - Description
     - Security considerations
     - Interoperability considerations
     - Obsolete/Non-obsolete status
     - Published specification
     - Person & email address to contact for further information

   Values to be added to this namespace require IETF Review (see
   [RFC5226], Section 4.1).

5.1.2.  Linked JSON Field Registrations

   [todo: fill this in]

   - version: the version that you are linking to.  issued in the GET
     request.

   - range: the range linking to.  also issued in GET request.

   - body: a cache of the expected response to the GET request.
     - [todo: specify how to set Accept: header to get right
       content-type of response]

5.1.3.  Comments on Linked JSON Field Registrations

   Comments on registered Linked JSON Fields may be submitted by members
   of the community to the IANA at iana@iana.org.  These comments will
   be reviewed by the Linked JSON Fields reviewer and then passed on to
   the "owner" of the Linked JSON Field if possible.  Submitters of
   comments may request that their comment be attached to the Linked
   JSON Field registration itself; if the IANA, in consultation with the
   Version Types reviewer, approves, the comment will be made accessible
   in conjunction with the type registration.

5.1.4.  Change Procedures

   Once a Linked JSON Field has been published by the IANA, the owner
   may request a change to its definition.  The same procedure that
   would be appropriate for the original registration request is used to
   process a change request.

   Linked JSON Field registrations may not be deleted; Linked JSON
   Fields that are no longer believed appropriate for use can be
   declared OBSOLETE; such Linked JSON Fields will be clearly marked in
   the list published by the IANA.

   Significant changes to a Linked JSON Field's definition should be
   requested only when there are serious omissions or errors in the
   published specification.  When review is required, a change request
   may be denied if it renders entities that were valid under the
   previous definition invalid under the new definition.

   The owner of a Linked JSON Field may pass responsibility to another
   person or agency by informing the IANA; this can be done without
   discussion or review.

   The IESG may reassign responsibility for a Linked JSON Field.  The
   most common case of this will be to enable changes to be made to
   types where the author of the registration has died, moved out of
   contact, or is otherwise unable to make changes that are important to
   the community.


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: toomim@gmail.com
   Web:   https://invisible.college/@toomim