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.

Table of Contents

• 1. Introduction
• 2. Namespace Convention
• 3. When and How to Use JSON Namespaces
• 4. Security Considerations
• 5. IANA Considerations
• 6. References
• 6.1. Normative References
• 6.2. Informative References
• Appendix A. Acknowledgements
• Authors' Addresses

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

6.2. Informative References

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