Network Working Group P. Saint-Andre Internet-Draft J. Hildebrand Intended status: Informational M. Miller Expires: April 26, 2012 Cisco October 24, 2011 JavaScript Object Notation (JSON) Namespaces draft-saintandre-json-namespaces-00 Abstract This document defines a convention for namespaced variable names in JavaScript Object Notation (JSON) data. 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 April 26, 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. Saint-Andre, et al. Expires April 26, 2012 [Page 1] Internet-Draft JSON Namespaces October 2011 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Namespace Convention . . . . . . . . . . . . . . . . . . . . . 3 3. When and How to Use JSON Namespaces . . . . . . . . . . . . . . 3 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 4 6.1. Normative References . . . . . . . . . . . . . . . . . . . 4 6.2. Informative References . . . . . . . . . . . . . . . . . . 4 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 5 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 5 Saint-Andre, et al. Expires April 26, 2012 [Page 2] Internet-Draft JSON Namespaces October 2011 1. Introduction JavaScript Object Notation [JSON] is a text format for the serialization of structured data, derived from the object literals of the JavaScript programming language. Unlike the Extensible Markup Language [XML], JSON does not provide methods for qualifying variable names, as XML does for elements and attributes [XML-NAMES]. However, in certain circumstances such namespaces can be useful. Therefore, this document defines a convention for namespaced variable names in JSON data. The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. Feedback is welcome on the apps-discuss@ietf.org mailing list. 2. Namespace Convention Various approaches have been proposed to namespaces (or "distributed extensibility") in JSON, from a centralized registry of variable names to prefixing with the "reverse domain name" of the namespace owner (e.g., "com.example.foo"). All of these approaches are preferable to use of the "x-" prefix [XDASH] or a similar construction, since they provides attribution and traceability for each namespace. The convention described here follows "Clark Notation" [CLARK] by preceding a variable name with a Uniform Resource Identifier [URI] enclosed in curly brackets ('{' and '}'). The use of URIs provides improved re-use of data models across existing representations, especially with XML when qualified by XML namespaces. In JSON, a variable name that is namespaced in this way is the "string" production when appearing as the first part of the "member" production, as those productions are defined in [JSON]. An example follows. {http://example.com/foo}bar Namespace names MUST NOT include the characters '{' and '}'. 3. When and How to Use JSON Namespaces The convention described here is not intended for use in "standalone" JSON objects, especially those defined by a JSON schema Saint-Andre, et al. Expires April 26, 2012 [Page 3] Internet-Draft JSON Namespaces October 2011 [JSON-SCHEMA]. Instead, it is intended for use when a particular variable is likely to be re-used or interleaved within data that represents other JSON objects. The following example shows a namespaced variable name used within an OAuth access token [OAUTH]. { "access_token":"2YotnFZFEjr1zCsicMWpAA", "token_type":"example", "expires_in":3600, "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", "{http://example.com/foo}bar":"baz" } Namespaces MUST NOT be used for core JSON attributes (such as 'char' and 'number'). An application MUST ignore namespaced variables that it does not understand, where by "ignore" is meant "discard the data without acting upon it or returning an error to the sender". 4. Security Considerations This convention introduces no security concerns beyond those described in [JSON]. 5. IANA Considerations This document requests no actions of the IANA. 6. References 6.1. Normative References [JSON] Crockford, D., "The application/json Media Type for JavaScript Object Notation (JSON)", RFC 4627, July 2006. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. 6.2. Informative References [CLARK] Clark, J., "Clark Notation", February 1999, . [JSON-SCHEMA] Saint-Andre, et al. Expires April 26, 2012 [Page 4] Internet-Draft JSON Namespaces October 2011 Zyp, K. and G. Court, "A JSON Media Type for Describing the Structure and Meaning of JSON Documents", draft-zyp-json-schema-03 (work in progress), November 2010. [OAUTH] Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 2.0 Authorization Protocol", draft-ietf-oauth-v2-22 (work in progress), September 2011. [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [XDASH] Saint-Andre, P., Crocker, D., and M. Nottingham, "Deprecating Use of the "X-" Prefix in Application Protocols", draft-ietf-appsawg-xdash-02 (work in progress), October 2011. [XML] Maler, E., Yergeau, F., Sperberg-McQueen, C., Paoli, J., and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth Edition)", World Wide Web Consortium Recommendation REC- xml-20081126, November 2008, . [XML-NAMES] Thompson, H., Hollander, D., Layman, A., Bray, T., and R. Tobin, "Namespaces in XML 1.0 (Third Edition)", World Wide Web Consortium Recommendation REC-xml-names-20091208, December 2009, . Appendix A. Acknowledgements This document has benefited from texts about distributed extensibility posted on the Internet by David Baron, Tim Bray, James Clark, Yaron Goland, Joe Gregoria, Mike Hanson, Jack Moffitt, Mark Nottingham, and Simon St. Laurent. Saint-Andre, et al. Expires April 26, 2012 [Page 5] Internet-Draft JSON Namespaces October 2011 Authors' Addresses Peter Saint-Andre Cisco 1899 Wynkoop Street, Suite 600 Denver, CO 80202 USA Phone: +1-303-308-3282 Email: psaintan@cisco.com Joe Hildebrand Cisco 1899 Wynkoop Street, Suite 600 Denver, CO 80202 USA Email: jhildebr@cisco.com Matt Miller Cisco 1899 Wynkoop Street, Suite 600 Denver, CO 80202 USA Phone: +1-303-308-3282 Email: mamille2@cisco.com Saint-Andre, et al. Expires April 26, 2012 [Page 6]