rfc9553.original.xml   rfc9553.xml 
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc>
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="*trust200902" submissionTyp <!DOCTYPE rfc [
e="IETF" category="std" xml:lang="en" consensus="true" docName="draft-ietf-calex <!ENTITY nbsp "&#160;">
t-jscontact-16" obsoletes="" updates="" tocInclude="true" symRefs="true" sortRef <!ENTITY zwsp "&#8203;">
s="true" version="3"> <!ENTITY nbhy "&#8209;">
<!ENTITY wj "&#8288;">
]>
<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 --> <!-- xml2rfc v2v3 conversion 3.6.0 -->
<front> <front>
<title abbrev="JSContact">JSContact: A JSON representation of contact data</
title> <!--[rfced] *AD, changes were submitted after the document was
<seriesInfo name="Internet-Draft" value="draft-ietf-calext-jscontact-16"/> initially approved. Please review the updates from version 15
to version 16 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"> <author initials="R." surname="Stepanek" fullname="Robert Stepanek">
<organization>Fastmail</organization> <organization>Fastmail</organization>
<address> <address>
<postal> <postal>
<street>PO Box 234, Collins St West</street> <extaddr>PO Box 234</extaddr>
<street>Collins St. West</street>
<city>Melbourne</city> <city>Melbourne</city>
<code>VIC 8007</code> <region>VIC</region>
<code>8007</code>
<country>Australia</country> <country>Australia</country>
<region> </region> <region></region>
</postal> </postal>
<email>rsto@fastmailteam.com</email> <email>rsto@fastmailteam.com</email>
</address> </address>
</author> </author>
<author initials="M." surname="Loffredo" fullname="Mario Loffredo"> <author initials="M." surname="Loffredo" fullname="Mario Loffredo">
<organization>IIT-CNR</organization> <organization>IIT-CNR</organization>
<address> <address>
<postal> <postal>
<street>Via Moruzzi,1</street> <street>Via Moruzzi, 1</street>
<city>Pisa</city> <city>Pisa</city>
<code>56124</code> <code>56124</code>
<country>Italy</country> <country>Italy</country>
<region> </region> <region></region>
</postal> </postal>
<email>mario.loffredo@iit.cnr.it</email> <email>mario.loffredo@iit.cnr.it</email>
</address> </address>
</author> </author>
<date year="2023" month="November" day="9"/> <date year="2024" month="March"/>
<area>Applications</area> <area>art</area>
<workgroup>Calendaring Extensions</workgroup> <workgroup>calext</workgroup>
<keyword>JSON</keyword> <keyword>JSON</keyword>
<keyword>addressbook</keyword> <keyword>addressbook</keyword>
<keyword>contacts</keyword> <keyword>contacts</keyword>
<keyword>cards</keyword> <keyword>cards</keyword>
<keyword>VCARD</keyword> <keyword>VCARD</keyword>
<abstract> <abstract>
<t>This specification defines a data model and JSON representation of cont act card information that can be used for data storage and exchange in address b ook or directory applications. It aims to be an alternative to the vCard data f ormat and to be unambiguous, extendable and simple to process. In contrast to t he JSON-based jCard format, it is not a direct mapping from the vCard data model and expands semantics where appropriate.</t> <t>This specification defines a data model and JavaScript Object Notation (JSON) representation of contact card information that can be used for data stor age and exchange in address book or directory applications. It aims to be an al ternative 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 map ping from the vCard data model and expands semantics where appropriate.</t>
</abstract> </abstract>
</front> </front>
<middle> <middle>
<section anchor="introduction" numbered="true" toc="default"> <section anchor="introduction" numbered="true" toc="default">
<name>Introduction</name> <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 altern ative to the vCard data format <xref target="RFC6350" format="default"/>.</t> <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 altern ative to the vCard data format <xref target="RFC6350" format="default"/>.</t>
<t>The key design considerations for this data model are as follows:</t> <t>The key design considerations for this data model are as follows:</t>
<ul spacing="normal"> <ul spacing="normal">
<li>The data model and set of attributes should mostly be compatible wit <li>The data model and set of attributes should be mostly compatible wit
h the one defined for the vCard data format <xref target="RFC6350" format="defau h the model defined for the vCard data format <xref target="RFC6350" format="def
lt"/> and extensions (<xref target="RFC6473" format="default"/>, <xref target="R ault"/> and extensions <xref target="RFC6473" format="default"/> <xref target="R
FC6474" format="default"/>, <xref target="RFC6715" format="default"/>, <xref tar FC6474" format="default"/> <xref target="RFC6715" format="default"/> <xref targe
get="RFC6869" format="default"/>, <xref target="RFC8605" format="default"/>). T t="RFC6869" format="default"/> <xref target="RFC8605" format="default"/>. The s
he specification should add new attributes or value types where appropriate. Not pecification should add new attributes or value types where appropriate. Not all
all existing vCard definitions need an equivalent in JSContact, especially if t existing vCard definitions need an equivalent in JSContact, especially if the v
he vCard definition is considered to be obsolete or otherwise inappropriate. Co Card definition is considered to be obsolete or otherwise inappropriate. Conver
nversion between the data formats need not fully preserve semantic meaning.</li> sion 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 represented must be described as sim ple key-value pairs, reducing complexity of their representation.</li> <li>The attributes of the card data represented must be described as sim ple key-value pairs, reducing complexity of their representation.</li>
<li>The data model should avoid all ambiguities and make it difficult to make mistakes during implementation.</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 requiring an update to this document.</li> <li>Extensions, such as new properties and components, <bcp14>MUST NOT</ bcp14> lead to a required update of this document.</li>
</ul> </ul>
<t>The representation of this data model is defined in the I-JSON format < xref target="RFC7493" format="default"/>, which is a strict subset of the JavaSc ript Object Notation (JSON) Data Interchange Format <xref target="RFC8259" forma t="default"/>. Using JSON is mostly a pragmatic choice: its widespread use make s JSContact easier to adopt, and the availability of production-ready JSON imple mentations eliminates a whole category of parser-related interoperability issues .</t> <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 subs et of the JSON data interchange format <xref target="RFC8259" format="default"/> . Using JSON is mostly a pragmatic choice: its widespread use makes JSContact e asier to adopt, and the availability of production-ready JSON implementations el iminates a whole category of parser-related interoperability issues.</t>
<section anchor="relation-to-vcard" numbered="true" toc="default"> <section anchor="relation-to-vcard" numbered="true" toc="default">
<name>Motivation and Relation to vCard, jCard and xCard</name> <name>Motivation and Relation to vCard, jCard, and xCard</name>
<t>The vCard data format <xref target="RFC6350"/> is an interchange form <t>The vCard data format <xref target="RFC6350"/> is an interchange form
at for contacts data between address book service providers and vendors. Howeve at for contacts data between address book service providers and vendors. Howeve
r, this format has gone through multiple specifications iterations with only a s r, this format has gone through multiple specification iterations with only a su
ubset of its deprecated <xref target="RFC2426">version 3</xref> being widely in bset of its deprecated <xref target="RFC2426">version 3</xref> being widely in u
use. Consequently, products and services internally use a richer contact data m se. Consequently, products and services use an internal contact data model that
odel than they expose when serializing that information to vCard. In addition, is richer than what they expose when serializing that information to vCard. In
service providers often use a proprietary JSON representation of contact data in addition, service providers often use a proprietary JSON representation of cont
their APIs.</t> act data in their APIs.</t>
<t>JSContact provides a standard JSON-based data model and representatio n of contact data as an alternative to proprietary formats.</t> <t>JSContact provides a standard JSON-based data model and representatio n of contact data as an alternative to proprietary formats.</t>
<t>While writing this document, several features missing in vCard were b <t>At the time of writing this document, several missing features in vCa
rought to the attention of the authors, such as social media contacts, gender pr rd were brought to the attention of the authors such as social media contacts, g
onouns and others. This highlights how vCard is not perceived as an evolving fo ender pronouns, and others. This highlights how vCard is not perceived as an ev
rmat and consequently hasn't been updated since close to ten years. JSContact a olving format and, consequently, hasn't been updated for about ten years. JSCon
ddresses these unmet demands and defines new vCard properties and parameters to tact addresses these unmet demands and defines new vCard properties and paramete
allow interchanging them in both formats.</t> rs to allow interchanging them in both formats.</t>
<t>The xCard <xref target="RFC6351" format="default"/> and jCard <xref t <t>The xCard <xref target="RFC6351" format="default"/> and jCard <xref t
arget="RFC7095" format="default"/> specifications define alternative representat arget="RFC7095" format="default"/> specifications define alternative representat
ions for vCard data, in XML and JSON format respectively. Both explicitly aim t ions for vCard data in XML and JSON formats, respectively. Both explicitly aim
o not change the underlying data model. Accordingly, they are regarded as equal to not change the underlying data model. Accordingly, they are regarded as equa
to vCard in the context of this document.</t> l to vCard in the context of this document.</t>
</section> </section>
<section anchor="notational-conventions" numbered="true" toc="default"> <section anchor="notational-conventions" numbered="true" toc="default">
<name>Notational Conventions</name> <name>Notational Conventions</name>
<t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp <t>The key words "<bcp14>MUST</bcp14>", "<bcp14>MUST NOT</bcp14>", "<bcp
14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp1 14>REQUIRED</bcp14>", "<bcp14>SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp1
4>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "< 4>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "<
bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp1 bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp1
4>" in this document are to be interpreted as described in BCP 14 <xref target=" 4>" in this document are to be interpreted as described in BCP 14 <xref target="
RFC2119" format="default" sectionFormat="of" derivedContent="RFC2119"/> <xref ta RFC2119" format="default" sectionFormat="of" derivedContent="RFC2119"/> <xref ta
rget="RFC8174" format="default" sectionFormat="of" derivedContent="RFC8174"/> wh rget="RFC8174" format="default" sectionFormat="of" derivedContent="RFC8174"/> wh
en, and only when, they appear in all capitals, as shown here.</t> en, and only when, they appear in all capitals, as shown here.</t>
<t>The ABNF definitions in this document use the notations of <xref targ <t>The ABNF definitions in this document use the notations of <xref targ
et="RFC5234"/>. ABNF rules not defined in this document either are defined in <x et="RFC5234"/>. ABNF rules not defined in this document are defined in either <x
ref target="RFC5234"/> (such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, an ref target="RFC5234"/> (such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, an
d DIGIT) or <xref target="RFC6350"/>.</t> d DIGIT) or <xref target="RFC6350"/>.</t>
</section> </section>
<section anchor="data-type-notations"> <section anchor="data-type-notations">
<name>Data Type Notations</name> <name>Data Type Notations</name>
<t>This section introduces the notations and terminology used to define data types in JSContact.</t> <t>This section introduces the notations and terminology used to define data types in JSContact.</t>
<t>The underlying format for JSContact is JSON and so also its data type <t>The underlying format for JSContact is JSON, so its data types also b
s build on JSON values. The terms "object" and "array" as well as the four prim uild on JSON values. The terms "object" and "array" as well as the four primiti
itive types ("strings", "numbers", "booleans", and "null") are to be interpreted ve types ("strings", "numbers", "booleans", and "null") are to be interpreted as
as described in <xref target="RFC8259" section="1"/>. All JSContact data <bcp1 described in <xref target="RFC8259" section="1"/>. All JSContact data <bcp14>M
4>MUST</bcp14> be valid according to the constraints given in <xref target="RFC7 UST</bcp14> be valid according to the constraints given in <xref target="RFC7493
493">I-JSON</xref>. Unless otherwise noted, all member names in JSON objects an ">I-JSON</xref>. Unless otherwise noted, all member names in JSON objects and a
d all string values are case-sensitive. Within context of JSON objects, the ter ll string values are case-sensitive.
m "key" is synonymous with "member name" as defined in <xref target="RFC8259" se Within the context of JSON objects, the term "key" is synonymous with "member na
ction="1"/>.</t> me" as defined in <xref target="RFC8259" section="1"/>.</t>
<section anchor="objects-and-properties" numbered="true" toc="default"> <section anchor="objects-and-properties" numbered="true" toc="default">
<name>Objects and Properties</name> <name>Objects and Properties</name>
<t>JSContact defines data types for contact information such as addres
ses or names. This information typically consists of multiple related elements, <!-- [rfced] The use of <tt> and <em>
for example a personal name and surname together form a name. These related el
ements are organized in JSContact objects. A JSContact object is a JSON object a) In the html and pdf outputs, the text enclosed in <tt> is output in
which:</t> 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 addres
ses or names. This information typically consists of multiple related elements;
for example, a personal name and surname together form a name. These related e
lements are organized in JSContact objects. A JSContact object is a JSON object
that has the following:</t>
<ol> <ol>
<li>Has a unique type name registered in the <xref target="iana-type <li>A unique type name registered in the IANA <xref target="iana-ty
-registry">IANA JSContact Types Registry</xref>.</li> pe-registry">"JSContact Types" registry</xref>.</li>
<li>Has one or more object members for which the name and allowed va <li>One or more object members for which the name and allowed value
lue types are specified. Such members are called "properties".</li> types are specified. Such members are called "properties".</li>
<li>Has one property named <tt>@type</tt> with a string value that m <li>One property named <tt>@type</tt> with a string value that match
atches the type name of this JSContact object. In general, this property does n es the type name of the JSContact object. In general, this property does not ne
ot need to be set explicitly as outlined in <xref target="prop-type"/>.</li> ed to be set explicitly as outlined in <xref target="prop-type"/>.</li>
</ol> </ol>
<t>The following sections specify how to define JSContact object types <t>The following sections specify how to define JSContact object types
. <xref target="validating-jscontact"/> and <xref target="vendor-specific-extens . Sections <xref target="validating-jscontact" format="counter"/> and <xref targ
ions"/> then define the exact requirements for property names.</t> et="vendor-specific-extensions" format="counter"/> then define the exact requir
<t>The next paragraph illustrates how a JSContact object is defined:</ ements for property names.</t>
t> <t>The next paragraph illustrates how a JSContact object is defined.</
<blockquote> t>
<!--[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.
-->
<t>A Foo object has the following properties:</t> <t>A Foo object has the following properties:</t>
<ul> <dl spacing="normal">
<li><tt>qux</tt>: Number (mandatory). Defines the qux-ishness of <dt><tt>qux</tt>:</dt><dd> Number (mandatory). Defines the qux-is
this contact. The value <bcp14>MUST</bcp14> be an integer greater than 0 and le hness of this contact. The value <bcp14>MUST</bcp14> be an integer greater than
ss than 10.</li> 0 and less than 10.</dd>
</ul> </dl>
</blockquote>
<t>Here, a JSContact object type named <tt>Foo</tt> is defined. In ad <t>Here, a JSContact object type named <tt>Foo</tt> is defined. In ad
dition to its <tt>@type</tt> property it has a property named <tt>qux</tt> for w dition to its <tt>@type</tt> property, it has a property named <tt>qux</tt> for
hich values <bcp14>MUST</bcp14> be valid according to the definition of the <tt> which values <bcp14>MUST</bcp14> be valid according to the definition of the <tt
Number</tt> type. The property has one attribute, <tt>mandatory</tt>, which spe >Number</tt> type. The property has one attribute, <tt>mandatory</tt>, which sp
cifies that the property <bcp14>MUST</bcp14> be present for an instance of this ecifies that the property <bcp14>MUST</bcp14> be present for an instance of this
JSContact object to be valid. Finally, a free-text description describes the se JSContact object to be valid. Finally, a free-text description describes the s
mantics and further restrictions.</t> emantics and further restrictions.</t>
</section> </section>
<section anchor="type-signatures" numbered="true" toc="default"> <section anchor="type-signatures" numbered="true" toc="default">
<name>Type Signatures</name> <name>Type Signatures</name>
<t>Type signatures are given for all JSON values and JSContact definit ions in this document. The following conventions are used:</t> <t>Type signatures are given for all JSON values and JSContact definit ions in this document. The following conventions are used:</t>
<ul spacing="normal"> <dl spacing="normal">
<li><tt>String</tt> - The JSON string type.</li> <dt><tt>String</tt>:</dt><dd> The JSON string type.</dd>
<li><tt>Number</tt> - The JSON number type.</li> <dt><tt>Number</tt>:</dt><dd> The JSON number type.</dd>
<li><tt>Boolean</tt> - The JSON boolean type.</li> <dt><tt>Boolean</tt>:</dt><dd> The JSON boolean type.</dd>
<li><tt>A[B]</tt> - A JSON object where the keys are all of the type <dt><tt>A[B]</tt>:</dt><dd> A JSON object where all keys are of type
<tt>A</tt>, and the values are all of the type <tt>B</tt>.</li> <tt>A</tt> and all values are of type <tt>B</tt>.</dd>
<li><tt>A[]</tt> - A JSON array of values of type <tt>A</tt>.</li> <dt><tt>A[]</tt>:</dt><dd> A JSON array of values of type <tt>A</tt>
<li><tt>A|B</tt> - The value is either of type <tt>A</tt> or of type .</dd>
<tt>B</tt>.</li> <dt><tt>A|B</tt>:</dt><dd> The value is either of type <tt>A</tt> or
<li><tt>*</tt> - The type is undefined (the value could be any type, of type <tt>B</tt>.</dd>
although permitted values may be constrained by the context of this value).</li <dt><tt>* *</tt>:</dt><dd> The type is undefined (the value could be
> any type, although permitted values may be constrained by the context of this v
</ul> alue).</dd>
</dl>
<t><xref target="common-data-types"/> defines common data types, inclu ding signed or unsigned integers and dates.</t> <t><xref target="common-data-types"/> defines common data types, inclu ding signed or unsigned integers and dates.</t>
</section> </section>
<section anchor="property-attributes" numbered="true" toc="default"> <section anchor="property-attributes" numbered="true" toc="default">
<name>Property Attributes</name> <name>Property Attributes</name>
<t>Object properties may also have a set of attributes defined along w ith the type signature. These have the following meanings:</t> <t>Object properties may also have a set of attributes defined along w ith the type signature. These have the following meanings:</t>
<ul> <dl spacing="normal">
<li><tt>mandatory</tt>: The property <bcp14>MUST</bcp14> be set for <dt><tt>mandatory</tt>:</dt><dd> The property <bcp14>MUST</bcp14> be
an instance of this object to be valid.</li> set for an instance of this object to be valid.</dd>
<li><tt>optional</tt>: The property can but not need be set for an i <dt><tt>optional</tt>:</dt><dd> The property can, but need not, be s
nstance of this object to be valid.</li> et for an instance of this object to be valid.</dd>
<li><tt>default</tt>: This is followed by a JSON value. That value w <dt><tt>default</tt>:</dt><dd> This is followed by a JSON value. Tha
ill be used for this property if it is omitted.</li> t value will be used for this property if it is omitted.</dd>
<li><tt>defaultType</tt>: This is followed by the name of a JSContac <dt><tt>defaultType</tt>:</dt><dd> This is followed by the name of a
t object type. A property value of JSContact object type is expected to be of t JSContact object type. A property value of JSContact object type is expected t
his named type, in case it omits the <tt>@type</tt> property.</li> o be of this named type, in case it omits the <tt>@type</tt> property.</dd>
</ul> </dl>
</section> </section>
<section anchor="prop-type" numbered="true" toc="default"> <section anchor="prop-type" numbered="true" toc="default">
<name>The <tt>@type</tt> Property</name> <name>The <tt>@type</tt> Property</name>
<t>This property is defined as:</t> <dl spacing="normal">
<ul> <dt><tt>@type</tt>:</dt><dd> String. Specifies the type of the obje
<li><tt>@type</tt>: String. Specifies the type of this object. Thi ct. It <bcp14>MUST</bcp14> match the type name of the JSContact object of which
s <bcp14>MUST</bcp14> match the type name of the JSContact object of which this the JSON object is an instance of.</dd>
JSON object is an instance of.</li> </dl>
</ul> <t>The purpose of the <tt>@type</tt> property is to help implementatio
<t>The purpose of this property is to help implementations identify wh ns identify which JSContact object type a given JSON object represents. Impleme
ich JSContact object type a given JSON object represents. Implementations <bcp1 ntations <bcp14>MUST</bcp14> validate that JSON objects with this property confo
4>MUST</bcp14> validate that JSON objects with this property conform to the spec rm to the specification of the JSContact object type of that name.</t>
ification of the JSContact object type of that name.</t> <t>In many cases, the <tt>@type</tt> property value is implied by wher
<t>In many cases the <tt>@type</tt> property value is implied by where e its object occurs in JSContact data. Assuming that both <tt>A</tt> and <tt>B</
its object occurs in JSContact data. Assuming that both <tt>A</tt> and <tt>B</t tt> are JSContact object types:</t>
t> are JSContact object types:</t>
<ul> <ul>
<li>An object that is set as the value for a property with type sign <li>An object that is set as the value for a property with type sign
ature <tt>A</tt> <bcp14>MAY</bcp14> have the <tt>@type</tt> property set. If th ature <tt>A</tt> <bcp14>MAY</bcp14> have the <tt>@type</tt> property set. If th
e <tt>@type</tt> property is not set then its value is implied to be <tt>A</tt> e <tt>@type</tt> property is not set, then its value is implied to be <tt>A</tt>
by the property definition.</li> by the property definition.</li>
<li>An object that is set as the value for a property with type sign <li>An object that is set as the value for a property with type sign
ature <tt>A|B (defaultType: A)</tt> <bcp14>MAY</bcp14> have the <tt>@type</tt> p ature <tt>A|B (defaultType: A)</tt> <bcp14>MAY</bcp14> have the <tt>@type</tt> p
roperty set if it is an instance of <tt>A</tt>. It <bcp14>MUST</bcp14> have the roperty set if it is an instance of <tt>A</tt>. It <bcp14>MUST</bcp14> have the
<tt>@type</tt> property set if it is an instance of <tt>B</tt>. If instead the <tt>@type</tt> property set if it is an instance of <tt>B</tt>. If, instead, t
<tt>defaultType</tt> attribute is not defined then the <tt>@type</tt> property he <tt>defaultType</tt> attribute is not defined, then the <tt>@type</tt> proper
<bcp14>MUST</bcp14> also be set for <tt>A</tt>.</li> ty <bcp14>MUST</bcp14> also be set for <tt>A</tt>.</li>
<li>An object that is not the value of a property, such as the root <li>An object that is not the value of a property, such as the root
of JSON data (directly or as member of an array), <bcp14>MUST</bcp14> have the < of JSON data (directly or as a member of an array), <bcp14>MUST</bcp14> have the
tt>@type</tt> property set.</li> <tt>@type</tt> property set.</li>
</ul> </ul>
</section> </section>
</section> </section>
<section anchor="common-data-types" numbered="true" toc="default"> <section anchor="common-data-types" numbered="true" toc="default">
<name>Common Data Types</name> <name>Common Data Types</name>
<t>In addition to the standard JSON data types, a couple of additional d ata types are common to the definitions of JSContact objects and properties.</t> <t>In addition to the standard JSON data types, a couple of additional d ata types are common to the definitions of JSContact objects and properties.</t>
<section anchor="id" numbered="true" toc="default"> <section anchor="id" numbered="true" toc="default">
<name>Id</name> <name>Id</name>
<t>Where <tt>Id</tt> is given as a data type, it means a <tt>String</t <t>Where <tt>Id</tt> is given as a data type, it means a <tt>String</t
t> of at least 1 and a maximum of 255 octets in size, and it <bcp14>MUST</bcp14> t> of at least 1 and a maximum of 255 octets in size, and it <bcp14>MUST</bcp14>
only contain characters from the <tt>URL and Filename Safe</tt> base64url alpha only contain characters from the <tt>URL and Filename Safe</tt> base64url alpha
bet, as defined in Section 5 of <xref target="RFC4648" format="default"/>, exclu bet, as defined in <xref target="RFC4648" sectionFormat="of" section="5"/>, excl
ding the pad character (<tt>=</tt>). This means the allowed characters are the uding the pad character (<tt>=</tt>). This means the allowed characters are the
ASCII alphanumeric characters (<tt>A-Za-z0-9</tt>), hyphen (<tt>-</tt>), and und ASCII alphanumeric characters (<tt>A-Za-z0-9</tt>), hyphen (<tt>-</tt>), and un
erscore (<tt>_</tt>).</t> derscore (<tt>_</tt>).</t>
<t>In many places in JSContact a JSON map is used where the map keys a <t>In many places in JSContact, a JSON map is used where the map keys
re of type Id and the map values are all the same type of object. This construc are of type Id and the map values are all the same type of object. This constru
tion represents an unordered set of objects, with the added advantage that each ction 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 patc entry has a name (the corresponding map key). This allows for more concise pat
hing of objects, and, when applicable, for the objects in question to be referen ching of objects and, when applicable, for the objects in question to be referen
ced from other objects within the JSContact object. The map keys <bcp14>MUST</b ced from other objects within the JSContact object. The map keys <bcp14>MUST</b
cp14> be preserved across multiple versions of the JSContact object.</t> cp14> be preserved across multiple versions of the JSContact object.</t>
<t>Unless otherwise specified for a particular property, there are no <t>Unless otherwise specified for a particular property, there are no
uniqueness constraints on an Id value (other than, of course, the requirement th uniqueness constraints on an Id value (other than, of course, the requirement th
at you cannot have two values with the same key within a single JSON map). For at 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 t example, two <xref target="card">Card</xref> objects might use the same Ids in t
heir respective <tt>photos</tt> properties. Or within the same Card the same Id heir respective <tt>photos</tt> properties. Or within the same Card, the same I
could appear in the <tt>emails</tt> and <tt>phones</tt> properties. These situ d could appear in the <tt>emails</tt> and <tt>phones</tt> properties. These sit
ations do not imply any semantic connections among the objects.</t> uations do not imply any semantic connections among the objects.</t>
</section> </section>
<section anchor="int-unsignedint" numbered="true" toc="default"> <section anchor="int-unsignedint" numbered="true" toc="default">
<name>Int and UnsignedInt</name> <name>Int and UnsignedInt</name>
<t>Where <tt>Int</tt> is given as a data type, it means an integer in <t>Where <tt>Int</tt> is given as a data type, it means an integer in
the range -2<sup>53</sup>+1 &lt;= value &lt;= 2<sup>53</sup>-1, the safe range f the range -2<sup>53</sup>+1 &lt;= value &lt;= 2<sup>53</sup>-1, which is the saf
or integers stored in a floating-point double, represented as a JSON <tt>Number< e range for integers stored in a floating-point double, represented as a JSON <t
/tt>.</t> t>Number</tt>.</t>
<t>Where <tt>UnsignedInt</tt> is given as a data type, it means an int <t>Where <tt>UnsignedInt</tt> is given as a data type, it means an int
eger in the range 0 &lt;= value &lt;= 2<sup>53</sup>-1, represented as a JSON <t eger in the range 0 &lt;= value &lt;= 2<sup>53</sup>-1 represented as a JSON <tt
t>Number</tt>.</t> >Number</tt>.</t>
</section> </section>
<section anchor="patchobject" numbered="true" toc="default"> <section anchor="patchobject" numbered="true" toc="default">
<name>PatchObject</name> <name>PatchObject</name>
<t>A PatchObject is of type <tt>String[*]</tt>, and represents an unor <t>A PatchObject is of type <tt>String[*]</tt> and represents an unord
dered set of patches on a JSON object. ered set of patches on a JSON object.
Each key is a path represented in a subset of JSON pointer format <xref ta Each key is a path represented in a subset of the JSON Pointer format <
rget="RFC6901"/>. The paths have an implicit leading <tt>/</tt>, so each key is xref target="RFC6901"/>. The paths have an implicit leading <tt>/</tt>, so each
prefixed with <tt>/</tt> before applying the JSON pointer evaluation algorithm. key is prefixed with <tt>/</tt> before applying the JSON Pointer evaluation alg
</t> orithm.</t>
<t>A patch within a PatchObject is only valid if all the following con ditions apply:</t> <t>A patch within a PatchObject is only valid if all the following con ditions apply:</t>
<ol> <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 o f its existing members. To add or remove members, one needs to replace the comp lete array value).</li> <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 "-" a s an array index in any of its reference tokens (i.e., you <bcp14>MUST NOT</bcp1 4> 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 com plete array value).</li>
<li>All reference tokens prior to the last (i.e., the value after th e final slash) <bcp14>MUST</bcp14> already exist as values in the object being p atched. If the last reference token is an array index, then a member at this in dex <bcp14>MUST</bcp14> already exist in the referenced array.</li> <li>All reference tokens prior to the last (i.e., the value after th e final slash) <bcp14>MUST</bcp14> already exist as values in the object being p atched. If the last reference token is an array index, then a member at this in dex <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., <tt>ad dresses/1/city</tt> and <tt>addresses</tt>.</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., <tt>ad dresses/1/city</tt> and <tt>addresses</tt>.</li>
<li>The value for the patch <bcp14>MUST</bcp14> be valid for the pro perty being set (of the correct type and obeying any other applicable restrictio ns), or if null the property <bcp14>MUST</bcp14> be optional.</li> <li>The value for the patch <bcp14>MUST</bcp14> be valid for the pro perty being set (of the correct type and obeying any other applicable restrictio ns), or if null, the property <bcp14>MUST</bcp14> be optional.</li>
</ol> </ol>
<t>The value associated with each pointer determines how to apply that patch:</t> <t>The value associated with each pointer determines how to apply that patch:</t>
<ul> <ul>
<li>If null, remove the property from the patched object. If the ke y is not present in the parent, this is a no-op.</li> <li>If null, remove the property from the patched object. If the ke y 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> <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> </ul>
<t>A PatchObject does not define its own <xref target="prop-type"><tt> <t>A PatchObject does not define its own <xref target="prop-type"><tt>
@type</tt></xref> property. Instead, a <tt>@type</tt> property in a patch <bcp1 @type</tt></xref> property. Instead, an <tt>@type</tt> property in a patch <bcp
4>MUST</bcp14> be handled as any other patched property value.</t> 14>MUST</bcp14> be handled as any other patched property value.</t>
<t>Implementations <bcp14>MUST</bcp14> reject in its entirety a PatchO <t>Implementations <bcp14>MUST</bcp14> reject a PatchObject in its ent
bject if any of its patches are invalid. Implementations <bcp14>MUST NOT</bcp1 irety if any of its patches are invalid. Implementations <bcp14>MUST NOT</bcp1
4> apply partial patches.</t> 4> apply partial patches.</t>
</section> </section>
<section anchor="resource" numbered="true" toc="default"> <section anchor="resource" numbered="true" toc="default">
<name>Resource</name> <name>Resource</name>
<t>This data type defines a resource associated with the entity repres
ented by this Card, identified by a URI <xref target="RFC3986" format="default"/ <!--[rfced] When the term "Card" is referred to in the running text,
>. Several property definitions later in this document refer to the Resource da there is a mix of "this Card" and "the Card". For consistency and
ta type as the basis for their property-specific value types. The Resource data clarity, we updated several instances of "this Card" to "the
type defines the properties that are common to all of them. Property definitio Card". Please review and let us know if any further updates are
ns making use of Resource <bcp14>MAY</bcp14> define additional properties for th needed.
eir value types.</t>
<t>The <tt>@type</tt> property value <bcp14>MUST NOT</bcp14> be <tt>Re One example
source</tt>, instead it <bcp14>MUST</bcp14> be the name of a concrete resource t
ype (see <xref target="resource-properties"/>). A Resource object has the follo Original:
wing properties.</t> The date and time when the data in this Card was last
<ul spacing="normal"> modified.
<li>
<t>@type: <tt>String</tt>. Specifies the type of this resource ob Current:
ject. The allowed value is defined in later sections of this document for each The date and time when the data in the Card was last
concrete resource type (<xref target="resource-properties"/>).</t> modified.
</li> -->
<li>
<t>kind: <tt>String</tt> (optional). <t>The <tt>Resource</tt> data type defines a resource associated with
The kind of the resource. The allowed values are defined in the property defini the entity represented by the Card, identified by a URI <xref target="RFC3986" f
tion that makes use of the Resource type. Some property definitions may change ormat="default"/>. Later in this document, several property definitions refer t
this property from being optional to mandatory. o the Resource data type as the basis for their property-specific value types.
</t> The Resource data type defines the properties that are common to all of them. P
</li> roperty definitions making use of Resource <bcp14>MAY</bcp14> define additional
<li>uri: <tt>String</tt> (mandatory). properties for their value types.</t>
The resource value. This <bcp14>MUST</bcp14> be a <em>URI</em> as defined in Se <t>The <tt>@type</tt> property value <bcp14>MUST NOT</bcp14> be <tt>Re
ction 3 of <xref target="RFC3986" format="default"/>.</li> source</tt>; instead, it <bcp14>MUST</bcp14> be the name of a concrete resource
<li>mediaType: <tt>String</tt> (optional). type (see <xref target="resource-properties"/>). A Resource object has the foll
Used for URI resource values. Provides the media type <xref target="RFC2046" fo owing properties.</t>
rmat="default"/> of the resource identified by the URI.</li> <dl spacing="normal">
<li>contexts: <tt>String[Boolean]</tt> (optional). <dt>@type:</dt><dd> <tt>String</tt>. Specifies the type of this res
The contexts in which to use this resource. Also see <xref target="prop-context ource object. The allowed value is defined in later sections of this document f
s"/>.</li> or each concrete resource type (<xref target="resource-properties"/>).</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>kind:</dt><dd> <tt>String</tt> (optional).
The preference of this resource in relation to other resources. Als The kind of the resource. The allowed values are defined in the property defini
o see <xref target="prop-pref"/>.</li> tion that makes use of the Resource type. Some property definitions may change
<li>label: <tt>String</tt> (optional). this property from being optional to mandatory. </dd>
A custom label for the value, see <xref target="prop-label"/>.</li> <dt>uri:</dt><dd> <tt>String</tt> (mandatory).
</ul> The resource value. This <bcp14>MUST</bcp14> be a <em>URI</em> as defined in <x
ref target="RFC3986" sectionFormat="of" section="3"/>.</dd>
<dt>mediaType:</dt><dd> <tt>String</tt> (optional).
Used for URI resource values. Provides the media type <xref target="RFC2046" fo
rmat="default"/> of the resource identified by the URI.</dd>
<dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
The contexts in which to use this resource. Also see <xref target="prop-contexts
"/>.</dd>
<dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
The preference of the resource in relation to other resources. Also
see <xref target="prop-pref"/>.</dd>
<dt>label:</dt><dd> <tt>String</tt> (optional).
A custom label for the value. Also see <xref target="prop-label"/>.<
/dd>
</dl>
</section> </section>
<section anchor="utcdatetime" numbered="true" toc="default"> <section anchor="utcdatetime" numbered="true" toc="default">
<name>UTCDateTime</name> <name>UTCDateTime</name>
<t>This is a string in <xref target="RFC3339" format="default"/> <tt>d <t><tt>UTCDateTime</tt> is a string in <tt>date-time</tt> format <xref
ate-time</tt> format, with the further restrictions that any letters <bcp14>MUST target="RFC3339" format="default"/>, with further restrictions that any letters
</bcp14> be in uppercase, and the time offset <bcp14>MUST</bcp14> be the charact <bcp14>MUST</bcp14> be in uppercase and the time offset <bcp14>MUST</bcp14> be
er <tt>Z</tt>. Fractional second values <bcp14>MUST NOT</bcp14> be included unl the character <tt>Z</tt>. Fractional second values <bcp14>MUST NOT</bcp14> be i
ess non-zero and <bcp14>MUST NOT</bcp14> have trailing zeros, to ensure there is ncluded unless they are non-zero, and they <bcp14>MUST NOT</bcp14> have trailing
only a single representation for each date-time.</t> zeros to ensure there is only a single representation for each date-time.</t>
<t>For example, <tt>2010-10-10T10:10:10.003Z</tt> is conformant, but < <t>For example, <tt>2010-10-10T10:10:10.003Z</tt> is conformant, but <
tt>2010-10-10T10:10:10.000Z</tt> is invalid and is correctly encoded as <tt>2010 tt>2010-10-10T10:10:10.000Z</tt> is invalid; the correct encoding is <tt>2010-10
-10-10T10:10:10Z</tt>.</t> -10T10:10:10Z</tt>.</t>
</section> </section>
</section> </section>
<section anchor="common-properties"> <section anchor="common-properties">
<name>Common Properties</name> <name>Common Properties</name>
<t>Most of the properties in this document are specific to a single JSCo <t>Most of the properties in this document are specific to a single JSCo
ntact object type. Such properties are defined along with the respective object ntact 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 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</bcp1 defined here to avoid repetition. Note that these properties <bcp14>MUST</bcp1
4> only be set for a JSContact object if they are explicitly mentioned to be all 4> only be set for a JSContact object if they are explicitly mentioned as allowa
owed for this object type.</t> ble 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"> <section anchor="prop-contexts" numbered="true" toc="default">
<name>contexts</name> <name>contexts</name>
<t>Type: <tt>String[Boolean]</tt></t> <t>Type: <tt>String[Boolean]</tt></t>
<t>This property associates contact information with one or more conte xts in which it should be used. For example, someone might have distinct phone numbers for work and private contexts, and may set the desired context on the re spective phone number in the <xref target="phones"><tt>phones</tt></xref> proper ty.</t> <t>This property associates contact information with one or more conte xts in which it should be used. For example, someone might have distinct phone numbers for work and private contexts and may set the desired context on the res pective phone number in the <xref target="phones"><tt>phones</tt></xref> propert y.</t>
<t>This section defines common contexts. Additional contexts may be d efined in the properties or data types that make use of this property. The <xre f target="enumerated-values">enumerated</xref> common context values are:</t> <t>This section defines common contexts. Additional contexts may be d efined in the properties or data types that make use of this property. The <xre f target="enumerated-values">enumerated</xref> common context values are:</t>
<ul spacing="normal"> <ul spacing="normal">
<li><tt>private</tt>: the contact information may be used in a priva <li><tt>private</tt>: the contact information that may be used in a
te context.</li> private context.</li>
<li><tt>work</tt>: the contact information may be used in a professi <li><tt>work</tt>: the contact information that may be used in a pro
onal context.</li> fessional context.</li>
</ul> </ul>
</section> </section>
<section anchor="prop-extra" numbered="true" toc="default"> <section anchor="prop-extra" numbered="true" toc="default">
<name>extra</name> <name>extra</name>
<t>This is a reserved property name. Implementations <bcp14>MUST NOT</ <t><tt>extra</tt> is a reserved property name. Implementations <bcp14>
bcp14> set this property in a JSContact object. Any JSContact object including MUST NOT</bcp14> set this property in a JSContact object. Any JSContact object
a property with this name <bcp14>MUST</bcp14> be considered invalid.</t> including a property with this name <bcp14>MUST</bcp14> be considered invalid.</
<t>The purpose of this reserved property name is to provide implemento t>
rs with a name which is certain to never occur as a property name in a JSContact <t>The purpose of this reserved property name is to provide implemento
object. Implementations might want to map unknown or vendor-specific propertie rs with a name that is certain to never occur as a property name in a JSContact
s to a variable with this name, but this is implementation-specific.</t> object. Implementations might want to map unknown or vendor-specific properties
to a variable with this name, but this is implementation-specific.</t>
</section> </section>
<section anchor="prop-label" numbered="true" toc="default"> <section anchor="prop-label" numbered="true" toc="default">
<name>label</name> <name>label</name>
<t>Type: <tt>String</tt></t> <t>Type: <tt>String</tt></t>
<t>This property allows associating contact data with user-defined lab els. Such labels may be set for phone numbers, email addresses and resources. Typically, these labels are displayed along with their associated contact data i n graphical user interfaces. Such labels best be succinct to properly display o n small graphical interfaces and screens.</t> <t>This property allows associating contact data with user-defined lab els. Such labels may be set for phone numbers, email addresses, and resources. Typically, these labels are displayed along with their associated contact data in graphical user interfaces. Note that succinct labels are best for proper disp lay on small graphical interfaces and screens.</t>
</section> </section>
<section anchor="prop-pref" numbered="true" toc="default"> <section anchor="prop-pref" numbered="true" toc="default">
<name>pref</name> <name>pref</name>
<t>Type: <tt>UnsignedInt</tt></t> <t>Type: <tt>UnsignedInt</tt></t>
<t>This property allows defining a preference order for contact inform ation. For example, a person may have two email addresses and prefer to be cont acted with one of them.</t> <t>This property allows defining a preference order for contact inform ation. For example, a person may have two email addresses and prefer to be cont acted with one of them.</t>
<t>Its value <bcp14>MUST</bcp14> be in the range 1 and 100. Lower val <t>Its value <bcp14>MUST</bcp14> be in the range of 1 to 100. Lower v
ues correspond to a higher level of preference, with 1 being most preferred. If alues correspond to a higher level of preference, with 1 being most preferred.
no preference is set, then the contact information <bcp14>MUST</bcp14> be inter If no preference is set, then the contact information <bcp14>MUST</bcp14> be int
preted as being least preferred.</t> erpreted as being least preferred.</t>
<t>Note that the preference only is defined in relation to contact inf <t>Note that the preference is only defined in relation to contact inf
ormation of the same type. For example, the preference orders within emails and ormation of the same type. For example, the preference orders within emails and
phone numbers are independent of each other.</t> phone numbers are independent of each other.</t>
</section> </section>
<section anchor="prop-phonetic" numbered="true" toc="default"> <section anchor="prop-phonetic" numbered="true" toc="default">
<name>phonetic</name> <name>phonetic</name>
<t>This property defines how to pronounce a value in the language indi <t>The phonetic property defines how to pronounce a value in the langu
cated in the Card <xref target="language">language</xref> property or the langua age indicated in the Card <xref target="language">language</xref> property or th
ge tag of its <xref target="localizations">localizations</xref>. Exemplary uses e language tag of its <xref target="localizations">localizations</xref>. Exempl
are to define how to pronounce Japanese names, or for romanization of Mandarin ary uses of this property are defining how to pronounce Japanese names and roman
or Cantonese name and address components. The properties are defined as follows izing Mandarin or Cantonese name and address components. The properties are def
:</t> ined as follows:</t>
<ul spacing="normal"> <dl spacing="normal">
<li> <dt>phonetic:</dt><dd> <tt>String</tt>.
<t>phonetic: <tt>String</tt>. Contains the phonetic representation of a value.
Contains the phonetic representation of a value. Any script lan
guage subtag in the Card <xref target="language">language</xref> property <bcp14 <!--[rfced] Can "ignored for use with" be updated as "ignored and not
>MUST</bcp14> be ignored for use with the <tt>phonetic</tt> property. If this p used with" for clarity as shown below?
roperty is set, then at least one of the <tt>phoneticScript</tt> or <tt>phonetic
System</tt> properties that relate to this value <bcp14>MUST</bcp14> be set.</t> Original:
</li> Any script language subtag in the Card language (Section 2.1.5)
<li> property MUST be ignored for use with the phonetic property.
<t>phoneticScript: <tt>String</tt>.
The script used in the value of the related <tt>phonetic</tt> pr Perhaps:
operty. This <bcp14>MUST</bcp14> be a valid script subtag as defined in <xref t Any script language subtag in the Card language (Section 2.1.5)
arget="RFC5646" section="2.2.3"/>.</t> property MUST be ignored and not used with the phonetic property.
</li> -->
<li>
<t>phoneticSystem: <tt>String</tt>. Any script language subtag in the Card <xref target="language">langua
The phonetic system used in the related value of the <tt>phonetic< ge</xref> property <bcp14>MUST</bcp14> be ignored for use with the <tt>phonetic<
/tt> property. The <xref target="enumerated-values">enumerated values</xref> ar /tt> property. If this property is set, then at least one of the <tt>phoneticSc
e:</t> ript</tt> or <tt>phoneticSystem</tt> properties that relate to this value <bcp14
>MUST</bcp14> be set.</dd>
<dt>phoneticScript:</dt><dd> <tt>String</tt>.
The script used in the value of the related <tt>phonetic</tt> proper
ty. This <bcp14>MUST</bcp14> be a valid script subtag as defined in <xref targe
t="RFC5646" section="2.2.3"/>. </dd>
<dt>phoneticSystem:</dt><dd><t> <tt>String</tt>.
The phonetic system used in the related value of the <tt>phonetic<
/tt> property. The <xref target="enumerated-values">enumerated</xref> values ar
e:</t>
<ul> <ul>
<li><tt>ipa</tt>: denotes the <xref target="IPA">International P honetic Alphabet</xref>.</li> <li><tt>ipa</tt>: denotes the <xref target="IPA">International P honetic Alphabet</xref>.</li>
<li><tt>jyut</tt>: denotes the Cantonese romanization system "Jy utping".</li> <li><tt>jyut</tt>: denotes the Cantonese romanization system "Jy utping".</li>
<li><tt>piny</tt>: denotes the Standard Mandarin romanization sy stem "Hanyu Pinyin".</li> <li><tt>piny</tt>: denotes the Standard Mandarin romanization sy stem "Hanyu Pinyin".</li>
</ul> </ul>
</li> </dd>
</ul> </dl>
<t>The relation between the <tt>phoneticSystem</tt>, <tt>phoneticScrip <t>The relation between the <tt>phoneticSystem</tt>, <tt>phoneticScrip
t</tt> and <tt>phonetic</tt> properties is type-specific. This specification de t</tt>, and <tt>phonetic</tt> properties is type-specific. This specification d
fines this relation in the <xref target="name">Name</xref> and <xref target="add efines this relation in the <xref target="name">Name</xref> and <xref target="ad
resses">Address</xref> object types, respectively.</t> dresses">Address</xref> object types, respectively.</t>
<t>The following example illustrates the <tt>phonetic</tt> property fo r a <xref target="name">name</xref>:</t> <t>The following example illustrates the <tt>phonetic</tt> property fo r a <xref target="name">name</xref>:</t>
<figure anchor="example-phonetic"> <figure anchor="example-phonetic">
<name>Example of <tt>phonetic</tt> for the name "John Smith" as pron ounced in the USA.</name> <name>Example of a <tt>phonetic</tt> Property for the Name "John Smi th" as Pronounced in the USA</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"name": { "name": {
"components": [{ "components": [{
"kind": "given", "kind": "given",
"value": "John", "value": "John",
"phonetic": "/ˈdʒɑːn/" "phonetic": "/ˈdʒɑːn/"
}, { }, {
"kind": "surname", "kind": "surname",
"value": "Smith", "value": "Smith",
"phonetic": "/smɪθ/" "phonetic": "/smɪθ/"
}], }],
"phoneticSystem": "ipa" "phoneticSystem": "ipa"
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
<section anchor="internationalization"> <section anchor="internationalization">
<name>Internationalization</name> <name>Internationalization</name>
<t>JSContact aims to be used for international contacts and addressbook data. Notably text values such as names and addresses are likely to cover a wide range of languages and cultures. This section describes internationalization f or free-form text values, as well as for Uniform Resource Identifiers (URIs).</t > <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 wi de range of languages and cultures. This section describes internationalization for free-form text values as well as Uniform Resource Identifiers (URIs).</t>
<section> <section>
<name>Free-form text</name> <name>Free-Form Text</name>
<t>Properties having free-form text values <bcp14>MAY</bcp14> contain <t>Properties having free-form text values <bcp14>MAY</bcp14> contain
any valid sequence of Unicode characters encoded as a JSON string. Such values 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 bidi can contain unidirectional left-to-right and right-to-left text, as well as bidi
rectional text using Unicode Directional Formatting Characters described in Sect rectional text using Unicode Directional Formatting Characters as described in S
ion 2 of <xref target="UBiDi"/>. Implementations setting bidirectional text <bcp ection 2 of <xref target="UBiDi"/>. Implementations setting bidirectional text <
14>MUST</bcp14> make sure that each property value complies with the requirement bcp14>MUST</bcp14> make sure that each property value complies with the requirem
s of the Unicode Bidirectional Algorithm. Implementations <bcp14>MUST NOT</bcp1 ents of the Unicode Bidirectional Algorithm. Implementations <bcp14>MUST NOT</b
4> assume that text values of adjacent properties are processed or displayed as cp14> assume that text values of adjacent properties are processed or displayed
a combined string, for example the values of a given name component and a surnam as a combined string; for example, the values of a given name component and a su
e component may or may not to be rendered together.</t> rname component may or may not be rendered together.</t>
</section> </section>
<section> <section>
<name>URIs</name> <name>URIs</name>
<t>Several properties require their string value to be a URI as define <t>Several properties require their string value to be a URI as define
d in <xref target="RFC3986"/>. Implementations <bcp14>MUST</bcp14> make sure to d in <xref target="RFC3986"/>. Implementations <bcp14>MUST</bcp14> make sure to
use proper percent-encoding for URIs that can not be represented using unreserv use proper percent-encoding for URIs that cannot be represented using unreserve
ed URI characters. <xref target="RFC3987" section="3.1"/> defines how to conver d URI characters. <xref target="RFC3987" section="3.1"/> defines how to convert
t Internationalized Resource Identifiers to URIs. JSContact makes no recommenda Internationalized Resource Identifiers to URIs.
tion how to display URIs, but section "4.8.3 Internationalization and special ch
aracters" of the <xref target="W3C-URL">W3C URL Standard</xref> provides guidanc <!--[rfced] We notice that "URL Living Standard"
e for URLs found in context of a web browser.</t> <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> </section>
<section anchor="validating-jscontact"> <section anchor="validating-jscontact">
<name>Validating JSContact</name> <name>Validating JSContact</name>
<t>This specification distinguishes between three kinds of properties re <t>This specification distinguishes between three kinds of properties re
garding validation: IANA-registered properties and unknown properties are define garding validation: IANA-registered properties and unknown properties, which are
d in this section, while vendor-specific properties are defined in <xref target= defined in this section, and vendor-specific properties, which are defined in <
"vendor-specific-properties"/>. A JSContact object is invalid if any of its pro xref target="vendor-specific-properties"/>. A JSContact object is invalid if an
perties are invalid.</t> y of its properties are invalid.</t>
<t>This document defines for each property if it is mandatory or optiona <t>This document defines whether each property is mandatory or optional.
l. A mandatory property <bcp14>MUST</bcp14> be present for a JSContact object t A mandatory property <bcp14>MUST</bcp14> be present for a JSContact object to
o be valid. An optional property does not need to be present. The values of bo be valid. An optional property does not need to be present. The values of both
th required and optional properties <bcp14>MUST</bcp14> adhere to the data type required and optional properties <bcp14>MUST</bcp14> adhere to the data type an
and definition of that property.</t> d definition of that property.</t>
<section anchor="case-sensitivity"> <section anchor="case-sensitivity">
<name>Case-Sensitivity</name> <name>Case-Sensitivity</name>
<t>All property names, object type names and enumerated values are cas e-sensitive, if not explicitly stated otherwise in their according definition. Implementations <bcp14>MUST</bcp14> handle a JSContact object as invalid if a ty pe name, property name or enumerated value only differs in case from one defined for any JSContact version known to that implementation. This applies regardles s of what JSContact version the Card object defines in its <xref target="prop-ve rsion"><tt>version</tt></xref> property. <xref target="unknown-properties"/> de fines how to handle unknown properties.</t> <t>All property names, object type names, and enumerated values are ca se-sensitive, unless explicitly stated otherwise in their definitions. Implemen tations <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 an y JSContact version known to that implementation. This applies regardless of wh at JSContact version the Card object defines in its <xref target="prop-version"> <tt>version</tt></xref> property. <xref target="unknown-properties"/> defines h ow to handle unknown properties.</t>
</section> </section>
<section anchor="iana-registered-properties" numbered="true" toc="defaul t"> <section anchor="iana-registered-properties" numbered="true" toc="defaul t">
<name>IANA-registered Properties</name> <name>IANA-Registered Properties</name>
<t> <t>
An IANA-registered property is any property that has been registered ac cording to the IANA property registry rules as outlined in <xref target="iana-co nsiderations"/>. All properties defined in this specification, including their object value types and enumerated values, are registered at IANA. An IANA-registered property is any property that has been registered ac cording to the IANA property registry rules as outlined in <xref target="iana-co nsiderations"/>. All properties defined in this specification, including their object value types and enumerated values, are registered at IANA.
</t> </t>
<t> <t>
Implementations <bcp14>MUST</bcp14> validate IANA-registered properties in JSContact data, unless they are unknown to the implementation (see <xref targ et="unknown-properties"/>). They <bcp14>MUST</bcp14> reject invalid IANA-regist ered 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 JSCon tact specification version defined in the Card <tt>version</tt> property (<xref target="prop-version"/>). 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-regi stered property but the value violates its definition according to the JSContact specification version defined in the Card <xref target="prop-version"><tt>versi on</tt></xref> property.
</t> </t>
<t> <t>
IANA-registered property names <bcp14>MUST NOT</bcp14> contain US-AS
CII control characters (U+0000 to U+001F, U+007F), the <tt>COLON</tt> (U+003A) o <!-- [rfced] The RFC Production Center has been advised that "ASCII"
r <tt>QUOTATION MARK</tt> (U+0022) characters. They <bcp14>MUST</bcp14> only co and not "US-ASCII" should be used. May we change two instances
ntain US-ASCII alphanumeric characters that match the ALPHA and DIGIT rules defi of "US-ASCII" in this document to "ASCII"?
ned in <xref target="RFC5234" section="B.1"/>) or the <tt>COMMERCIAL AT</tt> (U+
0040) character. IANA-registered property names <bcp14>MUST</bcp14> be notated Original:
in lower camel case. 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 US-AS
CII control characters (U+0000 to U+001F, U+007F), the <tt>COLON</tt> (U+003A),
or the <tt>QUOTATION MARK</tt> (U+0022). They <bcp14>MUST</bcp14> only contain
US-ASCII alphanumeric characters that match the ALPHA and DIGIT rules defined in
<xref target="RFC5234" section="B.1"/> or the <tt>COMMERCIAL AT</tt> (U+0040) c
haracter. IANA-registered property names <bcp14>MUST</bcp14> be notated in lowe
r camel case.
</t> </t>
</section> </section>
<section anchor="unknown-properties" numbered="true" toc="default"> <section anchor="unknown-properties" numbered="true" toc="default">
<name>Unknown Properties</name> <name>Unknown Properties</name>
<t> <t>
Implementations may encounter JSContact data where a property name i Implementations may encounter JSContact data where a property name i
s unknown to that implementation, but the name adheres to the syntactic restrict s unknown to that implementation but the name adheres to the syntactic restricti
ions of IANA-registered property names. Implementations <bcp14>MUST</bcp14> mak ons of IANA-registered property names. Implementations <bcp14>MUST</bcp14> make
e sure that such a name does not violate the case-sensitivity rules defined in < sure that such a name does not violate the case-sensitivity rules defined in <x
xref target="case-sensitivity"/>. If the property name is valid, then implement ref target="case-sensitivity"/>. If the property name is valid, then implementa
ations <bcp14>MUST NOT</bcp14> treat such properties as invalid. Instead, they tions <bcp14>MUST NOT</bcp14> treat such properties as invalid. Instead, they <
<bcp14>MUST</bcp14> preserve them in the JSContact object.</t> bcp14>MUST</bcp14> preserve them in the JSContact object.</t>
<t>Implementations that create or update JSContact data <bcp14>MUST</b <t>Implementations that create or update JSContact data <bcp14>MUST</b
cp14> only set IANA-registered properties or vendor-specific properties. Preser cp14> only set IANA-registered properties or vendor-specific properties. Preser
ving properties that are unknown to the implementation, is to allow applications ving properties that are unknown to the implementation is to allow applications
and services to interoperate without data loss, even if not all of them impleme and services to interoperate without data loss, even if not all of them implemen
nt the same set of JSContact extensions. t the same set of JSContact extensions.
</t> </t>
</section> </section>
<section anchor="enumerated-values" numbered="true" toc="default"> <section anchor="enumerated-values" numbered="true" toc="default">
<name>Enumerated Values</name> <name>Enumerated Values</name>
<t>Several properties in this document restrict their allowed values to be from a list of String values. These values are case-sensitive. If not no ted otherwise for a specific property, the initial list of values for such prope rties is registered at IANA in the <xref target="iana-enum-registry">JSContact E num Values Registry</xref>. Implementations <bcp14>MUST</bcp14> only set IANA-r egistered or <xref target="vendor-specific-values">vendor-specific</xref> values for such properties.</t> <t>Several properties in this document restrict their allowed values t o a list of String values. These values are case-sensitive. If not noted other wise 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 Valu es" registry</xref>. Implementations <bcp14>MUST</bcp14> only set IANA-register ed or <xref target="vendor-specific-values">vendor-specific</xref> values for su ch properties.</t>
</section> </section>
</section> </section>
<section anchor="vendor-specific-extensions"> <section anchor="vendor-specific-extensions">
<name>Vendor-Specific Extensions</name> <name>Vendor-Specific Extensions</name>
<t>Vendors may extend properties and values for experimentation or to st ore contacts data that only is useful for a single service or application. Such extensions are not meant for interoperation. If instead interoperation is desi red, vendors are strongly encouraged to define and register new properties, type s and values at IANA. <xref target="iana-considerations"/> defines how to regis ter new properties, types or values at IANA. <xref target="iana-registered-prop erties"/> defines the naming conventions for IANA-registered elements.</t> <t>Vendors may extend properties and values for experimentation or to st ore contacts data that is only useful for a single service or application. Such extensions are not meant for interoperation. If, instead, interoperation is de sired, vendors are strongly encouraged to define and register new properties, ty pes, and values at IANA as defined in <xref target="iana-considerations"/>. <xre f target="iana-registered-properties"/> defines the naming conventions for IANA- registered elements.</t>
<section anchor="vendor-specific-properties" numbered="true" toc="defaul t"> <section anchor="vendor-specific-properties" numbered="true" toc="defaul t">
<name>Vendor-specific Properties</name> <name>Vendor-Specific Properties</name>
<t> <t>
Vendor-specific property names <bcp14>MUST</bcp14> start with a vend or-specific prefix followed by a name, as produced by the <tt>v-extension</tt> A BNF below. The prefix and name together form the property name. The vendor-spe cific prefix <bcp14>MUST</bcp14> be a domain name under control of the service o r application that sets the property, but it need not resolve in the Domain Name System <xref target="RFC1034"/> and <xref target="RFC1035"/>. The prefix <tt>i etf.org</tt> and its subdomain names are reserved for IETF specifications. The name <bcp14>MUST NOT</bcp14> contain the <tt>TILDE</tt> (U+007E) and <tt>SOLIDUS </tt> (U+002F) characters, as these require special-escaping when encoding a JSO N Pointer <xref target="RFC6901"/> for that property. Vendor-specific property names <bcp14>MUST</bcp14> start with a vend or-specific prefix followed by a name, as produced by the <tt>v-extension</tt> A BNF below. The prefix and name together form the property name. The vendor-spe cific prefix <bcp14>MUST</bcp14> be a domain name under control of the service o r application that sets the property, but it need not resolve in the Domain Name System <xref target="RFC1034"/> <xref target="RFC1035"/>. The prefix <tt>ietf. org</tt> and its subdomain names are reserved for IETF specifications. The name <bcp14>MUST NOT</bcp14> contain the <tt>TILDE</tt> (U+007E) and <tt>SOLIDUS</tt > (U+002F) characters, as these require special escaping when encoding a JSON Po inter <xref target="RFC6901"/> for that property.
</t> </t>
<t> <t>
Vendor-specific properties <bcp14>MAY</bcp14> be set in any JSContact ob ject. Implementations <bcp14>MUST</bcp14> preserve vendor-specific properties i n JSContact data, irrespective if they know their use. They <bcp14>MUST NOT</bc p14> reject the property value as invalid, unless they are in control of the ven dor-specific property as outlined in the above paragraph. Vendor-specific properties <bcp14>MAY</bcp14> be set in any JSContact ob ject. Implementations <bcp14>MUST</bcp14> preserve vendor-specific properties i n JSContact data, irrespective if they know their use. They <bcp14>MUST NOT</bc p14> reject the property value as invalid, unless they are in control of the ven dor-specific property as outlined in the above paragraph.
</t> </t>
<t>The ABNF rule <tt>v-extension</tt> formally defines valid vendor-sp ecific property names. Note that the vendor prefix allows for more values than are allowed as Internationalized Domain Names (IDN) <xref target="RFC8499"/>. T his is to allow JSContact implementations simply validate property names without implementing the full set of rules that apply to domain names.</t> <t>The ABNF rule <tt>v-extension</tt> formally defines valid vendor-specif ic property names. Note that the vendor prefix allows for more values than Inter nationalized 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"> <figure anchor="vendor-property-abnf">
<name>ABNF rules for vendor-specific property names</name> <name>ABNF Rules for Vendor-Specific Property Names</name>
<sourcecode name="" type="abnf"><![CDATA[ <sourcecode name="" type="abnf"><![CDATA[
v-extension = v-prefix ":" v-name v-extension = v-prefix ":" v-name
v-prefix = v-label *("." v-label) v-prefix = v-label *("." v-label)
v-label = alnum-int / alnum-int *(alnum-int / "-") alnum-int v-label = alnum-int / alnum-int *(alnum-int / "-") alnum-int
alnum-int = ALPHA / DIGIT / NON-ASCII alnum-int = ALPHA / DIGIT / NON-ASCII
; see RFC 6350 Section 3.3 ; see RFC 6350, Section 3.3
v-name = 1*(WSP / "!" / %x23-2e / %x30-7d / NON-ASCII) v-name = 1*(WSP / "!" / %x23-2e / %x30-7d / NON-ASCII)
; any characters except CTLs, DQUOTE, SOLIDUS and TILDE ; any characters except CTLs, DQUOTE, SOLIDUS, and TILDE
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
<t> <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 prop erty value is a JSON object then the keys of such objects need not be named as v endor-specific properties. The example in <xref target="vendor-property-example "/> illustrates this: The value of vendor-specific properties can be any valid JSON value, and naming restrictions do not apply to such values. Specifically, if the prop erty 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-exam ple"/>:
</t> </t>
<figure anchor="vendor-property-example"> <figure anchor="vendor-property-example">
<name>Examples of vendor-specific properties</name> <name>Examples of Vendor-Specific Properties</name>
<artwork><![CDATA[ <sourcecode type=""><![CDATA[
"example.com:foo": "bar", "example.com:foo": "bar",
"example.com:foo2": { "example.com:foo2": {
"bar": "baz" "bar": "baz"
} }
]]></artwork> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="vendor-specific-values" numbered="true" toc="default"> <section anchor="vendor-specific-values" numbered="true" toc="default">
<name>Vendor-specific Values</name> <name>Vendor-Specific Values</name>
<t> <t>
Some JSContact IANA-registered properties allow their values to be v endor-specific. One such example is the <tt>kind</tt> property <xref target="ki nd"/>, which enumerates its standard values but also allows for arbitrary vendor -specific values. Such vendor-specific values <bcp14>MUST</bcp14> be valid <tt> v-extension</tt> values as defined in <xref target="vendor-specific-properties"/ >. The example in <xref target="vendor-value-example"/> illustrates this: Some JSContact IANA-registered properties allow their values to be v endor-specific. One such example is the <xref target="kind"><tt>kind</tt></xre f> property, which enumerates its standard values but also allows for arbitrary vendor-specific values. Such vendor-specific values <bcp14>MUST</bcp14> be vali d <tt>v-extension</tt> values as defined in <xref target="vendor-specific-proper ties"/>. The example in <xref target="vendor-value-example"/> illustrates this:
</t> </t>
<figure anchor="vendor-value-example"> <figure anchor="vendor-value-example">
<name>Example of a vendor-specific value</name> <name>Example of a Vendor-Specific Value</name>
<artwork><![CDATA[ <sourcecode><![CDATA[
"kind": "example.com:baz" "kind": "example.com:baz"
]]></artwork> ]]></sourcecode>
</figure> </figure>
<t> <t>
Vendors are strongly encouraged to specify a new standard value once a ven dor-specific one turns out to be useful also for other systems. Vendors are strongly encouraged to specify a new standard value once a ven dor-specific one turns out to also be useful for other systems.
</t> </t>
</section> </section>
</section> </section>
<section anchor="versioning"> <section anchor="versioning">
<name>Versioning</name> <name>Versioning</name>
<t>Every instance of a JSContact <xref target="card">Card</xref> indicat <t>Every instance of a JSContact <xref target="card">Card</xref> indicat
es which JSContact version its IANA-registered properties and values are based o es which JSContact version its IANA-registered properties and values are based o
n. The version is indicated both in the <xref target="prop-version"><tt>version n.
</tt></xref> property within the Card and in the <xref target="iana-media-type">
version</xref> parameter of the JSContact MIME content type. All IANA-registered <!--[rfced] As "MIME" is no longer used in the IANA registry, may we
elements indicate the version at which they got introduced or obsoleted.</t> 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"><tt>vers
ion</tt></xref> property within the Card and in the <xref target="iana-media-typ
e">version</xref> parameter of the JSContact MIME content type. All IANA-registe
red elements indicate the version at which they were introduced or obsoleted.</t
>
<section> <section>
<name>Version Format and Requirements</name> <name>Version Format and Requirements</name>
<t>A JSContact version consists of a numeric major and minor version, <t>A JSContact version consists of a numeric major and minor version,
separated by the <tt>FULL STOP</tt> character (U+002E). Later versions are nume separated by the <tt>FULL STOP</tt> character (U+002E). Later versions are nume
rically higher than former versions, with the major version being more significa rically higher than former versions, with the major version being more significa
nt than the minor version. A version value is produced by the ABNF</t> nt 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>
<sourcecode name="" type="abnf"><![CDATA[ <sourcecode name="" type="abnf"><![CDATA[
jsversion = 1*DIGIT "." 1*DIGIT jsversion = 1*DIGIT "." 1*DIGIT
]]></sourcecode> ]]></sourcecode>
<t>Differing major version values indicate substantial differences in </figure>
JSContact semantics and format. Implementations <bcp14>MUST</bcp14> be prepared <t>Differing major version values indicate substantial differences in
that property definitions and other JSContact elements differ in a backwards-in JSContact semantics and format. Implementations <bcp14>MUST</bcp14> be prepared
compatible manner.</t> for property definitions and other JSContact elements that differ in a backward
<t>Differing minor version values indicate additions that enrich JSCon s-incompatible manner.</t>
tact data, but do not introduce backwards-incompatible changes. Typically, thes <t>Differing minor version values indicate additions that enrich JSCon
e are new property enum values or properties with narrow semantic scope. A new tact data but do not introduce backwards-incompatible changes. Typically, these
minor version <bcp14>MUST NOT</bcp14> require implementations to change their pr are new property enum values or properties with a narrow semantic scope. A new
ocessing of JSContact data. Changing the major version number resets the minor minor version <bcp14>MUST NOT</bcp14> require implementations to change their p
version number to zero.</t> rocessing of JSContact data. Changing the major version number resets the minor
version number to zero.</t>
</section> </section>
<section anchor="current-version"> <section anchor="current-version">
<name>Current Version</name> <name>Current Version</name>
<t>This specification registers JSContact version value <tt>1.0</tt> ( <xref target="tab-iana-version-registry"/>).</t> <t>This specification registers JSContact version value <tt>1.0</tt> ( <xref target="tab-iana-version-registry"/>).</t>
</section> </section>
</section> </section>
</section> </section>
<section anchor="card" numbered="true" toc="default"> <section anchor="card" numbered="true" toc="default">
<name>Card</name> <name>Card</name>
<t>This section defines the JSContact object type Card. A Card stores cont act information, typically that of a person, organization or company.</t> <t>This section defines the JSContact object type Card. A Card stores cont act information, typically that of a person, organization, or company.</t>
<t>Its media type is defined in <xref target="iana-media-type"/>.</t> <t>Its media type is defined in <xref target="iana-media-type"/>.</t>
<t><xref target="example-card"/> basic Card for the person "John Doe". A s the object is the topmost object in the JSON data it has the <tt>@type</tt> pr operty set according to the rules defined <xref target="prop-type"/>.</t> <t><xref target="example-card"/> shows a basic Card for the person "John D oe". As the object is the topmost object in the JSON data, it has the <tt>@type </tt> property set according to the rules defined in <xref target="prop-type"/>. </t>
<figure anchor="example-card"> <figure anchor="example-card">
<name>Example of a basic <tt>Card</tt></name> <name>Example of a Basic <tt>Card</tt></name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
{ {
"@type": "Card", "@type": "Card",
"version": "1.0", "version": "1.0",
"uid": "22B2C7DF-9120-4969-8460-05956FE6B065", "uid": "22B2C7DF-9120-4969-8460-05956FE6B065",
"kind": "individual", "kind": "individual",
"name": { "name": {
"components": [ "components": [
{ "kind": "given", "value": "John" }, { "kind": "given", "value": "John" },
{ "kind": "surname", "value": "Doe" } { "kind": "surname", "value": "Doe" }
], ],
"isOrdered": true "isOrdered": true
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
<section anchor="metadata-properties" numbered="true" toc="default"> <section anchor="metadata-properties" numbered="true" toc="default">
<name>Metadata Properties</name> <name>Metadata Properties</name>
<t>This section defines properties about this instance of a Card, such a s its unique identifier, its creation date, how it relates to other Cards and ot her metadata information.</t> <t>This section defines properties about this instance of a Card such as its unique identifier, its creation date, and how it relates to other Cards and other metadata information.</t>
<section anchor="cardtype" numbered="true" toc="default"> <section anchor="cardtype" numbered="true" toc="default">
<name>@type</name> <name>@type</name>
<t>Type: <tt>String</tt> (mandatory).</t> <t>Type: <tt>String</tt> (mandatory)</t>
<t>This <bcp14>MUST</bcp14> be <tt>Card</tt>, if set.</t> <t>This <bcp14>MUST</bcp14> be <tt>Card</tt>, if set.</t>
</section> </section>
<section anchor="prop-version" numbered="true" toc="default"> <section anchor="prop-version" numbered="true" toc="default">
<name>version</name> <name>version</name>
<t>Type: <tt>String</tt> (mandatory).</t> <t>Type: <tt>String</tt> (mandatory)</t>
<t>Specifies the JSContact version used to define this Card. The valu <t>This specifies the JSContact version used to define the Card. The
e <bcp14>MUST</bcp14> be one of the IANA-registered JSContact Enum Values for th value <bcp14>MUST</bcp14> be one of the IANA-registered JSContact Enum Values fo
e <tt>version</tt> property. Also see <xref target="current-version"/>.</t> r the <tt>version</tt> property. Also see <xref target="current-version"/>.</t>
<figure anchor="example-version"> <figure anchor="example-version">
<name><tt>version</tt> example</name> <name><tt>version</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"version": "1.0" "version": "1.0"
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="created" numbered="true" toc="default"> <section anchor="created" numbered="true" toc="default">
<name>created</name> <name>created</name>
<t>Type: <tt>UTCDateTime</tt> (optional).</t> <t>Type: <tt>UTCDateTime</tt> (optional)</t>
<t>The date and time when this Card was created.</t> <t>The date and time when the Card was created.</t>
<figure anchor="example-created"> <figure anchor="example-created">
<name><tt>created</tt> example</name> <name><tt>created</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"created": "2022-09-30T14:35:10Z" "created": "2022-09-30T14:35:10Z"
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="kind" numbered="true" toc="default"> <section anchor="kind" numbered="true" toc="default">
<name>kind</name> <name>kind</name>
<t>Type: <tt>String</tt> (optional, default: <tt>individual</tt>). Th <t>Type: <tt>String</tt> (optional; default: <tt>individual</tt>)</t>
e kind of the entity the Card represents.</t> <t>The kind of the entity the Card represents.</t>
<t>The <xref target="enumerated-values">enumerated</xref> values are:< /t> <t>The <xref target="enumerated-values">enumerated</xref> values are:< /t>
<ul spacing="normal"> <ul spacing="normal">
<!--[rfced] In Section 2.1.4 under the definition of "device", we made
the examples singular since "device" is singular. If you prefer
otherwise, please let us know.
Original:
* device: a device, such as appliances, computers, or network
elements
Current:
* device: a device such as an appliance, a computer, or a network
element
-->
<li><tt>individual</tt>: a single person</li> <li><tt>individual</tt>: a single person</li>
<li><tt>group</tt>: a group person of persons or entities</li> <li><tt>group</tt>: a group of people or entities</li>
<li><tt>org</tt>: an organization</li> <li><tt>org</tt>: an organization</li>
<li><tt>location</tt>: a named location</li> <li><tt>location</tt>: a named location</li>
<li><tt>device</tt>: a device, such as appliances, computers, or net work elements</li> <li><tt>device</tt>: a device such as an appliance, a computer, or a network element</li>
<li><tt>application</tt>: a software application</li> <li><tt>application</tt>: a software application</li>
</ul> </ul>
<figure anchor="example-kind"> <figure anchor="example-kind">
<name><tt>kind</tt> example</name> <name><tt>kind</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"kind": "individual" "kind": "individual"
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="language" numbered="true" toc="default"> <section anchor="language" numbered="true" toc="default">
<name>language</name> <name>language</name>
<t>Type: <tt>String</tt> (optional).</t> <t>Type: <tt>String</tt> (optional)</t>
<t>This is the language tag, as defined in <xref target="RFC5646"/>, t <t>This is the language tag, as defined in <xref target="RFC5646"/>, t
hat best describes the language used for text in the Card, optionally including hat best describes the language used for text in the Card, optionally including
additional information such as the script. Note that values <bcp14>MAY</bcp14> additional information such as the script. Note that values <bcp14>MAY</bcp14>
be localized in the <tt>localizations</tt> property <xref target="localizations" be localized in the <xref target="localizations"><tt>localizations</tt></xref>
/>.</t> property.</t>
<figure anchor="example-language"> <figure anchor="example-language">
<name><tt>language</tt> example</name> <name><tt>language</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"language": "de-AT" "language": "de-AT"
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="members" numbered="true" toc="default"> <section anchor="members" numbered="true" toc="default">
<name>members</name> <name>members</name>
<t>Type: <tt>String[Boolean]</tt> (optional).</t> <t>Type: <tt>String[Boolean]</tt> (optional)</t>
<t>This identifies the set of Cards that are members of this group Car <t>This identifies the set of Cards that are members of this group Car
d. Each key in the set is the <tt>uid</tt> property value of the member, each b d. Each key in the set is the <tt>uid</tt> property value of the member, and ea
oolean value <bcp14>MUST</bcp14> be <tt>true</tt>. If this property is set, then ch boolean value <bcp14>MUST</bcp14> be <tt>true</tt>. If this property is set,
the value of the <tt>kind</tt> property <bcp14>MUST</bcp14> be <tt>group</tt>.< then the value of the <tt>kind</tt> property <bcp14>MUST</bcp14> be <tt>group</t
/t> t>.</t>
<t>The opposite is not true. A group Card will usually contain the <t <t>The opposite is not true. A group Card will usually contain the <t
t>members</tt> property to specify the members of the group, but it is not requi t>members</tt> property to specify the members of the group, but it is not requi
red to. A group Card without the <tt>members</tt> property can be considered an red to. A group Card without the <tt>members</tt> property can be considered an
abstract grouping, or one whose members are known empirically (e.g., "IETF Par abstract grouping or one whose members are known empirically (e.g., "IETF Part
ticipants").</t> icipants").</t>
<figure anchor="example-members"> <figure anchor="example-members">
<name><tt>members</tt> example</name> <name><tt>members</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"kind": "group", "kind": "group",
"name": { "name": {
"full": "The Doe family" "full": "The Doe family"
}, },
"uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667", "uid": "urn:uuid:ab4310aa-fa43-11e9-8f0b-362b9e155667",
"members": { "members": {
"urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true, "urn:uuid:03a0e51f-d1aa-4385-8a53-e29025acd8af": true,
"urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true "urn:uuid:b8767877-b4a1-4c70-9acc-505d3819e519": true
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="prodId" numbered="true" toc="default"> <section anchor="prodId" numbered="true" toc="default">
<name>prodId</name> <name>prodId</name>
<t>Type: <tt>String</tt> (optional).</t> <t>Type: <tt>String</tt> (optional)</t>
<t>The identifier for the product that created the Card. If set, the value <bcp14>MUST</bcp14> be at least one character long.</t> <t>The identifier for the product that created the Card. If set, the value <bcp14>MUST</bcp14> be at least one character long.</t>
<figure anchor="example-prodId"> <figure anchor="example-prodId">
<name><tt>prodId</tt> example</name> <name><tt>prodId</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"prodId": "ACME Contacts App version 1.23.5" "prodId": "ACME Contacts App version 1.23.5"
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="relatedTo" numbered="true" toc="default"> <section anchor="relatedTo" numbered="true" toc="default">
<name>relatedTo</name> <name>relatedTo</name>
<t>Type: <tt>String[Relation]</tt> (optional).</t> <t>Type: <tt>String[Relation]</tt> (optional)</t>
<t>Relates the object to other Cards. This is represented as a map, w <t>This relates the object to other Cards. It is represented as a map
here each key is the <tt>uid</tt> of the related Card and the value defines the , where each key is the <tt>uid</tt> of the related Card, and the value defines
relation. The Relation object has the following properties:</t> the relation. The Relation object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Relation</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Relation</tt>, if set.
</li> </dd>
<li> <dt>relation:</dt><dd><t> <tt>String[Boolean]</tt> (optional; defaul
<t>relation: <tt>String[Boolean]</tt> (optional, default: empty Ob t: empty Object). Describes how the linked object is related to the linking obje
ject) ct. The relation is defined as a set of relation types. The key in the set def
Describes how the linked object is related to the linking object ines the relation type; the value for each key in the set <bcp14>MUST</bcp14> be
. The relation is defined as a set of relation types. The key in the set defin <tt>true</tt>. The relationship between the two objects is undefined if the se
es the relation type, the value for each key in the set <bcp14>MUST</bcp14> be < t is empty.</t>
tt>true</tt>. The relationship between the two objects is undefined if the set <t>The initial list of <xref target="enumerated-values">enumerated</
is empty.</t> xref> relation types matches the IANA-registered <xref target="IANA-vCard">TYPE<
<t>The initial list of <xref target="enumerated-values">enumerated /xref> parameter values of the vCard RELATED property (<xref target="RFC6350" se
</xref> relation types matches the IANA-registered <xref target="IANAvCard">TYPE ction="6.6.6"/>):</t>
parameter</xref> values of the vCard RELATED property (<xref target="RFC6350" s
ection="6.6.6"/>):</t> <!--[rfced] In Section 2.1.8, we updated the order of the enumerated
relation types list by moving "co-resident" and "co-worker" above
"colleague". The list is now in alphabetical order. Please let us
know of any objections.
There are several other lists in the document. Please review and let
us know if any other terms should be placed in alphabetical order.
-->
<ul> <ul>
<li> <li>
<tt>acquaintance</tt> <tt>acquaintance</tt>
</li> </li>
<li> <li>
<tt>agent</tt> <tt>agent</tt>
</li> </li>
<li> <li>
<tt>child</tt> <tt>child</tt>
</li> </li>
<li> <li>
<tt>colleague</tt> <tt>co-resident</tt>
</li> </li>
<li> <li>
<tt>contact</tt> <tt>co-worker</tt>
</li> </li>
<li> <li>
<tt>co-resident</tt> <tt>colleague</tt>
</li> </li>
<li> <li>
<tt>co-worker</tt> <tt>contact</tt>
</li> </li>
<li> <li>
<tt>crush</tt> <tt>crush</tt>
</li> </li>
<li> <li>
<tt>date</tt> <tt>date</tt>
</li> </li>
<li> <li>
<tt>emergency</tt> <tt>emergency</tt>
</li> </li>
skipping to change at line 575 skipping to change at line 854
<li> <li>
<tt>sibling</tt> <tt>sibling</tt>
</li> </li>
<li> <li>
<tt>spouse</tt> <tt>spouse</tt>
</li> </li>
<li> <li>
<tt>sweetheart</tt> <tt>sweetheart</tt>
</li> </li>
</ul> </ul>
</li> </dd></dl>
</ul>
<figure anchor="example-relatedto"> <figure anchor="example-relatedto">
<name><tt>relatedTo</tt> example</name> <name><tt>relatedTo</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"relatedTo": { "relatedTo": {
"urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6": { "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6": {
"relation": { "relation": {
"friend": true "friend": true
} }
}, },
"8cacdfb7d1ffdb59@example.com": { "8cacdfb7d1ffdb59@example.com": {
"relation": {} "relation": {}
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="uid" numbered="true" toc="default"> <section anchor="uid" numbered="true" toc="default">
<name>uid</name> <name>uid</name>
<t>Type: <tt>String</tt> (mandatory).</t> <t>Type: <tt>String</tt> (mandatory)</t>
<t>An identifier, used to associate the object as the same across diff <t>An identifier that is used to associate the object as the same acro
erent systems, address books and views. The value <bcp14>SHOULD</bcp14> be a UR ss different systems, address books, and views. The value <bcp14>SHOULD</bcp14>
N <xref target="RFC8141"/> but for compatibility with <xref target="RFC6350"/> i be a URN <xref target="RFC8141"/>, but for compatibility with <xref target="RFC
t <bcp14>MAY</bcp14> also be a URI <xref target="RFC3986"/> or free-text value. 6350"/>, it <bcp14>MAY</bcp14> also be a URI <xref target="RFC3986"/> or free-te
The value of the URN <bcp14>SHOULD</bcp14> be in the <tt>uuid</tt> namespace <x xt value. The value of the URN <bcp14>SHOULD</bcp14> be in the <tt>uuid</tt> na
ref target="RFC4122" format="default"/>. As of this writing, a <xref target="I- mespace <xref target="RFC4122" format="default"/>.
D.ietf-uuidrev-rfc4122bis">revision</xref> of the UUID standard document is bein
g worked on and is likely to introduce new UUID versions and best practices to g <!--[rfced] FYI: For clarity and ease of reading, we added a reference
enerate global unique identifiers. Implementors <bcp14>SHOULD</bcp14> follow an to RFC 4122 as shown below.
y recommendations described there. Until then, implementations <bcp14>SHOULD</b
cp14> generate identifiers using the random or pseudo-random UUID version descri Original:
bed in <xref target="RFC4122" section="4.4"/>.</t> As of this writing, a revision [I-D.ietf-uuidrev-rfc4122bis] of the
UUID standard document is being worked on and is likely to
introduce new UUID versions and best practices to generate global
unique identifiers.
Current:
As of this writing, a revision [UUID] of the Universally Unique
Identifier (UUID) Standards Track document [RFC4122] is in
progress and will likely introduce new UUID versions and
best practices for generating global unique identifiers [UUID].
-->
As of this writing, a <xref target="I-D.ietf-uuidrev-rfc4122bis">revision</xref>
of the Universally Unique Identifier (UUID) Standards Track document <xref targ
et="RFC4122" format="default"/> is in progress and will likely introduce new UUI
D versions and best practices to generate global unique identifiers. Implemento
rs <bcp14>SHOULD</bcp14> follow any recommendations described there. Until then
, implementations <bcp14>SHOULD</bcp14> generate identifiers using the random or
pseudorandom UUID version described in <xref target="RFC4122" section="4.4"/>.<
/t>
<figure anchor="example-uid"> <figure anchor="example-uid">
<name><tt>uid</tt> example</name> <name><tt>uid</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6" "uid": "urn:uuid:f81d4fae-7dec-11d0-a765-00a0c91e6bf6"
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="updated" numbered="true" toc="default"> <section anchor="updated" numbered="true" toc="default">
<name>updated</name> <name>updated</name>
<t>Type: <tt>UTCDateTime</tt> (optional).</t> <t>Type: <tt>UTCDateTime</tt> (optional)</t>
<t>The date and time when the data in this Card was last modified.</t> <t>The date and time when the data in the Card was last modified.</t>
<figure anchor="example-updated"> <figure anchor="example-updated">
<name><tt>updated</tt> example</name> <name><tt>updated</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"updated": "2021-10-31T22:27:10Z" "updated": "2021-10-31T22:27:10Z"
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
<section anchor="name-and-organization-properties" numbered="true" toc="de fault"> <section anchor="name-and-organization-properties" numbered="true" toc="de fault">
<name>Name and Organization Properties</name> <name>Name and Organization Properties</name>
<t>This section defines properties that name the entity represented by t his Card, its related organizations and roles, as well as how to refer the entit y represented by this Card in spoken or written language.</t> <t>This section defines properties that name the entity represented by t he Card and its related organizations and roles. It also describes how to refer to the entity represented by the Card in spoken or written language.</t>
<section anchor="name" numbered="true" toc="default"> <section anchor="name" numbered="true" toc="default">
<name>name</name> <name>name</name>
<t>Type: <tt>Name</tt> (optional).</t> <t>Type: <tt>Name</tt> (optional)</t>
<t>The name of the entity represented by this Card. This can be any t <t>The name of the entity represented by the Card. This can be any ty
ype of name, e.g., it can but need not be the legal name of a person.</t> pe of name, e.g., it can, but need not, be the legal name of a person.</t>
<section> <section>
<name>Name object</name> <name>Name Object</name>
<t>A Name object has the following properties</t> <t>A Name object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Name</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Name</tt>, if set.
</li> </dd>
<li> <dt>components:</dt><dd><t> <tt>NameComponent[]</tt> (optional).
<t>components: <tt>NameComponent[]</tt> (optional). The <xref t The <xref target="namecomponent">components</xref> making up this name. This pr
arget="namecomponent">components</xref> making up this name. This property <bcp operty <bcp14>MUST</bcp14> be set if the <tt>full</tt> property is not set; othe
14>MUST</bcp14> be set if the <tt>full</tt> property is not set, otherwise it <b rwise, it <bcp14>SHOULD</bcp14> be set. The component list <bcp14>MUST</bcp14>
cp14>SHOULD</bcp14> be set. The component list <bcp14>MUST</bcp14> have at leas have at least one entry having a different <tt>kind</tt> than <tt>separator</tt>
t one entry having a different <tt>kind</tt> than <tt>separator</tt>.</t> .</t>
<t>Name components <bcp14>SHOULD</bcp14> be ordered such that th <t>Name components <bcp14>SHOULD</bcp14> be ordered such that wh
eir values joined as a String produce a valid full name of this entity. If so, en their values are joined as a String, a valid full name of the entity is produ
implementations <bcp14>MUST</bcp14> set the <tt>isOrdered</tt> property value to ced. If so, implementations <bcp14>MUST</bcp14> set the <tt>isOrdered</tt> prop
<tt>true</tt>.</t> erty value to <tt>true</tt>.</t>
<t>If the name components are ordered, then the <tt>defaultSepar <t>If the name components are ordered, then the <tt>defaultSepar
ator</tt> property and name components of kind <tt>separator</tt> give guidance ator</tt> property and name components of kind <tt>separator</tt> give guidance
on what characters to insert between components, but implementations are free to on what characters to insert between components, but implementations are free to
choose any others. In lack of a separator, inserting a single Space character choose any others. When lacking a separator, inserting a single space characte
in between name component values is a good choice.</t> r in between the name component values is a good choice.</t>
<t>If instead the name components follow no particular order, th <t>If, instead, the name components follow no particular order,
en the <tt>isOrdered</tt> property value <bcp14>MUST</bcp14> be <tt>false</tt>, then the <tt>isOrdered</tt> property value <bcp14>MUST</bcp14> be <tt>false</tt>
the <tt>components</tt> property <bcp14>MUST NOT</bcp14> contain a NameComponent , the <tt>components</tt> property <bcp14>MUST NOT</bcp14> contain a NameCompone
of kind <tt>separator</tt> and the <tt>defaultSeparator</tt> property <bcp14>MU nt of kind <tt>separator</tt>, and the <tt>defaultSeparator</tt> property <bcp14
ST NOT</bcp14> be set.</t> >MUST NOT</bcp14> be set.</t>
<t><xref target="example-name-twoword"/> is an example for the n <t><xref target="example-name-twoword"/> shows an example for th
ame "Vincent van Gogh". Note how a single name component value may consist of m e name "Vincent van Gogh". Note how a single name component value may consist o
ultiple words. <xref target="example-name-surname2"/> illustrates a name with a f multiple words.</t>
second surname, such as a Spanish name. Additional examples are shown in <xref
target="example-name-sortas"/> and <xref target="example-localizations-replace"
/>.</t>
<figure anchor="example-name-twoword"> <figure anchor="example-name-twoword">
<name>Example for a surname with two words</name> <name>Example of a Surname with Two Words</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"name": { "name": {
"components": [ "components": [
{ "kind": "given", "value": "Vincent" }, { "kind": "given", "value": "Vincent" },
{ "kind": "surname", "value": "van Gogh" } { "kind": "surname", "value": "van Gogh" }
], ],
"isOrdered": true "isOrdered": true
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
<figure anchor="example-name-surname2">
<name>Example for a second surname</name> <!--[rfced] FYI: The text that describes Figure 16 was located above
Figure 15, so we placed it above Figure 16 instead. The update is
shown in Section 2.2.1.1.
-->
<t>
<xref target="example-name-surname2"/> illustrates a name with a second surname
such as a Spanish name. Additional examples are shown in Figures <xref target="
example-name-sortas" format="counter"/> and <xref target="example-localizations-
replace" format="counter"/>.</t>
<figure anchor="example-name-surname2">
<name>Example of a Second Surname</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"name": { "name": {
"components": [ "components": [
{ "kind": "given", "value": "Diego" }, { "kind": "given", "value": "Diego" },
{ "kind": "surname", "value": "Rivera" }, { "kind": "surname", "value": "Rivera" },
{ "kind": "surname2", "value": "Barrientos" } { "kind": "surname2", "value": "Barrientos" }
], ],
"isOrdered": true "isOrdered": true
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</li> </dd>
<li>isOrdered: <tt>Boolean</tt> (optional, default: <tt>false</tt> <dt>isOrdered:</dt><dd> <tt>Boolean</tt> (optional; default: <tt>f
). This indicates if the name component sequence in the <tt>components</tt> pro alse</tt>). Indicates if the name component sequence in the <tt>components</tt>
perty is ordered.</li> property is ordered.</dd>
<li>defaultSeparator: <tt>String</tt> (optional). <dt>defaultSeparator:</dt><dd> <tt>String</tt> (optional).
The default separator to insert between name component values wh The default separator to insert between name component values when
en concatenating all name component values to a single String. Also see the def concatenating all name component values to a single String.
inition of the <tt>separator</tt> kind for the NameComponent object. This prope
rty <bcp14>MUST NOT</bcp14> be set if the Name <tt>isOrdered</tt> property value <!--[rfced] FYI: For ease, we added links to Sections 2.2.1.2
is <tt>false</tt> or if the <tt>components</tt> property is not set.</li> (NameComponent) and 2.5.1.2 (AddressComponent) in the text
<li> shown below. If any further updates are needed, please let us
<t>full: <tt>String</tt> (optional). know.
This is the full name representation of this Name. This property <b
cp14>MUST</bcp14> be set if the <tt>components</tt> property is not set.</t> Section 2.2.1.1
Original:
Also see the definition of the separator kind for
the NameComponent object.
Current:
Also see the definition of the separator kind for
the NameComponent (Section 2.2.1.2) object.
...
Section 2.5.1.1
Original:
Also see the definition of the separator kind
for the AddressComponent object.
Current:
Also see the definition of the separator kind
for the AddressComponent (Section 2.5.1.2) object.
-->
Also see the definition of the <tt>separator</tt> kind for the <xre
f target="namecomponent">NameComponent</xref> object. This property <bcp14>MUST
NOT</bcp14> be set if the Name <tt>isOrdered</tt> property value is <tt>false</
tt> or if the <tt>components</tt> property is not set.</dd>
<dt>full:</dt><dd><t><tt>String</tt> (optional).
The full name representation of the Name. This property <bcp14>MUST
</bcp14> be set if the <tt>components</tt> property is not set.</t>
<figure anchor="example-full"> <figure anchor="example-full">
<name><tt>full</tt> example</name> <name><tt>full</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"full": "Mr. John Q. Public, Esq." "full": "Mr. John Q. Public, Esq."
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</li> </dd>
<li> <dt>
<t>sortAs: <tt>String[String]</tt> (optional).</t> sortAs:</dt><dd><t> <tt>String[String]</tt> (optional). Defines
<t>This defines how this name lexicographically sorts in relatio how the name lexicographically sorts in relation to other names when compared by
n to other names when compared by a name component type. The key in the map def a name component type. The key in the map defines the name component type. Th
ines the name component type. The value for that key defines the verbatim strin e value for that key defines the verbatim string to compare when sorting by the
g to compare when sorting by this name component type. Absence of a key indicat name component type. Absence of a key indicates that the name component type <b
es that this name component type <bcp14>SHOULD NOT</bcp14> be considered during cp14>SHOULD NOT</bcp14> be considered during sort. Sorting by that missing name
sort. Sorting by that missing name component type or if the <tt>sortAs</tt> pro component type, or if the <tt>sortAs</tt> property is not set, is implementatio
perty is not set is implementation-specific. This property <bcp14>MUST NOT</bcp n-specific. This property <bcp14>MUST NOT</bcp14> be set if the <tt>components<
14> be set if the <tt>components</tt> property is not set.</t> /tt> property is not set.</t>
<t>Each key in the map <bcp14>MUST</bcp14> be a valid name compo <t>Each key in the map <bcp14>MUST</bcp14> be a valid name compo
nent type value as defined for the <tt>kind</tt> property of the NameComponent o nent type value as defined for the <tt>kind</tt> property of the NameComponent o
bject (see below). For each key in the map there <bcp14>MUST</bcp14> exist at l bject (see below). For each key in the map, there <bcp14>MUST</bcp14> exist at
east one NameComponent object having that type in the <tt>components</tt> proper least one NameComponent object that has the type in the <tt>components</tt> prop
ty of this name.</t> erty of the name.</t>
<t><xref target="example-name-sortas"/> illustrates the use of s <t><xref target="example-name-sortas"/> illustrates the use of s
ortAs. The property value indicates that the middle name followed by both surna ortAs. The property value indicates that the middle name followed by both surna
mes should be used when sorting this name by surname. The absence of the <tt>mi mes should be used when sorting the name by surname. The absence of <tt>middle<
ddle</tt> indicates that the middle name on its own should be disregarded during /tt> indicates that the middle name on its own should be disregarded during sort
sort. Even though the name only contains one name component for the given name . Even though the name only contains one name component for the given name, the
, the sortAs property still explicitly defines how to sort by given name as othe sortAs property still explicitly defines how to sort by the given name; otherwi
rwise sorting by it would be undefined.</t> se, sorting by it would be undefined.</t>
</li> </dd>
<li> <dt>
<t>phoneticScript: <tt>String</tt> (optional). phoneticScript:</dt><dd> <tt>String</tt> (optional).
The script used in the value of the NameComponent <tt>phonetic</ The script used in the value of the NameComponent <tt>phonetic</
tt> property. Also see <xref target="prop-phonetic"/>. See <xref target="examp tt> property. See <xref target="prop-phonetic"/> for more information and <xref
le-name-phonetic"/> for an example.</t> target="example-name-phonetic"/> for an example.</dd>
</li> <dt>
<li> phoneticSystem:</dt><dd><t> <tt>String</tt> (optional).
<t>phoneticSystem: <tt>String</tt> (optional). The phonetic system used in the NameComponent <tt>phonetic</tt> pr
The phonetic system used in the NameComponent <tt>phonetic</tt> pr operty. See <xref target="prop-phonetic"/> for more information and <xref targe
operty. Also see <xref target="prop-phonetic"/>. See <xref target="exampl t="example-name-phonetic"/> for an example.</t>
e-name-phonetic"/> for an example.</t> </dd>
</li> </dl>
</ul>
<figure anchor="example-name-sortas"> <figure anchor="example-name-sortas">
<name>Example for <tt>sortAs</tt></name> <name><tt>sortAs</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"name": { "name": {
"components": [ "components": [
{ "kind": "given", "value": "Robert" }, { "kind": "given", "value": "Robert" },
{ "kind": "given2", "value": "Pau" }, { "kind": "given2", "value": "Pau" },
{ "kind": "surname", "value": "Shou Chang" } { "kind": "surname", "value": "Shou Chang" }
], ],
"sortAs": { "sortAs": {
"surname": "Pau Shou Chang", "surname": "Pau Shou Chang",
"given": "Robert" "given": "Robert"
}, },
"isOrdered": true "isOrdered": true
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
<figure anchor="example-name-phonetic"> <figure anchor="example-name-phonetic">
<name>Example for <tt>phonetic</tt> and <tt>localizations</tt></name <name><tt>phonetic</tt> and <tt>localizations</tt> Example</name>
> <sourcecode type=""><![CDATA[
<artwork><![CDATA[
{ {
"@type": "Card", "@type": "Card",
"language": "zh-Hant", "language": "zh-Hant",
"name": { "name": {
"components": [ "components": [
{ "kind": "surname", "value": "孫" }, { "kind": "surname", "value": "孫" },
{ "kind": "given", "value": "中山" }, { "kind": "given", "value": "中山" },
{ "kind": "given2", "value": "文" }, { "kind": "given2", "value": "文" },
{ "kind": "given2", "value": "逸仙" } { "kind": "given2", "value": "逸仙" }
] ]
skipping to change at line 734 skipping to change at line 1059
"yue": { "yue": {
"name/phoneticSystem": "jyut", "name/phoneticSystem": "jyut",
"name/phoneticScript": "Latn", "name/phoneticScript": "Latn",
"name/components/0/phonetic": "syun1", "name/components/0/phonetic": "syun1",
"name/components/1/phonetic": "zung1saan1", "name/components/1/phonetic": "zung1saan1",
"name/components/2/phonetic": "man4", "name/components/2/phonetic": "man4",
"name/components/3/phonetic": "jat6sin1" "name/components/3/phonetic": "jat6sin1"
} }
} }
} }
]]></artwork> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="namecomponent"> <section anchor="namecomponent">
<name>NameComponent</name> <name>NameComponent</name>
<t>A NameComponent object has the following properties:</t> <t>A NameComponent object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>NameComponent</tt>, if set. This <bcp14>MUST</bcp14> be <tt>NameComponent</tt>, if set.
</li> </dd>
<li>value: <tt>String</tt> (mandatory). <dt>value:</dt><dd> <tt>String</tt> (mandatory).
The value of this name component. This can be composed of one or multiple words The value of the name component. This can be composed of one or multiple words
, such as "Poe" or "van Gogh".</li> such as "Poe" or "van Gogh".</dd>
<li> <dt>kind:</dt><dd><t> <tt>String</tt> (mandatory).
<t>kind: <tt>String</tt> (mandatory). The kind of the name component. The <xref target="enumerated-valu
The kind of this name component. The <xref target="enumerated-val es">enumerated</xref> values are:
ues">enumerated</xref> values are:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li><tt>title</tt>: an honorific title or prefix, e.g., "Mr", <li><tt>title</tt>: an honorific title or prefix, e.g., "Mr.",
"Ms", "Dr".</li> "Ms.", or "Dr.".</li>
<li><tt>given</tt>: a given name, also known as "first name", <li><tt>given</tt>: a given name, also known as "first name" o
"personal name".</li> r "personal name".</li>
<li><tt>given2</tt>: a name that appears between the given and <li><tt>given2</tt>: a name that appears between the given and
surname, such as a middle name or patronymic name.</li> surname such as a middle name or patronymic name.</li>
<li><tt>surname</tt>: a surname, also known as "last name", "f <li><tt>surname</tt>: a surname, also known as "last name" or
amily name".</li> "family name".</li>
<li><tt>surname2</tt>: a secondary surname (used in some cultu res), also known as "maternal surname".</li> <li><tt>surname2</tt>: a secondary surname (used in some cultu res), also known as "maternal surname".</li>
<li><tt>credential</tt>: a credential, also known as "accredi tation qualifier" or "honorific suffix", e.g., "B.A.", "Esq.".</li> <li><tt>credential</tt>: a credential, also known as "accredi tation qualifier" or "honorific suffix", e.g., "B.A.", "Esq.".</li>
<li><tt>generation</tt>: a generation marker or qualifier, e.g <li><tt>generation</tt>: a generation marker or qualifier, e.g
., “Jr.” or “III”.</li> ., "Jr." or "III".</li>
<li><tt>separator</tt>: a formatting separator between two ord <li><tt>separator</tt>: a formatting separator between two ord
ered name non-separator components. The <tt>value</tt> property of the componen ered name non-separator components. The <tt>value</tt> property of the componen
t includes the verbatim separator, for example a hyphen character or even an emp t includes the verbatim separator, for example, a hyphen character or even an em
ty string. This value has higher precedence than the <tt>defaultSeparator</tt> pty string. This value has higher precedence than the <tt>defaultSeparator</tt>
property of the Name. Implementations <bcp14>MUST NOT</bcp14> insert two consec property of the Name. Implementations <bcp14>MUST NOT</bcp14> insert two conse
utive separator components, instead they <bcp14>SHOULD</bcp14> insert a single s cutive separator components; instead, they <bcp14>SHOULD</bcp14> insert a single
eparator component with the combined value. This component kind <bcp14>MUST NOT separator component with the combined value. This component kind <bcp14>MUST N
</bcp14> be set if the Name <tt>isOrdered</tt> property value is <tt>false</tt>. OT</bcp14> be set if the Name <tt>isOrdered</tt> property value is <tt>false</tt
</li> >.</li>
</ul> </ul>
</li> </dd>
<li>phonetic: <tt>String</tt> (optional). This defines how to pro <dt>phonetic:</dt><dd> <tt>String</tt> (optional). Defines how to
nounce this name component. If this property is set, then at least one of the N pronounce the name component. If this property is set, then at least one of th
ame object <tt>phoneticSystem</tt> or <tt>phoneticScript</tt> properties <bcp14> e Name object properties, <tt>phoneticSystem</tt> or <tt>phoneticScript</tt>, <b
MUST</bcp14> be set. Also see <xref target="prop-phonetic"/>.</li> cp14>MUST</bcp14> be set. Also see <xref target="prop-phonetic"/>.</dd>
</ul> </dl>
</section> </section>
<section anchor="nicknames" numbered="true" toc="default"> <section anchor="nicknames" numbered="true" toc="default">
<name>nicknames</name> <name>nicknames</name>
<t>Type: <tt>Id[Nickname]</tt> (optional).</t> <t>Type: <tt>Id[Nickname]</tt> (optional)</t>
<t>The nicknames of the entity represented by this Card. A Nickname <t>The nicknames of the entity represented by the Card. A Nickname
object has the following properties:</t> object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Nickname</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Nickname</tt>, if set.
</li> </dd>
<li>name: <tt>String</tt> (mandatory). <dt>name:</dt><dd> <tt>String</tt> (mandatory).
The nickname. The nickname.
</li> </dd>
<li>contexts: <tt>String[Boolean]</tt> (optional) <dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
The contexts in which to use this nickname. Also see <xref target="prop-context The contexts in which to use the nickname. Also see <xref target="prop-contexts
s"/>.</li> "/>.</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
The preference of this nickname in relation to other nicknames. Als The preference of the nickname in relation to other nicknames. Also
o see <xref target="prop-pref"/>.</li> see <xref target="prop-pref"/>.</dd>
</ul> </dl>
<figure anchor="example-nicknames"> <figure anchor="example-nicknames">
<name><tt>nicknames</tt> example</name> <name><tt>nicknames</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"nicknames": { "nicknames": {
"k391": { "k391": {
"name": "Johnny" "name": "Johnny"
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
<section anchor="organizations" numbered="true" toc="default"> <section anchor="organizations" numbered="true" toc="default">
<name>organizations</name> <name>organizations</name>
<t>Type: <tt>Id[Organization]</tt> (optional).</t> <t>Type: <tt>Id[Organization]</tt> (optional)</t>
<t>The companies or organizations names and units associated with this <t>The company or organization names and units associated with the Car
Card. An Organization object has the following properties, of which at least o d. An Organization object has the following properties, of which at least one o
ne of the <tt>name</tt> and <tt>units</tt> properties <bcp14>MUST</bcp14> be set f the <tt>name</tt> and <tt>units</tt> properties <bcp14>MUST</bcp14> be set:</t
:</t> >
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Organization</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Organization</tt>, if set.
</li> </dd>
<li>name: <tt>String</tt> (optional). <dt>name:</dt><dd> <tt>String</tt> (optional).
The name of this organization. The name of the organization.
</li> </dd>
<li>units: <tt>OrgUnit[]</tt> (optional). <dt>units:</dt><dd> <tt>OrgUnit[]</tt> (optional).
A list of organizational units, ordered descending by hierarchy (e.g A list of organizational units, ordered as descending by hierarchy (
., a geographic or functional division sorts before a department within that div e.g., a geographic or functional division sorts before a department within that
ision). If set, the list <bcp14>MUST</bcp14> contain at least one entry. division). If set, the list <bcp14>MUST</bcp14> contain at least one entry.
</li> </dd>
<li>sortAs: <tt>String</tt> (optional). <dt>sortAs:</dt><dd> <tt>String</tt> (optional).
This defines how this organization name lexicographically sorts in r Defines how the organization name lexicographically sorts in relatio
elation to other organizations when compared by name. The value defines the ver n to other organizations when compared by the name. The value defines the verba
batim string value to compare. In absence of this property, the <tt>name</tt> p tim string value to compare. In absence of this property, the <tt>name</tt> pro
roperty value <bcp14>MAY</bcp14> be used for comparison. perty value <bcp14>MAY</bcp14> be used for comparison.
</li> </dd>
<li>contexts: <tt>String[Boolean]</tt> (optional). <dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
The contexts in which association with this organization apply. For example, me The contexts in which association with the organization apply. For example, mem
mbership in a choir may only apply in a private context. Also see <xref target= bership in a choir may only apply in a private context. Also see <xref target="
"prop-contexts"/>.</li> prop-contexts"/>.</dd>
</ul> </dl>
<t>A OrgUnit object has the following properties:</t> <t>An OrgUnit object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>OrgUnit</tt>, if set. This <bcp14>MUST</bcp14> be <tt>OrgUnit</tt>, if set.
</li> </dd>
<li>name: <tt>String</tt> (mandatory). <dt>name:</dt><dd> <tt>String</tt> (mandatory).
The name of this organizational unit. The name of the organizational unit.
</li> </dd>
<li>sortAs: <tt>String</tt> (optional). <dt>sortAs:</dt><dd> <tt>String</tt> (optional).
This defines how this organization unit name lexicographically sorts Defines how the organization unit name lexicographically sorts in re
in relation to other organizational units of the same level when compared by na lation to other organizational units of the same level when compared by the name
me. The level is defined by the array index of this organizational unit in the . The level is defined by the array index of the organizational unit in the <tt
<tt>units</tt> property of the Organization object. The property value defines >units</tt> property of the Organization object. The property value defines the
the verbatim string value to compare. In absence of this property, the <tt>name verbatim string value to compare. In absence of this property, the <tt>name</t
</tt> property value <bcp14>MAY</bcp14> be used for comparison. t> property value <bcp14>MAY</bcp14> be used for comparison.
</li> </dd>
</ul> </dl>
<figure anchor="example-organizations"> <figure anchor="example-organizations">
<name><tt>organizations</tt> example</name> <name><tt>organizations</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"organizations": { "organizations": {
"o1": { "o1": {
"name": "ABC, Inc.", "name": "ABC, Inc.",
"units": [ "units": [
{ "name": "North American Division" }, { "name": "North American Division" },
{ "name": "Marketing" } { "name": "Marketing" }
], ],
"sortAs": "ABC" "sortAs": "ABC"
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="speakToAs" numbered="true" toc="default"> <section anchor="speakToAs" numbered="true" toc="default">
<name>speakToAs</name> <name>speakToAs</name>
<t>Type: <tt>SpeakToAs</tt> (optional).</t> <t>Type: <tt>SpeakToAs</tt> (optional)</t>
<t>Provides information how to address, speak to or refer to the entit <t>Provides information on how to address, speak to, or refer to the e
y that is represented by this Card. A SpeakToAs object has the following proper ntity that is represented by the Card. A SpeakToAs object has the following pro
ties, of which at least one of the <tt>grammaticalGender</tt> and <tt>pronouns</ perties, of which at least one of the <tt>grammaticalGender</tt> and <tt>pronoun
tt> properties <bcp14>MUST</bcp14> be set:</t> s</tt> properties <bcp14>MUST</bcp14> be set:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>SpeakToAs</tt>, if set. This <bcp14>MUST</bcp14> be <tt>SpeakToAs</tt>, if set.
</li> </dd>
<li> <dt>
<t>grammaticalGender: <tt>String</tt> (optional). grammaticalGender:</dt><dd><t> <tt>String</tt> (optional).
Defines which grammatical gender to use in salutations and other g rammatical constructs. Defines which grammatical gender to use in salutations and other g rammatical constructs.
For example, the German language distinguishes by grammatical gend er in salutations such as "Sehr geehrte" (feminine) and "Sehr geehrter" (masculi ne). For example, the German language distinguishes by grammatical gend er in salutations such as "Sehr geehrte" (feminine) and "Sehr geehrter" (masculi ne).
The <xref target="enumerated-values">enumerated</xref> values are: </t> The <xref target="enumerated-values">enumerated</xref> values are: </t>
<ul spacing="normal"> <ul spacing="compact">
<li> <li>
<tt>animate</tt> <tt>animate</tt>
</li> </li>
<li> <li>
<tt>common</tt> <tt>common</tt>
</li> </li>
<li> <li>
<tt>feminine</tt> <tt>feminine</tt>
</li> </li>
<li> <li>
<tt>inanimate</tt> <tt>inanimate</tt>
</li> </li>
<li> <li>
<tt>masculine</tt> <tt>masculine</tt>
</li> </li>
<li> <li>
<tt>neuter</tt> <tt>neuter</tt>
</li> </li>
</ul> </ul>
<t>Note that the grammatical gender does not allow inferring the g ender identities or assigned sex of the contact.</t> <t>Note that the grammatical gender does not allow inferring the g ender identities or assigned sex of the contact.</t>
</li> </dd>
<li> <dt>pronouns:</dt><dd><t> <tt>Id[Pronouns]</tt> (optional).
<t>pronouns: <tt>Id[Pronouns]</tt> (optional).
Defines the pronouns that the contact chooses to use for themselves .</t> Defines the pronouns that the contact chooses to use for themselves .</t>
</li> </dd>
</ul> </dl>
<t>A Pronouns object has the following properties:</t> <t>A Pronouns object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Pronouns</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Pronouns</tt>, if set.
</li> </dd>
<li>pronouns: <tt>String</tt> (mandatory). <dt>pronouns:</dt><dd> <tt>String</tt> (mandatory).
Defines the pronouns. Any value or form is allowed. Examples in Defines the pronouns. Any value or form is allowed. Examples in
English include <tt>she/her</tt> and <tt>they/them/theirs</tt>. The value <bcp1 English include <tt>she/her</tt> and <tt>they/them/theirs</tt>. The value <bcp1
4>MAY</bcp14> be overridden in the <tt>localizations</tt> property (<xref target 4>MAY</bcp14> be overridden in the <xref target="localizations"><tt>localization
="localizations"/>).</li> s</tt></xref> property.</dd>
<li>contexts: <tt>String[Boolean]</tt> (optional). <dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
The contexts in which to use these pronouns. Also see <xref target="prop-contex The contexts in which to use the pronouns. Also see <xref target="prop-contexts
ts"/>.</li> "/>.</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
The preference of these pronouns in relation to other pronouns in th The preference of the pronouns in relation to other pronouns in the
e same context. Also see <xref target="prop-pref"/>.</li> same context. Also see <xref target="prop-pref"/>.</dd>
</ul> </dl>
<figure anchor="example-speakToAs"> <figure anchor="example-speakToAs">
<name><tt>speakToAs</tt> example</name> <name><tt>speakToAs</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"speakToAs": { "speakToAs": {
"grammaticalGender": "neuter", "grammaticalGender": "neuter",
"pronouns": { "pronouns": {
"k19": { "k19": {
"pronouns": "they/them", "pronouns": "they/them",
"pref": 2 "pref": 2
}, },
"k32": { "k32": {
"pronouns": "xe/xir", "pronouns": "xe/xir",
"pref": 1 "pref": 1
} }
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="titles" numbered="true" toc="default"> <section anchor="titles" numbered="true" toc="default">
<name>titles</name> <name>titles</name>
<t>Type : <tt>Id[Title]</tt> (optional).</t> <t>Type: <tt>Id[Title]</tt> (optional)</t>
<t>The job titles or functional positions of the entity represented by <t>The job titles or functional positions of the entity represented by
this Card. A Title object has the following properties:</t> the Card. A Title object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Title</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Title</tt>, if set.
</li> </dd>
<li>name: <tt>String</tt> (mandatory). <dt>name:</dt><dd> <tt>String</tt> (mandatory).
The title or role name of the entity represented by this Card. The title or role name of the entity represented by the Card.
</li> </dd>
<li> <dt>kind:</dt><dd><t> <tt>String</tt> (optional; default: <tt>title<
<t>kind: <tt>String</tt> (optional, default <tt>title</tt>). /tt>).
Describes the organizational or situational kind of this title. Some Describes the organizational or situational kind of the title. Some o
organizations and individuals distinguish between <em>titles</em> as organizatio rganizations and individuals distinguish between <em>titles</em> as organization
nal positions and <em>roles</em> as more temporary assignments, such as in proje al positions and <em>roles</em> as more temporary assignments such as in project
ct management.</t> management.</t>
<t>The <xref target="enumerated-values">enumerated</xref> values a re:</t> <t>The <xref target="enumerated-values">enumerated</xref> values a re:</t>
<ul> <ul spacing ="compact">
<li> <li> <tt>title</tt></li>
<tt>title</tt> <li><tt>role</tt> </li>
</li>
<li>
<tt>role</tt>
</li>
</ul> </ul>
</li> </dd>
<li>organizationId: <tt>Id</tt> (optional). <dt>organizationId:</dt><dd> <tt>Id</tt> (optional).
The identifier of the organization in which this title is held. The identifier of the organization in which this title is held.
</li> </dd>
</ul> </dl>
<figure anchor="example-titles"> <figure anchor="example-titles">
<name><tt>titles</tt> example</name> <name><tt>titles</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"titles": { "titles": {
"le9": { "le9": {
"kind": "title", "kind": "title",
"name": "Research Scientist" "name": "Research Scientist"
}, },
"k2": { "k2": {
"kind": "role", "kind": "role",
"name": "Project Leader", "name": "Project Leader",
"organizationId": "o2" "organizationId": "o2"
skipping to change at line 964 skipping to change at line 1282
"o2": { "o2": {
"name": "ABC, Inc." "name": "ABC, Inc."
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
<section anchor="contact-properties" numbered="true" toc="default"> <section anchor="contact-properties" numbered="true" toc="default">
<name>Contact Properties</name> <name>Contact Properties</name>
<t>This section defines properties how to contact the entity represented by this Card.</t> <t>This section defines how properties contact the entity represented by the Card.</t>
<section anchor="emails" numbered="true" toc="default"> <section anchor="emails" numbered="true" toc="default">
<name>emails</name> <name>emails</name>
<t>Type: <tt>Id[EmailAddress]</tt> (optional).</t> <t>Type: <tt>Id[EmailAddress]</tt> (optional)</t>
<t>The email addresses to contact the entity represented by this Card. <t>The email addresses in which to contact the entity represented by t
An EmailAddress object has the following properties:</t> he Card. An EmailAddress object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>EmailAddress</tt>, if set. This <bcp14>MUST</bcp14> be <tt>EmailAddress</tt>, if set.
</li> </dd>
<li>address: <tt>String</tt> (mandatory). <dt>address:</dt><dd> <tt>String</tt> (mandatory).
The email address. This <bcp14>MUST</bcp14> be an <em>addr-spec</em> value as d The email address. This <bcp14>MUST</bcp14> be an <em>addr-spec</em> value as d
efined in Section 3.4.1 of <xref target="RFC5322" format="default"/>.</li> efined in <xref target="RFC5322" sectionFormat="of" section="3.4.1"/>.</dd>
<li>contexts: <tt>String[Boolean]</tt> (optional). <dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
The contexts in which to use this email address. Also see <xref target="prop-co The contexts in which to use this email address. Also see <xref target="prop-co
ntexts"/>.</li> ntexts"/>.</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
The preference of this email address in relation to other email addr The preference of the email address in relation to other email addre
esses. Also see <xref target="prop-pref"/>.</li> sses. Also see <xref target="prop-pref"/>.</dd>
<li>label: <tt>String</tt> (optional). <dt>label:</dt><dd> <tt>String</tt> (optional).
A custom label for the value, see <xref target="prop-label"/>.</li> A custom label for the value. Also see <xref target="prop-label"/>.<
</ul> /dd>
</dl>
<figure anchor="example-emails"> <figure anchor="example-emails">
<name><tt>emails</tt> example</name> <name><tt>emails</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"emails": { "emails": {
"e1": { "e1": {
"contexts": { "contexts": {
"work": true "work": true
}, },
"address": "jqpublic@xyz.example.com" "address": "jqpublic@xyz.example.com"
}, },
"e2": { "e2": {
"address": "jane_doe@example.com", "address": "jane_doe@example.com",
"pref": 1 "pref": 1
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="onlineServices" numbered="true" toc="default"> <section anchor="onlineServices" numbered="true" toc="default">
<name>onlineServices</name> <name>onlineServices</name>
<t>Type: <tt>Id[OnlineService]</tt> (optional).</t> <t>Type: <tt>Id[OnlineService]</tt> (optional)</t>
<t>The online services that are associated with the entity represented <t>The online services that are associated with the entity represented
by this Card. This can be messaging services, social media profiles, and other by the Card. This can be messaging services, social media profiles, and other.
. An OnlineService object has the following properties, of which at least the < An OnlineService object has the following properties, of which at least the <t
tt>uri</tt> or <tt>user</tt> property <bcp14>MUST</bcp14> be set:</t> t>uri</tt> or <tt>user</tt> property <bcp14>MUST</bcp14> be set:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>OnlineService</tt>, if set. This <bcp14>MUST</bcp14> be <tt>OnlineService</tt>, if set.
</li> </dd>
<li>service: <tt>String</tt> (optional). <dt>service:</dt><dd> <tt>String</tt> (optional).
The name of the online service or protocol. The name <bcp14>MAY</ The name of the online service or protocol. The name <bcp14>MAY</
bcp14> be capitalized the same as on the service's website, app or publishing ma bcp14> be capitalized the same as on the service's website, app, or publishing m
terial, but names <bcp14>MUST</bcp14> be considered equal is they match case-ins aterial, but names <bcp14>MUST</bcp14> be considered equal if they match case-in
ensitively. Examples are <tt>GitHub</tt>, <tt>kakao</tt>, <tt>Mastodon</tt>.</l sensitively. Examples are <tt>GitHub</tt>, <tt>Kakao</tt>, and <tt>Mastodon</tt
i> >.</dd>
<li>uri: <tt>String</tt> (optional). <dt>uri:</dt><dd> <tt>String</tt> (optional).
This identifies the entity represented by this card at the online service. This Identifies the entity represented by the Card at the online service. This <bcp1
<bcp14>MUST</bcp14> be a <em>URI</em> as defined in Section 3 of <xref target=" 4>MUST</bcp14> be a <em>URI</em> as defined in <xref target="RFC3986" sectionFor
RFC3986" format="default"/>.</li> mat="of" section="3"/>.</dd>
<li>user: <tt>String</tt> (optional). <dt>user:</dt><dd> <tt>String</tt> (optional).
This names the entity represented by this Card at the online servi Names the entity represented by the Card at the online service. A
ce. Any free-text value is allowed. The <tt>service</tt> property <bcp14>SHOUL ny free-text value is allowed. The <tt>service</tt> property <bcp14>SHOULD</bcp
D</bcp14> be set.</li> 14> be set.</dd>
<li>contexts: <tt>String[Boolean]</tt> (optional). <dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
The contexts in which to use this service. Also see <xref target="prop-contexts The contexts in which to use the service. Also see <xref target="prop-contexts"
"/>.</li> />.</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
The preference of this service in relation to other services. Also The preference of the service in relation to other services. Also s
see <xref target="prop-pref"/>.</li> ee <xref target="prop-pref"/>.</dd>
<li>label: <tt>String</tt> (optional). <dt>label:</dt><dd> <tt>String</tt> (optional).
A custom label for the value, see <xref target="prop-label"/>.</li> A custom label for the value. Also see <xref target="prop-label"/>.<
</ul> /dd>
</dl>
<figure anchor="example-onlineServices"> <figure anchor="example-onlineServices">
<name><tt>onlineServices</tt> example</name> <name><tt>onlineServices</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"onlineServices": { "onlineServices": {
"x1": { "x1": {
"uri": "xmpp:alice@example.com" "uri": "xmpp:alice@example.com"
}, },
"x2": { "x2": {
"service": "Mastodon", "service": "Mastodon",
"user": "@alice@example2.com", "user": "@alice@example2.com",
"uri": "https://example2.com/@alice" "uri": "https://example2.com/@alice"
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="phones" numbered="true" toc="default"> <section anchor="phones" numbered="true" toc="default">
<name>phones</name> <name>phones</name>
<t>Type: <tt>Id[Phone]</tt> (optional).</t> <t>Type: <tt>Id[Phone]</tt> (optional)</t>
<t>The phone numbers to contact the entity represented by this Card. <t>The phone numbers in which to contact the entity represented by the
A Phone object has the following properties:</t> Card. A Phone object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Phone</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Phone</tt>, if set.
</li> </dd>
<li>number: <tt>String</tt> (mandatory). <dt>number:</dt><dd> <tt>String</tt> (mandatory).
The phone number, as either a URI or free-text. Typical URI schemes are the <xr The phone number as either a URI or free text. Typical URI schemes are <tt>tel<
ef target="RFC3966" format="default"/> <tt>tel</tt> or <xref target="RFC3261" fo /tt> <xref target="RFC3966" format="default"/> or <tt>sip</tt> <xref target="RFC
rmat="default"/> <tt>sip</tt> schemes, but any URI scheme is allowed.</li> 3261" format="default"/>, but any URI scheme is allowed.</dd>
<li> <dt>features:</dt><dd><t> <tt>String[Boolean]</tt> (optional).
<t>features: <tt>String[Boolean]</tt> (optional). The set of contact features that the phone number may be used for.
The set of contact features that this phone number may be used for The set is represented as an object, with each key being a method type. The b
. The set is represented as an object, with each key being a method type. The oolean value <bcp14>MUST</bcp14> be <tt>true</tt>. The <xref target="enumerated
boolean value <bcp14>MUST</bcp14> be <tt>true</tt>. The <xref target="enumerate -values">enumerated</xref> method type values are:
d-values">enumerated</xref> method type values are:
</t> </t>
<ul spacing="normal"> <ul spacing="compact">
<li><tt>mobile</tt>: the number is for a mobile phone.</li> <li><tt>mobile</tt>: the number for a mobile phone.</li>
<li><tt>voice</tt>: the number is for calling by voice.</li> <li><tt>voice</tt>: the number for calling by voice.</li>
<li><tt>text</tt>: the number supports text messages (SMS).</li> <li><tt>text</tt>: the number that supports text messages (SMS).
<li><tt>video</tt>: the number supports video conferencing.</li> </li>
<li><tt>main-number</tt>: this number is the main phone number, <li><tt>video</tt>: the number that supports video conferencing.
such as the number of the front-desk at a company, as opposed to a direct-dial n </li>
umber of an individual employee.</li> <li><tt>main-number</tt>: the main phone number such as the numb
er of the front desk at a company, as opposed to a direct-dial number of an indi
vidual employee.</li>
<li><tt>textphone</tt>: the number is for a device for people wi th hearing or speech difficulties.</li> <li><tt>textphone</tt>: the number is for a device for people wi th hearing or speech difficulties.</li>
<li><tt>fax</tt>: the number is for sending faxes.</li> <li><tt>fax</tt>: the number for sending faxes.</li>
<li><tt>pager</tt>: the number is for a pager or beeper.</li> <li><tt>pager</tt>: the number for a pager or beeper.</li>
</ul> </ul>
</li> </dd>
<li>contexts: <tt>String[Boolean]</tt> (optional). <dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
The contexts in which to use this number. Also see <xref target="prop-contexts" The contexts in which to use the number. Also see <xref target="prop-contexts"/
/>.</li> >.</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
The preference of this number in relation to other numbers. Also se The preference of the number in relation to other numbers. Also see
e <xref target="prop-pref"/>.</li> <xref target="prop-pref"/>.</dd>
<li>label: <tt>String</tt> (optional). <dt>label:</dt><dd> <tt>String</tt> (optional).
A custom label for the value, see <xref target="prop-label"/>.</li> A custom label for the value. Also see <xref target="prop-label"/>.<
</ul> /dd>
</dl>
<figure anchor="example-phones"> <figure anchor="example-phones">
<name><tt>phones</tt> example</name> <name><tt>phones</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"phones": { "phones": {
"tel0": { "tel0": {
"contexts": { "contexts": {
"private": true "private": true
}, },
"features": { "features": {
"voice": true "voice": true
}, },
"number": "tel:+1-555-555-5555;ext=5555", "number": "tel:+1-555-555-5555;ext=5555",
skipping to change at line 1095 skipping to change at line 1412
"work": true "work": true
}, },
"number": "tel:+1-201-555-0123" "number": "tel:+1-201-555-0123"
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="preferredLanguages" numbered="true" toc="default"> <section anchor="preferredLanguages" numbered="true" toc="default">
<name>preferredLanguages</name> <name>preferredLanguages</name>
<t>Type : <tt>Id[LanguagePref]</tt> (optional).</t> <t>Type : <tt>Id[LanguagePref]</tt> (optional)</t>
<t>Defines the preferred languages for contacting the entity associate <t>Defines the preferred languages for contacting the entity associate
d with this Card.</t> d with the Card.</t>
<t>A LanguagePref object has the following properties:</t> <t>A LanguagePref object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>LanguagePref</tt>, if set. This <bcp14>MUST</bcp14> be <tt>LanguagePref</tt>, if set.
</li> </dd>
<li>language: <tt>String</tt> (mandatory). The preferred language. <dt>language:</dt><dd> <tt>String</tt> (mandatory). The preferred l
This <bcp14>MUST</bcp14> a language tag as defined in <xref target="RFC5646"/>. anguage. This <bcp14>MUST</bcp14> be a language tag as defined in <xref target=
</li> "RFC5646"/>.</dd>
<li>contexts: <tt>String[Boolean]</tt> (optional). <dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
Defines the contexts in which to use this language. Also see <xref target="prop Defines the contexts in which to use the language. Also see <xref target="prop-
-contexts"/>.</li> contexts"/>.</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
Defines the preference of this language in relation to other languages of the sa Defines the preference of the language in relation to other languages of the sam
me contexts. Also see <xref target="prop-pref"/>.</li> e contexts. Also see <xref target="prop-pref"/>.</dd>
</ul> </dl>
<figure anchor="example-preferredLanguages"> <figure anchor="example-preferredLanguages">
<name><tt>preferredLanguages</tt> example</name> <name><tt>preferredLanguages</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"preferredLanguages": { "preferredLanguages": {
"l1": { "l1": {
"language": "en", "language": "en",
"contexts": { "contexts": {
"work": true "work": true
}, },
"pref": 1 "pref": 1
}, },
"l2": { "l2": {
skipping to change at line 1139 skipping to change at line 1456
"private": true "private": true
} }
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
<section anchor="calendaring-and-scheduling-properties" numbered="true" to c="default"> <section anchor="calendaring-and-scheduling-properties" numbered="true" to c="default">
<name>Calendaring and Scheduling Properties</name> <name>Calendaring and Scheduling Properties</name>
<t>This section defines properties how to schedule calendar events with the entity represented by this Card.</t> <t>This section defines properties for scheduling calendar events with t he entity represented by the Card.</t>
<section anchor="calendars" numbered="true" toc="default"> <section anchor="calendars" numbered="true" toc="default">
<name>calendars</name> <name>calendars</name>
<t>Type: <tt>Id[Calendar]</tt> (optional).</t> <t>Type: <tt>Id[Calendar]</tt> (optional)</t>
<t>These are resources for calendaring, such as calendars to lookup fr <t>These are resources for calendaring such as using calendars to look
ee-busy information for the entity represented by this Card. A Calendar object up free-busy information for the entity represented by the Card. A Calendar ob
has all properties of the <xref target="resource">Resource</xref> data type, wit ject has all properties of the <xref target="resource">Resource</xref> data type
h the following additional definitions:</t> , with the following additional definitions:</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Cal endar</tt>, if set.</li> <li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Cal endar</tt>, if set.</li>
<li><t>The <tt>kind</tt> property is mandatory. Its <xref target="e numerated-values">enumerated</xref> values are:</t> <li><t>The <tt>kind</tt> property is mandatory. Its <xref target="e numerated-values">enumerated</xref> values are:</t>
<ul> <ul spacing="normal">
<li> <li>
<tt>calendar</tt>: the resource is a calendar that contains en tries such as calendar events or tasks.</li> <tt>calendar</tt>: The resource is a calendar that contains en tries such as calendar events or tasks.</li>
<li> <li>
<tt>freeBusy</tt>: the resource allows for free-busy lookups, for example to schedule group events.</li> <tt>freeBusy</tt>: The resource allows for free-busy lookups, for example, to schedule group events.</li>
</ul> </ul>
</li> </li>
</ul> </ul>
<figure anchor="example-calendars"> <figure anchor="example-calendars">
<name><tt>calendars</tt> example</name> <name><tt>calendars</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"calendars": { "calendars": {
"calA": { "calA": {
"kind": "calendar", "kind": "calendar",
"uri": "webcal://calendar.example.com/calA.ics" "uri": "webcal://calendar.example.com/calA.ics"
}, },
"project-a": { "project-a": {
"kind": "freeBusy", "kind": "freeBusy",
"uri": "https://calendar.example.com/busy/project-a" "uri": "https://calendar.example.com/busy/project-a"
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="schedulingAddresses" numbered="true" toc="default"> <section anchor="schedulingAddresses" numbered="true" toc="default">
<name>schedulingAddresses</name> <name>schedulingAddresses</name>
<t>Type: <tt>Id[SchedulingAddress]</tt> (optional).</t> <t>Type: <tt>Id[SchedulingAddress]</tt> (optional)</t>
<t>The scheduling addresses by which the entity may receive calendar s cheduling invitations. A SchedulingAddress object has the following properties: </t> <t>The scheduling addresses by which the entity may receive calendar s cheduling invitations. A SchedulingAddress object has the following properties: </t>
<ul spacing="normal"> <dl spacing="normal">
<li> <dt>@type:</dt><dd> <tt>String</tt>.
<t>@type: <tt>String</tt>. This <bcp14>MUST</bcp14> be <tt>SchedulingAddress</tt>, if set.
This <bcp14>MUST</bcp14> be <tt>SchedulingAddress</tt>, if set.</t </dd>
> <dt>uri:</dt><dd> <tt>String</tt> (mandatory).
</li> The address to use for calendar scheduling with the contact. This <bcp14>MUST</
<li>uri: <tt>String</tt> (mandatory). bcp14> be a URI as defined in <xref target="RFC3986" sectionFormat="of" section=
The address to use for calendar scheduling with this contact. This <bcp14>MUST< "3"/>.</dd>
/bcp14> be a URI as defined in Section 3 of <xref target="RFC3986" format="defau <dt>contexts:</dt><dd> <tt>String[Boolean]</tt> (optional).
lt"/>.</li> The contexts in which to use the scheduling address. Also see <xref target="pro
<li>contexts: <tt>String[Boolean]</tt> (optional). p-contexts"/>.</dd>
The contexts in which to use this scheduling address. Also see <xref target="pr <dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
op-contexts"/>.</li> The preference of the scheduling address in relation to other schedu
<li>pref: <tt>UnsignedInt</tt> (optional). ling addresses. Also see <xref target="prop-pref"/>.</dd>
The preference of this scheduling address in relation to other sched <dt>label:</dt><dd> <tt>String</tt> (optional).
uling address. Also see <xref target="prop-pref"/>.</li> A custom label for the scheduling address. Also see <xref target="pr
<li>label: <tt>String</tt> (optional). op-label"/>.</dd>
A custom label for the scheduling address, see <xref target="prop-la </dl>
bel"/>.</li>
</ul>
<figure anchor="example-schedulingAddresses"> <figure anchor="example-schedulingAddresses">
<name><tt>schedulingAddresses</tt> example</name> <name><tt>schedulingAddresses</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"schedulingAddresses": { "schedulingAddresses": {
"sched1": { "sched1": {
"uri": "mailto:janedoe@example.com" "uri": "mailto:janedoe@example.com"
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
<section anchor="address-and-location-properties" numbered="true" toc="def ault"> <section anchor="address-and-location-properties" numbered="true" toc="def ault">
<name>Address and Location Properties</name> <name>Address and Location Properties</name>
<t>This section defines properties for postal addresses and geographical locations associated with the entity represented by this Card.</t> <t>This section defines properties for postal addresses and geographical locations associated with the entity represented by the Card.</t>
<section anchor="addresses" numbered="true" toc="default"> <section anchor="addresses" numbered="true" toc="default">
<name>addresses</name> <name>addresses</name>
<t>Type: <tt>Id[Address]</tt> (optional).</t> <t>Type: <tt>Id[Address]</tt> (optional)</t>
<t>A map of address identifiers to Address objects, containing physica l locations.</t> <t>A map of address identifiers to Address objects, containing physica l locations.</t>
<section> <section>
<name>Address object</name> <name>Address Object</name>
<t>An Address object has the following properties:</t> <t>An Address object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Address</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Address</tt>, if set.
</li> </dd>
<li> <dt>
<t>components: <tt>AddressComponent[]</tt> (optional). The <xre components:</dt><dd><t> <tt>AddressComponent[]</tt> (optional).
f target="addresscomponent">components</xref> making up this address. This prop The <xref target="addresscomponent">components</xref> that make up the address.
erty <bcp14>MUST</bcp14> be set if the <tt>full</tt> property is not set, otherw This property <bcp14>MUST</bcp14> be set if the <tt>full</tt> property is not
ise it <bcp14>SHOULD</bcp14> be set. The component list <bcp14>MUST</bcp14> hav set; otherwise, it <bcp14>SHOULD</bcp14> be set. The component list <bcp14>MUST
e at least one entry having a different <tt>kind</tt> than <tt>separator</tt>.</ </bcp14> have at least one entry that has a <tt>kind</tt> other than <tt>separat
t> or</tt>.</t>
<t>Address components <bcp14>SHOULD</bcp14> be ordered such that <t>Address components <bcp14>SHOULD</bcp14> be ordered such that
their values joined as a String produce a valid full address. If so, implement when their values are joined as a String, a valid full address is produced. If
ations <bcp14>MUST</bcp14> set the <tt>isOrdered</tt> property value to <tt>true so, implementations <bcp14>MUST</bcp14> set the <tt>isOrdered</tt> property val
</tt>.</t> ue to <tt>true</tt>.</t>
<t>If the address components are ordered, then the <tt>defaultSe <t>If the address components are ordered, then the <tt>defaultSe
parator</tt> property and address components of kind <tt>separator</tt> give gui parator</tt> property and address components of kind <tt>separator</tt> give gui
dance what characters to insert between components, but implementations are free dance on what characters to insert between components, but implementations are f
to choose any others. In lack of a separator, inserting a single Space charact ree to choose any others. When lacking a separator, inserting a single space ch
er in between address component values is a good choice.</t> aracter in between address component values is a good choice.</t>
<t>If instead the address components follow no particular order, <t>If, instead, the address components follow no particular orde
then the <tt>isOrdered</tt> property value <bcp14>MUST</bcp14> be <tt>false</tt r, then the <tt>isOrdered</tt> property value <bcp14>MUST</bcp14> be <tt>false</
>, the <tt>components</tt> property <bcp14>MUST NOT</bcp14> contain a AddressCom tt>, the <tt>components</tt> property <bcp14>MUST NOT</bcp14> contain an Address
ponent of kind <tt>separator</tt> and the <tt>defaultSeparator</tt> property <bc Component of kind <tt>separator</tt>, and the <tt>defaultSeparator</tt> property
p14>MUST NOT</bcp14> be set.</t> <bcp14>MUST NOT</bcp14> be set.</t>
</li> </dd>
<li>isOrdered: <tt>Boolean</tt> (optional, default: <tt>false</tt> <dt>isOrdered:</dt><dd> <tt>Boolean</tt> (optional; default: <tt>f
). This indicates if the address component sequence in the <tt>components</tt> alse</tt>). Indicates if the address component sequence in the <tt>components</
property is ordered.</li> tt> property is ordered.</dd>
<li>countryCode: <tt>String</tt> (optional). <dt>countryCode:</dt><dd> <tt>String</tt> (optional).
The Alpha-2 country code <xref target="ISO.3166-1.2006"/>.</li> The Alpha-2 country code <xref target="ISO.3166-1"/>.</dd>
<li>coordinates: <tt>String</tt> (optional). A <xref target="RFC5 <dt>coordinates:</dt><dd> <tt>String</tt> (optional). A "geo:" UR
870" format="default"/> "geo:" URI for the address.</li> I <xref target="RFC5870" format="default"/> for the address.</dd>
<li>timeZone: <tt>String</tt> (optional). Identifies the time zon <dt>timeZone:</dt><dd> <tt>String</tt> (optional). Identifies the
e this address is located in. This <bcp14>MUST</bcp14> be a time zone name regi time zone the address is located in. This <bcp14>MUST</bcp14> be a time zone na
stered in the <xref target="IANATZ">IANA Time Zone Database</xref>.</li> me registered in IANA's <xref target="IANA-TZ">Time Zone Database</xref>.</dd>
<li> <dt>
<t>contexts: <tt>String[Boolean]</tt> (optional). contexts:</dt><dd><t> <tt>String[Boolean]</tt> (optional).
The contexts of the address information. The boolean value <bcp14>MUST</bcp14> be <tt>true</tt>. In addition to the common contexts (<xref target="prop-contex ts"/>), allowed key values are: The contexts of the address information. The boolean value <bcp14>MUST</bcp14> be <tt>true</tt>. In addition to the common contexts (<xref target="prop-contex ts"/>), allowed key values are:
</t> </t>
<ul spacing="normal"> <ul spacing="compact">
<li><tt>billing</tt>: an address to be used for billing.</li> <li><tt>billing</tt>: an address to be used for billing.</li>
<li><tt>delivery</tt>: an address to be used for delivering ph ysical items.</li> <li><tt>delivery</tt>: an address to be used for delivering ph ysical items.</li>
</ul> </ul>
</li> </dd>
<li>full: <tt>String</tt> (optional). <dt>full:</dt><dd> <tt>String</tt> (optional).
This is the full address, including street, region or country. Th The full address, including street, region, or country. The purpo
e purpose of this property is to define an address, even if the individual addre se of this property is to define an address, even if the individual address comp
ss components are not known. If the <tt>street</tt> property is set, the <tt>fu onents are not known. If the <tt>street</tt> property is set, the <tt>full</tt>
ll</tt> property <bcp14>SHOULD NOT</bcp14> be set. property <bcp14>SHOULD NOT</bcp14> be set.
</li> </dd>
<li>defaultSeparator: <tt>String</tt> (optional). <dt>defaultSeparator:</dt><dd> <tt>String</tt> (optional).
The default separator to insert between address component values w The default separator to insert between address component values w
hen concatenating all address component values to a single String. Also see the hen concatenating all address component values to a single String. Also see the
definition of the <tt>separator</tt> kind for the AddressComponent object. Thi definition of the <tt>separator</tt> kind for the <xref target="addresscomponent
s property <bcp14>MUST NOT</bcp14> be set if the Address <tt>isOrdered</tt> prop ">AddressComponent</xref> object. This property <bcp14>MUST NOT</bcp14> be set
erty value is <tt>false</tt> or if the <tt>components</tt> property is not set.< if the Address <tt>isOrdered</tt> property value is <tt>false</tt> or if the <tt
/li> >components</tt> property is not set.</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>pref:</dt><dd> <tt>UnsignedInt</tt> (optional).
The preference of this address in relation to other addresses. Also The preference of the address in relation to other addresses. Also
see <xref target="prop-pref"/>.</li> see <xref target="prop-pref"/>.</dd>
<li> <dt>
<t>phoneticScript: <tt>String</tt> (optional). phoneticScript:</dt><dd> <tt>String</tt> (optional).
The script used in the value of the AddressComponent <tt>phoneti The script used in the value of the AddressComponent <tt>phoneti
c</tt> property. Also see <xref target="prop-phonetic"/>.</t> c</tt> property. Also see <xref target="prop-phonetic"/>.
</li> </dd>
<li> <dt>
<t>phoneticSystem: <tt>String</tt> (optional). phoneticSystem:</dt><dd> <tt>String</tt> (optional).
The phonetic system used in the AddressComponent <tt>phonetic</tt> The phonetic system used in the AddressComponent <tt>phonetic</tt>
property. Also see <xref target="prop-phonetic"/>.</t> property. Also see <xref target="prop-phonetic"/>.</dd>
</li> </dl>
</ul> <t>The following example illustrates the use of the <tt>address</tt>
<t>The following example illustrates the use of the <tt>address</tt> property. Additional examples are shown in <xref target="address-examples"/>.<
property. Additional examples are in <xref target="address-examples"/>.</t> /t>
<figure anchor="example-address-us"> <figure anchor="example-address-us">
<name>Example of the address "54321 Oak St, Reston, VA 20190, USA"
</name> <!--[rfced] Titles for Figures 30-32
a) May we remove the postal addresses from the titles of
Figures 30 and 31 to make them more concise? If so, may we list
the addresses in the text above the figures as shown below?
Original:
Section 2.5.1.1
The following example illustrates the use of the address property.
Additional examples are in Section 2.5.1.3.
Figure 30: Example of the address "54321 Oak St, Reston, CA 20190, USA"
Section 2.5.1.3
The following are examples of addresses, in addition to Figure 30.
Figure 31: Example of the address "46, 1 Sukhumvit 51 Alley,
Khlong Tan Nuea, Watthana, Bangkok 10110, Thailand"
Perhaps:
Section 2.5.1.1
The following example illustrates the use of the address property for
"54321 Oak St, Reston, CA 20190, USA". Additional examples are shown
in Section 2.5.1.3.
Figure 30: Example of an Address in the USA
Section 2.5.1.3
The following example illustrates the use of the address property for
"46, 1 Sukhumvit 51 Alley, Khlong Tan Nuea, Watthana, Bangkok 10110,
Thailand". See Figure 30 for an additional example.
Figure 31: Example of an Address in Thailand
b) FYI: We removed the section mention (Section 2.7.1) from the title of
Figure 32 and placed it within the added text above the figure as shown
below. Please let us know of any concerns.
Original:
Section 2.5.1.3
Figure 32: Example of an address in Tokyo and its localization
Section 2.7.1 in Japanese.
Current:
The following example illustrates the use of an address in Tokyo and
its localization (Section 2.7.1) in Japanese.
Figure 32: Example of an Address in Tokyo and Its Localization
in Japanese
-->
<name>Example of the Address "54321 Oak St, Reston, VA 20190, USA"
</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"addresses": { "addresses": {
"k23": { "k23": {
"contexts": { "contexts": {
"work": true "work": true
}, },
"components": [ "components": [
{ "kind": "number", "value": "54321" }, { "kind": "number", "value": "54321" },
{ "kind": "separator", "value": " " }, { "kind": "separator", "value": " " },
{ "kind": "name", "value": "Oak St" }, { "kind": "name", "value": "Oak St" },
skipping to change at line 1279 skipping to change at line 1646
], ],
"countryCode": "US", "countryCode": "US",
"defaultSeparator": ", ", "defaultSeparator": ", ",
"isOrdered": true "isOrdered": true
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="addresscomponent"> <section anchor="addresscomponent">
<name>AddressComponent object</name> <name>AddressComponent Object</name>
<t>An AddressComponent object has the following properties:</t> <t>An AddressComponent object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>AddressComponent</tt>, if set. This <bcp14>MUST</bcp14> be <tt>AddressComponent</tt>, if set.
</li> </dd>
<li>value: <tt>String</tt> (mandatory). <dt>value:</dt><dd> <tt>String</tt> (mandatory).
The value of this address component.</li> The value of the address component.</dd>
<li> <dt>
<t>kind: <tt>String</tt> (mandatory). kind:</dt><dd><t> <tt>String</tt> (mandatory).
The kind of this address component. The <xref target="enumerated- The kind of the address component. The <xref target="enumerated-v
values">enumerated</xref> values are: alues">enumerated</xref> values are:
</t> </t>
<ul spacing="normal"> <ul spacing="compact">
<li><tt>room</tt>: the room or suite number or identifier.</li <li><tt>room</tt>: the room, suite number, or identifier.</li>
> <li><tt>apartment</tt>: the extension designation such as the
<li><tt>apartment</tt>: the extension designation, such as apa apartment number, unit, or box number.</li>
rtment number or unit or box number.</li> <li><tt>floor</tt>: the floor or level the address is located
<li><tt>floor</tt>: the floor or level this address is located on.</li>
on.</li> <li><tt>building</tt>: the building, tower, or condominium the
<li><tt>building</tt>: the building, tower, or condominium thi address is located in.</li>
s address is located in.</li> <li><tt>number</tt>: the street number, e.g., "123". This val
<li><tt>number</tt>: the street number, e.g., "123". This val ue is not restricted to numeric values and can include any value such as number
ue is not restricted to numeric values, and can include any value such as number ranges ("112-10"), grid style ("39.2 RD"), alphanumerics ("N6W23001"), or fracti
ranges ("112–10"), grid style ("39.2 RD"), alphanumerics ("N6W23001") or fracti onals ("123 1/2").</li>
onals ("123 1/2").</li>
<li><tt>name</tt>: the street name.</li> <li><tt>name</tt>: the street name.</li>
<li><tt>block</tt>: the block name or number.</li> <li><tt>block</tt>: the block name or number.</li>
<li><tt>subdistrict</tt>: the subdistrict, ward or other subun it of a district.</li> <li><tt>subdistrict</tt>: the subdistrict, ward, or other subu nit of a district.</li>
<li><tt>district</tt>: the district name.</li> <li><tt>district</tt>: the district name.</li>
<li><tt>locality</tt>: the municipality, city, town, village, <li><tt>locality</tt>: the municipality, city, town, village,
post-town, or another locality.</li> post town, or other locality.</li>
<li><tt>region</tt>: the administrative area, such as province <li><tt>region</tt>: the administrative area such as province,
, state, prefecture, county, canton.</li> state, prefecture, county, or canton.</li>
<li><tt>postcode</tt>: the postal code, post code, ZIP code or <li><tt>postcode</tt>: the postal code, post code, ZIP code, o
other short code associated with the address by the relevant country's postal s r other short code associated with the address by the relevant country's postal
ystem.</li> system.</li>
<li><tt>country</tt>: the country name.</li> <li><tt>country</tt>: the country name.</li>
<li><tt>direction</tt>: the Cardinal direction or quadrant, e. <li><tt>direction</tt>: the cardinal direction or quadrant, e.
g., "North".</li> g., "north".</li>
<li><tt>landmark</tt>: the publicly known prominent feature th <li><tt>landmark</tt>: the publicly known prominent feature th
at can substitute the street name and number, e.g., White House, Taj Mahal.</li> at can substitute the street name and number, e.g., "White House" or "Taj Mahal"
.</li>
<li><tt>postOfficeBox</tt>: the post office box number or iden tifier.</li> <li><tt>postOfficeBox</tt>: the post office box number or iden tifier.</li>
<li><tt>separator</tt>: a formatting separator between two ord ered address non-separator components. The <tt>value</tt> property of the compo nent includes the verbatim separator, for example a hyphen character or even an empty string. This value has higher precedence than the <tt>defaultSeparator</t t> property of the Address. Implementations <bcp14>MUST NOT</bcp14> insert two consecutive separator components, instead they <bcp14>SHOULD</bcp14> insert a si ngle separator component with the combined value. This component kind <bcp14>MU ST NOT</bcp14> be set if the Address <tt>isOrdered</tt> property value is <tt>fa lse</tt>.</li> <li><tt>separator</tt>: a formatting separator between two ord ered address non-separator components. The <tt>value</tt> property of the compo nent includes the verbatim separator, for example, a hyphen character or even an empty string. This value has higher precedence than the <tt>defaultSeparator</ tt> property of the Address. Implementations <bcp14>MUST NOT</bcp14> insert two consecutive separator components; instead, they <bcp14>SHOULD</bcp14> insert a single separator component with the combined value. This component kind <bcp14> MUST NOT</bcp14> be set if the Address <tt>isOrdered</tt> property value is <tt> false</tt>.</li>
</ul> </ul>
</li> </dd>
<li>phonetic: <tt>String</tt> (optional). This defines how to pro <dt>phonetic:</dt><dd> <tt>String</tt> (optional). Defines how to
nounce this name component. If this property is set, then at least one of the A pronounce the name component. If this property is set, then at least one of th
ddress object <tt>phoneticSystem</tt> or <tt>phoneticScript</tt> properties <bcp e Address object <tt>phoneticSystem</tt> or <tt>phoneticScript</tt> properties <
14>MUST</bcp14> be set. Also see <xref target="prop-phonetic"/>.</li> bcp14>MUST</bcp14> be set. Also see <xref target="prop-phonetic"/>.</dd>
</ul> </dl>
</section> </section>
<section anchor="address-examples"> <section anchor="address-examples">
<name>Address examples</name> <name>Address Examples</name>
<t>The following are examples of addresses, in addition to <xref tar <t>Examples of addresses are shown below; also see <xref target="exa
get="example-address-us"/>.</t> mple-address-us"/>.</t>
<figure anchor="example-address-th"> <figure anchor="example-address-th">
<name>Example of the address "46, 1 Sukhumvit 51 Alley, Khlong Tan Nuea, Watthana, Bangkok 10110, Thailand"</name> <name>Example of the Address "46, 1 Sukhumvit 51 Alley, Khlong Tan Nuea, Watthana, Bangkok 10110, Thailand"</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"addresses": { "addresses": {
"k25": { "k25": {
"components": [ "components": [
{ "kind": "number", "value": "46" }, { "kind": "number", "value": "46" },
{ "kind": "name", "value": "1 Sukhumvit 51 Alley" }, { "kind": "name", "value": "1 Sukhumvit 51 Alley" },
{ "kind": "subdistrict", "value": "Khlong Tan Nuea" }, { "kind": "subdistrict", "value": "Khlong Tan Nuea" },
{ "kind": "district", "value": " Watthana" }, { "kind": "district", "value": " Watthana" },
{ "kind": "locality", "value": "Bangkok" }, { "kind": "locality", "value": "Bangkok" },
{ "kind": "country", "value": "Thailand" }, { "kind": "country", "value": "Thailand" },
{ "kind": "postcode", "value": "10110" } { "kind": "postcode", "value": "10110" }
], ],
"defaultSeparator": ", ", "defaultSeparator": ", ",
"isOrdered": true "isOrdered": true
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
<t>
The following example illustrates the use of an address in Tokyo and its localiz
ation (<xref target="localizations"/>) in Japanese.
</t>
<figure anchor="example-address-jp"> <figure anchor="example-address-jp">
<name>Example of an address in Tokyo and its localization <xref ta rget="localizations"/> in Japanese.</name> <name>Example of an Address in Tokyo and Its Localization in Japan ese</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"addresses": { "addresses": {
"k26": { "k26": {
"components": [ "components": [
{ "kind": "block", "value": "2-7" }, { "kind": "block", "value": "2-7" },
{ "kind": "separator", "value": "-" }, { "kind": "separator", "value": "-" },
{ "kind": "number", "value": "2" }, { "kind": "number", "value": "2" },
{ "kind": "separator", "value": " " }, { "kind": "separator", "value": " " },
{ "kind": "district", "value": "Marunouchi" }, { "kind": "district", "value": "Marunouchi" },
{ "kind": "locality", "value": "Chiyoda-ku" }, { "kind": "locality", "value": "Chiyoda-ku" },
skipping to change at line 1383 skipping to change at line 1753
} }
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
</section> </section>
<section anchor="resource-properties" numbered="true" toc="default"> <section anchor="resource-properties" numbered="true" toc="default">
<name>Resource Properties</name> <name>Resource Properties</name>
<t>This section defines properties for digital resources associated with the entity represented by this Card.</t> <t>This section defines properties for digital resources associated with the entity represented by the Card.</t>
<section anchor="cryptoKeys" numbered="true" toc="default"> <section anchor="cryptoKeys" numbered="true" toc="default">
<name>cryptoKeys</name> <name>cryptoKeys</name>
<t>Type: <tt>Id[CryptoKey]</tt> (optional).</t> <t>Type: <tt>Id[CryptoKey]</tt> (optional)</t>
<t>These are cryptographic resources such as public keys and certifica <t>These are cryptographic resources such as public keys and certifica
tes associated with the entity represented by this Card. A CryptoKey object has tes associated with the entity represented by the Card. A CryptoKey object has
all properties of the <xref target="resource">Resource</xref> data type, with t all properties of the <xref target="resource">Resource</xref> data type, with th
he following additional definitions:</t> e following additional definition:</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Cry ptoKey</tt>, if set.</li> <li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Cry ptoKey</tt>, if set.</li>
</ul> </ul>
<t>The following example shows how refer to an external cryptographic resource.</t> <t>The following example shows how to refer to an external cryptograph ic resource.</t>
<figure anchor="example-cryptoKeys-external"> <figure anchor="example-cryptoKeys-external">
<name><tt>cryptoKeys</tt> example with external data</name> <name>Example of <tt>cryptoKeys</tt> with External Data</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"cryptoKeys": { "cryptoKeys": {
"mykey1": { "mykey1": {
"uri": "https://www.example.com/keys/jdoe.cer" "uri": "https://www.example.com/keys/jdoe.cer"
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
<t>The following example shows how to embed key data in the CryptoKey. The key data is depicted in multiple lines only for demonstration purposes.</t > <t>The following example shows how to embed key data in the CryptoKey. The key data is depicted in multiple lines only for demonstration purposes.</t >
<figure anchor="example-cryptoKeys-embedded"> <figure anchor="example-cryptoKeys-embedded">
<name><tt>cryptoKeys</tt> example with embedded data</name> <name>Example of <tt>cryptoKeys</tt> with Embedded Data</name>
<sourcecode name="" type="json"><![CDATA[
<!--[rfced] The sourcecode in Figure 34 (Section 2.6.1) was 8
characters over the 72-character limit, so we adjusted the line
breaks as shown below. Please let us know if any further updates
are needed.
Original:
"cryptoKeys": { "cryptoKeys": {
"mykey2": { "mykey2": {
"uri": "data:application/pgp-keys;base64,LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtF "uri": "data:application/pgp-keys;base64,LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtF
WS0tLS0tCk1JSUJDZ0tDQVFFQSt4R1ovd2N6OXVnRnBQMDdOc3BvNlUxN2wwWWhGa WS0tLS0tCk1JSUJDZ0tDQVFFQSt4R1ovd2N6OXVnRnBQMDdOc3BvNlUxN2wwWWhGa
UZweHhVNHBUazNMaWZ6OVIzenNJc3UKRVJ3dGE3K2ZXSWZ4T28yMDhldHQvamhza2 UZweHhVNHBUazNMaWZ6OVIzenNJc3UKRVJ3dGE3K2ZXSWZ4T28yMDhldHQvamhza2
lWb2RTRXQzUUJHaDRYQmlweVdvcEt3WjkzSEhhRFZaQUFMaS8yQQoreFRCdFdkRW8 lWb2RTRXQzUUJHaDRYQmlweVdvcEt3WjkzSEhhRFZaQUFMaS8yQQoreFRCdFdkRW8
3WEdVdWpLRHZDMi9hWkt1a2ZqcE9pVUk4QWhMQWZqbWxjRC9VWjFRUGgwbUhzZ2xS 3WEdVdWpLRHZDMi9hWkt1a2ZqcE9pVUk4QWhMQWZqbWxjRC9VWjFRUGgwbUhzZ2xS
TkNtcEN3Cm13U1hBOVZObWh6K1BpQitEbWw0V1duS1cvVkhvMnVqVFh4cTcrZWZNV TkNtcEN3Cm13U1hBOVZObWh6K1BpQitEbWw0V1duS1cvVkhvMnVqVFh4cTcrZWZNV
TRIMmZueTNTZTNLWU9zRlBGR1oxVE4KUVNZbEZ1U2hXckhQdGlMbVVkUG9QNkNWMm TRIMmZueTNTZTNLWU9zRlBGR1oxVE4KUVNZbEZ1U2hXckhQdGlMbVVkUG9QNkNWMm
1NTDF0aytsN0RJSXFYclFoTFVLREFDZU01cm9NeDBrTGhVV0I4UAorMHVqMUNObE5 1NTDF0aytsN0RJSXFYclFoTFVLREFDZU01cm9NeDBrTGhVV0I4UAorMHVqMUNObE5
ONEpSWmxDN3hGZnFpTWJGUlU5WjRONll3SURBUUFCCi0tLS0tRU5EIFJTQSBQVUJM ONEpSWmxDN3hGZnFpTWJGUlU5WjRONll3SURBUUFCCi0tLS0tRU5EIFJTQSBQVUJM
SUMgS0VZLS0tLS0K" SUMgS0VZLS0tLS0K"
} }
} }
Current:
"cryptoKeys": {
"mykey2": {
"uri": "data:application/pgp-keys;base64,LS0tLS1CRUdJTiBSU0EgUFVC
TElDIEtFWS0tLS0tCk1JSUJDZ0tDQVFFQSt4R1ovd2N6OXVnRnBQMDdOc
3BvNlUxN2wwWWhGaUZweHhVNHBUazNMaWZ6OVIzenNJc3UKRVJ3dGE3K2
ZXSWZ4T28yMDhldHQvamhza2lWb2RTRXQzUUJHaDRYQmlweVdvcEt3Wjk
zSEhhRFZaQUFMaS8yQQoreFRCdFdkRW83WEdVdWpLRHZDMi9hWkt1a2Zq
cE9pVUk4QWhMQWZqbWxjRC9VWjFRUGgwbUhzZ2xSTkNtcEN3Cm13U1hBO
VZObWh6K1BpQitEbWw0V1duS1cvVkhvMnVqVFh4cTcrZWZNVTRIMmZueT
NTZTNLWU9zRlBGR1oxVE4KUVNZbEZ1U2hXckhQdGlMbVVkUG9QNkNWMm1
NTDF0aytsN0RJSXFYclFoTFVLREFDZU01cm9NeDBrTGhVV0I4UAorMHVq
MUNObE5ONEpSWmxDN3hGZnFpTWJGUlU5WjRONll3SURBUUFCCi0tLS0tR
U5EIFJTQSBQVUJMSUMgS0VZLS0tLS0K"
}
}
-->
<sourcecode name="" type="json"><![CDATA[
"cryptoKeys": {
"mykey2": {
"uri": "data:application/pgp-keys;base64,LS0tLS1CRUdJTiBSU0EgUFVC
TElDIEtFWS0tLS0tCk1JSUJDZ0tDQVFFQSt4R1ovd2N6OXVnRnBQMDdOc
3BvNlUxN2wwWWhGaUZweHhVNHBUazNMaWZ6OVIzenNJc3UKRVJ3dGE3K2
ZXSWZ4T28yMDhldHQvamhza2lWb2RTRXQzUUJHaDRYQmlweVdvcEt3Wjk
zSEhhRFZaQUFMaS8yQQoreFRCdFdkRW83WEdVdWpLRHZDMi9hWkt1a2Zq
cE9pVUk4QWhMQWZqbWxjRC9VWjFRUGgwbUhzZ2xSTkNtcEN3Cm13U1hBO
VZObWh6K1BpQitEbWw0V1duS1cvVkhvMnVqVFh4cTcrZWZNVTRIMmZueT
NTZTNLWU9zRlBGR1oxVE4KUVNZbEZ1U2hXckhQdGlMbVVkUG9QNkNWMm1
NTDF0aytsN0RJSXFYclFoTFVLREFDZU01cm9NeDBrTGhVV0I4UAorMHVq
MUNObE5ONEpSWmxDN3hGZnFpTWJGUlU5WjRONll3SURBUUFCCi0tLS0tR
U5EIFJTQSBQVUJMSUMgS0VZLS0tLS0K"
}
}
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="directories" numbered="true" toc="default"> <section anchor="directories" numbered="true" toc="default">
<name>directories</name> <name>directories</name>
<t>Type: <tt>Id[Directory]</tt> (optional).</t> <t>Type: <tt>Id[Directory]</tt> (optional)</t>
<t>These are directory service resources, such as entries in a directo <t>These are directory service resources such as entries in a director
ry or organizational directories for lookup. A Directory object has all propert y or organizational directories for lookup. A Directory object has all properti
ies of the <xref target="resource">Resource</xref> data type, with the following es of the <xref target="resource">Resource</xref> data type, with the following
additional definitions:</t> additional definitions:</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Dir ectory</tt>, if set.</li> <li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Dir ectory</tt>, if set.</li>
<li> <li>
<t>The <tt>kind</tt> property is mandatory. Its <xref target="enu merated-values">enumerated</xref> values are:</t> <t>The <tt>kind</tt> property is mandatory. Its <xref target="enu merated-values">enumerated</xref> values are:</t>
<ul> <ul>
<li><tt>directory</tt>: the resource is a directory service wher <li><tt>directory</tt>: the resource is a directory service that
e the entity represented by this Card is part of. This typically is an organiza the entity represented by the Card is a part of. This typically is an organiza
tional directory that also contains associated entities, e.g., co-workers and m tional directory that also contains associated entities, e.g., co-workers and ma
anagement in a company directory.</li> nagement in a company directory.</li>
<li><tt>entry</tt>: the resource is a directory entry of the ent <li><tt>entry</tt>: the resource is a directory entry of the ent
ity represented by this Card. In contrast to the <tt>directory</tt> type, this ity represented by the Card. In contrast to the <tt>directory</tt> type, this i
is the specific URI for the entity <em>within</em> a directory.</li> s the specific URI for the entity <em>within</em> a directory.</li>
</ul> </ul>
</li> </li>
</ul> </ul>
<t>In addition, the Directory object has the following property:</t> <t>In addition, the Directory object has the following property:</t>
<ul> <dl>
<li>listAs: <tt>UnsignedInt</tt> (optional). <dt>listAs:</dt><dd> <tt>UnsignedInt</tt> (optional).
This defines the position of this directory resource in the list of al Defines the position of the directory resource in the list of all Dire
l Directory objects having the same <tt>kind</tt> in this Card. If set, the <tt ctory objects having the same <tt>kind</tt> in the Card. If set, the <tt>listAs
>listAs</tt> value <bcp14>MUST</bcp14> be higher than zero. Multiple directory </tt> value <bcp14>MUST</bcp14> be higher than zero. Multiple directory resourc
resources <bcp14>MAY</bcp14> have the same <tt>listAs</tt> property value, or no es <bcp14>MAY</bcp14> have the same <tt>listAs</tt> property value or none. Sor
ne. Sorting such entries is implementation-specific. ting such entries is implementation-specific.
</li> </dd>
</ul> </dl>
<figure anchor="example-directories"> <figure anchor="example-directories">
<name><tt>directories</tt> example</name> <name><tt>directories</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"directories": { "directories": {
"dir1": { "dir1": {
"kind": "entry", "kind": "entry",
"uri": "https://dir.example.com/addrbook/jdoe/Jean%20Dupont.vcf" "uri": "https://dir.example.com/addrbook/jdoe/Jean%20Dupont.vcf"
}, },
"dir2": { "dir2": {
"kind": "directory", "kind": "directory",
"uri": "ldap://ldap.example/o=Example%20Tech,ou=Engineering", "uri": "ldap://ldap.example/o=Example%20Tech,ou=Engineering",
"pref": 1 "pref": 1
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="links" numbered="true" toc="default"> <section anchor="links" numbered="true" toc="default">
<name>links</name> <name>links</name>
<t>Type: <tt>Id[Link]</tt> (optional).</t> <t>Type: <tt>Id[Link]</tt> (optional)</t>
<t>These are links to resources that do not fit any of the other use-c <t>These are links to resources that do not fit any of the other use-c
ase specific resource properties. A Link object has all properties of the <xref ase-specific resource properties. A Link object has all properties of the <xref
target="resource">Resource</xref> data type, with the following additional defi target="resource">Resource</xref> data type, with the following additional defi
nitions:</t> nitions:</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Lin k</tt>, if set.</li> <li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Lin k</tt>, if set.</li>
<li><t>The <tt>kind</tt> property is optional. Its <xref target="en umerated-values">enumerated</xref> values are:</t> <li><t>The <tt>kind</tt> property is optional. Its <xref target="en umerated-values">enumerated</xref> values are:</t>
<ul> <ul>
<li><tt>contact</tt>: the resource is a URI by which the entity represented by this Card may be contacted, including web forms or other media th at require user interaction.</li> <li><tt>contact</tt>: the resource is a URI by which the entity represented by the Card may be contacted; this includes web forms or other media that require user interaction.</li>
</ul> </ul>
</li> </li>
</ul> </ul>
<figure anchor="example-links"> <figure anchor="example-links">
<name><tt>links</tt> example</name> <name><tt>links</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"links": { "links": {
"link3": { "link3": {
"kind": "contact", "kind": "contact",
"uri": "mailto:contact@example.com", "uri": "mailto:contact@example.com",
"pref": 1 "pref": 1
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="media" numbered="true" toc="default"> <section anchor="media" numbered="true" toc="default">
<name>media</name> <name>media</name>
<t>Type: <tt>Id[Media]</tt> (optional).</t> <t>Type: <tt>Id[Media]</tt> (optional)</t>
<t>These are media resources such as photographs, avatars, or sounds a <t>These are media resources such as photographs, avatars, or sounds t
ssociated with the entity represented by this Card. A Media object has all prop hat are associated with the entity represented by the Card. A Media object has
erties of the <xref target="resource">Resource</xref> data type, with the follow all properties of the <xref target="resource">Resource</xref> data type, with th
ing additional definitions:</t> e following additional definitions:</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Med ia</tt>, if set.</li> <li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Med ia</tt>, if set.</li>
<li> <li>
<t>The <tt>kind</tt> property is mandatory. Its <xref target="enu merated-values">enumerated</xref> values are:</t> <t>The <tt>kind</tt> property is mandatory. Its <xref target="enu merated-values">enumerated</xref> values are:</t>
<ul> <ul spacing="normal">
<li><tt>photo</tt>: the resource is a photograph or avatar.</li> <li><tt>photo</tt>: the resource is a photograph or avatar.</li>
<li><tt>sound</tt>: the resource is audio media, e.g., to speci fy the proper pronunciation of the name property contents.</li> <li><tt>sound</tt>: the resource is audio media, e.g., to speci fy the proper pronunciation of the name property contents.</li>
<li><tt>logo</tt>: the resource is a graphic image or logo assoc iated with the entity represented by this Card.</li> <li><tt>logo</tt>: the resource is a graphic image or logo assoc iated with the entity represented by the Card.</li>
</ul> </ul>
</li> </li>
</ul> </ul>
<figure anchor="example-media"> <figure anchor="example-media">
<name><tt>media</tt> example</name> <name><tt>media</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"media": { "media": {
"res45": { "res45": {
"kind": "sound", "kind": "sound",
"uri": "CID:JOHNQ.part8.19960229T080000.xyzMail@example.com" "uri": "CID:JOHNQ.part8.19960229T080000.xyzMail@example.com"
}, },
"res47": { "res47": {
"kind": "logo", "kind": "logo",
"uri": "https://www.example.com/pub/logos/abccorp.jpg" "uri": "https://www.example.com/pub/logos/abccorp.jpg"
}, },
skipping to change at line 1522 skipping to change at line 1934
"kind": "photo", "kind": "photo",
"uri": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4..." "uri": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQAASABIAAD/4..."
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
<section anchor="multilingual-properties" numbered="true" toc="default"> <section anchor="multilingual-properties" numbered="true" toc="default">
<name>Multilingual Properties</name> <name>Multilingual Properties</name>
<t>This section defines properties how to localize the content of this C ard in human languages.</t> <t>This section defines properties for localizing the content of the Car d in human languages.</t>
<section anchor="localizations" numbered="true" toc="default"> <section anchor="localizations" numbered="true" toc="default">
<name>localizations</name> <name>localizations</name>
<t>Type: String[PatchObject] (optional).</t> <t>Type: String[PatchObject] (optional)</t>
<t>This localizes property values in this Card to languages other than <t>This localizes property values to languages (other than the main la
the main language. Localizations provide language-specific alternatives for ex nguage) in the Card. Localizations provide language-specific alternatives for e
isting property values and <bcp14>SHOULD NOT</bcp14> add new properties.</t> xisting property values and <bcp14>SHOULD NOT</bcp14> add new properties.</t>
<t>The keys in the localizations property object are language tags <xr <t>The keys in the localizations property object are language tags <xr
ef target="RFC5646"/>. The values are patch objects which localize the Card in t ef target="RFC5646"/>. The values are patch objects that localize the Card in th
he respective language tag. The paths in the PatchObject are relative to the Ca e respective language tag. The paths in the PatchObject are relative to the Car
rd that includes the <tt>localizations</tt> property. A patch <bcp14>MUST NOT</ d that includes the <tt>localizations</tt> property. A patch <bcp14>MUST NOT</b
bcp14> target the <tt>localizations</tt> property.</t> cp14> target the <tt>localizations</tt> property.</t>
<t>Conceptually, a Card is localized as follows:</t> <t>Conceptually, a Card is localized as follows:</t>
<ul> <ul>
<li>Determine the language tag in which this Card should be localize d in.</li> <li>Determine the language tag in which the Card should be localized .</li>
<li>If the localizations property includes a key for that language, obtain the PatchObject value. If there is no such key, stop.</li> <li>If the localizations property includes a key for that language, obtain the PatchObject value. If there is no such key, stop.</li>
<li>Create a copy of the Card, but do not copy the localizations pro perty.</li> <li>Create a copy of the Card, but do not copy the localizations pro perty.</li>
<li>Apply all patches in the PatchObject to the copy of the Card.</l i> <li>Apply all patches in the PatchObject to the copy of the Card.</l i>
<li>Optionally, set the <tt>language</tt> property in the copy of th e Card.</li> <li>Optionally, set the <tt>language</tt> property in the copy of th e Card.</li>
<li>Use the patched copy of the Card as the localized variant of the original Card.</li> <li>Use the patched copy of the Card as the localized variant of the original Card.</li>
</ul> </ul>
<t>A patch in the PatchObject may contain any value type. Its value < bcp14>MUST</bcp14> be a valid value according to the definition of the patched p roperty.</t> <t>A patch in the PatchObject may contain any value type. Its value < bcp14>MUST</bcp14> be a valid value according to the definition of the patched p roperty.</t>
<t><xref target="example-localizations-replace"/> localizes the <tt>na me</tt> property by completely replacing its contents in Ukrainian language with Cyrillic script.</t> <t><xref target="example-localizations-replace"/> localizes the <tt>na me</tt> property by completely replacing its contents in Ukrainian language with Cyrillic script.</t>
<figure anchor="example-localizations-replace"> <figure anchor="example-localizations-replace">
<name>Example for localizing a top-level property</name> <name>Example of Localizing a Top-Level Property</name>
<artwork><![CDATA[ <sourcecode type=""><![CDATA[
{ {
"name": { "name": {
"components": [ "components": [
{ "kind": "title", "value": "Mr." }, { "kind": "title", "value": "Mr." },
{ "kind": "given", "value": "Ivan" }, { "kind": "given", "value": "Ivan" },
{ "kind": "given2", "value": "Petrovich" }, { "kind": "given2", "value": "Petrovich" },
{ "kind": "surname", "value": "Vasiliev" } { "kind": "surname", "value": "Vasiliev" }
] ]
}, },
"localizations": { "localizations": {
skipping to change at line 1564 skipping to change at line 1976
"components": [ "components": [
{ "kind": "title", "value": "г-н" }, { "kind": "title", "value": "г-н" },
{ "kind": "given", "value": "Иван" }, { "kind": "given", "value": "Иван" },
{ "kind": "given2", "value": "Петрович" }, { "kind": "given2", "value": "Петрович" },
{ "kind": "surname", "value": "Васильев" } { "kind": "surname", "value": "Васильев" }
] ]
} }
} }
} }
} }
]]></artwork> ]]></sourcecode>
</figure> </figure>
<t><xref target="example-localizations-patch"/> localizes the title na me by patching <em>inside</em> the <tt>titles</tt> property. All properties but the <tt>name</tt> property in the Title object are left as-is.</t> <t><xref target="example-localizations-patch"/> localizes the title na me by patching <em>inside</em> the <tt>titles</tt> property. All properties, ex cept the <tt>name</tt> property in the Title object, are left as is.</t>
<figure anchor="example-localizations-patch"> <figure anchor="example-localizations-patch">
<name>Example for localizing a nested property</name> <name>Example of Localizing a Nested Property</name>
<artwork><![CDATA[
<!--[rfced] In Figure 39, is the term "autor" correct, or should it be
"author"?
Original:
"titles/t1/name": "autor"
-->
<sourcecode type=""><![CDATA[
"name": { "name": {
"full": "Gabriel García Márquez" "full": "Gabriel García Márquez"
}, },
"titles": { "titles": {
"t1": { "t1": {
"kind": "title", "kind": "title",
"name": "novelist" "name": "novelist"
} }
}, },
"localizations": { "localizations": {
"es": { "es": {
"titles/t1/name": "autor" "titles/t1/name": "autor"
} }
} }
]]></artwork> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
<section anchor="additional-properties" numbered="true" toc="default"> <section anchor="additional-properties" numbered="true" toc="default">
<name>Additional Properties</name> <name>Additional Properties</name>
<t>This section defines properties for which none of the previous sectio ns are appropriate.</t> <t>This section defines properties for which none of the previous sectio ns are appropriate.</t>
<section anchor="anniversaries" numbered="true" toc="default"> <section anchor="anniversaries" numbered="true" toc="default">
<name>anniversaries</name> <name>anniversaries</name>
<t>Type : Id[Anniversary] (optional).</t> <t>Type: Id[Anniversary] (optional)</t>
<t>These are memorable dates and events for the entity represented by <t>These are memorable dates and events for the entity represented by
this Card. An Anniversary object has the following properties:</t> the Card. An Anniversary object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Anniversary</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Anniversary</tt>, if set.
</li> </dd>
<li> <dt>
<t>kind: <tt>String</tt> (mandatory). kind:</dt><dd><t> <tt>String</tt> (mandatory).
Specifies the kind of the anniversary. The <xref target="enumerat Specifies the kind of anniversary. The <xref target="enumerated-v
ed-values">enumerated</xref> values are: alues">enumerated</xref> values are:
</t> </t>
<ul spacing="normal"> <ul spacing="compact">
<li><tt>birth</tt>: a birthday anniversary</li> <li><tt>birth</tt>: a birthday anniversary</li>
<li><tt>death</tt>: a deathday anniversary</li> <li><tt>death</tt>: a deathday anniversary</li>
<li><tt>wedding</tt>: a wedding day anniversary</li> <li><tt>wedding</tt>: a wedding day anniversary</li>
</ul> </ul>
</li> </dd>
<li> <dt>
<t>date: <tt>PartialDate|Timestamp</tt> (mandatory, defaultType: < date:</dt><dd><t> <tt>PartialDate|Timestamp</tt> (mandatory; defau
tt>PartialDate</tt>).</t> ltType: <tt>PartialDate</tt>). The date of the anniversary in the Gregorian cal
<t>The date of this anniversary in the Gregorian calendar. This < endar. This <bcp14>MUST</bcp14> be either a whole or partial calendar date or a
bcp14>MUST</bcp14> either be a whole or partial calendar date or a complete UTC complete UTC timestamp (see the definition of the Timestamp and PartialDate obj
timestamp (see the definition of the Timestamp and PartialDate object types belo ect types below).</t>
w).</t> </dd>
</li> <dt>place:</dt><dd> Address (optional). An address associated with t
<li>place: Address (optional). his anniversary, e.g., the place of birth or death.</dd>
An address associated with this anniversary, e.g., the place of bir </dl>
th or death.</li> <t>A PartialDate object represents a complete or partial calendar date
</ul> in the Gregorian calendar. It represents a complete date, a year, a month in a
<t>A PartialDate object represents a complete or partial calendar date year, or a day in a month. It has the following properties, of which at least
in the Gregorian calendar. It represents either a complete date, or a year, or <tt>year</tt> or <tt>month</tt> and <tt>day</tt> <bcp14>MUST</bcp14> be set:</t>
a month in a year, or a day in a month. It has the following properties, of wh <dl spacing="normal">
ich at least <tt>year</tt> or <tt>month</tt> and <tt>day</tt> <bcp14>MUST</bcp14 <dt>@type:</dt><dd> <tt>String</tt>.
> be set:</t>
<ul spacing="normal">
<li>@type: <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>PartialDate</tt>, if set. This <bcp14>MUST</bcp14> be <tt>PartialDate</tt>, if set.
</li> </dd>
<li>year: <tt>UnsignedInt</tt> (optional). This is the calendar yea <dt>year: </dt><dd><tt>UnsignedInt</tt> (optional). The calendar ye
r.</li> ar.</dd>
<li>month: <tt>UnsignedInt</tt> (optional). This is the calendar mo <dt>month:</dt><dd> <tt>UnsignedInt</tt> (optional). The calendar m
nth, represented as the integers 1 &lt;= month &lt;= 12. If this property is se onth, represented as the integers 1 &lt;= month &lt;= 12. If this property is s
t then either <tt>year</tt> or <tt>day</tt> <bcp14>MUST</bcp14> be set.</li> et, then either <tt>year</tt> or <tt>day</tt> <bcp14>MUST</bcp14> be set.</dd>
<li>day: <tt>UnsignedInt</tt> (optional). This is the calendar mont <dt>day:</dt><dd> <tt>UnsignedInt</tt> (optional). The calendar mon
h day, represented as the integers 1 &lt;= day &lt;= 31, depending on the validi th day, represented as the integers 1 &lt;= day &lt;= 31, depending on the valid
ty within the month and year. If this property is set then <tt>month</tt> <bcp1 ity within the month and year. If this property is set,
4>MUST</bcp14> be set.</li> then <tt>month</tt> <bcp14>MUST</bcp14> be set.</dd>
<li>calendarScale: <tt>String</tt> (optional). This is the calendar <dt>calendarScale:</dt><dd> <tt>String</tt> (optional). The calenda
system in which this date occurs, in lowercase. This <bcp14>MUST</bcp14> be ei r system in which this date occurs, in lowercase. This <bcp14>MUST</bcp14> be e
ther a CLDR-registered calendar system name <xref target="RFC7529" format="defau ither a calendar system name registered as a Common Locale Data Repository (CLDR
lt"/> or a vendor-specific value. The year, month and day still <bcp14>MUST</bc ) <xref target="RFC7529" format="default"/> or a vendor-specific value. The yea
p14> be represented in the Gregorian calendar. Note that the <tt>year</tt> prop r, month, and day still <bcp14>MUST</bcp14> be represented in the Gregorian cale
erty might be required to convert the date between the Gregorian calendar and th ndar. Note that the <tt>year</tt> property might be required to convert the dat
e respective calendar system.</li> e between the Gregorian calendar and the respective calendar system.</dd>
</ul> </dl>
<t>A Timestamp object has the following properties:</t> <t>A Timestamp object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>. This <bcp14>MUST</bcp14> be <tt
This <bcp14>MUST</bcp14> be <tt>Timestamp</tt>, if set. >Timestamp</tt>, if set.
</li> </dd>
<li>utc: <tt>UTCDateTime</tt> (mandatory). Specifies the point in t <dt>utc:</dt><dd> <tt>UTCDateTime</tt> (mandatory). Specifies the p
ime in UTC time. oint in time in UTC time.
</li> </dd>
</ul> </dl>
<t><xref target="example-anniversaries"/> illustrates anniversaries wi <t><xref target="example-anniversaries"/> illustrates anniversaries wi
th partial dates and timestamp. Note how the <tt>@type</tt> property is set for th partial dates and a timestamp. Note how the <tt>@type</tt> property is set f
the <tt>Timestamp</tt> object value according to the rules defined <xref target or the <tt>Timestamp</tt> object value according to the rules defined in <xref t
="prop-type"/>.</t> arget="prop-type"/>.</t>
<figure anchor="example-anniversaries"> <figure anchor="example-anniversaries">
<name><tt>anniversaries</tt> example</name> <name><tt>anniversaries</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"anniversaries": { "anniversaries": {
"k8": { "k8": {
"kind": "birth", "kind": "birth",
"date": { "date": {
"year": 1953, "year": 1953,
"month": 4, "month": 4,
"day": 15 "day": 15
} }
}, },
skipping to change at line 1663 skipping to change at line 2081
"place": { "place": {
"full": "4445 Tree Street\nNew England, ND 58647\nUSA" "full": "4445 Tree Street\nNew England, ND 58647\nUSA"
} }
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="keywords" numbered="true" toc="default"> <section anchor="keywords" numbered="true" toc="default">
<name>keywords</name> <name>keywords</name>
<t>Type: <tt>String[Boolean]</tt> (optional). <t>Type: <tt>String[Boolean]</tt> (optional)</t><t>
A set of free-text keywords, also known as <em>tags</em>. The set is represente d as an object, with each key being a keyword. The boolean value <bcp14>MUST</b cp14> be <tt>true</tt>.</t> A set of free-text keywords, also known as <em>tags</em>. The set is represente d as an object, with each key being a keyword. The boolean value <bcp14>MUST</b cp14> be <tt>true</tt>.</t>
<figure anchor="example-keywords"> <figure anchor="example-keywords">
<name><tt>keywords</tt> example</name> <name><tt>keywords</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"keywords": { "keywords": {
"internet": true, "internet": true,
"IETF": true "IETF": true
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="notes" numbered="true" toc="default"> <section anchor="notes" numbered="true" toc="default">
<name>notes</name> <name>notes</name>
<t>Type: <tt>Id[Note]</tt> (optional).</t> <t>Type: <tt>Id[Note]</tt> (optional)</t>
<t>Free-text notes associated with this Card. A Note object has the f <t>Free-text notes that are associated with the Card. A Note object h
ollowing properties:</t> as the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Note</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Note</tt>, if set.
</li> </dd>
<li> <dt>
<t>note: <tt>String</tt> (mandatory). The free text value of this note:</dt><dd> <tt>String</tt> (mandatory). The free-text value of
note.</t> this note.
</li> </dd>
<li> <dt>
<t>created: <tt>UTCDateTime</tt> (optional). The date and time wh created:</dt><dd> <tt>UTCDateTime</tt> (optional). The date and t
en this note was created.</t> ime when this note was created.
</li> </dd>
<li> <dt>
<t>author: <tt>Author</tt> (optional). The author of this note.</ author:</dt><dd> <tt>Author</tt> (optional). The author of this no
t> te.
</li> </dd>
</ul> </dl>
<t>An Author object has the following properties, of which at least on <t>An Author object has the following properties, of which at least on
e other than <tt>@type</tt> <bcp14>MUST</bcp14> be set:</t> e property other than <tt>@type</tt> <bcp14>MUST</bcp14> be set:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>Author</tt>, if set. This <bcp14>MUST</bcp14> be <tt>Author</tt>, if set.
</li> </dd>
<li> <dt>
<t>name: <tt>String</tt> (optional). The name of this author.</t> name:</dt><dd> <tt>String</tt> (optional). The name of this author
</li> .
<li> </dd>
<t>uri: <tt>String</tt> (optional). A URI value that identifies t <dt>
he author.</t> uri:</dt><dd><t><tt>String</tt> (optional). A URI value that ident
</li> ifies the author.</t>
</ul> </dd>
</dl>
<figure anchor="example-notes"> <figure anchor="example-notes">
<name><tt>notes</tt> example</name> <name><tt>notes</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"notes": { "notes": {
"n1": { "n1": {
"note": "Open office hours are 1600 to 1715 EST, Mon-Fri", "note": "Open office hours are 1600 to 1715 EST, Mon-Fri",
"created": "2022-11-23T15:01:32Z", "created": "2022-11-23T15:01:32Z",
"author": { "author": {
"name": "John" "name": "John"
} }
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
<section anchor="personalInfo" numbered="true" toc="default"> <section anchor="personalInfo" numbered="true" toc="default">
<name>personalInfo</name> <name>personalInfo</name>
<t>Type: <tt>Id[PersonalInfo]</tt> (optional).</t> <t>Type: <tt>Id[PersonalInfo]</tt> (optional)</t>
<t>Defines personal information about the entity represented by this C <t>Defines personal information about the entity represented by the Ca
ard. rd.
A PersonalInfo object has the following properties:</t> A PersonalInfo object has the following properties:</t>
<ul spacing="normal"> <dl spacing="normal">
<li>@type: <tt>String</tt>. <dt>@type:</dt><dd> <tt>String</tt>.
This <bcp14>MUST</bcp14> be <tt>PersonalInfo</tt>, if set. This <bcp14>MUST</bcp14> be <tt>PersonalInfo</tt>, if set.
</li> </dd>
<li> <dt>
<t>kind: <tt>String</tt> (mandatory). kind:</dt><dd><t> <tt>String</tt> (mandatory).
Specifies the kind of this personal information. The <xref target Specifies the kind of personal information. The <xref target="enu
="enumerated-values">enumerated</xref> values are: merated-values">enumerated</xref> values are:
</t> </t>
<ul spacing="normal"> <ul spacing="normal">
<li><tt>expertise</tt>: a field of expertise or credential</li> <li><tt>expertise</tt>: a field of expertise or a credential</li >
<li><tt>hobby</tt>: a hobby</li> <li><tt>hobby</tt>: a hobby</li>
<li><tt>interest</tt>: an interest</li> <li><tt>interest</tt>: an interest</li>
</ul> </ul>
</li> </dd>
<li>value: <tt>String</tt> (mandatory). <dt>value:</dt><dd> <tt>String</tt> (mandatory).
The actual information.</li> The actual information.</dd>
<li> <dt>
<t>level: <tt>String</tt> (optional). level:</dt><dd><t> <tt>String</tt> (optional).
Indicates the level of expertise, or engagement in hobby or intere Indicates the level of expertise or engagement in hobby or interes
st. t.
The <xref target="enumerated-values">enumerated</xref> values ar e:</t> The <xref target="enumerated-values">enumerated</xref> values ar e:</t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
<tt>high</tt> <tt>high</tt>
</li> </li>
<li> <li>
<tt>medium</tt> <tt>medium</tt>
</li> </li>
<li> <li>
<tt>low</tt> <tt>low</tt>
</li> </li>
</ul> </ul>
</li> </dd>
<li>listAs: <tt>UnsignedInt</tt> (optional). <dt>listAs:</dt><dd> <tt>UnsignedInt</tt> (optional).
This defines the position of this personal information in the list o Defines the position of the personal information in the list of all
f all PersonalInfo objects having the same <tt>kind</tt> in this Card. If set, PersonalInfo objects that have the same <tt>kind</tt> in the Card. If set, the
the <tt>listAs</tt> value <bcp14>MUST</bcp14> be higher than zero. Multiple per <tt>listAs</tt> value <bcp14>MUST</bcp14> be higher than zero. Multiple persona
sonal information entries <bcp14>MAY</bcp14> have the same <tt>listAs</tt> prope l information entries <bcp14>MAY</bcp14> have the same <tt>listAs</tt> property
rty value, or none. Sorting such entries is implementation-specific. value or none. Sorting such entries is implementation-specific.
</li> </dd>
<li>label: <tt>String</tt> (optional). <dt>label:</dt><dd> <tt>String</tt> (optional).
A custom label. See <xref target="prop-label"/>.</li> A custom label. See <xref target="prop-label"/>.</dd>
</ul> </dl>
<figure anchor="example-personalInfo"> <figure anchor="example-personalInfo">
<name><tt>personalInfo</tt> example</name> <name><tt>personalInfo</tt> Example</name>
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"personalInfo": { "personalInfo": {
"pi2": { "pi2": {
"kind": "expertise", "kind": "expertise",
"value": "chemistry", "value": "chemistry",
"level": "high" "level": "high"
}, },
"pi1": { "pi1": {
"kind": "hobby", "kind": "hobby",
"value": "reading", "value": "reading",
skipping to change at line 1792 skipping to change at line 2210
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</section> </section>
</section> </section>
</section> </section>
<section anchor="iana-considerations" numbered="true" toc="default"> <section anchor="iana-considerations" numbered="true" toc="default">
<name>IANA Considerations</name> <name>IANA Considerations</name>
<section anchor="iana-media-type" numbered="true" toc="default"> <section anchor="iana-media-type" numbered="true" toc="default">
<name>Media Type Registration</name> <name>Media Type Registration</name>
<t><xref target="I-D.ietf-calext-jscontact"/> defines a media type for u
se with JSContact data formatted in JSON.</t> <!-- [rfced] We have included some specific questions about the IANA
<dl newline="true" spacing="normal"> text below. In addition to responding to those questions, please
review all of the IANA-related updates carefully and let us know
if any further updates are needed.
a) FYI: In Section 3.5.1, we placed the "Reference or Description" entry
below the "Change Controller" entry to match the order of the template
at https://www.iana.org/assignments/jscontact/.
b) In Sections 3.5.1, 3.6.1, and 3.7.1, may we update the definition of
"Change Controller" as shown below to make the text parallel with the
other entries?
Original:
Change Controller: This is who may request a change to this entry's
definition (IETF for RFCs from the IETF stream).
Perhaps:
Change Controller: Person or entity responsible for requesting a
change to the entry's definition (IETF for RFCs from the IETF stream).
c) In Sections 3.5.1, 3.6.1, 3.7.1, and 3.7.2:
- Is "Table 1" the correct reference in the sentences below (note that
there are 4 instances of each sentence)? Table 1 displays values from
the "JSContact Version" registry, not the "JSContact Enum Value" registry.
Please let us know if an update is needed to the registry name and/or the
table number.
Original:
The version MUST be one of the allowed values of the version property
in the JSContact Enum Value registry (see Table 1).
The Until Version value either MUST be not set, or one of the allowed
values of the version property in the JSContact Enum Value registry
(see Table 1).
d) In Section 3.5.2 (Table 2):
- Note that the content of Table 2 in the PDF output is cut off rather
than wrapping. We have opened an issue for this. Please see
<https://github.com/ietf-tools/xml2rfc/issues/1110>.
- As Table is 2 characters past the 72-character limit, may we reformat
the table to fit by removing the Ref column and linking each section
number to the corresponding Property Context? For an example of the output,
see <https://www.rfc-editor.org/authors/rfc9553-table.pdf#table-2>.
- FYI: We have moved the entry for the "version" property name to appear
above "year" so that it appears in alphabetical order. Please let us know if
you prefer the previous order.
- FYI: Under "contexts", "label", "pref", and "uri", we ordered
Section "1.4.4" first in the Reference column since this section
corresponds to these terms. Please let us know if you prefer otherwise.
- Under the "@type" property name in the "References" column, should
references to Sections "2.5.1.2" and "2.2.1.2" be added for
"AddressComponent" and "NameComponent", respectively, or does Sections
"2.5.1" and "2.2.1" serve as the references for these terms?
If Sections "2.5.1.2" and "2.2.1.2" are used, should Sections "2.5.1"
and "2.2.1" also be updated under the "AddressComponent" and
"NameComponent" entries, respectively, in Tables 2 and 4 for
consistency?
- Under "full" and "isOrdered", should "Section 2.5.1" be
"Section 2.5.1.1" instead for direct access to these terms?
- Under "phoneticScript" and "phoneticSystem", should
"Section 2.2.1" be "Section 2.2.1.1" instead for direct
access to these terms?
e) In Section 3.7.1, should the definition of "Reference" be added
after "Change Controller" to match the template at
https://www.iana.org/assignments/jscontact? Also, since "Initial
Contents" is not included in the template, should it be removed and
made into a separate paragraph?
f) In Section 3.7.2, should the definition of "Change Controller" be
added after "Until Version" to match the template at
https://www.iana.org/assignments/jscontact?
g) In Section 3.7.3:
- FYI: We have moved the "phoneticSystem" entry and table above the
"relation" entry and table so that it appears in alphabetical order.
Please let us know if you prefer otherwise.
- Should the following updates be made so that readers are taken directly
to the enum values?
- In Table 6, should Section "2.5.1" be updated to "2.5.1.1"?
- In Table 10, should Section "2.5.1" be updated to "2.5.1.2"?
- In Table 17, should Section "2.2.1" be updated to "2.2.1.2"?
-->
<t>This document defines a media type for use with JSContact data format
ted in JSON.</t>
<dl newline="false" spacing="normal">
<dt>Type name:</dt> <dt>Type name:</dt>
<dd>application</dd> <dd>application</dd>
<dt>Subtype name:</dt> <dt>Subtype name:</dt>
<dd>jscontact+json</dd> <dd>jscontact+json</dd>
<dt>Required parameters:</dt> <dt>Required parameters:</dt>
<dd> <dd>
<t>None</t> <t>None</t>
</dd> </dd>
<dt>Optional parameters:</dt> <dt>Optional parameters:</dt>
<dd> <dd><t>version</t> <t>This parameter conveys the version of the JSCont
<dl newline="false" spacing="normal"> act data in the body part. It <bcp14>MUST NOT</bcp14> occur more than once. If
<dt>version</dt> this parameter is set, then the values of all JSContact <xref target="iana-prop
<dd>This parameter conveys the version of the JSContact data in th erty-registry-version"><tt>version</tt></xref> properties in the body part <bcp1
e body part. It <bcp14>MUST NOT</bcp14> occur more than once. If this paramete 4>MUST</bcp14> match the parameter value.</t>
r is set, then the values of all JSContact <xref target="iana-property-registry-
version"><tt>version</tt></xref> properties in the body part <bcp14>MUST</bcp14>
match the parameter value.</dd>
</dl>
</dd> </dd>
<dt>Encoding considerations:</dt> <dt>Encoding considerations:</dt>
<dd>This is the same as the encoding considerations of application/jso n, as specified in <xref target="RFC8259" sectionFormat="of" section="11"/>.</dd > <dd>This is the same as the encoding considerations of application/jso n, as specified in <xref target="RFC8259" sectionFormat="of" section="11"/>.</dd >
<dt>Security considerations:</dt> <dt>Security considerations:</dt>
<dd> See <xref target="security-considerations" format="default"/> of <xref target="I-D.ietf-calext-jscontact"/>.</dd> <dd> See <xref target="security-considerations" format="default"/> of RFC 9553.</dd>
<dt>Interoperability considerations:</dt> <dt>Interoperability considerations:</dt>
<dd>While JSContact is designed to avoid ambiguities as much as possib le, when converting objects from other contact formats to/from JSContact, it is possible that differing representations for the same logical data or ambiguities in interpretation might arise. The semantic equivalence of two JSContact objec ts may be determined differently by different applications, for example, where U RL values differ in case between the two objects.</dd> <dd>While JSContact is designed to avoid ambiguities as much as possib le, when converting objects from other contact formats to/from JSContact, it is possible that differing representations for the same logical data or ambiguities in interpretation might arise. The semantic equivalence of two JSContact objec ts may be determined differently by different applications, for example, where U RL values differ in case between the two objects.</dd>
<dt>Published specification:</dt> <dt>Published specification:</dt>
<dd>TBD</dd> <dd>RFC 9553</dd>
<dt>Applications that use this media type:</dt> <dt>Applications that use this media type:</dt>
<dd>Applications that currently make use of the text/vcard media type can use this as an alternative.</dd> <dd>Applications that currently make use of the text/vCard media type can use this as an alternative.</dd>
<dt>Fragment identifier considerations:</dt> <dt>Fragment identifier considerations:</dt>
<dd>A JSON Pointer fragment identifier may be used, as defined in <xre f target="RFC6901" sectionFormat="comma" section="6"/>.</dd> <dd>A JSON Pointer fragment identifier may be used, as defined in <xre f target="RFC6901" sectionFormat="comma" section="6"/>.</dd>
<dt>Additional information:</dt> <dt>Additional information:</dt>
<dd> <dd><t><br/></t>
<dl newline="false" spacing="normal"> <dl newline="false" spacing="compact">
<dt>Magic number(s):</dt> <dt>Magic number(s):</dt>
<dd>N/A</dd> <dd>N/A</dd>
<dt>File extensions(s):</dt> <dt>File extensions(s):</dt>
<dd>N/A</dd> <dd>N/A</dd>
<dt>Macintosh file type code(s):</dt> <dt>Macintosh file type code(s):</dt>
<dd>N/A</dd> <dd>N/A</dd>
</dl> </dl>
</dd> </dd>
<dt>Person &amp; email address to contact for further information:</dt > <dt>Person &amp; email address to contact for further information:</dt >
<dd>calsify@ietf.org</dd> <dd>calsify@ietf.org</dd>
<dt>Intended usage:</dt> <dt>Intended usage:</dt>
<dd>COMMON</dd> <dd>COMMON</dd>
<dt>Restrictions on usage:</dt> <dt>Restrictions on usage:</dt>
<dd>N/A</dd> <dd>N/A</dd>
<dt>Author:</dt> <dt>Author:</dt>
<dd>See the "Author's Address" section of <xref target="I-D.ietf-calex t-jscontact"/>.</dd> <dd>See the "Authors' Addresses" section of RFC 9553.</dd>
<dt>Change controller:</dt> <dt>Change controller:</dt>
<dd>IETF</dd> <dd>IETF</dd>
</dl> </dl>
</section> </section>
<section anchor="iana-jscontact-registry" numbered="true" toc="default"> <section anchor="iana-jscontact-registry" numbered="true" toc="default">
<name>Creation of the "JSContact" Registry Group</name> <name>Creation of the JSContact Registry Group</name>
<t>IANA is asked to create the "JSContact" registry group. The new regi <t>IANA has created the "JSContact" registry group. The new registry de
stry definitions in the following sections all belong to that group.</t> finitions in the following sections all belong to that group.</t>
</section> </section>
<section anchor="iana-registry-policy" numbered="true" toc="default"> <section anchor="iana-registry-policy" numbered="true" toc="default">
<name>Registry Policy and Change Procedures</name> <name>Registry Policy and Change Procedures</name>
<t>Registry assignments that introduce <xref target="versioning">backwar
ds-incompatible</xref> changes require the JSContact major version to change, ot <!--[rfced] Since "backwards-incompatibility" is mentioned in Section
her changes only require to change the minor version. The registry policy for a 1.9.1, should the reference below be updated from Section 1.9 to
ssignments that require the JSContact major version to change is Standards Actio Section 1.9.1?
n (<xref target="RFC8126" sectionFormat="comma" section="4.9"/>). The registry
policy for other assignments is Specification Required (<xref target="RFC8126" s Original:
ectionFormat="comma" section="4.6"/>).</t> Registry assignments that introduce backwards-incompatible
<t>The Designated Expert decides if a major or minor version change is r (Section 1.9) changes require the JSContact major version
equired and assigns the new version to the <xref target="iana-version-registry"> to change, other changes only require to change the minor
Version Registry</xref>. Version numbers increment by one, and a major version version.
change resets the minor version to zero. An assignment may apply multiple chang
es and to more than one registry at once, in which case a single version change Perhaps:
is sufficient. If the registry policy is Specification Required, then the Desig Registry assignments that introduce backwards-incompatible
nated Expert may decide that it is enough to document the new assignment in the (Section 1.9.1) changes require the JSContact major version
Description item of the respective registry.</t> to change; other changes only require a change to the minor
version.
-->
<t>Registry assignments that introduce <xref target="versioning">backwar
ds-incompatible</xref> changes require the JSContact major version to change; ot
her changes only require a change to the minor version. The registry policy for
assignments that require the JSContact major version to change is Standards Act
ion (<xref target="RFC8126" sectionFormat="comma" section="4.9"/>). The registr
y policy for other assignments is Specification Required (<xref target="RFC8126"
sectionFormat="comma" section="4.6"/>).</t>
<t>The designated expert (DE) decides if a major or minor version change
is required and assigns the new version to the <xref target="iana-version-regis
try">"JSContact Version" registry</xref>. Version numbers increment by one, and
a major version change resets the minor version to zero. An assignment may app
ly multiple changes and to more than one registry at once, in which case a singl
e version change is sufficient. If the registry policy is Specification Require
d, then the DE may decide that it is enough to document the new assignment in th
e Description item of the respective registry.</t>
<t>A registration <bcp14>MUST</bcp14> have an intended usage of <tt>comm on</tt>, <tt>reserved</tt>, or <tt>obsolete</tt>.</t> <t>A registration <bcp14>MUST</bcp14> have an intended usage of <tt>comm on</tt>, <tt>reserved</tt>, or <tt>obsolete</tt>.</t>
<ul> <ul>
<li>A <tt>common</tt> usage denotes an item with shared semantics and syntax across systems. Up-to-date systems <bcp14>MUST</bcp14> expect such items to occur in JSContact data.</li> <li>A <tt>common</tt> usage denotes an item with shared semantics and syntax across systems. Up-to-date systems <bcp14>MUST</bcp14> expect such items to occur in JSContact data.</li>
<li>A <tt>reserved</tt> usage reserves an item in the registry without assigning semantics to avoid name collisions with future extensions or protocol use.</li> <li>A <tt>reserved</tt> usage reserves an item in the registry without assigning semantics to avoid name collisions with future extensions or protocol use.</li>
<li>An <tt>obsolete</tt> usage denotes an item that is no longer expec ted to be added by up-to-date systems. A new assignment has probably been defin ed covering the obsolete item's semantics.</li> <li>An <tt>obsolete</tt> usage denotes an item that is no longer expec ted to be added by up-to-date systems. A new assignment has probably been defin ed, covering the obsolete item's semantics.</li>
</ul> </ul>
<t>The registration procedure is not a formal standards process but rath er an administrative procedure intended to allow community comment and check whe ther it is coherent without excessive time delay. It is designed to encourage v endors to document and register new items they add for use cases not covered by the original specification, leading to increased interoperability.</t> <t>The registration procedure is not a formal standards process but rath er an administrative procedure intended to allow community comments and to check whether it is coherent without excessive time delay. It is designed to encoura ge vendors to document and register new items they add for use cases not covered by the original specification, leading to increased interoperability.</t>
<section anchor="iana-registry-preliminary-community-review" numbered="t rue" toc="default"> <section anchor="iana-registry-preliminary-community-review" numbered="t rue" toc="default">
<name>Preliminary Community Review</name> <name>Preliminary Community Review</name>
<t>Notice of a potential new registration <bcp14>MUST</bcp14> be sent <t>Notice of a potential new registration <bcp14>MUST</bcp14> be sent
to the Calext mailing list to the Calext WG mailing list
&lt;calsify@ietf.org&gt; for review. This mailing list is appropriat &lt;calsify@ietf.org&gt; for review. This mailing list is appropriat
e to solicit community feedback e for soliciting community feedback on a proposed registry assignment.</t>
on a proposed registry assignment.</t>
<t>The intent of the public posting to this list is to solicit comment s and feedback on the choice of <t>The intent of the public posting to this list is to solicit comment s and feedback on the choice of
the item name or value, the unambiguity of its description, and a rev iew of any the item name or value, the unambiguity of its description, and a rev iew of any
interoperability or security considerations. The submitter may sub mit a revised registration proposal interoperability or security considerations. The submitter may sub mit a revised registration proposal
or abandon the registration completely at any time.</t> or abandon the registration completely at any time.</t>
</section> </section>
<section anchor="iana-registry-submit-request-to-iana" numbered="true" t oc="default"> <section anchor="iana-registry-submit-request-to-iana" numbered="true" t oc="default">
<name>Submit Request to IANA</name> <name>Submit Request to IANA</name>
<t>Registration requests can be sent to &lt;iana@iana.org&gt;.</t> <t>Registration requests can be sent to IANA &lt;iana@iana.org&gt;.</t >
</section> </section>
<section anchor="iana-registry-designated-expert-review" numbered="true" toc="default"> <section anchor="iana-registry-designated-expert-review" numbered="true" toc="default">
<name>Designated Expert Review</name> <name>Designated Expert Review</name>
<t>The primary concern of the designated expert (DE) is preventing nam <t>The primary concern of the DE is preventing name collisions and enc
e collisions and encouraging the submitter to document security and privacy cons ouraging the submitter to document security and privacy considerations.</t>
iderations.</t> <t>A new type name, property name, or enumerated value <bcp14>MUST NOT
<t>A new type name, property name or enumerated value <bcp14>MUST NOT< </bcp14> differ only in case from an already-registered name or value.</t>
/bcp14> differ only in case from an already registered name or value.</t>
<t>For a common-use registration, the DE <t>For a common-use registration, the DE
is expected to confirm that suitable documentation is available to ensure interoperability. is expected to confirm that suitable documentation is available to ensure interoperability.
The DE should also verify that The DE should also verify that
the new assignment does not conflict with work that is active or alr eady published within the IETF.</t> the new assignment does not conflict with work that is active or alr eady published within the IETF.</t>
<t>The DE will either approve or deny the registration request and pub lish a notice of the decision <t>The DE will either approve or deny the registration request and pub lish a notice of the decision
to the Calext WG mailing list or its successor, as well as inform IAN A. A denial notice must be to the Calext WG mailing list or its successor, as well as inform IAN A. A denial notice must be
justified by an explanation, and, in the cases where it is possible , concrete suggestions on how the justified by an explanation, and in the cases where it is possible, concrete suggestions on how the
request can be modified to become acceptable should be provided.< /t> request can be modified to become acceptable should be provided.< /t>
</section> </section>
<section anchor="iana-registry-change-procedures" numbered="true" toc="d efault"> <section anchor="iana-registry-change-procedures" numbered="true" toc="d efault">
<name>Change Procedures</name> <name>Change Procedures</name>
<t>Once a JSContact registry group item has been published by IANA, th e change controller may request a <t>Once a JSContact registry group item has been published by IANA, th e Change Controller may request a
change to its definition. The same procedure that would be appropria te for the original registration change to its definition. The same procedure that would be appropria te for the original registration
request is used to process a change request.</t> request is used to process a change request.</t>
<t>JSContact registrations dot not get deleted; instead, items that ar e no longer believed appropriate for use are declared obsolete by a change to th eir "intended usage" field; such items will be clearly marked in the IANA regist ry.</t> <t>JSContact registrations do not get deleted; instead, items that are no longer believed appropriate for use are declared obsolete by a change to the ir "Intended Usage" field; such items will be clearly marked in the IANA registr y.</t>
<t>Significant changes to a JSContact registry item's definition shoul d be requested only when there are <t>Significant changes to a JSContact registry item's definition shoul d be requested only when there are
serious omissions or errors in the published specification, as such c hanges may cause serious omissions or errors in the published specification, as such c hanges may cause
interoperability issues. When review is required, a change request may be denied if it renders interoperability issues. When review is required, a change request may be denied if it renders
entities that were valid under the previous definition invalid un der the new definition.</t> entities that were valid under the previous definition invalid un der the new definition.</t>
</section> </section>
</section> </section>
<section anchor="iana-version-registry" numbered="true" toc="default"> <section anchor="iana-version-registry" numbered="true" toc="default">
<name>Creation of the "JSContact Version" Registry</name> <name>Creation of the JSContact Version Registry</name>
<t>IANA is asked to create the "JSContact Version" registry. The purpos <t>IANA has created the "JSContact Version" registry. The purpose of th
e of this new registry is to define the allowed value range of JSContact major a is new registry is to define the allowed value range of JSContact major and mino
nd minor version numbers.</t> r version numbers.</t>
<t>The registry entries sort numerically ascending by the "Major Version <t>The registry entries sort numerically in ascending order by the "Majo
" column.</t> r Version" column.</t>
<t>The registry process is outlined in <xref target="iana-registry-polic y" format="default"/>.</t> <t>The registry process is outlined in <xref target="iana-registry-polic y" format="default"/>.</t>
<section anchor="iana-version-registry-template" numbered="true" toc="de fault"> <section anchor="iana-version-registry-template" numbered="true" toc="de fault">
<name>"JSContact Version" Registry Template</name> <name>JSContact Version Registry Template</name>
<dl newline="false"> <dl newline="false">
<dt>Major Version:</dt> <dt>Major Version:</dt>
<dd>This is the numeric value of a JSContact major version number. It <bcp14>MUST</bcp14> be a positive integer.</dd> <dd>The numeric value of a JSContact major version number. It <bcp1 4>MUST</bcp14> be a positive integer.</dd>
<dt>Highest Minor Version:</dt> <dt>Highest Minor Version:</dt>
<dd> This is the maximum numeric value of a JSContact minor version for the given major version. It <bcp14>MUST</bcp14> be zero or a positive integ er. All numbers less than or equal this value are valid minor version values fo r the given major version.</dd> <dd> The maximum numeric value of a JSContact minor version for the given major version. It <bcp14>MUST</bcp14> be zero or a positive integer. All numbers less than or equal to this value are valid minor version values for the given major version.</dd>
</dl> </dl>
</section> </section>
<section anchor="iana-version-registry-contents" numbered="true" toc="de fault"> <section anchor="iana-version-registry-contents" numbered="true" toc="de fault">
<name>Initial Contents for the "JSContact Version" Registry</name> <name>Initial Contents of the JSContact Version Registry</name>
<t>The following table lists the initial valid major and minor version number ranges.</t> <t>The following table lists the initial valid major and minor version number ranges.</t>
<table anchor="tab-iana-version-registry" align="center"> <table anchor="tab-iana-version-registry" align="center">
<name>JSContact Versions</name> <name>JSContact Version Registry</name>
<thead> <thead>
<tr> <tr>
<th align="left">Major Version</th> <th align="left">Major Version</th>
<th align="left">Highest Minor Version</th> <th align="left">Highest Minor Version</th>
<th align="left">Reference</th>
</tr> </tr>
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td align="left">1</td> <td align="left">1</td>
<td align="left">0</td> <td align="left">0</td>
<td align="left">RFC 9553</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
</section> </section>
<section anchor="iana-property-registry" numbered="true" toc="default"> <section anchor="iana-property-registry" numbered="true" toc="default">
<name>Creation of the "JSContact Properties" Registry</name> <name>Creation of the JSContact Properties Registry</name>
<t>IANA is asked to create the "JSContact Properties" registry. The pur <t>IANA has created the "JSContact Properties" registry. The purpose of
pose of this new registry is to allow interoperability of extensions to JSContac this new registry is to allow interoperability of extensions to JSContact objec
t objects</t> ts.</t>
<t>The registry entries sort alphabetically ascending by the "Property N <t>The registry entries sort alphabetically in ascending order by the fo
ame" column first, "Property Context" second, "Since Version" third. Equal entr llowing columns: "Property Name" first, "Property Context" second, and "Since Ve
ies sort in any order.</t> rsion" third. Equal entries sort in any order.</t>
<t>The registry process for a new property is outlined in <xref target=" iana-registry-policy" format="default"/>.</t> <t>The registry process for a new property is outlined in <xref target=" iana-registry-policy" format="default"/>.</t>
<section anchor="iana-property-registry-template" numbered="true" toc="d efault"> <section anchor="iana-property-registry-template" numbered="true" toc="d efault">
<name>"JSContact Properties" Registry Template</name> <name>JSContact Properties Registry Template</name>
<dl newline="false"> <dl newline="false">
<dt>Property Name:</dt> <dt>Property Name:</dt>
<dd>This is the name of the property. The property name <bcp14>MUST <dd>The name of the property. The property name <bcp14>MUST NOT</bcp
NOT</bcp14> already be 14> already be
registered for registered for any of the object types listed in the "Property Context" field of
any of the object types listed in the "Property Context" this registration. Other object types <bcp14>MAY</bcp14> have already register
field of this registration. Other object ed a different property with the same name; however,
types <bcp14>MAY</bcp14> already have registered a di the same name <bcp14>MUST</bcp14> only be used when the semantics are analogous.
fferent property with the same name; however, </dd>
the same name <bcp14>MUST</bcp14> only be used wh
en the semantics are analogous.</dd>
<dt>Property Type:</dt> <dt>Property Type:</dt>
<dd> This is the type of this property, using type signatures, as sp ecified in <xref target="type-signatures" format="default"/>. <dd> The type of the property, using type signatures, as specified i n <xref target="type-signatures" format="default"/>.
The property type <bcp14>MUST</bcp14> be registered in the "J SContact Types" registry.</dd> The property type <bcp14>MUST</bcp14> be registered in the "J SContact Types" registry.</dd>
<dt>Property Context:</dt> <dt>Property Context:</dt>
<dd>This is a comma-separated list of JSContact object types (<xref <dd>A comma-separated list of JSContact object types (<xref target="
target="iana-type-registry-contents"/>) that contain this property.</dd> iana-type-registry-contents"/>) that contain the property.</dd>
<dt>Reference or Description:</dt>
<dd>This is a brief description or RFC number and section reference
where the property is specified (omitted for "reserved" property names). This mu
st include references to all RFC documents where this property is introduced or
updated.</dd>
<dt>Intended Usage:</dt> <dt>Intended Usage:</dt>
<dd>This may be "common", "reserved", or "obsolete".</dd> <dd>May be "common", "reserved", or "obsolete".</dd>
<dt>Since Version:</dt> <dt>Since Version:</dt>
<dd>This defines the JSContact version on which this property defini tion is based on. The version <bcp14>MUST</bcp14> be one of the allowed values of the <tt>version</tt> property in the JSContact Enum Value registry (see <xref target="tab-iana-version-registry"/>).</dd> <dd>The JSContact version on which the property definition is based. The version <bcp14>MUST</bcp14> be one of the allowed values of the <tt>versio n</tt> property in the "JSContact Enum Values" registry (see <xref target="tab-i ana-version-registry"/>).</dd>
<dt>Until Version:</dt> <dt>Until Version:</dt>
<dd>This defines the JSContact version after which this property got obsoleted and <bcp14>MUST NOT</bcp14> be used in later versions. The Until Ver sion value either <bcp14>MUST NOT</bcp14> be set, or be one of the allowed value s of the <tt>version</tt> property in the JSContact Enum Value registry (see <xr ef target="tab-iana-version-registry"/>).</dd> <dd>The JSContact version after which the property was obsoleted; th erefore, it <bcp14>MUST NOT</bcp14> be used in later versions. The Until Versio n value either <bcp14>MUST NOT</bcp14> be set or <bcp14>MUST</bcp14> be one of t he allowed values of the <tt>version</tt> property in the "JSContact Enum Values " registry (see <xref target="tab-iana-version-registry"/>).</dd>
<dt>Change Controller:</dt> <dt>Change Controller:</dt>
<dd>This is who may request a change to this entry's definition (<tt <dd>This is who may request a change to the entry's definition (<tt>
>IETF</tt> for RFCs from the IETF stream).</dd> IETF</tt> for RFCs from the IETF stream).</dd>
<dt>Reference or Description:</dt>
<dd>A brief description or RFC number and section reference where th
e property is specified (but omitted for "reserved" property names). This must i
nclude references to all RFC documents where this property is introduced or upda
ted.</dd>
</dl> </dl>
</section> </section>
<section anchor="iana-property-registry-contents" numbered="true" toc="d efault"> <section anchor="iana-property-registry-contents" numbered="true" toc="d efault">
<name>Initial Contents for the "JSContact Properties" Registry</name> <name>Initial Contents of the JSContact Properties Registry</name>
<t>The following table lists the initial <tt>common</tt> usage entries <t>The following table lists the initial <tt>common</tt> usage entries
of the "JSContact Properties" registry. The Since Version for all properties i of the "JSContact Properties" registry. For all properties, the Since Version
s <tt>1.0</tt>. The Until Version for all properties is not set. All RFC secti is <tt>1.0</tt>, the Until Version is not set, the Change Controller is <tt>IETF
on references are for <xref target="I-D.ietf-calext-jscontact"/>. The change co </tt>, and RFC section references are for RFC 9553.</t>
ntroller for all these properties is <tt>IETF</tt>.</t>
<table anchor="tab-iana-property-registry" align="center"> <table anchor="tab-iana-property-registry" align="center">
<name>JSContact Properties with "common" usage</name> <name>JSContact Properties with "common" Usage</name>
<thead> <thead>
<tr> <tr>
<th align="left">Property Name</th> <th align="left">Property Name</th>
<th align="left">Property Type</th> <th align="left">Property Type</th>
<th align="left">Property Context</th> <th align="left">Property Context</th>
<th align="left">Reference or Description</th> <th align="left">Ref</th>
</tr> </tr>
</thead> </thead>
<!-- Everything in here should be sorted alphabetically: table entri es by property name, the references for each property alphabetically by the obje ct type or property they refer to --> <!-- Everything in here should be sorted alphabetically: table entri es by property name, the references for each property alphabetically by the obje ct type or property they refer to -->
<tbody> <tbody>
<tr> <tr>
<td align="left">@type</td> <td align="left">@type</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Address, AddressComponent, Anniversary, Author, <td align="left">Address, AddressComponent, Anniversary, Author,
Card, Calendar, CryptoKey, Directory, EmailAddress, LanguagePref, Link, Media, Card, Calendar, CryptoKey, Directory, EmailAddress, LanguagePref, Link, Media,
Name, NameComponent, Nickname, Note, OnlineService, Organization, OrgUnit, Part Name, NameComponent, Nickname, Note, OnlineService, Organization, OrgUnit, Part
ialDate,PersonalInfo, Phone, Pronouns, Relation, SchedulingAddress, SpeakToAs, T ialDate, PersonalInfo, Phone, Pronouns, Relation, SchedulingAddress, SpeakToAs,
imestamp, Title</td> Timestamp, Title</td>
<td align="left"><xref target="addresses" format="default"/>, <x <td align="left">Sections <xref target="addresses" format="count
ref target="anniversaries" format="default"/>, <xref target="cardtype" format="d er"/>, <xref target="anniversaries" format="counter"/>, <xref target="cardtype"
efault"/>, <xref target="calendars" format="default"/>, <xref target="cryptoKeys format="counter"/>, <xref target="calendars" format="counter"/>, <xref target="c
" format="default"/>, <xref target="directories" format="default"/>, <xref targe ryptoKeys" format="counter"/>, <xref target="directories" format="counter"/>, <x
t="emails" format="default"/>, <xref target="preferredLanguages" format="default ref target="emails" format="counter"/>, <xref target="preferredLanguages" format
"/>, <xref target="links" format="default"/>, <xref target="media" format="defau ="counter"/>, <xref target="links" format="counter"/>, <xref target="media" form
lt"/>, <xref target="name" format="default"/>, <xref target="nicknames" format=" at="counter"/>, <xref target="name" format="counter"/>, <xref target="nicknames"
default"/>, <xref target="notes" format="default"/>, <xref target="onlineService format="counter"/>, <xref target="notes" format="counter"/>, <xref target="onli
s" format="default"/>, <xref target="organizations" format="default"/>, <xref ta neServices" format="counter"/>, <xref target="organizations" format="counter"/>,
rget="personalInfo" format="default"/>, <xref target="phones" format="default"/> <xref target="personalInfo" format="counter"/>, <xref target="phones" format="c
, <xref target="speakToAs" format="default"/>, <xref target="relatedTo" format=" ounter"/>, <xref target="speakToAs" format="counter"/>, <xref target="relatedTo"
default"/>, <xref target="schedulingAddresses" format="default"/>, <xref target= format="counter"/>, <xref target="schedulingAddresses" format="counter"/>, <xre
"titles" format="default"/></td> f target="titles" format="counter"/></td>
</tr>
<tr anchor="iana-property-registry-version">
<td align="left">version</td>
<td align="left">String</td>
<td align="left">Card</td>
<td align="left">
<xref target="prop-version" format="default"/>
</td>
</tr> </tr>
<tr> <tr>
<td align="left">address</td> <td align="left">address</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">EmailAddress</td> <td align="left">EmailAddress</td>
<td align="left"> <td align="left">
<xref target="emails" format="default"/> <xref target="emails" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2060 skipping to change at line 2580
<td align="left">NameComponent[]</td> <td align="left">NameComponent[]</td>
<td align="left">Name</td> <td align="left">Name</td>
<td align="left"> <td align="left">
<xref target="name" format="default"/> <xref target="name" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">contexts</td> <td align="left">contexts</td>
<td align="left">String[Boolean]</td> <td align="left">String[Boolean]</td>
<td align="left">Address, Calendar, CryptoKey, Directory, Email Address, LanguagePref, Link, Media, Nickname, OnlineService, Organization, Phone , Pronouns, SchedulingAddress</td> <td align="left">Address, Calendar, CryptoKey, Directory, Email Address, LanguagePref, Link, Media, Nickname, OnlineService, Organization, Phone , Pronouns, SchedulingAddress</td>
<td align="left"><xref target="prop-contexts" format="default"/> , <xref target="addresses" format="default"/>, <xref target="calendars" format=" default"/>, <xref target="cryptoKeys" format="default"/>, <xref target="director ies" format="default"/>, <xref target="emails" format="default"/>, <xref target= "preferredLanguages" format="default"/>, <xref target="links" format="default"/> , <xref target="media" format="default"/>, <xref target="nicknames" format="defa ult"/>, <xref target="onlineServices" format="default"/>, <xref target="organiza tions" format="default"/>, <xref target="phones" format="default"/>, <xref targe t="speakToAs" format="default"/>, <xref target="schedulingAddresses" format="def ault"/><xref target="resource" format="default"/></td> <td align="left">Sections <xref target="resource" format="count er"/>, <xref target="prop-contexts" format="counter"/>, <xref target="addresses" format="counter"/>, <xref target="calendars" format="counter"/>, <xref target=" cryptoKeys" format="counter"/>, <xref target="directories" format="counter"/>, < xref target="emails" format="counter"/>, <xref target="preferredLanguages" forma t="counter"/>, <xref target="links" format="counter"/>, <xref target="media" for mat="counter"/>, <xref target="nicknames" format="counter"/>, <xref target="onli neServices" format="counter"/>, <xref target="organizations" format="counter"/>, <xref target="phones" format="counter"/>, <xref target="speakToAs" format="coun ter"/>, <xref target="schedulingAddresses" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">coordinates</td> <td align="left">coordinates</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Address</td> <td align="left">Address</td>
<td align="left"> <td align="left">
<xref target="addresses" format="default"/> <xref target="addresses" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2082 skipping to change at line 2602
<td align="left">String</td> <td align="left">String</td>
<td align="left">Address</td> <td align="left">Address</td>
<td align="left"> <td align="left">
<xref target="addresses" format="default"/> <xref target="addresses" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">created</td> <td align="left">created</td>
<td align="left">UTCDateTime</td> <td align="left">UTCDateTime</td>
<td align="left">Card, Note</td> <td align="left">Card, Note</td>
<td align="left"><xref target="created" format="default"/>, <xre f target="notes" format="default"/></td> <td align="left">Sections <xref target="created" format="counter "/>, <xref target="notes" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">date</td> <td align="left">date</td>
<td align="left">PartialDate|Timestamp</td> <td align="left">PartialDate|Timestamp</td>
<td align="left">Anniversary</td> <td align="left">Anniversary</td>
<td align="left"> <td align="left">
<xref target="anniversaries" format="default"/> <xref target="anniversaries" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2104 skipping to change at line 2624
<td align="left">UnsignedInt</td> <td align="left">UnsignedInt</td>
<td align="left">PartialDate</td> <td align="left">PartialDate</td>
<td align="left"> <td align="left">
<xref target="anniversaries" format="default"/> <xref target="anniversaries" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">defaultSeparator</td> <td align="left">defaultSeparator</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Address, Name</td> <td align="left">Address, Name</td>
<td align="left"><xref target="addresses" format="default"/>, <td align="left">Sections <xref target="addresses" format="count
<xref target="name" format="default"/></td> er"/>,
<xref target="name" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">directories</td> <td align="left">directories</td>
<td align="left">Id[Directory]</td> <td align="left">Id[Directory]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="directories" format="default"/> <xref target="directories" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2135 skipping to change at line 2655
<td align="left">String[Boolean]</td> <td align="left">String[Boolean]</td>
<td align="left">Phone</td> <td align="left">Phone</td>
<td align="left"> <td align="left">
<xref target="phones" format="default"/> <xref target="phones" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">full</td> <td align="left">full</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Address, Name</td> <td align="left">Address, Name</td>
<td align="left"><xref target="addresses" format="default"/>, <td align="left">Sections <xref target="addresses" format="count
<xref target="name" format="default"/></td> er"/>,
<xref target="name" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">grammaticalGender</td> <td align="left">grammaticalGender</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">SpeakToAs</td> <td align="left">SpeakToAs</td>
<td align="left"> <td align="left">
<xref target="speakToAs" format="default"/> <xref target="speakToAs" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">isOrdered</td> <td align="left">isOrdered</td>
<td align="left">Boolean</td> <td align="left">Boolean</td>
<td align="left">Address, Name</td> <td align="left">Address, Name</td>
<td align="left"><xref target="addresses" format="default"/>, <td align="left">Sections <xref target="addresses" format="count
<xref target="name" format="default"/></td> er"/>,
<xref target="name" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">keywords</td> <td align="left">keywords</td>
<td align="left">String[Boolean]</td> <td align="left">String[Boolean]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="keywords" format="default"/> <xref target="keywords" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">kind</td> <td align="left">kind</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">AddressComponent, Anniversary, Calendar, Card, CryptoKey, Directory, Link, Media, NameComponent, PersonalInfo, Title</td> <td align="left">AddressComponent, Anniversary, Calendar, Card, CryptoKey, Directory, Link, Media, NameComponent, PersonalInfo, Title</td>
<td align="left"><xref target="addresses" format="default"/>, <x ref target="anniversaries" format="default"/>, <xref target="calendars" format=" default"/>, <xref target="kind" format="default"/>, <xref target="cryptoKeys" fo rmat="default"/>, <xref target="directories" format="default"/>, <xref target="l inks" format="default"/>, <xref target="media" format="default"/>, <xref target= "name" format="default"/>, <xref target="personalInfo" format="default"/>, <xref target="titles" format="default"/></td> <td align="left">Sections <xref target="addresses" format="count er"/>, <xref target="anniversaries" format="counter"/>, <xref target="calendars" format="counter"/>, <xref target="kind" format="counter"/>, <xref target="crypt oKeys" format="counter"/>, <xref target="directories" format="counter"/>, <xref target="links" format="counter"/>, <xref target="media" format="counter"/>, <xre f target="name" format="counter"/>, <xref target="personalInfo" format="counter" />, <xref target="titles" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">label</td> <td align="left">label</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Calendar, CryptoKey, Directory, EmailAddress, L ink, Media, OnlineService, PersonalInfo, Phone, SchedulingAddress</td> <td align="left">Calendar, CryptoKey, Directory, EmailAddress, L ink, Media, OnlineService, PersonalInfo, Phone, SchedulingAddress</td>
<td align="left"><xref target="prop-label" format="default"/>, < xref target="calendars" format="default"/>, <xref target="cryptoKeys" format="de fault"/>, <xref target="directories" format="default"/>, <xref target="emails" f ormat="default"/>, <xref target="links" format="default"/>, <xref target="media" format="default"/>, <xref target="onlineServices" format="default"/>, <xref tar get="personalInfo" format="default"/>, <xref target="phones" format="default"/>, <xref target="schedulingAddresses" format="default"/>, <xref target="resource" format="default"/></td> <td align="left">Sections <xref target="resource" format="counte r"/>, <xref target="prop-label" format="counter"/>, <xref target="calendars" for mat="counter"/>, <xref target="cryptoKeys" format="counter"/>, <xref target="dir ectories" format="counter"/>, <xref target="emails" format="counter"/>, <xref ta rget="links" format="counter"/>, <xref target="media" format="counter"/>, <xref target="onlineServices" format="counter"/>, <xref target="personalInfo" format=" counter"/>, <xref target="phones" format="counter"/>, <xref target="schedulingAd dresses" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">language</td> <td align="left">language</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Card, LanguagePref</td> <td align="left">Card, LanguagePref</td>
<td align="left"><xref target="language" format="default"/>, <td align="left">Sections <xref target="language" format="counte
<xref target="preferredLanguages" format="default"/></td> r"/>,
<xref target="preferredLanguages" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">level</td> <td align="left">level</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">PersonalInfo</td> <td align="left">PersonalInfo</td>
<td align="left"> <td align="left">
<xref target="personalInfo" format="default"/> <xref target="personalInfo" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2200 skipping to change at line 2720
<td align="left">Id[Link]</td> <td align="left">Id[Link]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="links" format="default"/> <xref target="links" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">listAs</td> <td align="left">listAs</td>
<td align="left">UnsignedInt</td> <td align="left">UnsignedInt</td>
<td align="left">Directory, PersonalInfo</td> <td align="left">Directory, PersonalInfo</td>
<td align="left"><xref target="directories" format="default"/>, <xref target="personalInfo" format="default"/></td> <td align="left">Sections <xref target="directories" format="cou nter"/>, <xref target="personalInfo" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">localizations</td> <td align="left">localizations</td>
<td align="left">String[PatchObject]</td> <td align="left">String[PatchObject]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="localizations" format="default"/> <xref target="localizations" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2222 skipping to change at line 2742
<td align="left">Id[Media]</td> <td align="left">Id[Media]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="media" format="default"/> <xref target="media" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">mediaType</td> <td align="left">mediaType</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Calendar, CryptoKey, Directory, Link, Media</td > <td align="left">Calendar, CryptoKey, Directory, Link, Media</td >
<td align="left"><xref target="resource" format="default"/>, <xr ef target="calendars" format="default"/>, <xref target="cryptoKeys" format="defa ult"/>, <xref target="directories" format="default"/>, <xref target="links" form at="default"/>, <xref target="media" format="default"/></td> <td align="left">Sections <xref target="resource" format="counte r"/>, <xref target="calendars" format="counter"/>, <xref target="cryptoKeys" for mat="counter"/>, <xref target="directories" format="counter"/>, <xref target="li nks" format="counter"/>, <xref target="media" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">members</td> <td align="left">members</td>
<td align="left">String[Boolean]</td> <td align="left">String[Boolean]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="members" format="default"/> <xref target="members" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2252 skipping to change at line 2772
<td align="left">Name</td> <td align="left">Name</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="name" format="default"/> <xref target="name" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">name</td> <td align="left">name</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Author, Nickname, Organization, OrgUnit, Title< /td> <td align="left">Author, Nickname, Organization, OrgUnit, Title< /td>
<td align="left"><xref target="notes" format="default"/>, <xref target="nicknames" format="default"/>, <xref target="organizations" format="defa ult"/>, <xref target="titles" format="default"/></td> <td align="left">Sections <xref target="notes" format="counter"/ >, <xref target="nicknames" format="counter"/>, <xref target="organizations" for mat="counter"/>, <xref target="titles" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">nicknames</td> <td align="left">nicknames</td>
<td align="left">Id[Nickname]</td> <td align="left">Id[Nickname]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="nicknames" format="default"/> <xref target="nicknames" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2330 skipping to change at line 2850
<td align="left">Id[Phone]</td> <td align="left">Id[Phone]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="phones" format="default"/> <xref target="phones" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">phonetic</td> <td align="left">phonetic</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">AddressComponent, NameComponent</td> <td align="left">AddressComponent, NameComponent</td>
<td align="left"><xref target="addresscomponent" format="default <td align="left">Sections <xref target="addresscomponent" format
"/>, ="counter"/>,
<xref target="namecomponent" format="default"/></td> <xref target="namecomponent" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">phoneticScript</td> <td align="left">phoneticScript</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Address, Name</td> <td align="left">Address, Name</td>
<td align="left"><xref target="name" format="default"/>, <td align="left">Sections <xref target="name" format="counter"/>
<xref target="addresses" format="default"/></td> ,
<xref target="addresses" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">phoneticSystem</td> <td align="left">phoneticSystem</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Address, Name</td> <td align="left">Address, Name</td>
<td align="left"><xref target="name" format="default"/>, <td align="left">Sections <xref target="name" format="counter"/>
<xref target="addresses" format="default"/></td> ,
<xref target="addresses" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">place</td> <td align="left">place</td>
<td align="left">Address</td> <td align="left">Address</td>
<td align="left">Anniversary</td> <td align="left">Anniversary</td>
<td align="left"> <td align="left">
<xref target="anniversaries" format="default"/> <xref target="anniversaries" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">pref</td> <td align="left">pref</td>
<td align="left">UnsignedInt</td> <td align="left">UnsignedInt</td>
<td align="left">Address, Calendar, CryptoKey, Directory, Email Address, LanguagePref, Link, Media, Nickname, OnlineService, Phone, Pronouns, Sc hedulingAddress</td> <td align="left">Address, Calendar, CryptoKey, Directory, Email Address, LanguagePref, Link, Media, Nickname, OnlineService, Phone, Pronouns, Sc hedulingAddress</td>
<td align="left"><xref target="prop-pref" format="default"/>, <x ref target="addresses" format="default"/>, <xref target="calendars" format="defa ult"/>, <xref target="cryptoKeys" format="default"/>, <xref target="directories" format="default"/>, <xref target="emails" format="default"/>, <xref target="pre ferredLanguages" format="default"/>, <xref target="links" format="default"/>, <x ref target="media" format="default"/>, <xref target="nicknames" format="default" />, <xref target="onlineServices" format="default"/>, <xref target="phones" form at="default"/>, <xref target="speakToAs" format="default"/>, <xref target="sched ulingAddresses" format="default"/>, <xref target="resource" format="default"/></ td> <td align="left">Sections <xref target="resource" format="counte r"/>, <xref target="prop-pref" format="counter"/>, <xref target="addresses" form at="counter"/>, <xref target="calendars" format="counter"/>, <xref target="crypt oKeys" format="counter"/>, <xref target="directories" format="counter"/>, <xref target="emails" format="counter"/>, <xref target="preferredLanguages" format="co unter"/>, <xref target="links" format="counter"/>, <xref target="media" format=" counter"/>, <xref target="nicknames" format="counter"/>, <xref target="onlineSer vices" format="counter"/>, <xref target="phones" format="counter"/>, <xref targe t="speakToAs" format="counter"/>, <xref target="schedulingAddresses" format="cou nter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">preferredLanguages</td> <td align="left">preferredLanguages</td>
<td align="left">String[LanguagePref]</td> <td align="left">String[LanguagePref]</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="preferredLanguages" format="default"/> <xref target="preferredLanguages" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2485 skipping to change at line 3005
<td align="left">UTCDateTime</td> <td align="left">UTCDateTime</td>
<td align="left">Card</td> <td align="left">Card</td>
<td align="left"> <td align="left">
<xref target="updated" format="default"/> <xref target="updated" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">uri</td> <td align="left">uri</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">Author, Calendar, CryptoKey, Directory, Link, M edia, OnlineService, SchedulingAddress</td> <td align="left">Author, Calendar, CryptoKey, Directory, Link, M edia, OnlineService, SchedulingAddress</td>
<td align="left"><xref target="notes" format="default"/>, <xref target="resource" format="default"/>, <xref target="calendars" format="default"/ >, <xref target="cryptoKeys" format="default"/>, <xref target="directories" form at="default"/>, <xref target="links" format="default"/>, <xref target="media" fo rmat="default"/>, <xref target="onlineServices" format="default"/>, <xref target ="schedulingAddresses" format="default"/></td> <td align="left">Sections <xref target="resource" format="counte r"/>, <xref target="notes" format="counter"/>, <xref target="calendars" format=" counter"/>, <xref target="cryptoKeys" format="counter"/>, <xref target="director ies" format="counter"/>, <xref target="links" format="counter"/>, <xref target=" media" format="counter"/>, <xref target="onlineServices" format="counter"/>, <xr ef target="schedulingAddresses" format="counter"/></td>
</tr> </tr>
<tr> <tr>
<td align="left">user</td> <td align="left">user</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">OnlineService</td> <td align="left">OnlineService</td>
<td align="left"> <td align="left">
<xref target="onlineServices" format="default"/> <xref target="onlineServices" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
skipping to change at line 2507 skipping to change at line 3027
<td align="left">UTCDateTime</td> <td align="left">UTCDateTime</td>
<td align="left">Timestamp</td> <td align="left">Timestamp</td>
<td align="left"> <td align="left">
<xref target="anniversaries" format="default"/> <xref target="anniversaries" format="default"/>
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">value</td> <td align="left">value</td>
<td align="left">String</td> <td align="left">String</td>
<td align="left">AddressComponent, NameComponent, PersonalInfo</ td> <td align="left">AddressComponent, NameComponent, PersonalInfo</ td>
<td align="left"><xref target="addresses" format="default"/>, <td align="left">Sections <xref target="addresses" format="count
<xref target="name" format="default"/>, er"/>,
<xref target="personalInfo" format="default"/></td> <xref target="name" format="counter"/>,
<xref target="personalInfo" format="counter"/></td>
</tr>
<tr anchor="iana-property-registry-version">
<td align="left">version</td>
<td align="left">String</td>
<td align="left">Card</td>
<td align="left">
<xref target="prop-version" format="default"/>
</td>
</tr> </tr>
<tr> <tr>
<td align="left">year</td> <td align="left">year</td>
<td align="left">UnsignedInt</td> <td align="left">UnsignedInt</td>
<td align="left">PartialDate</td> <td align="left">PartialDate</td>
<td align="left"> <td align="left">
<xref target="anniversaries" format="default"/> <xref target="anniversaries" format="default"/>
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<t>The following table lists the initial <tt>reserved</tt> usage entri es of the "JSContact Properties" registry. All RFC section references are for < xref target="I-D.ietf-calext-jscontact"/>. The change controller for all these properties is <tt>IETF</tt>.</t> <t>The following table lists the initial <tt>reserved</tt> usage entri es of the "JSContact Properties" registry. For this property, the Change Contro ller is <tt>IETF</tt>, and the RFC section reference is for RFC 9553.</t>
<table anchor="tab-iana-reserved-property-registry" align="center"> <table anchor="tab-iana-reserved-property-registry" align="center">
<name>JSContact Properties with "reserved" usage</name> <name>JSContact Properties with "reserved" Usage</name>
<thead> <thead>
<tr> <tr>
<th align="left">Property Name</th> <th align="left">Property Name</th>
<th align="left">Property Type</th> <th align="left">Property Type</th>
<th align="left">Property Context</th> <th align="left">Property Context</th>
<th align="left">Reference or Description</th> <th align="left">Reference/Description</th>
<th align="left">Intended Usage</th> <th align="left">Intended Usage</th>
</tr> </tr>
</thead> </thead>
<!-- Everything in here should be sorted alphabetically: table entri es by property name, the references for each property alphabetically by the obje ct type or property they refer to --> <!-- Everything in here should be sorted alphabetically: table entri es by property name, the references for each property alphabetically by the obje ct type or property they refer to -->
<tbody> <tbody>
<tr> <tr>
<td align="left">extra</td> <td align="left">extra</td>
<td align="left">not applicable</td> <td align="left">not applicable</td>
<td align="left">not applicable</td> <td align="left">not applicable</td>
<td align="left"> <td align="left">
<xref target="prop-extra" format="default"/> <xref target="prop-extra" format="default"/>
</td> </td>
<td align="left">reserved</td> <td align="left">reserved</td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
</section> </section>
<section anchor="iana-type-registry" numbered="true" toc="default"> <section anchor="iana-type-registry" numbered="true" toc="default">
<name>Creation of the "JSContact Types" Registry</name> <name>Creation of the JSContact Types Registry</name>
<t>IANA is asked to create the "JSContact Types" registry. The purpose <t>IANA has created the "JSContact Types" registry. The purpose of this
of this new registry is to avoid name collisions for JSContact type names and pr new registry is to avoid name collisions for JSContact type names and provide a
ovide a complete reference for all data types used for JSContact property values complete reference for all data types used for JSContact property values.</t>
.</t> <t>The registry entries sort alphabetically in ascending order by the "T
<t>The registry entries sort alphabetically ascending by the "Type Name" ype Name" column. Equal entries sort in any order.</t>
column. Equal entries sort in any order.</t>
<t>The registry process for a new type is outlined in <xref target="iana -registry-policy" format="default"/>.</t> <t>The registry process for a new type is outlined in <xref target="iana -registry-policy" format="default"/>.</t>
<section anchor="iana-type-registry-template" numbered="true" toc="defau lt"> <section anchor="iana-type-registry-template" numbered="true" toc="defau lt">
<name>"JSContact Types" Registry Template</name> <name>JSContact Types Registry Template</name>
<dl newline="false"> <dl newline="false">
<dt>Type Name:</dt> <dt>Type Name:</dt>
<dd>the name of the type</dd> <dd>The name of the type.</dd>
<dt>Reference or Description:</dt>
<dd>a brief description or RFC number and section reference where th
e Type is specified (may be omitted for "reserved" type names)</dd>
<dt>Intended Usage:</dt> <dt>Intended Usage:</dt>
<dd>common, reserved, or obsolete</dd> <dd>May be "common", "reserved", or "obsolete".</dd>
<dt>Since Version:</dt> <dt>Since Version:</dt>
<dd>This defines the JSContact version on which this type definition is based on. The version <bcp14>MUST</bcp14> be one of the allowed values of t he <tt>version</tt> property in the JSContact Enum Value registry (see <xref tar get="tab-iana-version-registry"/>).</dd> <dd>The JSContact version on which this type definition is based. T he version <bcp14>MUST</bcp14> be one of the allowed values of the <tt>version</ tt> property in the "JSContact Enum Values" registry (see <xref target="tab-iana -version-registry"/>).</dd>
<dt>Until Version:</dt> <dt>Until Version:</dt>
<dd>This defines the JSContact version after which this type definit ion got obsoleted and <bcp14>MUST NOT</bcp14> be used in later versions. The Un til Version value either <bcp14>MUST</bcp14> be not set, or one of the allowed v alues of the <tt>version</tt> property in the JSContact Enum Value registry (see <xref target="tab-iana-version-registry"/>).</dd> <dd>The JSContact version after which the type definition was obsole ted; therefore, it <bcp14>MUST NOT</bcp14> be used in later versions. The Until Version value either <bcp14>MUST NOT</bcp14> be set or <bcp14>MUST</bcp14> be o ne of the allowed values of the <tt>version</tt> property in the "JSContact Enum Values" registry (see <xref target="tab-iana-version-registry"/>).</dd>
<dt>Change Controller:</dt> <dt>Change Controller:</dt>
<dd>This is who may request a change to this entry's definition (<tt <dd>This is who may request a change to the entry's definition (<tt>
>IETF</tt> for RFCs from the IETF stream).</dd> IETF</tt> for RFCs from the IETF stream).</dd>
<dt>Reference or Description:</dt>
<dd>A brief description or RFC number and section reference where th
e Type is specified (may be omitted for "reserved" type names).</dd>
</dl> </dl>
</section> </section>
<section anchor="iana-type-registry-contents" numbered="true" toc="defau lt"> <section anchor="iana-type-registry-contents" numbered="true" toc="defau lt">
<name>Initial Contents for the "JSContact Types" Registry</name> <name>Initial Contents of the JSContact Types Registry</name>
<t>The following table lists the initial <tt>common</tt> usage entries <t>The following table lists the initial <tt>common</tt> usage entries
of the JSContact Types registry. The Since Version for all types is <tt>1.0</t in the "JSContact Types" registry. For all of these types, the Since Version i
t>. The Until Version for all types is not set. All RFC section references are s <tt>1.0</tt>, the Until Version is not set, the Change Controller is <tt>IETF<
for <xref target="I-D.ietf-calext-jscontact"/>. The change controller for all /tt>, and RFC section references are for RFC 9553.</t>
these properties is <tt>IETF</tt>.</t>
<table anchor="tab-iana-type-registry-common" align="left"> <table anchor="tab-iana-type-registry-common" align="left">
<name>JSContact Types with "common" usage</name> <name>JSContact Types with "common" Usage</name>
<thead> <thead>
<tr> <tr>
<th align="left">Type Name</th> <th align="left">Type Name</th>
<th align="left">Reference or Description</th> <th align="left">Reference or Description</th>
</tr> </tr>
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td align="left">Address</td> <td align="left">Address</td>
<td align="left"> <td align="left">
skipping to change at line 2800 skipping to change at line 3328
</td> </td>
</tr> </tr>
<tr> <tr>
<td align="left">UTCDateTime</td> <td align="left">UTCDateTime</td>
<td align="left"> <td align="left">
<xref target="utcdatetime" format="default"/> <xref target="utcdatetime" format="default"/>
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
<t>The following table lists the initial <tt>reserved</tt> usage entri es of the JSContact Types registry. All types are for version <tt>1.0</tt>. Al l RFC section references are for <xref target="I-D.ietf-calext-jscontact"/>. Th e change controller for all these properties is <tt>IETF</tt>.</t> <t>The following table lists the initial <tt>reserved</tt> usage entry of the "JSContact Types" registry. For this type, the version is <tt>1.0</tt>, the Change Controller is <tt>IETF</tt>, and the RFC section reference is for RF C 9553.</t>
<table anchor="tab-iana-type-registry-reserved" align="left"> <table anchor="tab-iana-type-registry-reserved" align="left">
<name>JSContact Types with "reserved" usage</name> <name>JSContact Types with "reserved" Usage</name>
<thead> <thead>
<tr> <tr>
<th align="left">Type Name</th> <th align="left">Type Name</th>
<th align="left">Reference or Description</th> <th align="left">Reference or Description</th>
</tr> </tr>
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td align="left">Resource</td> <td align="left">Resource</td>
<td align="left"> <td align="left">
<xref target="resource" format="default"/> <xref target="resource" format="default"/>
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</section> </section>
</section> </section>
<section anchor="iana-enum-registry" numbered="true" toc="default"> <section anchor="iana-enum-registry" numbered="true" toc="default">
<name>Creation of the "JSContact Enum Values" Registry</name> <name>Creation of the JSContact Enum Values Registry</name>
<t>IANA is asked to create the "JSContact Enum Values" registry. The pu <t>IANA has created the "JSContact Enum Values" registry. The purpose o
rpose of the new registry is to allow interoperable extension of semantics for f the new registry is to allow interoperable extension of semantics for JSConta
JSContact properties with enumerable values. Each such property will have a sub ct properties with enumerable values. Each such property will have a subregistr
registry of allowed values.</t> y of allowed values.</t>
<t>The registry entries sort alphabetically ascending by the "Property N <t>The registry entries sort alphabetically in ascending order by the fo
ame" column first, "Property Context" second, "Since Version" third. The enum v llowing columns: "Property Name" first, "Property Context" second, and "Since Ve
alues sort alphabetically ascending. Equal entries sort in any order.</t> rsion" third. The enum values sort alphabetically in ascending order. Equal en
tries sort in any order.</t>
<t>The registry process for a new enum value or adding a new enumerable property is outlined in <xref target="iana-registry-policy" format="default"/>.< /t> <t>The registry process for a new enum value or adding a new enumerable property is outlined in <xref target="iana-registry-policy" format="default"/>.< /t>
<section anchor="iana-enum-registry-registry-template" numbered="true" t oc="default"> <section anchor="iana-enum-registry-registry-template" numbered="true" t oc="default">
<name>"JSContact Enum Values" Registry Property Template</name> <name>JSContact Enum Values Registry Property Template</name>
<t>This template is for adding a subregistry for a new enumerable prop <t>This template is for adding a subregistry for a new enumerable prop
erty to the "JSContact Enum" registry.</t> erty to the "JSContact Enum Values" registry.</t>
<dl newline="false"> <dl newline="false">
<dt>Property Name:</dt> <dt>Property Name:</dt>
<dd>These are the name(s) of the property or properties where these values may be used. This <bcp14>MUST</bcp14> be registered in the "JSContact Pr operties" registry.</dd> <dd>The name(s) of the property or properties where these values may be used. This <bcp14>MUST</bcp14> be registered in the "JSContact Properties" registry.</dd>
<dt>Context:</dt> <dt>Context:</dt>
<dd>This is the list of allowed object types where the property or p roperties may appear, as registered in the "JSContact Properties" registry. Thi s disambiguates where there may be two distinct properties with the same name in different contexts.</dd> <dd>The list of allowed object types where the property or propertie s may appear, as registered in the "JSContact Properties" registry. This disamb iguates where there may be two distinct properties with the same name in differe nt contexts.</dd>
<dt>Since Version:</dt> <dt>Since Version:</dt>
<dd>This defines the JSContact version on which this enum value defi nition is based on. The version <bcp14>MUST</bcp14> be one of the allowed value s of the <tt>version</tt> property in the JSContact Enum Value registry (see <xr ef target="tab-iana-version-registry"/>).</dd> <dd>The JSContact version on which the enum value definition is base d. The version <bcp14>MUST</bcp14> be one of the allowed values of the <tt>vers ion</tt> property in the "JSContact Enum Values" registry (see <xref target="tab -iana-version-registry"/>).</dd>
<dt>Until Version:</dt> <dt>Until Version:</dt>
<dd>This defines the JSContact version after which this enum value d efinition got obsoleted and <bcp14>MUST NOT</bcp14> be used in later versions. The Until Version value either <bcp14>MUST</bcp14> be not set, or one of the all owed values of the <tt>version</tt> property in the JSContact Enum Value registr y (see <xref target="tab-iana-version-registry"/>).</dd> <dd>The JSContact version after which the enum value definition was obsoleted; therefore, the enum value definition <bcp14>MUST NOT</bcp14> be used in later versions. The Until Version value either <bcp14>MUST NOT</bcp14> be se t or <bcp14>MUST</bcp14> be one of the allowed values of the <tt>version</tt> pr operty in the "JSContact Enum Values" registry (see <xref target="tab-iana-versi on-registry"/>).</dd>
<dt>Change Controller:</dt> <dt>Change Controller:</dt>
<dd>This is who may request a change to this entry's definition (<tt >IETF</tt> for RFCs from the IETF stream).</dd> <dd>This is who may request a change to the entry's definition (<tt> IETF</tt> for RFCs from the IETF stream).</dd>
<dt>Initial Contents:</dt> <dt>Initial Contents:</dt>
<dd>This is the initial list of defined values for this enum, using the template defined in <xref target="iana-enum-registry-value-template" format= "default"/>. A subregistry will be created with these values for this property name/context tuple.</dd> <dd>The initial list of defined values for the enum, using the templ ate defined in <xref target="iana-enum-registry-value-template" format="default" />. A subregistry will be created with these values for this property name/cont ext tuple.</dd>
</dl> </dl>
</section> </section>
<section anchor="iana-enum-registry-value-template" numbered="true" toc= "default"> <section anchor="iana-enum-registry-value-template" numbered="true" toc= "default">
<name>"JSContact Enum Values" Registry Value Template</name> <name>JSContact Enum Values Registry Value Template</name>
<t>This template is for adding a new enum value to a subregistry in th <t>This template is for adding a new enum value to a subregistry in th
e JSContact Enum registry.</t> e "JSContact Enum Values" registry.</t>
<dl newline="false"> <dl newline="false">
<dt>Enum Value:</dt> <dt>Enum Value:</dt>
<dd>The verbatim value of the enum.</dd> <dd>The verbatim value of the enum.</dd>
<dt>Reference or Description:</dt>
<dd>A brief description or RFC number and section reference for the
semantics of this value.</dd>
<dt>Since Version:</dt> <dt>Since Version:</dt>
<dd>The JSContact version on which the enum value definition is base d on. The version <bcp14>MUST</bcp14> be one of the allowed values of the <tt>v ersion</tt> property in the JSContact Enum Value registry (see <xref target="tab -iana-version-registry"/>).</dd> <dd>The JSContact version on which the enum value definition is base d. The version <bcp14>MUST</bcp14> be one of the allowed values of the <tt>vers ion</tt> property in the "JSContact Enum Values" registry (see <xref target="tab -iana-version-registry"/>).</dd>
<dt>Until Version:</dt> <dt>Until Version:</dt>
<dd>The JSContact version after which this enum value got obsoleted <dd>The JSContact version after which the enum value was obsoleted;
and <bcp14>MUST NOT</bcp14> be used in later versions. The Until Version value therefore, the enum value <bcp14>MUST NOT</bcp14> be used in later versions. Th
either <bcp14>MUST</bcp14> be not set, or one of the allowed values of the <tt>v e Until Version value either <bcp14>MUST NOT</bcp14> be set or <bcp14>MUST</bcp1
ersion</tt> property in the JSContact Enum Value registry (see <xref target="tab 4> be one of the allowed values of the <tt>version</tt> property in the "JSConta
-iana-version-registry"/>).</dd> ct Enum Values" registry (see <xref target="tab-iana-version-registry"/>).</dd>
<dt>Reference or Description:</dt>
<dd>A brief description or RFC number and section reference for the
semantics of the value.</dd>
</dl> </dl>
</section> </section>
<section anchor="iana-enum-registry-contents" numbered="true" toc="defau lt"> <section anchor="iana-enum-registry-contents" numbered="true" toc="defau lt">
<name>Initial Contents for the "JSContact Enum Values" Registry</name> <name>Initial Contents of the JSContact Enum Values Registry</name>
<t>For each subregistry created in this section, all RFC section refer <t>For all entries in each subregistry created in this section, the Si
ences are for <xref target="I-D.ietf-calext-jscontact"/>. For all entries, the nce Version is <tt>1.0</tt>, the Until Version is not set, the Change Controller
Since Version is <tt>1.0</tt>, the Until Version is not set, the Change Controll is <tt>IETF</tt>, and RFC section references are for RFC 9553.</t>
er is <tt>IETF</tt>.</t>
<dl spacing="compact" newline="false" indent="20"> <dl spacing="compact" newline="false" indent="20">
<dt>Property Name:</dt> <dt>Property Name:</dt>
<dd>contexts</dd> <dd>contexts</dd>
<dt>Context:</dt> <dt>Context:</dt>
<dd>Address</dd> <dd>Address</dd>
<dt>Initial Contents:</dt> <dt>Initial Contents:</dt>
<dd> <dd>
<table anchor="tab-iana-enum-addr-contexts" align="left"> <table anchor="tab-iana-enum-addr-contexts" align="left">
<name>JSContact Enum Values for contexts (Context: Address)</nam e> <name>JSContact Enum Values for contexts (Context: Address)</nam e>
<thead> <thead>
skipping to change at line 2912 skipping to change at line 3440
</dd> </dd>
</dl> </dl>
<dl spacing="compact" newline="false" indent="20"> <dl spacing="compact" newline="false" indent="20">
<dt>Property Name:</dt> <dt>Property Name:</dt>
<dd>contexts</dd> <dd>contexts</dd>
<dt>Context:</dt> <dt>Context:</dt>
<dd>Calendar, CryptoKey, Directory, EmailAddress, LanguagePref, Lin k, Media, Nickname, OnlineService, Organization, Phone, Pronouns, SchedulingAddr ess</dd> <dd>Calendar, CryptoKey, Directory, EmailAddress, LanguagePref, Lin k, Media, Nickname, OnlineService, Organization, Phone, Pronouns, SchedulingAddr ess</dd>
<dt>Initial Contents:</dt> <dt>Initial Contents:</dt>
<dd> <dd>
<table anchor="tab-iana-enum-contexts" align="left"> <table anchor="tab-iana-enum-contexts" align="left">
<name>JSContact Enum Values for contexts (Context: Calendar, Cr yptoKey, Directory, EmailAddress, LanguagePref, Link, Media, Nickname, OnlineSer vice, Organization, Phone, Pronouns, SchedulingAddress)</name> <name>JSContact Enum Values for contexts (Context: Calendar, Cry ptoKey, Directory, EmailAddress, LanguagePref, Link, Media, Nickname, OnlineServ ice, Organization, Phone, Pronouns, SchedulingAddress)</name>
<thead> <thead>
<tr> <tr>
<th align="left">Enum Value</th> <th align="left">Enum Value</th>
<th align="left">Reference or Description</th> <th align="left">Reference or Description</th>
</tr> </tr>
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td align="left">private</td> <td align="left">private</td>
<td align="left"> <td align="left">
skipping to change at line 3012 skipping to change at line 3540
</dd> </dd>
</dl> </dl>
<dl spacing="compact" newline="false" indent="20"> <dl spacing="compact" newline="false" indent="20">
<dt>Property Name:</dt> <dt>Property Name:</dt>
<dd>grammaticalGender</dd> <dd>grammaticalGender</dd>
<dt>Context:</dt> <dt>Context:</dt>
<dd>SpeakToAs</dd> <dd>SpeakToAs</dd>
<dt>Initial Contents:</dt> <dt>Initial Contents:</dt>
<dd> <dd>
<table anchor="tab-iana-enum-speaktoas-grammaticalgender" align="l eft"> <table anchor="tab-iana-enum-speaktoas-grammaticalgender" align="l eft">
<name>JSContact Enum Values for kind (Context: SpeakToAs)</name> <name>JSContact Enum Values for grammaticalGender (Context: Spea kToAs)</name>
<thead> <thead>
<tr> <tr>
<th align="left">Enum Value</th> <th align="left">Enum Value</th>
<th align="left">Reference or Description</th> <th align="left">Reference or Description</th>
</tr> </tr>
</thead> </thead>
<tbody> <tbody>
<tr> <tr>
<td align="left">animate</td> <td align="left">animate</td>
<td align="left"> <td align="left">
skipping to change at line 3582 skipping to change at line 4110
<td align="left"> <td align="left">
<xref target="personalInfo" format="default"/> <xref target="personalInfo" format="default"/>
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</dd> </dd>
</dl> </dl>
<dl spacing="compact" newline="false" indent="20"> <dl spacing="compact" newline="false" indent="20">
<dt>Property Name:</dt> <dt>Property Name:</dt>
<dd>phoneticSystem</dd>
<dt>Context:</dt>
<dd>Address, Name</dd>
<dt>Initial Contents:</dt>
<dd>
<table anchor="tab-iana-enum-pronounce-system" align="left">
<name>JSContact Enum Values for phoneticSystem (Context: Address
, Name)</name>
<thead>
<tr>
<th align="left">Enum Value</th>
<th align="left">Reference or Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">ipa</td>
<td align="left">
<xref target="prop-phonetic" format="default"/>
</td>
</tr>
<tr>
<td align="left">jyut</td>
<td align="left">
<xref target="prop-phonetic" format="default"/>
</td>
</tr>
<tr>
<td align="left">piny</td>
<td align="left">
<xref target="prop-phonetic" format="default"/>
</td>
</tr>
</tbody>
</table>
</dd>
</dl>
<dl spacing="compact" newline="false" indent="20">
<dt>Property Name:</dt>
<dd>relation</dd> <dd>relation</dd>
<dt>Context:</dt> <dt>Context:</dt>
<dd>Relation</dd> <dd>Relation</dd>
<dt>Initial Contents:</dt> <dt>Initial Contents:</dt>
<dd> <dd>
<table anchor="tab-iana-enum-relation-relation" align="left"> <table anchor="tab-iana-enum-relation-relation" align="left">
<name>JSContact Enum Values for relation (Context: Relation)</na me> <name>JSContact Enum Values for relation (Context: Relation)</na me>
<thead> <thead>
<tr> <tr>
<th align="left">Enum Value</th> <th align="left">Enum Value</th>
skipping to change at line 3720 skipping to change at line 4286
<tr> <tr>
<td align="left">sweetheart</td> <td align="left">sweetheart</td>
<td align="left"> <td align="left">
<xref target="relatedTo" format="default"/> <xref target="relatedTo" format="default"/>
</td> </td>
</tr> </tr>
</tbody> </tbody>
</table> </table>
</dd> </dd>
</dl> </dl>
<dl spacing="compact" newline="false" indent="20">
<dt>Property Name:</dt>
<dd>phoneticSystem</dd>
<dt>Context:</dt>
<dd>Address, Name</dd>
<dt>Initial Contents:</dt>
<dd>
<table anchor="tab-iana-enum-pronounce-system" align="left">
<name>JSContact Enum Values for phoneticSystem (Context: Address
, Name)</name>
<thead>
<tr>
<th align="left">Enum Value</th>
<th align="left">Reference or Description</th>
</tr>
</thead>
<tbody>
<tr>
<td align="left">ipa</td>
<td align="left">
<xref target="prop-phonetic" format="default"/>
</td>
</tr>
<tr>
<td align="left">jyut</td>
<td align="left">
<xref target="prop-phonetic" format="default"/>
</td>
</tr>
<tr>
<td align="left">piny</td>
<td align="left">
<xref target="prop-phonetic" format="default"/>
</td>
</tr>
</tbody>
</table>
</dd>
</dl>
</section> </section>
</section> </section>
</section> </section>
<section anchor="security-considerations" numbered="true" toc="default"> <section anchor="security-considerations" numbered="true" toc="default">
<name>Security Considerations</name> <name>Security Considerations</name>
<t>Contact information is very privacy-sensitive. It can reveal the ident ity, location and credentials information, employment status, interests and hobb ies, and social network of a user. Its transmission and storage must be done ca refully to protect it from possible threats, such as eavesdropping, replay, mess age insertion, deletion, modification, and on-path attacks.</t> <t>Contact information is very privacy sensitive. It can reveal the ident ity, location, credentials information, employment status, interests and hobbies , and social network of a user. Its transmission and storage must be done caref ully to protect it from possible threats such as eavesdropping, replay, message insertion, deletion, modification, and on-path attacks.</t>
<t>The data being stored and transmitted may be used in systems with real- world consequences. For example, a malicious actor might provide JSContact data that uses the name of another person but insert their contact details to impers onate the unknown victim. Such systems must be careful to authenticate all data they receive to prevent them from being subverted and ensure the change comes f rom an authorized entity.</t> <t>The data being stored and transmitted may be used in systems with real- world consequences. For example, a malicious actor might provide JSContact data that uses the name of another person but insert their contact details to impers onate the unknown victim. Such systems must be careful to authenticate all data they receive to prevent them from being subverted and ensure the change comes f rom an authorized entity.</t>
<t>This document only defines the data format; such considerations are pri marily the concern of the API or method of storage and transmission of such file s.</t> <t>This document only defines the data format; such considerations are pri marily the concern of the API or method of storage and transmission of such file s.</t>
<section anchor="json-parsing" numbered="true" toc="default"> <section anchor="json-parsing" numbered="true" toc="default">
<name>JSON Parsing</name> <name>JSON Parsing</name>
<t>The security considerations of <xref target="RFC8259" format="default "/> apply to the use of JSON as the data interchange format. <t>The security considerations of <xref target="RFC8259" format="default "/> apply to the use of JSON as the data interchange format.
</t> </t>
<t>As for any serialization format, parsers need to thoroughly check the syntax of the supplied data. JSON uses opening and closing brackets for severa l types and structures, and it is possible that the end of the supplied data wil l be reached when scanning for a matching closing bracket; this is an error cond ition, and implementations need to stop scanning at the end of the supplied data .</t> <t>As for any serialization format, parsers need to thoroughly check the syntax of the supplied data. JSON uses opening and closing brackets for severa l types and structures, and it is possible that the end of the supplied data wil l be reached when scanning for a matching closing bracket; this is an error cond ition, and implementations need to stop scanning at the end of the supplied data .</t>
<t>JSON also uses a string encoding with some escape sequences to encode special characters within a string. Care is needed when processing these escap e sequences to ensure that they are fully formed before the special processing i s triggered, with special care taken when the escape sequences appear adjacent t o other (non-escaped) special characters or adjacent to the end of data (as in t he previous paragraph).</t> <t>JSON also uses a string encoding with some escape sequences to encode special characters within a string. Care is needed when processing these escap e sequences to ensure that they are fully formed before the special processing i s triggered, with special care taken when the escape sequences appear adjacent t o other (non-escaped) special characters or adjacent to the end of data (as in t he previous paragraph).</t>
<t>If parsing JSON into a non-textual structured data format, implementa tions may need to allocate storage to hold JSON string elements. Since JSON doe s not use explicit string lengths, the risk of denial of service due to resource exhaustion is small, but implementations may still wish to place limits on the size of allocations they are willing to make in any given context, to avoid untr usted data causing excessive memory allocation.</t> <t>If parsing JSON into a non-textual structured data format, implementa tions may need to allocate storage to hold JSON string elements. Since JSON doe s not use explicit string lengths, the risk of denial of service due to resource exhaustion is small, but implementations may still wish to place limits on the size of allocations they are willing to make in any given context, to avoid untr usted data causing excessive memory allocation.</t>
</section> </section>
<section anchor="uri-values" numbered="true" toc="default"> <section anchor="uri-values" numbered="true" toc="default">
<name>URI Values</name> <name>URI Values</name>
<t>Several JSContact properties contain URIs as values, and processing t hese properties requires extra care. <xref target="RFC3986" sectionFormat="of" section="7"/> discusses security risks related to URIs.</t> <t>Several JSContact properties contain URIs as values, and processing t hese properties requires extra care. <xref target="RFC3986" sectionFormat="of" section="7"/> discusses security risks related to URIs.</t>
<t>Fetching remote resources carries inherent risks. Connections must o nly be allowed on well-known ports, using allowed protocols (generally, just HTT P/HTTPS on their default ports). The URL must be resolved externally and not al lowed to access internal resources. Connecting to an external source reveals IP (and therefore often location) information.</t> <t>Fetching remote resources carries inherent risks. Connections must o nly be allowed on well-known ports, using allowed protocols (generally, just HTT P/HTTPS on their default ports). The URL must be resolved externally and not al lowed to access internal resources. Connecting to an external source reveals IP (and therefore often location) information.</t>
<t>A maliciously constructed JSContact object may contain a very large n umber of URIs. In the case of published address books with a large number of su bscribers, such objects could be widely distributed. Implementations should be careful to limit the automatic fetching of linked resources to reduce the risk o f this being an amplification vector for a denial-of-service attack.</t> <t>A maliciously constructed JSContact object may contain a very large n umber of URIs. In the case of published address books with a large number of su bscribers, such objects could be widely distributed. Implementations should be careful to limit the automatic fetching of linked resources to reduce the risk o f this being an amplification vector for a denial-of-service attack.</t>
</section> </section>
</section> </section>
</middle> </middle>
<back> <back>
<displayreference target="I-D.ietf-uuidrev-rfc4122bis" to="UUID"/>
<references> <references>
<name>References</name> <name>References</name>
<references> <references>
<name>Normative References</name> <name>Normative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.1
FC.1034.xml"/> 034.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.1
FC.1035.xml"/> 035.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2
FC.2046.xml"/> 046.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2
FC.2119.xml"/> 119.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.2
FC.2426.xml"/> 426.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3
FC.3339.xml"/> 339.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4
FC.4122.xml"/> 122.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.4
FC.4648.xml"/> 648.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5
FC.5234.xml"/> 234.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5
FC.5322.xml"/> 322.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5
FC.5646.xml"/> 646.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.5
FC.5870.xml"/> 870.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
FC.6350.xml"/> 350.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
FC.6901.xml"/> 901.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
FC.7493.xml"/> 493.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
FC.7529.xml"/> 529.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
FC.8126.xml"/> 126.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
FC.8141.xml"/> 141.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
FC.8174.xml"/> 174.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
FC.8259.xml"/> 259.xml"/>
<reference anchor="ISO.3166-1.2006">
<!--[rfced] The 2006 version of this reference has been withdrawn;
therefore, we replaced it with the 2020 version. Please let us
know if any further updates are needed.
Original:
[ISO.3166-1.2006]
International Organization for Standardization, "Codes for
the representation of names of countries, 3rd edition",
ISO Standard 3166-1, 2006.
Current:
[ISO.3166-1]
International Organization for Standardization, "Codes for
the representation of names of countries and their subdivisions -
Part 1: Country codes", ISO 3166-1:2020, August 2020.
-->
<reference anchor="ISO.3166-1">
<front> <front>
<title>Codes for the representation of names of countries, 3rd <title>Codes for the representation of names of countries and their
edition</title> subdivisions -- Part 1: Country codes
</title>
<author> <author>
<organization>International Organization for <organization>International Organization for Standardization</orga
Standardization</organization> nization>
</author> </author>
<date year="2006"/> <date month="August" year="2020"/>
</front> </front>
<seriesInfo name="ISO" value="Standard 3166-1"/> <seriesInfo name="ISO" value="3166-1:2020"/>
</reference> </reference>
<reference anchor="IANATZ" target="https://www.iana.org/time-zones">
<reference anchor="IANA-TZ" target="https://www.iana.org/time-zones">
<front> <front>
<title>IANA Time Zone Database</title> <title>Time Zone Database</title>
<author/> <author><organization>IANA</organization></author>
</front> </front>
</reference> </reference>
<reference anchor="IANAvCard" target="https://www.iana.org/assignments/v
card-elements/vcard-elements.xhtml"> <reference anchor="IANA-vCard" target="https://www.iana.org/assignments/
vcard-elements">
<front> <front>
<title>IANA vCard Elements</title> <title>vCard Elements</title>
<author/> <author><organization>IANA</organization></author>
</front> </front>
</reference> </reference>
</references> </references>
<references> <references>
<name>Informative References</name> <name>Informative References</name>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3
FC.3261.xml"/> 261.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3
FC.3966.xml"/> 966.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3
FC.3986.xml"/> 986.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.3
FC.3987.xml"/> 987.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
FC.6351.xml"/> 351.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
FC.6473.xml"/> 473.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
FC.6474.xml"/> 474.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
FC.6715.xml"/> 715.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.6
FC.6869.xml"/> 869.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.7
FC.7095.xml"/> 095.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
FC.8499.xml"/> 499.xml"/>
<xi:include href="https://xml2rfc.ietf.org/public/rfc/bibxml/reference.R <xi:include href="https://bib.ietf.org/public/rfc/bibxml/reference.RFC.8
FC.8605.xml"/> 605.xml"/>
<xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.
ietf-uuidrev-rfc4122bis.xml"/> <!--[I-D.ietf-uuidrev-rfc4122bis] in EDIT state; entered the long way to include
<xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D. the correct initials-->
ietf-calext-jscontact.xml"/> <reference anchor="I-D.ietf-uuidrev-rfc4122bis" target="https://datatracker.ietf
.org/doc/html/draft-ietf-uuidrev-rfc4122bis-14">
<front>
<title>Universally Unique IDentifiers (UUID)</title>
<author fullname="Kyzer R. Davis" initials="K. R." surname="Davis">
<organization>Cisco Systems</organization>
</author>
<author fullname="Brad Peabody" initials="B. G." surname="Peabody">
<organization>Uncloud</organization>
</author>
<author fullname="P. Leach" initials="P." surname="Leach">
<organization>University of Washington</organization>
</author>
<date day="6" month="November" year="2023"/>
</front>
<seriesInfo name="Internet-Draft" value="draft-ietf-uuidrev-rfc4122bis-14"/>
</reference>
<!-- [I-D.ietf-uuidrev-rfc4122bis] in EDIT state; companion document RFC YYY1
<reference anchor="RFCYYY1" target="https://www.rfc-editor.org/info/rfcYYY1">
<front>
<title>Universally Unique IDentifiers (UUID)</title>
<author initials="K. R." surname="Davis" fullname="Kyzer R. Davis">
<organization>Cisco Systems</organization>
</author>
<author initials="B. G." surname="Peabody" fullname="Brad Peabody">
<organization>Uncloud</organization>
</author>
<author initials="P." surname="Leach" fullname="P. Leach">
<organization>University of Washington</organization>
</author>
<date month="November" year="2024"/>
</front>
<seriesInfo name="RFC" value="YYY1"/>
<seriesInfo name="DOI" value="10.17487/RFCYYY1"/>
</reference>
-->
<!-- Note: Removed [I-D.ietf-calext-jscontact] as it is a self-reference.
<xi:include href="https://bib.ietf.org/public/rfc/bibxml3/reference.I-D.iet
f-calext-jscontact.xml"/>-->
<reference anchor="IPA" target="https://www.internationalphoneticalphabe t.org/"> <reference anchor="IPA" target="https://www.internationalphoneticalphabe t.org/">
<front> <front>
<title>International Phonetic Alphabet</title> <title>International Phonetic Alphabet</title>
<author/> <author><organization>IPA</organization></author>
</front> </front>
</reference> </reference>
<reference anchor="UBiDi" target="https://www.unicode.org/reports/tr9/"> <reference anchor="UBiDi" target="https://www.unicode.org/reports/tr9/">
<front> <front>
<title>Unicode® Standard Annex #9: Unicode Bidirectional Algorithm</ <title>Unicode Standard Annex #9: Unicode Bidirectional Algorithm</t
title> itle>
<author/> <author><organization>The Unicode Consortium</organization></author>
<date month="August" year="2023"/>
</front> </front>
<seriesInfo name="Unicode" value="15.1.0"/>
<refcontent>Revision 48</refcontent>
</reference> </reference>
<reference anchor="W3C-URL" target="https://url.spec.whatwg.org">
<reference anchor="WHATWG-URL" target="https://url.spec.whatwg.org">
<front> <front>
<title>W3C WG URL - Living Standard — Last Updated 21 August 2023</t <title>URL Living Standard</title>
itle> <author><organization>WHATWG
<author/> </organization>
</author>
<date month="January" year="2024"/>
</front> </front>
</reference> </reference>
</references> </references>
</references> </references>
<!-- [rfced] Terminology
a) Throughout the text, the following terminology appears to be used
inconsistently. Please review these occurrences and let us know if/how they
may be made consistent.
kind separator vs. separator kind
Additionally, let us know if/how the capitalization of "resource" terminology
should be made consistent. Please note that "resource values" and "Resource
data type" are used consistently.
Resource data type vs. resource data type
Resource object vs. resource object
Resource type vs. resource type
b) Note that we updated the text with the latter forms for consistency. Please
let us know if any further updates are needed.
Cardinal -> cardinal (per use in other RFCs)
Data Interchange Format -> data interchange format (per RFC 8259)
JSON pointer -> JSON Pointer (but lowercase "pointer" when used in general) (p
er RFC 6901)
-->
<!-- [rfced] FYI: We have added expansions for the following abbreviations
per Section 3.6 of RFC 7322 ("RFC Style Guide"). Please review each
expansion in the document carefully to ensure correctness.
Common Locale Data Repository (CLDR)
Internet JSON (I-JSON)
Universally Unique Identifier (UUID)
-->
<!-- [rfced] Please review the "Inclusive Language" portion of the online
Style Guide <https://www.rfc-editor.org/styleguide/part2/#inclusive_language>
and let us know if any changes are needed.
Note that our script did not flag any words in particular, but this should
still be reviewed as a best practice.
-->
</back> </back>
</rfc> </rfc>
 End of changes. 338 change blocks. 
1524 lines changed or deleted 2178 lines changed or added

This html diff was produced by rfcdiff 1.48.