JSON Reference
draft-pbryan-zyp-json-ref-01
The information below is for an old version of the document.
| Document | Type |
This is an older version of an Internet-Draft whose latest revision state is "Expired".
|
|
|---|---|---|---|
| Authors | Paul Bryan , Kris Zyp | ||
| Last updated | 2011-11-24 (Latest revision 2011-11-14) | ||
| RFC stream | (None) | ||
| Formats | |||
| Additional resources | |||
| Stream | Stream state | (No stream defined) | |
| Consensus boilerplate | Unknown | ||
| RFC Editor Note | (None) | ||
| IESG | IESG state | I-D Exists | |
| Telechat date | (None) | ||
| Responsible AD | (None) | ||
| Send notices to | (None) |
draft-pbryan-zyp-json-ref-01
Internet Engineering Task Force P. Bryan, Ed.
Internet-Draft ForgeRock US, Inc.
Intended status: Informational K. Zyp
Expires: May 27, 2012 SitePen (USA)
November 24, 2011
JSON Reference
draft-pbryan-zyp-json-ref-01
Abstract
JSON Reference allows a JSON value to reference another JSON value in
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 27, 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 27, 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. Error Handling . . . . . . . . . . . . . . . . . . . . . . . . 4
6. Media Type . . . . . . . . . . . . . . . . . . . . . . . . . . 4
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4
8. Security Considerations . . . . . . . . . . . . . . . . . . . . 4
9. Normative References . . . . . . . . . . . . . . . . . . . . . 4
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 5
Appendix B. Examples . . . . . . . . . . . . . . . . . . . . . . . 5
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 5
Bryan & Zyp Expires May 27, 2012 [Page 2]
Internet-Draft JSON Reference November 2011
1. Introduction
This specification defines a JSON [RFC4627] structure which allows a
JSON value to reference another JSON value in a JSON document. This
provides the 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, which contains a member named
"$ref", which has a JSON string value. Example:
{ "$ref": "http://example.com/example.json#/foo/bar" }
If a JSON value does not have these characteristics, then it SHOULD
NOT be interpreted as a JSON Reference.
The "$ref" string value contains a URI [RFC3986], which identifies
the location of the JSON value being referenced. It is an error
condition if the string value does not conform to URI syntax rules.
Any members other than "$ref" in a JSON Reference object SHALL be
ignored.
4. Resolution
Resolution of a JSON Reference object SHOULD yield the referenced
JSON value. Implementations MAY choose to replace the reference with
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.
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].
Bryan & Zyp Expires May 27, 2012 [Page 3]
Internet-Draft JSON Reference November 2011
5. Error Handling
In the event of an error condition, evaluation of the JSON Reference
SHOULD fail to complete.
6. 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.
7. IANA Considerations
This draft includes no request to IANA.
8. Security Considerations
A JSON Reference is not guaranteed to resolve to a JSON value.
Implementations of this specification SHOULD take appropriate
precautions.
Documents containing JSON References can be structured to resolve
cyclically. Implementations SHOULD include appropriate checks to
prevent such structures from resulting in infinite recursion or
iteration.
9. 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.
Bryan & Zyp Expires May 27, 2012 [Page 4]
Internet-Draft JSON Reference November 2011
Appendix A. Acknowledgements
The authors acknowledge the following individuals for their
contributed feedback, which influenced this specification:
Bob Aman, Francis Galiegue.
Appendix B. 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
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 27, 2012 [Page 5]