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


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

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 ( 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.

Table of Contents

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 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., ""). 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.


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 [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].


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] Zyp, K and G Court, "A JSON Media Type for Describing the Structure and Meaning of JSON Documents", Internet-Draft draft-zyp-json-schema-03, November 2010.
[OAUTH] Hammer-Lahav, E, Recordon, D and D Hardt, "The OAuth 2.0 Authorization Protocol", Internet-Draft draft-ietf-oauth-v2-22, 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", Internet-Draft draft-ietf-appsawg-xdash-02, 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.

Authors' Addresses

Peter Saint-Andre Cisco 1899 Wynkoop Street, Suite 600 Denver, CO 80202 USA Phone: +1-303-308-3282 EMail:
Joe Hildebrand Cisco 1899 Wynkoop Street, Suite 600 Denver, CO 80202 USA EMail:
Matt Miller Cisco 1899 Wynkoop Street, Suite 600 Denver, CO 80202 USA Phone: +1-303-308-3282 EMail: