idnits 2.17.1 draft-saintandre-json-namespaces-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (October 24, 2011) is 4568 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 4627 (ref. 'JSON') (Obsoleted by RFC 7158, RFC 7159) == Outdated reference: A later version (-04) exists of draft-zyp-json-schema-03 == Outdated reference: A later version (-31) exists of draft-ietf-oauth-v2-22 == Outdated reference: A later version (-05) exists of draft-ietf-appsawg-xdash-02 Summary: 1 error (**), 0 flaws (~~), 4 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group P. Saint-Andre 3 Internet-Draft J. Hildebrand 4 Intended status: Informational M. Miller 5 Expires: April 26, 2012 Cisco 6 October 24, 2011 8 JavaScript Object Notation (JSON) Namespaces 9 draft-saintandre-json-namespaces-00 11 Abstract 13 This document defines a convention for namespaced variable names in 14 JavaScript Object Notation (JSON) data. 16 Status of this Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on April 26, 2012. 33 Copyright Notice 35 Copyright (c) 2011 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Namespace Convention . . . . . . . . . . . . . . . . . . . . . 3 52 3. When and How to Use JSON Namespaces . . . . . . . . . . . . . . 3 53 4. Security Considerations . . . . . . . . . . . . . . . . . . . . 4 54 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 4 55 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 6.1. Normative References . . . . . . . . . . . . . . . . . . . 4 57 6.2. Informative References . . . . . . . . . . . . . . . . . . 4 58 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . . 5 59 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 5 61 1. Introduction 63 JavaScript Object Notation [JSON] is a text format for the 64 serialization of structured data, derived from the object literals of 65 the JavaScript programming language. Unlike the Extensible Markup 66 Language [XML], JSON does not provide methods for qualifying variable 67 names, as XML does for elements and attributes [XML-NAMES]. However, 68 in certain circumstances such namespaces can be useful. Therefore, 69 this document defines a convention for namespaced variable names in 70 JSON data. 72 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 73 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 74 "OPTIONAL" in this document are to be interpreted as described in 75 [RFC2119]. 77 Feedback is welcome on the apps-discuss@ietf.org mailing list. 79 2. Namespace Convention 81 Various approaches have been proposed to namespaces (or "distributed 82 extensibility") in JSON, from a centralized registry of variable 83 names to prefixing with the "reverse domain name" of the namespace 84 owner (e.g., "com.example.foo"). All of these approaches are 85 preferable to use of the "x-" prefix [XDASH] or a similar 86 construction, since they provides attribution and traceability for 87 each namespace. The convention described here follows "Clark 88 Notation" [CLARK] by preceding a variable name with a Uniform 89 Resource Identifier [URI] enclosed in curly brackets ('{' and '}'). 90 The use of URIs provides improved re-use of data models across 91 existing representations, especially with XML when qualified by XML 92 namespaces. 94 In JSON, a variable name that is namespaced in this way is the 95 "string" production when appearing as the first part of the "member" 96 production, as those productions are defined in [JSON]. An example 97 follows. 99 {http://example.com/foo}bar 101 Namespace names MUST NOT include the characters '{' and '}'. 103 3. When and How to Use JSON Namespaces 105 The convention described here is not intended for use in "standalone" 106 JSON objects, especially those defined by a JSON schema 108 [JSON-SCHEMA]. Instead, it is intended for use when a particular 109 variable is likely to be re-used or interleaved within data that 110 represents other JSON objects. The following example shows a 111 namespaced variable name used within an OAuth access token [OAUTH]. 113 { 114 "access_token":"2YotnFZFEjr1zCsicMWpAA", 115 "token_type":"example", 116 "expires_in":3600, 117 "refresh_token":"tGzv3JOkF0XG5Qx2TlKWIA", 118 "{http://example.com/foo}bar":"baz" 119 } 121 Namespaces MUST NOT be used for core JSON attributes (such as 'char' 122 and 'number'). 124 An application MUST ignore namespaced variables that it does not 125 understand, where by "ignore" is meant "discard the data without 126 acting upon it or returning an error to the sender". 128 4. Security Considerations 130 This convention introduces no security concerns beyond those 131 described in [JSON]. 133 5. IANA Considerations 135 This document requests no actions of the IANA. 137 6. References 139 6.1. Normative References 141 [JSON] Crockford, D., "The application/json Media Type for 142 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 144 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 145 Requirement Levels", BCP 14, RFC 2119, March 1997. 147 6.2. Informative References 149 [CLARK] Clark, J., "Clark Notation", February 1999, 150 . 152 [JSON-SCHEMA] 153 Zyp, K. and G. Court, "A JSON Media Type for Describing 154 the Structure and Meaning of JSON Documents", 155 draft-zyp-json-schema-03 (work in progress), 156 November 2010. 158 [OAUTH] Hammer-Lahav, E., Recordon, D., and D. Hardt, "The OAuth 159 2.0 Authorization Protocol", draft-ietf-oauth-v2-22 (work 160 in progress), September 2011. 162 [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 163 Resource Identifier (URI): Generic Syntax", STD 66, 164 RFC 3986, January 2005. 166 [XDASH] Saint-Andre, P., Crocker, D., and M. Nottingham, 167 "Deprecating Use of the "X-" Prefix in Application 168 Protocols", draft-ietf-appsawg-xdash-02 (work in 169 progress), October 2011. 171 [XML] Maler, E., Yergeau, F., Sperberg-McQueen, C., Paoli, J., 172 and T. Bray, "Extensible Markup Language (XML) 1.0 (Fifth 173 Edition)", World Wide Web Consortium Recommendation REC- 174 xml-20081126, November 2008, 175 . 177 [XML-NAMES] 178 Thompson, H., Hollander, D., Layman, A., Bray, T., and R. 179 Tobin, "Namespaces in XML 1.0 (Third Edition)", World Wide 180 Web Consortium Recommendation REC-xml-names-20091208, 181 December 2009, 182 . 184 Appendix A. Acknowledgements 186 This document has benefited from texts about distributed 187 extensibility posted on the Internet by David Baron, Tim Bray, James 188 Clark, Yaron Goland, Joe Gregoria, Mike Hanson, Jack Moffitt, Mark 189 Nottingham, and Simon St. Laurent. 191 Authors' Addresses 193 Peter Saint-Andre 194 Cisco 195 1899 Wynkoop Street, Suite 600 196 Denver, CO 80202 197 USA 199 Phone: +1-303-308-3282 200 Email: psaintan@cisco.com 202 Joe Hildebrand 203 Cisco 204 1899 Wynkoop Street, Suite 600 205 Denver, CO 80202 206 USA 208 Email: jhildebr@cisco.com 210 Matt Miller 211 Cisco 212 1899 Wynkoop Street, Suite 600 213 Denver, CO 80202 214 USA 216 Phone: +1-303-308-3282 217 Email: mamille2@cisco.com