-
Notifications
You must be signed in to change notification settings - Fork 2
/
draft-bhat-vcarddav-json.xml
463 lines (431 loc) · 20.7 KB
/
draft-bhat-vcarddav-json.xml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
<?xml version="1.0"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc compact="yes"?>
<?rfc strict="yes"?>
<?rfc symrefs="yes"?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<rfc category="std" docName="draft-bhat-vcarddav-json-00" ipr="trust200902">
<front>
<title abbrev="vCard in JSON">A JavaScript Object Notation (JSON) Representation for vCard</title>
<author initials="R." surname="Bhat" fullname="Raghurama Bhat">
<organization>Cisco Systems, Inc.</organization>
<address>
<postal>
<street>900 McCarthy Blvd.</street>
<city>Milpitas</city>
<region>CA</region>
<code>95035</code>
<country>USA</country>
</postal>
<phone>+1-408-902-2123</phone>
<email>ragbhat@cisco.com</email>
</address>
</author>
<author initials="P." surname="Saint-Andre" fullname="Peter Saint-Andre">
<organization>Cisco Systems, Inc.</organization>
<address>
<postal>
<street>1899 Wynkoop Street, Suite 600</street>
<city>Denver</city>
<region>CO</region>
<code>80202</code>
<country>USA</country>
</postal>
<phone>+1-303-308-3282</phone>
<email>psaintan@cisco.com</email>
</address>
</author>
<date year="2012" month="June" day="5"/>
<keyword>vCard</keyword>
<keyword>JSON</keyword>
<abstract>
<t>This document defines a representation of vCard data in JavaScript Object Notation (JSON).</t>
</abstract>
</front>
<middle>
<section title="Introduction" anchor="intro">
<t>vCard <xref target='RFC6350'/> is a data format for representing and exchanging information about individuals and other entities. It is a text-based format (as opposed to a binary format). This document defines a representation for vCard data in JavaScript Object Notation (JSON), a lightweight, text-based, language-independent data interchange format derived from the ECMAScript Programming Language Standard (see <xref target='RFC4627'/>). As with the XML representation of vCard defined in <xref target='RFC6351'/>, the data structure is exactly the same as for plain vCard, enabling a 1-to-1 mapping between the plain vCard format and the JSON representation (or the XML representation). The JSON formatting might be preferred in some contexts where JSON facilities are readily available and can be reused instead of writing a standalone vCard parser.</t>
</section>
<section title="Discussion Venue" anchor="venue">
<t>The preferred discussion venue for this document is the vcarddav@ietf.org mailing list, for which subscription information and archives can be found at <eref target='https://www.ietf.org/mailman/listinfo/vcarddav'/>.</t>
</section>
<section title="Terminology" anchor="terms">
<t>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 <xref target='RFC2119'/>.</t>
</section>
<section title="Example" anchor="example">
<t>To ease comparison with both plain vCard and the XML representation, the following example is a JSON representation of the same vCard (for Simon Perreault) that is also shown in <xref target='RFC6350'/> and <xref target='RFC6351'/>.</t>
<figure anchor='figure-1' title='JSON representation of RFC 6350 example'>
<artwork><![CDATA[
{
"version":"4.0",
"fn": "Simon Perreault",
"n": {
"surname": "Simon",
"given": "Perreault",
"suffix": [ "ing. jr", "M.Sc."]
},
"bday": { "date": "--0203" },
"anniversary": { "date-time": "20090808T1430-0500" },
"gender": { "sex" : "M" },
"lang": [ {
"pref": 1,
"language-tag": "fr",
},
{
"pref": 2,
"language-tag": "en",
},
],
"org": {
"type": "work",
"text": "Viagenie"
},
"adr": {
"type": "work",
"label": "Simon Perreault
2875 boul. Laurier, suite D2-630
Quebec, QC, Canada G1V 2M2",
"street": "2875 boul. Laurier, suite D2-630",
"locality": "Quebec",
"region": "QC",
"code": "G1V 2M2",
"country": "CA"
},
"tel": [ {
"type": ["work", "voice"],
"uri": "tel:+1-418-656-9254;ext=102"
},
{
"type": ["work", "text", "voice", "cell", "video"],
"uri": "tel:+1-418-262-6501"
}
],
"email": {
"type": "work",
"text": "simon.perreault@viagenie.ca"
},
"geo": {
"type": "work",
"uri": "geo:46.766336,-71.28955"
},
"key": {
"type": "work",
"uri": "http://www.viagenie.ca/simon.perreault/simon.asc"
},
"tz": "America/Montreal",
"url": {
"type": "home",
"uri": "http://nomis80.org"
}
}
]]></artwork>
</figure>
</section>
<section title="Design Considerations" anchor="design">
<t>The general idea is to map vCard parameters, properties and value types to JSON property/value pairs. For example, the "FN" property is mapped to the fn property. Value contains a text string that corresponds to the vCard property's value. vCard parameters are also mapped to JSON objects which are contained in the value object. For example, the "TYPE" parameter applied to the "TEL" property would look like the following in JSON.</t>
<figure anchor='figure-2' title='Mapping of a vCard parameter'>
<artwork><![CDATA[
"tel": {
"type": [ "voice", "video" ],
"uri": "tel:+1-555-555-555"
}
]]></artwork>
</figure>
<t>Parameters taking a list of values and properties with cardinality of more than one are converted to a JSON array object. Properties having structured values (e.g., the "N" property) are expressed by nested JSON object trees. Properties within that tree ("surname", "given", etc.) are mapped as simple name/value pairs. These pairs should follow the schema defined by the XML mapping of vCard(Appendix A in <xref target='RFC6351'/>) Line folding is a non-issue in JSON. Therefore, the mapping from vCard to JSON is done after the unfolding procedure is carried out. Conversely, the mapping from JSON to vCard is done before the folding procedure is carried out. The group construct (Section 3.2 in <xref target='RFC6350'/>) is represented with the JSON object of the same name. For example:</t>
<figure anchor='figure-3' title='Mapping of lists and structured values'>
<artwork><![CDATA[
{
"version" : "4.0"
"contact": {
"fn": "...",
"email": "..."
},
"media" : {
"photo": "..."
},
"categories": "..."
}
]]></artwork>
</figure>
<t>... is equivalent to:</t>
<figure anchor='figure-4' title='Plain vCard equivalent'>
<artwork><![CDATA[
BEGIN:VCARD
VERSION:4.0
contact.FN=...
contact.EMAIL=...
media.PHOTO=...
CATEGORIES=...
END:VCARD
]]></artwork>
</figure>
<t>The VALUE parameter from the plain VCARD format is used as the property name in the JSON format. If there is no VALUE parameter specified, it is treated as equivalent to VALUE=text. For example:</t>
<figure anchor='figure-5' title='Mapping of VALUE parameter'>
<artwork><![CDATA[
{
"email": {
"type": "work",
"text": "simon.perreault@viagenie.ca"
},
"geo": {
"type": "work",
"uri": "geo:46.766336,-71.28955"
},
"bday": { "date": "--0203" },
}
]]></artwork>
</figure>
<t>... is equivalent to:</t>
<figure anchor='figure-6' title='Plain vCard equivalent'>
<artwork><![CDATA[
BEGIN:VCARD
VERSION:4.0
EMAIL;VALUE=text;type=work:simon.perreault@viagenie.ca
GEO;VALUE=uri;type=work:geo:46.766336,-71.28955
BDATE;VALUE=date:--0203
END:VCARD
]]></artwork>
</figure>
<t>In the plain vCard format, the "VERSION" property was mandatory and played a role in extensibility. In XML, this property was dropped in favor of the XML namespace mechanism. In the JSON mapping, we keep the "version" property, which plays a similar role as in the plain vCard format.</t>
<t>Finally, there is no reason to include a top-level name of "vcard" or "vcards", since the data type can be determined from the media type of the data file.</t>
</section>
<section title="Extensibility" anchor="extensibility">
<t>The plain vCard format is extensible. New properties, parameters, data types and values (collectively known as vCard elements, not to be confused with XML elements) can be registered with IANA (see <xref target='RFC6350'/>, Section 10.2). It is expected that these vCard extensions will also specify extensions to the JSON format described in this document. New JSON vCard property and parameter element names MUST be lower-case. This is necessary to ensure that round-tripping between JSON and plain-text vCard works correctly. Unregistered extensions (i.e., those starting with "X-" and "VND-...-") are expressed in JSON by using properties starting with "x-" and "vnd-...-". Refer to <xref target='conversions'/> for the implications when converting between plain-text vCard and JSON. For example:</t>
<figure anchor='figure-7' title='An example of extensibility'>
<artwork><![CDATA[
{
"x-my-prop": {
"pref": 1,
"text": "value goes here"
}
}
]]></artwork>
</figure>
<t>A vCard JSON parser MUST ignore JSON parameters and properties for which it doesn't recognize the name.</t>
<t>In the XML representation of vCard <xref target='RFC6351'/>, extensibility is handled in part by using XML namespaces <xref target='XML-NAMES'/> for properties and parameters that have no equivalent in plain-text vCard. For extensions that might appear in both the JSON representation and the XML representation, it is RECOMMENDED to represent the JSON parameter or property name in "Clark Notation" <xref target='CLARK'/> by preceding the name itself with the Uniform Resource Identifier <xref target='RFC3986'/> of the XML namespace, enclosed in curly brackets ('{' and '}'); thus the "expanded name" will be of the form "{URI}name". For extensions that will appear in the JSON representation but not the XML representation, a mere (non-expanded) name can be used, or the name can be an expanded name formed in another manner (e.g., using the "reverse domain name" convention such as "com.example.vcard.foo").</t>
<t>The JSON format does not validate the cardinality of properties. This is a limitation of the JSON format specification. Cardinalities of the plain vCard format <xref target='RFC6350'/> MUST still be respected.</t>
</section>
<section title="Format Conversions" anchor="conversions">
<t>To follow</t>
</section>
<section title="Schema definition" anchor="schema">
<t>To follow</t>
</section>
<section title="Security Considerations" anchor="security">
<t>All the security considerations applicable to plain vCard <xref target='RFC6350'/> are also applicable to the JSON representation of vCard.</t>
<t>As explained in <xref target='RFC4627'/>, JSON is a subset of JavaScript, but it is a safe subset that excludes assignment and invocation. A JSON text can be safely passed into JavaScript's eval() function (which compiles and executes a string) if all the characters not enclosed in strings are in the set of characters that form JSON tokens.</t>
</section>
<section title="IANA Considerations" anchor="iana">
<t>To: ietf-types@iana.org</t>
<t>Subject: Registration of media type application/vcard+json</t>
<t>
<list style='hanging'>
<t hangText="Type name: application"></t>
<t hangText="Subtype name: vcard+json"></t>
<t hangText="Required parameters: (none)"></t>
<t hangText="Optional parameters: (none)"></t>
<t hangText="Encoding considerations:">8bit if UTF-8; binary if UTF-16 or UTF-32; see RFC 4627.</t>
<t hangText="Security considerations:">All of the security considerations specified in RFC 4627 and RFC 6350 apply.</t>
<t hangText="Interoperability considerations: (none)"></t>
<t hangText="Specification:">&rfc.number;</t>
<t hangText="Applications that use this media type:">vCard processors.</t>
<t hangText="Additional information:">
<list style='hanging'>
<t hangText="Magic number(s):">(none)</t>
<t hangText="File extension(s):">.jcard</t>
<t hangText="Macintosh file type code(s):">TEXT</t>
</list>
</t>
<t hangText="Person and email address to contact for further information:">vCard discussion mailing list, <vcarddav@ietf.org></t>
<t hangText="Intended usage:">COMMON</t>
<t hangText="Restrictions on usage:">(none)</t>
<t hangText="Author:">Peter Saint-Andre, <psaintan@cisco.com></t>
<t hangText="Change controller:">Peter Saint-Andre, <psaintan@cisco.com></t>
</list></t>
</section>
<section title="Acknowledgements" anchor="acks">
<t>Thanks to Joe Hildebrand for his feedback.</t>
<t>Some text in this document was borrowed from <xref target='RFC6351'/>.</t>
</section>
</middle>
<back>
<references title="Normative References">
<reference anchor='RFC2119'>
<front>
<title abbrev='RFC Key Words'>Key words for use in RFCs to Indicate Requirement Levels</title>
<author initials='S.' surname='Bradner' fullname='Scott Bradner'>
<organization>Harvard University</organization>
<address>
<postal>
<street>1350 Mass. Ave.</street>
<street>Cambridge</street>
<street>MA 02138</street></postal>
<phone>- +1 617 495 3864</phone>
<email>sob@harvard.edu</email></address></author>
<date year='1997' month='March' />
<area>General</area>
<keyword>keyword</keyword>
<abstract>
<t>
In many standards track documents several words are used to signify
the requirements in the specification. These words are often
capitalized. This document defines these words as they should be
interpreted in IETF documents. Authors who follow these guidelines
should incorporate this phrase near the beginning of their document:
<list>
<t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL
NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in
RFC 2119.
</t></list></t>
<t>
Note that the force of these words is modified by the requirement
level of the document in which they are used.
</t></abstract></front>
<seriesInfo name='BCP' value='14' />
<seriesInfo name='RFC' value='2119' />
<format type='TXT' octets='4723' target='http://www.rfc-editor.org/rfc/rfc2119.txt' />
<format type='HTML' octets='17491' target='http://xml.resource.org/public/rfc/html/rfc2119.html' />
<format type='XML' octets='5777' target='http://xml.resource.org/public/rfc/xml/rfc2119.xml' />
</reference>
<reference anchor='RFC4627'>
<front>
<title>The application/json Media Type for JavaScript Object Notation (JSON)</title>
<author initials='D.' surname='Crockford' fullname='D. Crockford'>
<organization /></author>
<date year='2006' month='July' />
<abstract>
<t>JavaScript Object Notation (JSON) is a lightweight, text-based, language-independent data interchange format. It was derived from the ECMAScript Programming Language Standard. JSON defines a small set of formatting rules for the portable representation of structured data. This memo provides information for the Internet community.</t></abstract></front>
<seriesInfo name='RFC' value='4627' />
<format type='TXT' octets='16319' target='http://www.rfc-editor.org/rfc/rfc4627.txt' />
</reference>
<reference anchor='RFC6350'>
<front>
<title>vCard Format Specification</title>
<author initials='S.' surname='Perreault' fullname='S. Perreault'>
<organization /></author>
<date year='2011' month='August' />
<abstract>
<t>This document defines the vCard data format for representing and exchanging a variety of information about individuals and other entities (e.g., formatted and structured name and delivery addresses, email address, multiple telephone numbers, photograph, logo, audio clips, etc.). This document obsoletes RFCs 2425, 2426, and 4770, and updates RFC 2739. [STANDARDS-TRACK]</t></abstract></front>
<seriesInfo name='RFC' value='6350' />
<format type='TXT' octets='139895' target='http://www.rfc-editor.org/rfc/rfc6350.txt' />
</reference>
</references>
<references title="Informative References">
<reference anchor='CLARK' target='http://www.jclark.com/xml/xmlns.htm'>
<front>
<title>Clark Notation</title>
<author initials='J.' surname='Clark' fullname='James Clark'>
</author>
<date year='1999' month='February' />
</front>
</reference>
<reference anchor='RFC3986'>
<front>
<title abbrev='URI Generic Syntax'>Uniform Resource Identifier (URI): Generic Syntax</title>
<author initials='T.' surname='Berners-Lee' fullname='Tim Berners-Lee'>
<organization abbrev='W3C/MIT'>World Wide Web Consortium</organization>
<address>
<postal>
<street>Massachusetts Institute of Technology</street>
<street>77 Massachusetts Avenue</street>
<city>Cambridge</city>
<region>MA</region>
<code>02139</code>
<country>USA</country></postal>
<phone>+1-617-253-5702</phone>
<facsimile>+1-617-258-5999</facsimile>
<email>timbl@w3.org</email>
<uri>http://www.w3.org/People/Berners-Lee/</uri></address></author>
<author initials='R.' surname='Fielding' fullname='Roy T. Fielding'>
<organization abbrev='Day Software'>Day Software</organization>
<address>
<postal>
<street>5251 California Ave., Suite 110</street>
<city>Irvine</city>
<region>CA</region>
<code>92617</code>
<country>USA</country></postal>
<phone>+1-949-679-2960</phone>
<facsimile>+1-949-679-2972</facsimile>
<email>fielding@gbiv.com</email>
<uri>http://roy.gbiv.com/</uri></address></author>
<author initials='L.' surname='Masinter' fullname='Larry Masinter'>
<organization abbrev='Adobe Systems'>Adobe Systems Incorporated</organization>
<address>
<postal>
<street>345 Park Ave</street>
<city>San Jose</city>
<region>CA</region>
<code>95110</code>
<country>USA</country></postal>
<phone>+1-408-536-3024</phone>
<email>LMM@acm.org</email>
<uri>http://larry.masinter.net/</uri></address></author>
<date year='2005' month='January' />
<area>Applications</area>
<keyword>uniform resource identifier</keyword>
<keyword>URI</keyword>
<keyword>URL</keyword>
<keyword>URN</keyword>
<keyword>WWW</keyword>
<keyword>resource</keyword>
<abstract>
<t>
A Uniform Resource Identifier (URI) is a compact sequence of characters
that identifies an abstract or physical resource. This specification
defines the generic URI syntax and a process for resolving URI references
that might be in relative form, along with guidelines and security
considerations for the use of URIs on the Internet.
The URI syntax defines a grammar that is a superset of all valid URIs,
allowing an implementation to parse the common components of a URI
reference without knowing the scheme-specific requirements of every
possible identifier. This specification does not define a generative
grammar for URIs; that task is performed by the individual
specifications of each URI scheme.
</t></abstract></front>
<seriesInfo name='STD' value='66' />
<seriesInfo name='RFC' value='3986' />
<format type='TXT' octets='141811' target='http://www.rfc-editor.org/rfc/rfc3986.txt' />
<format type='HTML' octets='213584' target='http://xml.resource.org/public/rfc/html/rfc3986.html' />
<format type='XML' octets='163534' target='http://xml.resource.org/public/rfc/xml/rfc3986.xml' />
</reference>
<reference anchor='RFC6351'>
<front>
<title>xCard: vCard XML Representation</title>
<author initials='S.' surname='Perreault' fullname='S. Perreault'>
<organization /></author>
<date year='2011' month='August' />
<abstract>
<t>This document defines the XML schema of the vCard data format. [STANDARDS-TRACK]</t></abstract></front>
<seriesInfo name='RFC' value='6351' />
<format type='TXT' octets='34086' target='http://www.rfc-editor.org/rfc/rfc6351.txt' />
</reference>
<reference anchor="XML-NAMES" target='http://www.w3.org/TR/2009/REC-xml-names-20091208'>
<front>
<title>Namespaces in XML 1.0 (Third Edition)</title>
<author initials='H.' surname='Thompson' fullname='Henry S. Thompson'>
<organization />
</author>
<author initials='D.' surname='Hollander' fullname='Dave Hollander'>
<organization />
</author>
<author initials='A.' surname='Layman' fullname='Andrew Layman'>
<organization />
</author>
<author initials='T.' surname='Bray' fullname='Tim Bray'>
<organization />
</author>
<author initials='R.' surname='Tobin' fullname='Richard Tobin'>
<organization />
</author>
<date month='December' day='8' year='2009' />
</front>
<seriesInfo name='World Wide Web Consortium Recommendation' value='REC-xml-names-20091208' />
<format type='HTML' target='http://www.w3.org/TR/2009/REC-xml-names-20091208' />
</reference>
</references>
</back>
</rfc>