Internet Engineering Task Force P. Bryan, Ed.
Internet-Draft ForgeRock US, Inc.
Intended status: Informational K. Zyp
Expires: May 17, 2012 SitePen (USA)
November 14, 2011
JSON Reference
draft-pbryan-zyp-json-ref-00
Abstract
JSON Reference allows a JSON value to be referenced from within a
JSON document.
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). 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."
This Internet-Draft will expire on May 17, 2012.
Copyright Notice
Copyright (c) 2011 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.
Bryan & Zyp Expires May 17, 2012 [Page 1]
Internet-Draft JSON Reference November 2011
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
4. Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . 3
5. Media Type . . . . . . . . . . . . . . . . . . . . . . . . . . 3
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4
7. Security Considerations . . . . . . . . . . . . . . . . . . . . 4
8. Normative References . . . . . . . . . . . . . . . . . . . . . 4
Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . . 4
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 4
Bryan & Zyp Expires May 17, 2012 [Page 2]
Internet-Draft JSON Reference November 2011
1. Introduction
This specification defines a JSON [RFC4627] structure for referencing
a specific JSON value within a JSON document. This provides a basis
for transclusion in JSON: the use of a target resource as an
effective substitute for the reference.
2. 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].
3. Syntax
A JSON Reference is a JSON object containing a single member "$ref",
whose value identifies another JSON value via a URI [RFC3986].
Example:
{ "$ref": "http://example.com/example.json#/foo/bar" }
4. Resolution
Resolution of a JSON Reference object SHOULD yield the referenced
JSON 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.
If a URI contains a fragment identifier, then the fragment should be
resolved per the fragment resolution mechansim of the referrant
document. If the representation of the referrant document is JSON,
then the fragment identifier SHOULD be interpreted as a [JSON
Pointer].
5. Media Type
Documents that use JSON Reference SHOULD include a media type
parameter: application/json; profile=http://json-schema.org/json-ref
or refer to a schema that extends http://json-schema.org/json-ref.
Bryan & Zyp Expires May 17, 2012 [Page 3]
Internet-Draft JSON Reference November 2011
6. IANA Considerations
This draft includes no request to IANA.
7. Security Considerations
A JSON Reference is not guaranteed to resolve to a JSON value.
Implementations of this specification should be aware of this and
take appropriate precautions.
8. Normative References
[JSON Pointer]
Bryan, P. and K. Zyp, "JSON Pointer", October 2011, <http:
//tools.ietf.org/html/draft-pbryan-zyp-json-pointer-02>.
[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.
[RFC4627] Crockford, D., "The application/json Media Type for
JavaScript Object Notation (JSON)", RFC 4627, July 2006.
Appendix A. Examples
TBD.
Authors' Addresses
Paul C. Bryan (editor)
ForgeRock US, Inc.
201 NE Park Plaza Drive Suite 196
Vancouver, WA 98684
USA
Phone: +1 604 783 1481
Email: paul.bryan@forgerock.com
Bryan & Zyp Expires May 17, 2012 [Page 4]
Internet-Draft JSON Reference November 2011
Kris Zyp
SitePen (USA)
530 Lytton Avenue
Palo Alto, CA 94301
USA
Phone: +1 650 968 8787
Email: kris@sitepen.com
Bryan & Zyp Expires May 17, 2012 [Page 5]