idnits 2.17.00 (12 Aug 2021) /tmp/idnits50340/draft-bhat-vcarddav-json-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 (June 5, 2012) is 3636 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 4627 (Obsoleted by RFC 7158, RFC 7159) Summary: 1 error (**), 0 flaws (~~), 1 warning (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group R. Bhat 3 Internet-Draft P. Saint-Andre 4 Intended status: Standards Track Cisco Systems, Inc. 5 Expires: December 7, 2012 June 5, 2012 7 A JavaScript Object Notation (JSON) Representation for vCard 8 draft-bhat-vcarddav-json-00 10 Abstract 12 This document defines a representation of vCard data in JavaScript 13 Object Notation (JSON). 15 Status of this Memo 17 This Internet-Draft is submitted in full conformance with the 18 provisions of BCP 78 and BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF). Note that other groups may also distribute 22 working documents as Internet-Drafts. The list of current Internet- 23 Drafts is at http://datatracker.ietf.org/drafts/current/. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 This Internet-Draft will expire on December 7, 2012. 32 Copyright Notice 34 Copyright (c) 2012 IETF Trust and the persons identified as the 35 document authors. All rights reserved. 37 This document is subject to BCP 78 and the IETF Trust's Legal 38 Provisions Relating to IETF Documents 39 (http://trustee.ietf.org/license-info) in effect on the date of 40 publication of this document. Please review these documents 41 carefully, as they describe your rights and restrictions with respect 42 to this document. Code Components extracted from this document must 43 include Simplified BSD License text as described in Section 4.e of 44 the Trust Legal Provisions and are provided without warranty as 45 described in the Simplified BSD License. 47 Table of Contents 49 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 2. Discussion Venue . . . . . . . . . . . . . . . . . . . . . . . 3 51 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 4. Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 53 5. Design Considerations . . . . . . . . . . . . . . . . . . . . 5 54 6. Extensibility . . . . . . . . . . . . . . . . . . . . . . . . 7 55 7. Format Conversions . . . . . . . . . . . . . . . . . . . . . . 8 56 8. Schema definition . . . . . . . . . . . . . . . . . . . . . . 8 57 9. Security Considerations . . . . . . . . . . . . . . . . . . . 8 58 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 59 11. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 9 60 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 61 12.1. Normative References . . . . . . . . . . . . . . . . . . 9 62 12.2. Informative References . . . . . . . . . . . . . . . . . 9 63 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 10 65 1. Introduction 67 vCard [RFC6350] is a data format for representing and exchanging 68 information about individuals and other entities. It is a text-based 69 format (as opposed to a binary format). This document defines a 70 representation for vCard data in JavaScript Object Notation (JSON), a 71 lightweight, text-based, language-independent data interchange format 72 derived from the ECMAScript Programming Language Standard (see 73 [RFC4627]). As with the XML representation of vCard defined in 74 [RFC6351], the data structure is exactly the same as for plain vCard, 75 enabling a 1-to-1 mapping between the plain vCard format and the JSON 76 representation (or the XML representation). The JSON formatting 77 might be preferred in some contexts where JSON facilities are readily 78 available and can be reused instead of writing a standalone vCard 79 parser. 81 2. Discussion Venue 83 The preferred discussion venue for this document is the 84 vcarddav@ietf.org mailing list, for which subscription information 85 and archives can be found at 86 . 88 3. Terminology 90 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 91 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 92 "OPTIONAL" in this document are to be interpreted as described in 93 [RFC2119]. 95 4. Example 97 To ease comparison with both plain vCard and the XML representation, 98 the following example is a JSON representation of the same vCard (for 99 Simon Perreault) that is also shown in [RFC6350] and [RFC6351]. 101 { 102 "version":"4.0", 103 "fn": "Simon Perreault", 104 "n": { 105 "surname": "Simon", 106 "given": "Perreault", 107 "suffix": [ "ing. jr", "M.Sc."] 108 }, 109 "bday": { "date": "--0203" }, 110 "anniversary": { "date-time": "20090808T1430-0500" }, 111 "gender": { "sex" : "M" }, 112 "lang": [ { 113 "pref": 1, 114 "language-tag": "fr", 115 }, 116 { 117 "pref": 2, 118 "language-tag": "en", 119 }, 120 ], 121 "org": { 122 "type": "work", 123 "text": "Viagenie" 124 }, 125 "adr": { 126 "type": "work", 127 "label": "Simon Perreault 128 2875 boul. Laurier, suite D2-630 129 Quebec, QC, Canada G1V 2M2", 130 "street": "2875 boul. Laurier, suite D2-630", 131 "locality": "Quebec", 132 "region": "QC", 133 "code": "G1V 2M2", 134 "country": "CA" 135 }, 136 "tel": [ { 137 "type": ["work", "voice"], 138 "uri": "tel:+1-418-656-9254;ext=102" 139 }, 140 { 141 "type": ["work", "text", "voice", "cell", "video"], 142 "uri": "tel:+1-418-262-6501" 143 } 144 ], 145 "email": { 146 "type": "work", 147 "text": "simon.perreault@viagenie.ca" 148 }, 149 "geo": { 150 "type": "work", 151 "uri": "geo:46.766336,-71.28955" 152 }, 153 "key": { 154 "type": "work", 155 "uri": "http://www.viagenie.ca/simon.perreault/simon.asc" 156 }, 157 "tz": "America/Montreal", 158 "url": { 159 "type": "home", 160 "uri": "http://nomis80.org" 161 } 162 } 164 Figure 1: JSON representation of RFC 6350 example 166 5. Design Considerations 168 The general idea is to map vCard parameters, properties and value 169 types to JSON property/value pairs. For example, the "FN" property 170 is mapped to the fn property. Value contains a text string that 171 corresponds to the vCard property's value. vCard parameters are also 172 mapped to JSON objects which are contained in the value object. For 173 example, the "TYPE" parameter applied to the "TEL" property would 174 look like the following in JSON. 176 "tel": { 177 "type": [ "voice", "video" ], 178 "uri": "tel:+1-555-555-555" 179 } 181 Figure 2: Mapping of a vCard parameter 183 Parameters taking a list of values and properties with cardinality of 184 more than one are converted to a JSON array object. Properties 185 having structured values (e.g., the "N" property) are expressed by 186 nested JSON object trees. Properties within that tree ("surname", 187 "given", etc.) are mapped as simple name/value pairs. These pairs 188 should follow the schema defined by the XML mapping of vCard(Appendix 189 A in [RFC6351]) Line folding is a non-issue in JSON. Therefore, the 190 mapping from vCard to JSON is done after the unfolding procedure is 191 carried out. Conversely, the mapping from JSON to vCard is done 192 before the folding procedure is carried out. The group construct 193 (Section 3.2 in [RFC6350]) is represented with the JSON object of the 194 same name. For example: 196 { 197 "version" : "4.0" 198 "contact": { 199 "fn": "...", 200 "email": "..." 201 }, 202 "media" : { 203 "photo": "..." 204 }, 205 "categories": "..." 206 } 208 Figure 3: Mapping of lists and structured values 210 ... is equivalent to: 212 BEGIN:VCARD 213 VERSION:4.0 214 contact.FN=... 215 contact.EMAIL=... 216 media.PHOTO=... 217 CATEGORIES=... 218 END:VCARD 220 Figure 4: Plain vCard equivalent 222 The VALUE parameter from the plain VCARD format is used as the 223 property name in the JSON format. If there is no VALUE parameter 224 specified, it is treated as equivalent to VALUE=text. For example: 226 { 227 "email": { 228 "type": "work", 229 "text": "simon.perreault@viagenie.ca" 230 }, 231 "geo": { 232 "type": "work", 233 "uri": "geo:46.766336,-71.28955" 234 }, 235 "bday": { "date": "--0203" }, 236 } 238 Figure 5: Mapping of VALUE parameter 240 ... is equivalent to: 242 BEGIN:VCARD 243 VERSION:4.0 244 EMAIL;VALUE=text;type=work:simon.perreault@viagenie.ca 245 GEO;VALUE=uri;type=work:geo:46.766336,-71.28955 246 BDATE;VALUE=date:--0203 247 END:VCARD 249 Figure 6: Plain vCard equivalent 251 In the plain vCard format, the "VERSION" property was mandatory and 252 played a role in extensibility. In XML, this property was dropped in 253 favor of the XML namespace mechanism. In the JSON mapping, we keep 254 the "version" property, which plays a similar role as in the plain 255 vCard format. 257 Finally, there is no reason to include a top-level name of "vcard" or 258 "vcards", since the data type can be determined from the media type 259 of the data file. 261 6. Extensibility 263 The plain vCard format is extensible. New properties, parameters, 264 data types and values (collectively known as vCard elements, not to 265 be confused with XML elements) can be registered with IANA (see 266 [RFC6350], Section 10.2). It is expected that these vCard extensions 267 will also specify extensions to the JSON format described in this 268 document. New JSON vCard property and parameter element names MUST 269 be lower-case. This is necessary to ensure that round-tripping 270 between JSON and plain-text vCard works correctly. Unregistered 271 extensions (i.e., those starting with "X-" and "VND-...-") are 272 expressed in JSON by using properties starting with "x-" and 273 "vnd-...-". Refer to Section 7 for the implications when converting 274 between plain-text vCard and JSON. For example: 276 { 277 "x-my-prop": { 278 "pref": 1, 279 "text": "value goes here" 280 } 281 } 283 Figure 7: An example of extensibility 285 A vCard JSON parser MUST ignore JSON parameters and properties for 286 which it doesn't recognize the name. 288 In the XML representation of vCard [RFC6351], extensibility is 289 handled in part by using XML namespaces [XML-NAMES] for properties 290 and parameters that have no equivalent in plain-text vCard. For 291 extensions that might appear in both the JSON representation and the 292 XML representation, it is RECOMMENDED to represent the JSON parameter 293 or property name in "Clark Notation" [CLARK] by preceding the name 294 itself with the Uniform Resource Identifier [RFC3986] of the XML 295 namespace, enclosed in curly brackets ('{' and '}'); thus the 296 "expanded name" will be of the form "{URI}name". For extensions that 297 will appear in the JSON representation but not the XML 298 representation, a mere (non-expanded) name can be used, or the name 299 can be an expanded name formed in another manner (e.g., using the 300 "reverse domain name" convention such as "com.example.vcard.foo"). 302 The JSON format does not validate the cardinality of properties. 303 This is a limitation of the JSON format specification. Cardinalities 304 of the plain vCard format [RFC6350] MUST still be respected. 306 7. Format Conversions 308 To follow 310 8. Schema definition 312 To follow 314 9. Security Considerations 316 All the security considerations applicable to plain vCard [RFC6350] 317 are also applicable to the JSON representation of vCard. 319 As explained in [RFC4627], JSON is a subset of JavaScript, but it is 320 a safe subset that excludes assignment and invocation. A JSON text 321 can be safely passed into JavaScript's eval() function (which 322 compiles and executes a string) if all the characters not enclosed in 323 strings are in the set of characters that form JSON tokens. 325 10. IANA Considerations 327 To: ietf-types@iana.org 329 Subject: Registration of media type application/vcard+json 330 Type name: application 331 Subtype name: vcard+json 332 Required parameters: (none) 333 Optional parameters: (none) 334 Encoding considerations: 8bit if UTF-8; binary if UTF-16 or UTF-32; 335 see RFC 4627. 336 Security considerations: All of the security considerations 337 specified in RFC 4627 and RFC 6350 apply. 338 Interoperability considerations: (none) 339 Specification: XXXX 340 Applications that use this media type: vCard processors. 341 Additional information: 342 Magic number(s): (none) 343 File extension(s): .jcard 344 Macintosh file type code(s): TEXT 345 Person and email address to contact for further information: vCard 346 discussion mailing list, 347 Intended usage: COMMON 348 Restrictions on usage: (none) 349 Author: Peter Saint-Andre, 350 Change controller: Peter Saint-Andre, 352 11. Acknowledgements 354 Thanks to Joe Hildebrand for his feedback. 356 Some text in this document was borrowed from [RFC6351]. 358 12. References 360 12.1. Normative References 362 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 363 Requirement Levels", BCP 14, RFC 2119, March 1997. 365 [RFC4627] Crockford, D., "The application/json Media Type for 366 JavaScript Object Notation (JSON)", RFC 4627, July 2006. 368 [RFC6350] Perreault, S., "vCard Format Specification", RFC 6350, 369 August 2011. 371 12.2. Informative References 373 [CLARK] Clark, J., "Clark Notation", February 1999, 374 . 376 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 377 Resource Identifier (URI): Generic Syntax", STD 66, 378 RFC 3986, January 2005. 380 [RFC6351] Perreault, S., "xCard: vCard XML Representation", 381 RFC 6351, August 2011. 383 [XML-NAMES] 384 Thompson, H., Hollander, D., Layman, A., Bray, T., and R. 385 Tobin, "Namespaces in XML 1.0 (Third Edition)", World Wide 386 Web Consortium Recommendation REC-xml-names-20091208, 387 December 2009, 388 . 390 Authors' Addresses 392 Raghurama Bhat 393 Cisco Systems, Inc. 394 900 McCarthy Blvd. 395 Milpitas, CA 95035 396 USA 398 Phone: +1-408-902-2123 399 Email: ragbhat@cisco.com 401 Peter Saint-Andre 402 Cisco Systems, Inc. 403 1899 Wynkoop Street, Suite 600 404 Denver, CO 80202 405 USA 407 Phone: +1-303-308-3282 408 Email: psaintan@cisco.com