-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathrfc9553.xml
5676 lines (5557 loc) · 259 KB
/
rfc9553.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
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc [
<!ENTITY nbsp " ">
<!ENTITY zwsp "​">
<!ENTITY nbhy "‑">
<!ENTITY wj "⁠">
]>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" docName="draft-ietf-calext-jscontact-16" number="9553" submissionType="IETF" consensus="true" category="std" xml:lang="en" obsoletes="" updates="" tocInclude="true" symRefs="true" sortRefs="true" version="3">
<!-- xml2rfc v2v3 conversion 3.6.0 -->
<front>
<!--[rfced] *AD, changes were submitted twice after the document
was initially approved. Please review the updates from version 15
to version 17 and let us know if you approve. The updates can
be viewed in this diff file:
https://www.rfc-editor.org/authors/rfc9553-ad-diff.html
Additionally, under "Until Version" (4 instances), we updated the
key words for clarity by replacing "MUST be not set, or be one of
the allowed values" with "MUST NOT be set or MUST be one of the
allowed values" as shown below. Please review and approve of this
change to the key words.
Original:
The Until Version value either MUST NOT be set, or be one of the
allowed values of the version property in the JSContact Enum Value
registry (see Table 1).
Current:
The Until Version value either MUST NOT be set or MUST be one of
the allowed values of the version property in the "JSContact Enum
Values" registry (see Table 1).
-->
<!--[rfced] This document is part of Cluster 481. As it does not
reference the other cluster documents, we have moved it forward in
AUTH48 on its own. However, would you like to hold publication
of this document until the other two documents complete AUTH48 so
that all three will be published together? The other documents will
be moved to AUTH48 shortly.
-->
<title abbrev="JSContact">JSContact: A JSON Representation of Contact Data</title>
<seriesInfo name="RFC" value="9553"/>
<author initials="R." surname="Stepanek" fullname="Robert Stepanek">
<organization>Fastmail</organization>
<address>
<postal>
<extaddr>PO Box 234</extaddr>
<street>Collins St. West</street>
<city>Melbourne</city>
<region>VIC</region>
<code>8007</code>
<country>Australia</country>
<region/>
</postal>
</address>
</author>
<author initials="M." surname="Loffredo" fullname="Mario Loffredo">
<organization>IIT-CNR</organization>
<address>
<postal>
<street>Via Moruzzi, 1</street>
<city>Pisa</city>
<code>56124</code>
<country>Italy</country>
<region/>
</postal>
</address>
</author>
<date year="2024" month="March"/>
<area>art</area>
<workgroup>calext</workgroup>
<keyword>JSON</keyword>
<keyword>addressbook</keyword>
<keyword>contacts</keyword>
<keyword>cards</keyword>
<keyword>VCARD</keyword>
<abstract>
<t>This specification defines a data model and JavaScript Object Notation (JSON) representation of contact card
information that can be used for data storage and exchange in address book or directory applications. It aims to
be an alternative to the vCard data format and to be unambiguous, extendable, and simple to process. In contrast
to the JSON-based jCard format, it is not a direct mapping from the vCard data model and expands semantics where
appropriate. Two additional specifications define new vCard elements and how to convert between JSContact and
vCard.
</t>
</abstract>
</front>
<middle>
<section anchor="introduction" numbered="true" toc="default">
<name>Introduction</name>
<t>This document defines a data model for contact card data normally used in address book or directory
applications and services. It aims to be an alternative to the vCard data format <xref target="RFC6350" format="default"/>.
</t>
<t>The key design considerations for this data model are as follows:</t>
<ul spacing="normal">
<li>The data model and set of attributes should be mostly compatible with the model defined for the vCard data
format
<xref target="RFC6350" format="default"/>
and extensions
<xref target="RFC6473" format="default"/>
<xref target="RFC6474" format="default"/>
<xref target="RFC6715" format="default"/>
<xref target="RFC6869" format="default"/>
<xref target="RFC8605" format="default"/>. The specification should add new attributes or value types where
appropriate. Not all existing vCard definitions need an equivalent in JSContact, especially if the vCard
definition is considered to be obsolete or otherwise inappropriate. Conversion between the data formats need
not fully preserve semantic meaning.
</li>
<!--[rfced] Please clarify the meaning of "reducing complexity of
their representation". Is the intended meaning that the
attributes must be described as simple key-value pairs to
reduce complexity (option A) or to reduce complexity of the
representation of the card data (option B)?
Original:
The attributes of the card data represented must be described as
simple key-value pairs, reducing complexity of their
representation.
Perhaps:
A) The attributes of the card data being represented must be
described as simple key-value pairs to reduce complexity.
or
B) The attributes of the card data must be described as simple
key-value pairs to reduce the complexity of the representation
of the card data.
-->
<li>The attributes of the card data must be described as simple key-value pairs to reduce the complexity of the
representation of the card data.
</li>
<li>The data model should avoid all ambiguities and make it difficult to make mistakes during implementation.
</li>
<li>Extensions, such as new properties and components, <bcp14>MUST NOT</bcp14> lead to a required update of this
document.
</li>
</ul>
<t>The representation of this data model is defined in the Internet JSON (I-JSON) format <xref target="RFC7493" format="default"/>,
which is a strict subset of the JSON data interchange format <xref target="RFC8259" format="default"/>. Using
JSON is mostly a pragmatic choice: its widespread use makes JSContact easier to adopt, and the availability of
production-ready JSON implementations eliminates a whole category of parser-related interoperability issues.
</t>
<section anchor="relation-to-vcard" numbered="true" toc="default">
<name>Motivation and Relation to vCard, jCard, and xCard</name>
<t>The vCard data format
<xref target="RFC6350"/>
is an interchange format for contacts data between address book service providers and vendors. However, this
format has gone through multiple specification iterations with only a subset of its deprecated <xref target="RFC2426">version 3
</xref> being widely in use. Consequently, products and services use an internal contact data model that is
richer than what they expose when serializing that information to vCard. In addition, service providers often
use a proprietary JSON representation of contact data in their APIs.
</t>
<t>JSContact provides a standard JSON-based data model and representation of contact data as an alternative to
proprietary formats.
</t>
<t>At the time of writing this document, several missing features in vCard were brought to the attention of the
authors such as social media contacts, gender pronouns, and others. This highlights how vCard is not perceived
as an evolving format and, consequently, hasn't been updated for about ten years. JSContact addresses these
unmet demands and defines new vCard properties and parameters to allow interchanging them in both formats.
</t>
<t>Two additional documents define the relation of JSContact and vCard:
<xref target="I-D.ietf-calext-vcard-jscontact-extensions" format="default"/>
defines new vCard properties and parameters.
<xref target="I-D.ietf-calext-jscontact-vcard" format="default"/>
defines how to convert JSContact data from and to vCard.
</t>
<t>The xCard
<xref target="RFC6351" format="default"/>
and jCard
<xref target="RFC7095" format="default"/>
specifications define alternative representations for vCard data in XML and JSON formats, respectively. Both
explicitly aim to not change the underlying data model. Accordingly, they are regarded as equal to vCard in
the context of this document.
</t>
</section>
<section anchor="notational-conventions" numbered="true" toc="default">
<name>Notational Conventions</name>
<t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp14>REQUIRED</bcp14>", "<bcp14>
SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>
RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp14>" in
this document are to be interpreted as described in BCP 14
<xref target="RFC2119" format="default" sectionFormat="of" derivedContent="RFC2119"/>
<xref target="RFC8174" format="default" sectionFormat="of" derivedContent="RFC8174"/>
when, and only when, they appear in all capitals, as shown here.
</t>
<t>The ABNF definitions in this document use the notations of <xref target="RFC5234"/>. ABNF rules not defined in
this document are defined in either
<xref target="RFC5234"/>
(such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT) or <xref target="RFC6350"/>.
</t>
</section>
<section anchor="data-type-notations">
<name>Data Type Notations</name>
<t>This section introduces the notations and terminology used to define data types in JSContact.</t>
<t>The underlying format for JSContact is JSON, so its data types also build on JSON values. The terms "object"
and "array" as well as the four primitive types ("strings", "numbers", "booleans", and "null") are to be
interpreted as described in <xref target="RFC8259" section="1"/>. All JSContact data <bcp14>MUST</bcp14> be
valid according to the constraints given in <xref target="RFC7493">I-JSON</xref>. Unless otherwise noted, all
member names in JSON objects and all string values are case-sensitive. Within the context of JSON objects, the
term "key" is synonymous with "member name" as defined in <xref target="RFC8259" section="1"/>.
</t>
<section anchor="objects-and-properties" numbered="true" toc="default">
<name>Objects and Properties</name>
<!-- [rfced] The use of <tt> and <em>
a) In the html and pdf outputs, the text enclosed in <tt> is output in
fixed-width font. In the txt output, there are no changes to the font,
and the quotation marks have been removed.
In the html and pdf outputs, the text enclosed in <em> is output in
italics. In the txt output, the text enclosed in <em> appears with an
underscore before and after.
Please review carefully and let us know if the output is acceptable or
if any updates are needed.
b) Some terms appear with and without the "<tt>" element, for example,
"@type", "Card", "version", etc. Please review and let us know if any
updates are needed for consistency.
-->
<t>JSContact defines data types for contact information such as addresses or names. This information typically
consists of multiple related elements; for example, a personal name and surname together form a name. These
related elements are organized in JSContact objects. A JSContact object is a JSON object that has the
following:
</t>
<ol>
<li>A unique type name registered in the IANA <xref target="iana-type-registry">"JSContact Types"
registry</xref>.
</li>
<li>One or more object members for which the name and allowed value types are specified. Such members are
called "properties".
</li>
<li>One property named @type with a string value that matches the type name of the JSContact object. In
general, this property does not need to be set explicitly as outlined in <xref target="prop-type"/>.
</li>
</ol>
<t>The following sections specify how to define JSContact object types. Sections
<xref target="validating-jscontact" format="counter"/>
and
<xref target="vendor-specific-extensions" format="counter"/>
then define the exact requirements for property names.
</t>
<t>The next paragraph illustrates how a JSContact object is defined. The names "Foo" and "baz" are only for demonstration and have no meaning outside the example.</t>
<ul empty="true" anchor="example-foo-object">
<li>
<t>A Foo object has the following properties:</t>
<dl spacing="normal">
<dt>@type: String.</dt>
<dd>The JSContact type of the object. The value <bcp14>MUST</bcp14> be "Foo", if set.
</dd>
<dt>baz: Number (mandatory).</dt>
<dd>The baz level of the contact. The value <bcp14>MUST</bcp14> be an integer greater than 0 and less
than 10.
</dd>
</dl>
</li>
</ul>
<t>The above paragraph illustrates the following:</t>
<ul>
<li>It defines a JSContact object type named "Foo" having two properties, named "@type" and "baz".</li>
<li>The @type property adheres to the rules outlined in <xref target="prop-type"/>. Because of this, it is
neither defined to be mandatory nor optional, as this depends on how the Foo object type is used.
</li>
<li>The baz property value <bcp14>MUST</bcp14> be valid according to the definition of the Number type.
</li>
<li>The property has one attribute, "mandatory", which specifies that the property <bcp14>MUST</bcp14> be
present for a value of the Foo object type to be valid.
</li>
<li>The free-text description of the baz property describes the semantics and further restrictions for its
values.
</li>
</ul>
<!--[rfced] Section 1.3.1. Please clarify the meaning of "qux-ishness"
as no other RFCs contain this term. Is it a well-known term, or
can it perhaps be rephrased for clarity?
Also, we removed the blockquote element from this text
because it is not a direct quote. Please let us know
if any further updates are needed.
Original:
A Foo object has the following properties:
qux: Number (mandatory). Defines the qux-ishness of this contact.
The value MUST be an integer greater than 0 and less than 10.
-->
</section>
<section anchor="type-signatures" numbered="true" toc="default">
<name>Type Signatures</name>
<t>Type signatures are given for all JSON values and JSContact definitions in this document. The following
conventions are used:
</t>
<dl spacing="normal">
<dt>String:</dt>
<dd>The JSON string type.</dd>
<dt>Number:</dt>
<dd>The JSON number type.</dd>
<dt>Boolean:</dt>
<dd>The JSON boolean type.</dd>
<dt>A[B]:</dt>
<dd>A JSON object where all keys are of type A and all values are of type B.</dd>
<dt>A[]:</dt>
<dd>A JSON array of values of type A.</dd>
<dt>A|B:</dt>
<dd>The value is either of type A or of type B.</dd>
<dt>*:</dt>
<dd>The type is undefined (the value could be any type, although permitted values may be constrained by the
context of this value).
</dd>
</dl>
<t><xref target="common-data-types"/>
defines common data types, including signed or unsigned integers and dates.
</t>
</section>
<section anchor="property-attributes" numbered="true" toc="default">
<name>Property Attributes</name>
<t>Object properties may also have a set of attributes defined along with the type signature. These have the
following meanings:
</t>
<dl spacing="normal">
<dt>mandatory:</dt>
<dd>The property <bcp14>MUST</bcp14> be set for an instance of this object to be valid.
</dd>
<dt>optional:</dt>
<dd>The property can, but need not, be set for an instance of this object to be valid.</dd>
<dt>default:</dt>
<dd>This is followed by a JSON value. That value will be used for this property if it is omitted.</dd>
<dt>defaultType:</dt>
<dd>This is followed by the name of a JSContact object type. A property value of JSContact object type is
expected to be of this named type, in case it omits the @type property.
</dd>
</dl>
</section>
<section anchor="prop-type" numbered="true" toc="default">
<name>The @type Property</name>
<dl spacing="normal">
<dt>@type: String.</dt>
<dd>The JSContact type of a JSON object. It <bcp14>MUST</bcp14> match the
type name of the JSContact object of which the JSON object is an instance of.
</dd>
</dl>
<t>The purpose of the @type property is to help implementations identify which JSContact object type a given
JSON object represents. Implementations <bcp14>MUST</bcp14> validate that JSON objects with this property
conform to the specification of the JSContact object type of that name.
</t>
<t>In many cases, the @type property value is implied by where its object occurs in JSContact data. Assuming
that both A and B are JSContact object types:
</t>
<ul>
<li>An object that is set as the value for a property with type signature "A" <bcp14>MAY</bcp14> have the
@type property set. If the @type property is not set, then its value is implied to be A by the property
definition.
</li>
<li>An object that is set as the value for a property with type signature "A|B (defaultType: A)" <bcp14>
MAY
</bcp14> have the @type property set if it is an instance of A. It <bcp14>MUST</bcp14> have the @type
property set if it is an instance of B. If, instead, the defaultType attribute is not defined, then the
@type property <bcp14>MUST</bcp14> also be set for A.
</li>
<li>An object that is not the value of a property, such as the topmost object in JSON data (directly or as a
member of an array), <bcp14>MUST</bcp14> have the @type property set.
</li>
</ul>
</section>
</section>
<section anchor="common-data-types" numbered="true" toc="default">
<name>Common Data Types</name>
<t>In addition to the standard JSON data types, a couple of additional data types are common to the definitions
of JSContact objects and properties.
</t>
<section anchor="id" numbered="true" toc="default">
<name>Id</name>
<t>Where "Id" is given as a data type, it means a String of at least 1 and a maximum of 255 octets in size,
and it <bcp14>MUST</bcp14> only contain characters from the "URL and Filename Safe" base64url alphabet, as
defined in <xref target="RFC4648" sectionFormat="of" section="5"/>, excluding the pad character ("="). This
means the allowed characters are the ASCII alphanumeric characters ("A-Za-z0-9"), hyphen ("-"), and
underscore ("_").
</t>
<t>In many places in JSContact, a JSON map is used where the map keys are of type Id and the map values are
all the same type of object. This construction represents an unordered set of objects, with the added
advantage that each entry has a name (the corresponding map key). This allows for more concise patching of
objects and, when applicable, for the objects in question to be referenced from other objects within the
JSContact object. The map keys <bcp14>MUST</bcp14> be preserved across multiple versions of the JSContact
object.
</t>
<t>Unless otherwise specified for a particular property, there are no uniqueness constraints on an Id value
(other than, of course, the requirement that you cannot have two values with the same key within a single
JSON map). For example, two <xref target="card">Card</xref> objects might use the same Ids in their
respective photos properties. Or within the same Card, the same Id could appear in the emails and phones
properties. These situations do not imply any semantic connections among the objects.
</t>
</section>
<section anchor="int-unsignedint" numbered="true" toc="default">
<name>Int and UnsignedInt</name>
<t>Where "Int" is given as a data type, it means an integer in the range -2<sup>53</sup>+1 <= value <= 2<sup>
53</sup>-1, which is the safe range for integers stored in a floating-point double, represented as a JSON
Number.
</t>
<t>Where "UnsignedInt" is given as a data type, it means an integer in the range 0 <= value <= 2<sup>
53</sup>-1 represented as a JSON Number.
</t>
</section>
<section anchor="patchobject" numbered="true" toc="default">
<name>PatchObject</name>
<t>A PatchObject is of type "String[*]" and represents an unordered set of patches on a JSON object. Each key
is a path represented in a subset of the JSON Pointer format <xref target="RFC6901"/>. The paths have an
implicit leading "/", so each key is prefixed with "/" before applying the JSON Pointer evaluation
algorithm.
</t>
<t>A patch within a PatchObject is only valid if all the following conditions apply:</t>
<ol>
<li>The pointer <bcp14>MAY</bcp14> reference inside an array, but if the last reference token in the pointer
is an array index, then the patch value <bcp14>MUST NOT</bcp14> be null. The pointer <bcp14>MUST NOT
</bcp14> use "-" as an array index in any of its reference tokens (i.e., you <bcp14>MUST NOT</bcp14> insert/delete
from an array, but you <bcp14>MAY</bcp14> replace the contents of its existing members. To add or remove
members, one needs to replace the complete array value).
</li>
<li>All reference tokens prior to the last (i.e., the value after the final slash) <bcp14>MUST</bcp14> already
exist as values in the object being patched. If the last reference token is an array index, then a member
at this index <bcp14>MUST</bcp14> already exist in the referenced array.
</li>
<li>There <bcp14>MUST NOT</bcp14> be two patches in the PatchObject where the pointer of one is the prefix
of the pointer of the other, e.g., "addresses/1/city" and "addresses".
</li>
<li>The value for the patch <bcp14>MUST</bcp14> be valid for the property being set (of the correct type and
obeying any other applicable restrictions), or if null, the property <bcp14>MUST</bcp14> be optional.
</li>
</ol>
<t>The value associated with each pointer determines how to apply that patch:</t>
<ul>
<li>If null, remove the property from the patched object. If the key is not present in the parent, this is a
no-op.
</li>
<li>If non-null, set the value given as the value for this property (this may be a replacement or addition
to the object being patched).
</li>
</ul>
<t>A PatchObject does not define its own <xref target="prop-type">@type</xref> property. Instead, the @type
property in a patch <bcp14>MUST</bcp14> be handled as any other patched property value.
</t>
<t>Implementations <bcp14>MUST</bcp14> reject a PatchObject in its entirety if any of its patches are invalid.
Implementations <bcp14>MUST NOT</bcp14> apply partial patches.
</t>
</section>
<section anchor="resource" numbered="true" toc="default">
<name>Resource</name>
<!--[rfced] When the term "Card" is referred to in the running text,
there is a mix of "this Card" and "the Card". For consistency and
clarity, we updated several instances of "this Card" to "the
Card". Please review and let us know if any further updates are
needed.
One example
Original:
The date and time when the data in this Card was last
modified.
Current:
The date and time when the data in the Card was last
modified.
-->
<t>The Resource data type defines a resource associated with the entity represented by the Card, identified by
a URI <xref target="RFC3986" format="default"/>. Later in this document, several property definitions refer
to the Resource type as the basis for their property-specific value types. The Resource type defines the
properties that are common to all of them. Property definitions making use of Resource <bcp14>MAY</bcp14> define
additional properties for their value types.
</t>
<t>A Resource object has the following properties:</t>
<dl spacing="normal">
<dt>@type: String.</dt>
<dd>The JSContact type of the object. The value <bcp14>MUST NOT</bcp14> be "Resource"; instead, the value <bcp14>MUST</bcp14> be the name
of a concrete resource type (see <xref target="resource-properties"/>).</dd>
<dt>kind: String (optional).</dt>
<dd>
The kind of the resource. The allowed values are defined in the property definition that makes use of the
Resource type. Some property definitions may change this property from being optional to mandatory.
</dd>
<dt>uri: String (mandatory).</dt>
<dd>
The resource value. This <bcp14>MUST</bcp14> be a <em>URI</em> as defined in <xref target="RFC3986" sectionFormat="of" section="3"/>.
</dd>
<dt>mediaType: String (optional).</dt>
<dd>
The media type <xref target="RFC2046" format="default"/> of the resource identified by the uri property value.
</dd>
<dt>contexts: String[Boolean] (optional).</dt>
<dd>
The contexts in which to use this resource. Also see <xref target="prop-contexts"/>.
</dd>
<dt>pref: UnsignedInt (optional).</dt>
<dd>
The preference of the resource in relation to other resources. Also see <xref target="prop-pref"/>.
</dd>
<dt>label: String (optional).</dt>
<dd>
A custom label for the value. Also see <xref target="prop-label"/>.
</dd>
</dl>
</section>
<section anchor="utcdatetime" numbered="true" toc="default">
<name>UTCDateTime</name>
<t>The UTCDateTime type is a String in "date-time" format <xref target="RFC3339" format="default"/>, with
further restrictions that any letters <bcp14>MUST</bcp14> be in uppercase and the time offset <bcp14>MUST
</bcp14> be the character "Z". Fractional second values <bcp14>MUST NOT</bcp14> be included unless they are
non-zero, and they <bcp14>MUST NOT</bcp14> have trailing zeros to ensure there is only a single
representation for each date-time.
</t>
<t>For example, "2010-10-10T10:10:10.003Z" is conformant, but "2010-10-10T10:10:10.000Z" is invalid; the
correct encoding is "2010-10-10T10:10:10Z".
</t>
</section>
</section>
<section anchor="common-properties">
<name>Common Properties</name>
<t>Most of the properties in this document are specific to a single JSContact object type. Such properties are
defined along with the respective object type. The properties in this section are common to multiple data
types and are defined here to avoid repetition. Note that these properties <bcp14>MUST</bcp14> only be set for
a JSContact object if they are explicitly mentioned as allowable for this object type.
</t>
<!--[rfced] Within Sections 1.5.1 to 2.8.4, there is inconsistency in
the way the property names are introduced - some of the lead-in
sentences are fragments and some work off of the property name in
the title. May we make this consistent by including the property
name (enclosed with <tt> in the XML file if preferred) in the lead-in
sentence as shown in the examples below? Note that there are 25 instances.
Some examples (see the text for more instances)
Original:
1.5.1 contexts
Type: String[Boolean]
This property associates contact information with one or more contexts
in which it should be used.
Perhaps:
1.5.1 contexts
Type: String[Boolean]
The contexts property associates contact information with one or more
contexts in which it should be used.
...
Original:
2.3.4 preferredLanguages
Type: Id{LanguagePref] (optional).
Defines the preferred languages for contacting the entity associated
with this Card.
Perhaps:
2.3.4 preferredLanguages
Type: Id{LanguagePref] (optional).
The preferredLanguages property defines the preferred languages for
contacting the entity associated with the Card.
...
Original:
2.6.2. directories
Type: Id[Directory] (optional).
These are directory service resources, such as entries in a
directory or organizational directories for lookup.
Perhaps:
2.6.2. directories
Type: Id[Directory] (optional)
The directories property specifies directory service resources
such as entries in a directory or organizational directories
for lookup.
-->
<section anchor="prop-contexts" numbered="true" toc="default">
<name>contexts</name>
<dl spacing="normal">
<dt>contexts: String[Boolean].</dt>
<dd>
<t>The contexts in which to use the contact information. For example, someone might have distinct phone numbers for work and private contexts and may set the desired context on the respective phone number in the <xref target="phones"> phones </xref> property. </t>
<t>This section defines common contexts. Additional contexts may be defined in the properties or data
types that make use of this property. The <xref target="enumerated-values">enumerated
</xref> common context values are:
</t>
<ul spacing="normal">
<li>private: the contact information that may be used in a private context.</li>
<li>work: the contact information that may be used in a professional context.</li>
</ul>
</dd>
</dl>
</section>
<section anchor="prop-label" numbered="true" toc="default">
<name>label</name>
<dl spacing="normal">
<dt>label: String.</dt>
<dd>The labels associated with the contact data. Such labels may be set for
phone numbers, email addresses, and other resources. Typically, these labels are displayed along with their
associated contact data in graphical user interfaces. Note that succinct labels are best for proper
display on small graphical interfaces and screens.
</dd>
</dl>
</section>
<section anchor="prop-pref" numbered="true" toc="default">
<name>pref</name>
<dl spacing="normal">
<dt>pref: UnsignedInt.</dt>
<dd>
<t>A preference order for contact information. For example, a person may
have two email addresses and prefer to be contacted with one of them.
</t>
<t>The value <bcp14>MUST</bcp14> be in the range of 1 to 100. Lower values correspond to a higher level of
preference, with 1 being most preferred. If no preference is set, then the contact information <bcp14>
MUST
</bcp14> be interpreted as being least preferred.
</t>
<t>Note that the preference is only defined in relation to contact information of the same type. For
example, the preference orders within emails and phone numbers are independent of each other.
</t>
</dd>
</dl>
</section>
<section anchor="prop-phonetic" numbered="true" toc="default">
<name>phonetic</name>
<t>The following properties define how to pronounce a value in the language indicated in the Card <xref target="language">language
</xref> property or the language tag of its <xref target="localizations">localizations</xref>. Exemplary uses
of these properties are defining how to pronounce Japanese names and romanizing Mandarin or Cantonese name
and address components. The properties are defined as follows:
</t>
<dl spacing="normal">
<dt>phonetic: String.</dt>
<dd>
The phonetic representation of a value.
<!--[rfced] Can "ignored for use with" be updated as "ignored and not
used with" for clarity as shown below?
Original:
Any script language subtag in the Card language (Section 2.1.5)
property MUST be ignored for use with the phonetic property.
Perhaps:
Any script language subtag in the Card language (Section 2.1.5)
property MUST be ignored and not used with the phonetic property.
-->
Any script language subtag in the Card <xref target="language">language</xref> property <bcp14>MUST
</bcp14> be ignored and not used with the phonetic property. If this property is set, then at least one of
the phoneticScript or phoneticSystem properties that relate to this value <bcp14>MUST</bcp14> be set.
</dd>
<dt>phoneticScript: String.</dt>
<dd>
The script used in the value of the related phonetic property. This <bcp14>MUST</bcp14> be a valid script
subtag as defined in <xref target="RFC5646" section="2.2.3"/>.
</dd>
<dt>phoneticSystem: String.</dt>
<dd>
<t>
The phonetic system used in the related value of the phonetic property. The <xref target="enumerated-values">enumerated
</xref> values are:
</t>
<ul>
<li>ipa: denotes the <xref target="IPA">International Phonetic Alphabet</xref>.
</li>
<li>jyut: denotes the Cantonese romanization system "Jyutping".</li>
<li>piny: denotes the Standard Mandarin romanization system "Hanyu Pinyin".</li>
</ul>
</dd>
</dl>
<t>The relation between the phoneticSystem, phoneticScript, and phonetic properties is type-specific. This
specification defines this relation in the <xref target="name">Name</xref> and <xref target="address">
Address
</xref> object types, respectively.
</t>
<t>The following example illustrates the phonetic property for a <xref target="name-prop">name</xref>:
</t>
<figure anchor="example-phonetic">
<name>Example of a phonetic Property for the Name "John Smith" as Pronounced in the USA</name>
<sourcecode name="" type="json"><![CDATA[
"name": {
"components": [{
"kind": "given",
"value": "John",
"phonetic": "/ˈdʒɑːn/"
}, {
"kind": "surname",
"value": "Smith",
"phonetic": "/smɪθ/"
}],
"phoneticSystem": "ipa"
}
]]></sourcecode>
</figure>
</section>
</section>
<section anchor="internationalization">
<name>Internationalization</name>
<t>JSContact aims to be used for international contacts and address book data. Notably, text values such as
names and addresses are likely to cover a wide range of languages and cultures. This section describes
internationalization for free-form text values as well as Uniform Resource Identifiers (URIs).
</t>
<section>
<name>Free-Form Text</name>
<t>Properties having free-form text values <bcp14>MAY</bcp14> contain any valid sequence of Unicode characters
encoded as a JSON string. Such values can contain unidirectional left-to-right and right-to-left text, as
well as bidirectional text using Unicode Directional Formatting Characters as described in Section 2 of <xref target="UBiDi"/>. Implementations setting bidirectional text <bcp14>MUST</bcp14> make sure that each
property value complies with the requirements of the Unicode Bidirectional Algorithm. Implementations <bcp14>
MUST NOT
</bcp14> assume that text values of adjacent properties are processed or displayed as a combined string; for
example, the values of a given name component and a surname component may or may not be rendered together.
</t>
</section>
<section>
<name>URIs</name>
<t>Several properties require their string value to be a URI as defined in <xref target="RFC3986"/>.
Implementations <bcp14>MUST</bcp14> make sure to use proper percent-encoding for URIs that cannot be
represented using unreserved URI characters.
<xref target="RFC3987" section="3.1"/>
defines how to convert Internationalized Resource Identifiers to URIs.
<!--[rfced] We notice that "URL Living Standard"
<https://url.spec.whatwg.org> is from the WHATWG and not the
W3C. We updated the running text and reference entry to reflect
this as shown below. Please let us know if any further changes
are needed.
Original:
JSContact makes no recommendation how to display URIs, but
section "4.8.3 Internationalization and special characters"
of the W3C URL Standard [W3C-URL] provides guidance for URLs
found in context of a web browser.
[W3C-URL] "W3C WG URL - Living Standard - Last Updated 21 August
2023", <https://url.spec.whatwg.org>.
Current:
JSContact makes no recommendation on how to display URIs, but the
WHATWG URL Living Standard (see "Internationalization and special characters"
(Section 4.8.3) of [WHATWG-URL]) provides guidance for URLs found in
the context of a web browser.
[WHATWG-URL] WHATWG, "URL Living Standard", January 2024,
<https://url.spec.whatwg.org>.
-->
JSContact makes no recommendation on how to display URIs, but the WHATWG URL Living Standard (see
"Internationalization and special characters" (Section 4.8.3) of <xref target="WHATWG-URL"/>) provides
guidance for URLs found in the context of a web browser.
</t>
</section>
</section>
<section anchor="validating-jscontact">
<name>Validating JSContact</name>
<t>This specification distinguishes between three kinds of properties regarding validation: IANA-registered
properties and unknown properties, which are defined in this section, and vendor-specific properties, which
are defined in <xref target="vendor-specific-properties"/>. A JSContact object is invalid if any of its
properties are invalid.
</t>
<t>This document defines whether each property is mandatory or optional. A mandatory property <bcp14>MUST
</bcp14> be present for a JSContact object to be valid. An optional property does not need to be present. The
values of both required and optional properties <bcp14>MUST</bcp14> adhere to the data type and definition of
that property.
</t>
<section anchor="case-sensitivity">
<name>Case-Sensitivity</name>
<t>All property names, object type names, and enumerated values are case-sensitive, unless explicitly stated
otherwise in their definitions. Implementations <bcp14>MUST</bcp14> handle a JSContact object as invalid if
a type name, property name, or enumerated value only differs in case from one defined for any JSContact
version known to that implementation. This applies regardless of what JSContact version the Card object
defines in its <xref target="prop-version">version</xref> property.
<xref target="unknown-properties"/>
defines how to handle unknown properties.
</t>
</section>
<section anchor="iana-registered-properties" numbered="true" toc="default">
<name>IANA-Registered Properties</name>
<t>
An IANA-registered property is any property that has been registered according to the IANA property registry
rules as outlined in <xref target="iana-considerations"/>. All properties defined in this specification,
including their object value types and enumerated values, are registered at IANA.
</t>
<t>
Implementations <bcp14>MUST</bcp14> validate IANA-registered properties in JSContact data, unless they are
unknown to the implementation (<xref target="unknown-properties"/>). They <bcp14>MUST</bcp14> reject invalid
IANA-registered properties. A property is invalid if its name matches the name of an IANA-registered
property but the value violates its definition according to the JSContact specification version defined in
the Card <xref target="prop-version">version</xref> property.
</t>
<t><!-- [rfced] The RFC Production Center has been advised that "ASCII"
and not "US-ASCII" should be used. May we change two instances
of "US-ASCII" in this document to "ASCII"?
Original:
IANA-registered property names MUST NOT contain US-ASCII control
characters (U+0000 to U+001F, U+007F), the COLON (U+003A) or
QUOTATION MARK (U+0022) characters. They MUST only contain US-ASCII
alphanumeric characters that match the ALPHA and DIGIT rules defined
in Appendix B.1 of [RFC5234]) or the COMMERCIAL AT (U+0040)
character.
Perhaps:
IANA-registered property names MUST NOT contain ASCII control
characters (U+0000 to U+001F, U+007F), the COLON (U+003A) or
QUOTATION MARK (U+0022) characters. They MUST only contain ASCII
alphanumeric characters that match the ALPHA and DIGIT rules defined
in Appendix B.1 of [RFC5234]) or the COMMERCIAL AT (U+0040)
character.
-->
IANA-registered property names <bcp14>MUST NOT</bcp14> contain ASCII control characters (U+0000 to U+001F,
U+007F), the COLON (U+003A), or the QUOTATION MARK (U+0022). They <bcp14>MUST</bcp14> only contain ASCII
alphanumeric characters that match the ALPHA and DIGIT rules defined in
<xref target="RFC5234" section="B.1"/>
or the COMMERCIAL AT (U+0040) character. IANA-registered property names <bcp14>MUST</bcp14> be notated in
lower camel case.
</t>
</section>
<section anchor="reserved-properties">
<name>Reserved Properties</name>
<t>IANA-registered properties can be reserved (<xref target="iana-registry-policy"/>). Implementations <bcp14>MUST NOT</bcp14> set properties having a reserved name in JSContact
objects for which this property is reserved, or all objects if the property context in the registry is "not applicable".
Reserved properties have no type and their type signature is "not applicable". Any JSContact object including a property which is reserved in context of this object <bcp14>MUST</bcp14> be considered invalid.</t>
<t>This document reserves one property:</t>
<section anchor="prop-extra" numbered="true" toc="default">
<name>extra</name>
<dl spacing="normal">
<dt>extra: not applicable.</dt>
<dd>The reserved property "extra" provides implementors with a property name that is certain to never
occur as a property in any JSContact object. Implementations might want to map unknown or vendor-specific
properties to a variable with this name, but this is implementation-specific.
</dd>
</dl>
</section>
</section>
<section anchor="unknown-properties" numbered="true" toc="default">
<name>Unknown Properties</name>
<t>
Implementations may encounter JSContact data where a property name is unknown to that implementation but the
name adheres to the syntactic restrictions of IANA-registered property names. Implementations <bcp14>MUST
</bcp14> make sure that such a name does not violate the case-sensitivity rules defined in <xref target="case-sensitivity"/>. If the property name is valid, then implementations <bcp14>MUST NOT
</bcp14> treat such properties as invalid. Instead, they <bcp14>MUST</bcp14> preserve them in the JSContact
object.
</t>
<t>Implementations that create or update JSContact data <bcp14>MUST</bcp14> only set IANA-registered
properties or vendor-specific properties. Preserving properties that are unknown to the implementation is to
allow applications and services to interoperate without data loss, even if not all of them implement the
same set of JSContact extensions.
</t>
</section>
<section anchor="enumerated-values" numbered="true" toc="default">
<name>Enumerated Values</name>
<t>Several properties in this document restrict their allowed values to a list of String values. These values
are case-sensitive. If not noted otherwise for a specific property, the initial list of values for such
properties is registered at IANA in the <xref target="iana-enum-registry">"JSContact Enum Values"
registry</xref>. Implementations <bcp14>MUST</bcp14> only set IANA-registered or <xref target="vendor-specific-values">vendor-specific
</xref> values for such properties.
</t>
</section>
</section>
<section anchor="vendor-specific-extensions">
<name>Vendor-Specific Extensions</name>
<t>Vendors may extend properties and values for experimentation or to store contacts data that is only useful
for a single service or application. Such extensions are not meant for interoperation. If, instead,
interoperation is desired, vendors are strongly encouraged to define and register new properties, types, and
values at IANA as defined in <xref target="iana-considerations"/>.
<xref target="iana-registered-properties"/>
defines the naming conventions for IANA-registered elements.
</t>
<section anchor="vendor-specific-properties" numbered="true" toc="default">
<name>Vendor-Specific Properties</name>
<t>
Vendor-specific property names <bcp14>MUST</bcp14> start with a vendor-specific prefix followed by a name,
as produced by the "v-extension" ABNF below. The prefix and name together form the property name. The
vendor-specific prefix <bcp14>MUST</bcp14> be a domain name under control of the service or application that
sets the property, but it need not resolve in the Domain Name System
<xref target="RFC1034"/>
<xref target="RFC1035"/>. The prefix "ietf.org" and its subdomain names are reserved for IETF
specifications. The name <bcp14>MUST NOT</bcp14> contain the TILDE (U+007E) and SOLIDUS (U+002F) characters,
as these require special escaping when encoding a JSON Pointer
<xref target="RFC6901"/>
for that property.
</t>
<t>
Vendor-specific properties <bcp14>MAY</bcp14> be set in any JSContact object. Implementations <bcp14>MUST
</bcp14> preserve vendor-specific properties in JSContact data, irrespective if they know their use. They <bcp14>
MUST NOT
</bcp14> reject the property value as invalid, unless they are in control of the vendor-specific property as
outlined in the above paragraph.
</t>
<t>The ABNF rule "v-extension" formally defines valid vendor-specific property names. Note that the vendor
prefix allows for more values than Internationalized Domain Names (IDNs)<xref target="RFC8499"/>; therefore,
JSContact implementations can simply validate property names without implementing the full set of rules that
apply to domain names.
</t>
<figure anchor="vendor-property-abnf">
<name>ABNF Rules for Vendor-Specific Property Names</name>
<sourcecode name="" type="abnf"><![CDATA[
v-extension = v-prefix ":" v-name
v-prefix = v-label *("." v-label)
v-label = alnum-int / alnum-int *(alnum-int / "-") alnum-int
alnum-int = ALPHA / DIGIT / NON-ASCII
; see RFC 6350, Section 3.3
v-name = 1*(WSP / "!" / %x23-2e / %x30-7d / NON-ASCII)
; any characters except CTLs, DQUOTE, SOLIDUS, and TILDE
]]></sourcecode>
</figure>
<t>
The value of vendor-specific properties can be any valid JSON value, and naming restrictions do not apply to
such values. Specifically, if the property value is a JSON object, then the keys of such objects need not be
named as vendor-specific properties, as illustrated in <xref target="vendor-property-example"/>:
</t>
<figure anchor="vendor-property-example">
<name>Examples of Vendor-Specific Properties</name>
<sourcecode type=""><![CDATA[
"example.com:foo": "bar",
"example.com:foo2": {
"bar": "baz"
}
]]></sourcecode>
</figure>
</section>
<section anchor="vendor-specific-values" numbered="true" toc="default">
<name>Vendor-Specific Values</name>
<t>
Some JSContact IANA-registered properties allow their values to be vendor-specific. One such example is the <xref target="kind">"kind"
</xref> property, which enumerates its standard values but also allows for arbitrary vendor-specific values.
Such vendor-specific values <bcp14>MUST</bcp14> be valid "v-extension" values as defined in <xref target="vendor-specific-properties"/>. The example in
<xref target="vendor-value-example"/>
illustrates this:
</t>
<figure anchor="vendor-value-example">
<name>Example of a Vendor-Specific Value</name>
<sourcecode><![CDATA[
"kind": "example.com:baz"
]]></sourcecode>
</figure>
<t>
Vendors are strongly encouraged to specify a new standard value once a vendor-specific one turns out to also
be useful for other systems.
</t>
</section>
</section>
<section anchor="versioning">
<name>Versioning</name>
<t>Every instance of a JSContact <xref target="card">Card</xref> indicates which JSContact version its
IANA-registered properties and values are based on.
<!--[rfced] As "MIME" is no longer used in the IANA registry, may we
update the text as follows?
Original:
The version is indicated both in the version (Section 2.1.2)
property within the Card and in the version (Section 3.1) parameter
of the JSContact MIME content type.
Perhaps:
The version is indicated both in the version (Section 2.1.2)
property within the Card and in the version (Section 3.1) parameter
of the JSContact media type.
-->
The version is indicated both in the <xref target="prop-version">version</xref> property within the Card and
in the <xref target="iana-media-type">version</xref> parameter of the JSContact media type. All
IANA-registered elements indicate the version at which they were introduced or obsoleted.
</t>
<t>A JSContact version consists of a major and minor version.</t>
<t>Differing major version values indicate substantial differences in JSContact semantics and format.
Implementations <bcp14>MUST</bcp14> be prepared for property definitions and other JSContact elements that
differ in a backwards-incompatible manner.
</t>
<t>Differing minor version values indicate additions that enrich JSContact data but do not introduce
backwards-incompatible changes. Typically, these are new property enum values or properties with a narrow
semantic scope. A new minor version <bcp14>MUST NOT</bcp14> require implementations to change their processing
of JSContact data. Changing the major version number resets the minor version number to zero.
</t>
<section anchor="version-format-and-reqs">
<name>Version Format and Requirements</name>
<t>A version value starts with the numeric major version, followed by the FULL STOP character (U+002E),
followed by the numeric minor version. Later versions are numerically higher than former versions, with the
major version being more significant than the minor version. A version value is produced by the following
ABNF:
</t>
<!--[rfced] Should Figure 5 have a title? Please review, and provide
a title if desired.
-->
<figure>
<name>The ABNF for JSContact Version Values</name>
<sourcecode name="" type="abnf"><![CDATA[