rfc9553.original.xml   rfc9553.xml 
<?xml version="1.0" encoding="utf-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE rfc> <!DOCTYPE rfc [
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="*trust200902" submissionTyp <!ENTITY nbsp "&#160;">
e="IETF" category="std" xml:lang="en" consensus="true" docName="draft-ietf-calex <!ENTITY zwsp "&#8203;">
t-jscontact-16" obsoletes="" updates="" tocInclude="true" symRefs="true" sortRef <!ENTITY nbhy "&#8209;">
s="true" version="3"> <!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</ <!--[rfced] *AD, changes were submitted twice after the document
title> was initially approved. Please review the updates from version 15
<seriesInfo name="Internet-Draft" value="draft-ietf-calext-jscontact-16"/> to version 17 and let us know if you approve. The updates can
be viewed in this diff file:
https://www.rfc-editor.org/authors/rfc9553-ad-diff.html
Additionally, under "Until Version" (4 instances), we updated the
key words for clarity by replacing "MUST be not set, or be one of
the allowed values" with "MUST NOT be set or MUST be one of the
allowed values" as shown below. Please review and approve of this
change to the key words.
Original:
The Until Version value either MUST NOT be set, or be one of the
allowed values of the version property in the JSContact Enum Value
registry (see Table 1).
Current:
The Until Version value either MUST NOT be set or MUST be one of
the allowed values of the version property in the "JSContact Enum
Values" registry (see Table 1).
-->
<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/>
</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/>
</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 <t>This specification defines a data model and JavaScript Object Notation
act card information that can be used for data storage and exchange in address b (JSON) representation of contact card
ook or directory applications. It aims to be an alternative to the vCard data f information that can be used for data storage and exchange in address bo
ormat and to be unambiguous, extendable and simple to process. In contrast to t ok or directory applications. It aims to
he JSON-based jCard format, it is not a direct mapping from the vCard data model be an alternative to the vCard data format and to be unambiguous, extend
and expands semantics where appropriate.</t> able, and simple to process. In contrast
to the JSON-based jCard format, it is not a direct mapping from the vCar
d data model and expands semantics where
appropriate. Two additional specifications define new vCard elements and
how to convert between JSContact and
vCard.
</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 <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 in address book or directory
ative to the vCard data format <xref target="RFC6350" format="default"/>.</t> applications and services. It aims to be an alternative to the vCard dat
a 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
lt"/> and extensions (<xref target="RFC6473" format="default"/>, <xref target="R format
FC6474" format="default"/>, <xref target="RFC6715" format="default"/>, <xref tar <xref target="RFC6350" format="default"/>
get="RFC6869" format="default"/>, <xref target="RFC8605" format="default"/>). T and extensions
he specification should add new attributes or value types where appropriate. Not <xref target="RFC6473" format="default"/>
all existing vCard definitions need an equivalent in JSContact, especially if t <xref target="RFC6474" format="default"/>
he vCard definition is considered to be obsolete or otherwise inappropriate. Co <xref target="RFC6715" format="default"/>
nversion between the data formats need not fully preserve semantic meaning.</li> <xref target="RFC6869" format="default"/>
<li>The attributes of the card data represented must be described as sim <xref target="RFC8605" format="default"/>. The specification should ad
ple key-value pairs, reducing complexity of their representation.</li> d new attributes or value types where
<li>The data model should avoid all ambiguities and make it difficult to appropriate. Not all existing vCard definitions need an equivalent in
make mistakes during implementation.</li> JSContact, especially if the vCard
<li>Extensions, such as new properties and components, <bcp14>MUST NOT</ definition is considered to be obsolete or otherwise inappropriate. Co
bcp14> lead to requiring an update to this document.</li> nversion between the data formats need
not fully preserve semantic meaning.
</li>
<!--[rfced] Please clarify the meaning of "reducing complexity of
their representation". Is the intended meaning that the
attributes must be described as simple key-value pairs to
reduce complexity (option A) or to reduce complexity of the
representation of the card data (option B)?
Original:
The attributes of the card data represented must be described as
simple key-value pairs, reducing complexity of their
representation.
Perhaps:
A) The attributes of the card data being represented must be
described as simple key-value pairs to reduce complexity.
or
B) The attributes of the card data must be described as simple
key-value pairs to reduce the complexity of the representation
of the card data.
-->
<li>The attributes of the card data must be described as simple key-valu
e pairs to reduce the complexity of the
representation of the card data.
</li>
<li>The data model should avoid all ambiguities and make it difficult to
make mistakes during implementation.
</li>
<li>Extensions, such as new properties and components, <bcp14>MUST NOT</
bcp14> lead to a required update of this
document.
</li>
</ul> </ul>
<t>The representation of this data model is defined in the I-JSON format < <t>The representation of this data model is defined in the Internet JSON (
xref target="RFC7493" format="default"/>, which is a strict subset of the JavaSc I-JSON) format <xref target="RFC7493" format="default"/>,
ript Object Notation (JSON) Data Interchange Format <xref target="RFC8259" forma which is a strict subset of the JSON data interchange format <xref targe
t="default"/>. Using JSON is mostly a pragmatic choice: its widespread use make t="RFC8259" format="default"/>. Using
s JSContact easier to adopt, and the availability of production-ready JSON imple JSON is mostly a pragmatic choice: its widespread use makes JSContact ea
mentations eliminates a whole category of parser-related interoperability issues sier to adopt, and the availability of
.</t> production-ready JSON implementations eliminates a whole category of par
ser-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
at for contacts data between address book service providers and vendors. Howeve <xref target="RFC6350"/>
r, this format has gone through multiple specifications iterations with only a s is an interchange format for contacts data between address book servic
ubset of its deprecated <xref target="RFC2426">version 3</xref> being widely in e providers and vendors. However, this
use. Consequently, products and services internally use a richer contact data m format has gone through multiple specification iterations with only a
odel than they expose when serializing that information to vCard. In addition, subset of its deprecated <xref target="RFC2426">version 3
service providers often use a proprietary JSON representation of contact data in </xref> being widely in use. Consequently, products and services use a
their APIs.</t> n internal contact data model that is
<t>JSContact provides a standard JSON-based data model and representatio richer than what they expose when serializing that information to vCar
n of contact data as an alternative to proprietary formats.</t> d. In addition, service providers often
<t>While writing this document, several features missing in vCard were b use a proprietary JSON representation of contact data in their APIs.
rought to the attention of the authors, such as social media contacts, gender pr </t>
onouns and others. This highlights how vCard is not perceived as an evolving fo <t>JSContact provides a standard JSON-based data model and representatio
rmat and consequently hasn't been updated since close to ten years. JSContact a n of contact data as an alternative to
ddresses these unmet demands and defines new vCard properties and parameters to proprietary formats.
allow interchanging them in both formats.</t> </t>
<t>The xCard <xref target="RFC6351" format="default"/> and jCard <xref t <t>At the time of writing this document, several missing features in vCa
arget="RFC7095" format="default"/> specifications define alternative representat rd were brought to the attention of the
ions for vCard data, in XML and JSON format respectively. Both explicitly aim t authors such as social media contacts, gender pronouns, and others. Th
o not change the underlying data model. Accordingly, they are regarded as equal is highlights how vCard is not perceived
to vCard in the context of this document.</t> as an evolving format and, consequently, hasn't been updated for about
ten years. JSContact addresses these
unmet demands and defines new vCard properties and parameters to allow
interchanging them in both formats.
</t>
<t>Two additional documents define the relation of JSContact and vCard:
<xref target="RFC9554" format="default"/>
defines new vCard properties and parameters, and
<xref target="RFC9555" format="default"/>
defines how to convert JSContact data from and to vCard.
</t>
<t>The xCard
<xref target="RFC6351" format="default"/>
and jCard
<xref target="RFC7095" format="default"/>
specifications define alternative representations for vCard data in XM
L and JSON formats, respectively. Both
explicitly aim to not change the underlying data model. Accordingly, t
hey are regarded as equal 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>
4>SHOULD</bcp14>", "<bcp14>SHOULD NOT</bcp14>", "<bcp14>RECOMMENDED</bcp14>", "< SHALL</bcp14>", "<bcp14>SHALL NOT</bcp14>", "<bcp14>SHOULD</bcp14>", "
bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</bcp14>", and "<bcp14>OPTIONAL</bcp1 <bcp14>SHOULD NOT</bcp14>", "<bcp14>
4>" in this document are to be interpreted as described in BCP 14 <xref target=" RECOMMENDED</bcp14>", "<bcp14>NOT RECOMMENDED</bcp14>", "<bcp14>MAY</b
RFC2119" format="default" sectionFormat="of" derivedContent="RFC2119"/> <xref ta cp14>", and "<bcp14>OPTIONAL</bcp14>" in
rget="RFC8174" format="default" sectionFormat="of" derivedContent="RFC8174"/> wh this document are to be interpreted as described in BCP 14
en, and only when, they appear in all capitals, as shown here.</t> <xref target="RFC2119" format="default" sectionFormat="of" derivedCont
<t>The ABNF definitions in this document use the notations of <xref targ ent="RFC2119"/>
et="RFC5234"/>. ABNF rules not defined in this document either are defined in <x <xref target="RFC8174" format="default" sectionFormat="of" derivedCont
ref target="RFC5234"/> (such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, an ent="RFC8174"/>
d DIGIT) or <xref target="RFC6350"/>.</t> when, and only when, they appear in all capitals, as shown here.
</t>
<t>The ABNF definitions in this document use the notations of <xref targ
et="RFC5234"/>. ABNF rules not defined in
this document are defined in either
<xref target="RFC5234"/>
(such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT) or <
xref target="RFC6350"/>.
</t>
</section> </section>
<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"
itive types ("strings", "numbers", "booleans", and "null") are to be interpreted and "array" as well as the four primitive types ("strings", "numbers",
as described in <xref target="RFC8259" section="1"/>. All JSContact data <bcp1 "booleans", and "null") are to be
4>MUST</bcp14> be valid according to the constraints given in <xref target="RFC7 interpreted as described in <xref target="RFC8259" section="1"/>. All
493">I-JSON</xref>. Unless otherwise noted, all member names in JSON objects an JSContact data <bcp14>MUST</bcp14> be
d all string values are case-sensitive. Within context of JSON objects, the ter valid according to the constraints given in <xref target="RFC7493">I-J
m "key" is synonymous with "member name" as defined in <xref target="RFC8259" se SON</xref>. Unless otherwise noted, all
ction="1"/>.</t> member names in JSON objects and all string values are case-sensitive.
Within the context of JSON objects, the
term "key" is synonymous with "member name" as defined in <xref target
="RFC8259" section="1"/>.
</t>
<section anchor="objects-and-properties" numbered="true" toc="default"> <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 <!-- [rfced] The use of <tt> and <em>
ses or names. This information typically consists of multiple related elements,
for example a personal name and surname together form a name. These related el a) In the html and pdf outputs, the text enclosed in <tt> is output in
ements are organized in JSContact objects. A JSContact object is a JSON object fixed-width font. In the txt output, there are no changes to the font,
which:</t> 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 elements are organized in JSContact objects. A JSContact obj
ect 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"
<li>Has one or more object members for which the name and allowed va registry</xref>.
lue types are specified. Such members are called "properties".</li> </li>
<li>Has one property named <tt>@type</tt> with a string value that m <li>One or more object members for which the name and allowed value
atches the type name of this JSContact object. In general, this property does n types are specified. Such members are
ot need to be set explicitly as outlined in <xref target="prop-type"/>.</li> called "properties".
</li>
<li>One property named @type with a string value that matches the ty
pe name of the JSContact object. In
general, this property does not need to be set explicitly as outli
ned 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
ions"/> then define the exact requirements for property names.</t> <xref target="validating-jscontact" format="counter"/>
<t>The next paragraph illustrates how a JSContact object is defined:</ and
t> <xref target="vendor-specific-extensions" format="counter"/>
<blockquote> then define the exact requirements for property names.
</t>
<t>The next paragraph illustrates how a JSContact object is defined.
The names "Foo" and "baz" are only for demonstration and have no meaning outside
the example.</t>
<ul empty="true" anchor="example-foo-object">
<li>
<t>A Foo object has the following properties:</t> <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>@type: String.</dt>
this contact. The value <bcp14>MUST</bcp14> be an integer greater than 0 and le <dd>The JSContact type of the object. The value <bcp14>MUST</bcp14
ss than 10.</li> > be "Foo", if set.
</ul> </dd>
</blockquote> <dt>baz: Number (mandatory).</dt>
<t>Here, a JSContact object type named <tt>Foo</tt> is defined. In ad <dd>The baz level of the contact. The value <bcp14>MUST</bcp14> be
dition to its <tt>@type</tt> property it has a property named <tt>qux</tt> for w an integer greater than 0 and less
hich values <bcp14>MUST</bcp14> be valid according to the definition of the <tt> than 10.
Number</tt> type. The property has one attribute, <tt>mandatory</tt>, which spe </dd>
cifies that the property <bcp14>MUST</bcp14> be present for an instance of this </dl>
JSContact object to be valid. Finally, a free-text description describes the se </li>
mantics and further restrictions.</t> </ul>
<t>The above paragraph illustrates the following:</t>
<ul>
<li>It defines a JSContact object type named "Foo" that has two prop
erties, named "@type" and "baz".</li>
<li>The @type property adheres to the rules outlined in <xref target
="prop-type"/>. Because of this, it is
neither defined to be mandatory nor optional, as this depends on h
ow the Foo object type is used.
</li>
<li>The baz property value <bcp14>MUST</bcp14> be valid according to
the definition of the Number type.
</li>
<li>The property has one attribute, "mandatory", which specifies tha
t the property <bcp14>MUST</bcp14> be
present for a value of the Foo object type to be valid.
</li>
<li>The free-text description of the baz property describes the sema
ntics and further restrictions for its
values.
</li>
</ul>
<!--[rfced] Section 1.3.1. Please clarify the meaning of "qux-ishness"
as no other RFCs contain this term. Is it a well-known term, or
can it perhaps be rephrased for clarity?
Also, we removed the blockquote element from this text
because it is not a direct quote. Please let us know
if any further updates are needed.
Original:
A Foo object has the following properties:
qux: Number (mandatory). Defines the qux-ishness of this contact
.
The value MUST be an integer greater than 0 and less than 10.
-->
</section> </section>
<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 <t>Type signatures are given for all JSON values and JSContact definit
ions in this document. The following conventions are used:</t> ions in this document. The following
<ul spacing="normal"> conventions are used:
<li><tt>String</tt> - The JSON string type.</li> </t>
<li><tt>Number</tt> - The JSON number type.</li> <dl spacing="normal">
<li><tt>Boolean</tt> - The JSON boolean type.</li> <dt>String:</dt>
<li><tt>A[B]</tt> - A JSON object where the keys are all of the type <dd>The JSON string type.</dd>
<tt>A</tt>, and the values are all of the type <tt>B</tt>.</li> <dt>Number:</dt>
<li><tt>A[]</tt> - A JSON array of values of type <tt>A</tt>.</li> <dd>The JSON number type.</dd>
<li><tt>A|B</tt> - The value is either of type <tt>A</tt> or of type <dt>Boolean:</dt>
<tt>B</tt>.</li> <dd>The JSON boolean type.</dd>
<li><tt>*</tt> - The type is undefined (the value could be any type, <dt>A[B]:</dt>
although permitted values may be constrained by the context of this value).</li <dd>A JSON object where all keys are of type A and all values are of
> type B.</dd>
</ul> <dt>A[]:</dt>
<t><xref target="common-data-types"/> defines common data types, inclu <dd>A JSON array of values of type A.</dd>
ding signed or unsigned integers and dates.</t> <dt>A|B:</dt>
<dd>The value is either of type A or of type B.</dd>
<dt>*:</dt>
<dd>The type is undefined (the value could be any type, although per
mitted values may be constrained by the
context of this value).
</dd>
</dl>
<t><xref target="common-data-types"/>
defines common data types, including signed or unsigned integers and
dates.
</t>
</section> </section>
<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 <t>Object properties may also have a set of attributes defined along w
ith the type signature. These have the following meanings:</t> ith the type signature. These have the
<ul> following meanings:
<li><tt>mandatory</tt>: The property <bcp14>MUST</bcp14> be set for </t>
an instance of this object to be valid.</li> <dl spacing="normal">
<li><tt>optional</tt>: The property can but not need be set for an i <dt>mandatory:</dt>
nstance of this object to be valid.</li> <dd>The property <bcp14>MUST</bcp14> be set for an instance of this
<li><tt>default</tt>: This is followed by a JSON value. That value w object to be valid.
ill be used for this property if it is omitted.</li> </dd>
<li><tt>defaultType</tt>: This is followed by the name of a JSContac <dt>optional:</dt>
t object type. A property value of JSContact object type is expected to be of t <dd>The property can, but need not, be set for an instance of this o
his named type, in case it omits the <tt>@type</tt> property.</li> bject to be valid.</dd>
</ul> <dt>default:</dt>
<dd>This is followed by a JSON value. That value will be used for th
is property if it is omitted.</dd>
<dt>defaultType:</dt>
<dd>This is followed by the name of a JSContact object type. A prope
rty value of JSContact object type is
expected to be of this named type, in case it omits the @type prop
erty.
</dd>
</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 @type Property</name>
<t>This property is defined as:</t> <dl spacing="normal">
<ul> <dt>@type: String.</dt>
<li><tt>@type</tt>: String. Specifies the type of this object. Thi <dd>The JSContact type of a JSON object. It <bcp14>MUST</bcp14> matc
s <bcp14>MUST</bcp14> match the type name of the JSContact object of which this h the
JSON object is an instance of.</li> type name of the JSContact object of which the JSON object is an i
</ul> nstance of.
<t>The purpose of this property is to help implementations identify wh </dd>
ich JSContact object type a given JSON object represents. Implementations <bcp1 </dl>
4>MUST</bcp14> validate that JSON objects with this property conform to the spec <t>The purpose of the @type property is to help implementations identi
ification of the JSContact object type of that name.</t> fy which JSContact object type a given
<t>In many cases the <tt>@type</tt> property value is implied by where JSON object represents. Implementations <bcp14>MUST</bcp14> validate
its object occurs in JSContact data. Assuming that both <tt>A</tt> and <tt>B</t that JSON objects with this property
t> are JSContact object types:</t> conform to the specification of the JSContact object type of that na
me.
</t>
<t>In many cases, the @type property value is implied by where its obj
ect occurs in JSContact data. Assuming
that both A and B 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 "A" <bcp14>MAY</bcp14> have the
e <tt>@type</tt> property is not set then its value is implied to be <tt>A</tt> @type property set. If the @type property is not set, then its val
by the property definition.</li> ue is implied to be A by the property
<li>An object that is set as the value for a property with type sign definition.
ature <tt>A|B (defaultType: A)</tt> <bcp14>MAY</bcp14> have the <tt>@type</tt> p </li>
roperty set if it is an instance of <tt>A</tt>. It <bcp14>MUST</bcp14> have the <li>An object that is set as the value for a property with type sign
<tt>@type</tt> property set if it is an instance of <tt>B</tt>. If instead the ature "A|B (defaultType: A)" <bcp14>
<tt>defaultType</tt> attribute is not defined then the <tt>@type</tt> property MAY
<bcp14>MUST</bcp14> also be set for <tt>A</tt>.</li> </bcp14> have the @type property set if it is an instance of A. It <
<li>An object that is not the value of a property, such as the root bcp14>MUST</bcp14> have the @type
of JSON data (directly or as member of an array), <bcp14>MUST</bcp14> have the < property set if it is an instance of B. If, instead, the defaultTy
tt>@type</tt> property set.</li> pe attribute is not defined, then the
@type property <bcp14>MUST</bcp14> also be set for A.
</li>
<li>An object that is not the value of a property, such as the topmo
st object in JSON data (directly or as a
member of an array), <bcp14>MUST</bcp14> have the @type property s
et.
</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 <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> 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 "Id" is given as a data type, it means a String of at least 1
t> of at least 1 and a maximum of 255 octets in size, and it <bcp14>MUST</bcp14> and a maximum of 255 octets in size,
only contain characters from the <tt>URL and Filename Safe</tt> base64url alpha and it <bcp14>MUST</bcp14> only contain characters from the "URL and
bet, as defined in Section 5 of <xref target="RFC4648" format="default"/>, exclu Filename Safe" base64url alphabet, as
ding the pad character (<tt>=</tt>). This means the allowed characters are the defined in <xref target="RFC4648" sectionFormat="of" section="5"/>,
ASCII alphanumeric characters (<tt>A-Za-z0-9</tt>), hyphen (<tt>-</tt>), and und excluding the pad character ("="). This
erscore (<tt>_</tt>).</t> means the allowed characters are the ASCII alphanumeric characters (
<t>In many places in JSContact a JSON map is used where the map keys a "A-Za-z0-9"), hyphen ("-"), and
re of type Id and the map values are all the same type of object. This construc underscore ("_").
tion represents an unordered set of objects, with the added advantage that each </t>
entry has a name (the corresponding map key). This allows for more concise patc <t>In many places in JSContact, a JSON map is used where the map keys
hing of objects, and, when applicable, for the objects in question to be referen are of type Id and the map values are
ced from other objects within the JSContact object. The map keys <bcp14>MUST</b all the same type of object. This construction represents an unorder
cp14> be preserved across multiple versions of the JSContact object.</t> ed set of objects, with the added
<t>Unless otherwise specified for a particular property, there are no advantage that each entry has a name (the corresponding map key). Th
uniqueness constraints on an Id value (other than, of course, the requirement th is allows for more concise patching of
at you cannot have two values with the same key within a single JSON map). For objects and, when applicable, for the objects in question to be refe
example, two <xref target="card">Card</xref> objects might use the same Ids in t renced from other objects within the
heir respective <tt>photos</tt> properties. Or within the same Card the same Id JSContact object. The map keys <bcp14>MUST</bcp14> be preserved acro
could appear in the <tt>emails</tt> and <tt>phones</tt> properties. These situ ss multiple versions of the JSContact
ations do not imply any semantic connections among the objects.</t> object.
</t>
<t>Unless otherwise specified for a particular property, there are no
uniqueness constraints on an Id value
(other than, of course, the requirement that you cannot have two val
ues with the same key within a single
JSON map). For example, two <xref target="card">Card</xref> objects
might use the same Ids in their
respective photos properties. Or within the same Card, the same Id c
ould appear in the emails and phones
properties. These situations do not imply any semantic connections a
mong 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 "Int" is given as a data type, it means an integer in the ran
the range -2<sup>53</sup>+1 &lt;= value &lt;= 2<sup>53</sup>-1, the safe range f ge -2<sup>53</sup>+1 &lt;= value &lt;= 2<sup>
or integers stored in a floating-point double, represented as a JSON <tt>Number< 53</sup>-1, which is the safe range for integers stored in a floatin
/tt>.</t> g-point double, represented as a JSON
<t>Where <tt>UnsignedInt</tt> is given as a data type, it means an int Number.
eger in the range 0 &lt;= value &lt;= 2<sup>53</sup>-1, represented as a JSON <t </t>
t>Number</tt>.</t> <t>Where "UnsignedInt" is given as a data type, it means an integer in
the range 0 &lt;= value &lt;= 2<sup>
53</sup>-1 represented as a JSON Number.
</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 "String[*]" and represents an unordered se
dered set of patches on a JSON object. t of patches on a JSON object. Each key
Each key is a path represented in a subset of JSON pointer format <xref ta is a path represented in a subset of the JSON Pointer format <xref t
rget="RFC6901"/>. The paths have an implicit leading <tt>/</tt>, so each key is arget="RFC6901"/>. The paths have an
prefixed with <tt>/</tt> before applying the JSON pointer evaluation algorithm. implicit leading "/", so each key is prefixed with "/" before applyi
</t> ng the JSON Pointer evaluation
algorithm.
</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 <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 the last reference token in the pointer
<bcp14>MUST NOT</bcp14> be null. The pointer <bcp14>MUST NOT</bcp14> use "-" as is an array index, then the patch value <bcp14>MUST NOT</bcp14> be
an array index in any of its reference tokens (i.e., you <bcp14>MUST NOT</bcp14 null. The pointer <bcp14>MUST NOT
> insert/delete from an array, but you <bcp14>MAY</bcp14> replace the contents o </bcp14> use "-" as an array index in any of its reference tokens
f its existing members. To add or remove members, one needs to replace the comp (i.e., you <bcp14>MUST NOT</bcp14> insert/delete
lete array value).</li> from an array, but you <bcp14>MAY</bcp14> replace the contents of
<li>All reference tokens prior to the last (i.e., the value after th its existing members. To add or remove
e final slash) <bcp14>MUST</bcp14> already exist as values in the object being p members, one needs to replace the complete array value).
atched. If the last reference token is an array index, then a member at this in </li>
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
<li>There <bcp14>MUST NOT</bcp14> be two patches in the PatchObject e final slash) <bcp14>MUST</bcp14> already
where the pointer of one is the prefix of the pointer of the other, e.g., <tt>ad exist as values in the object being patched. If the last reference
dresses/1/city</tt> and <tt>addresses</tt>.</li> token is an array index, then a member
<li>The value for the patch <bcp14>MUST</bcp14> be valid for the pro at this index <bcp14>MUST</bcp14> already exist in the referenced
perty being set (of the correct type and obeying any other applicable restrictio array.
ns), or if null the property <bcp14>MUST</bcp14> be optional.</li> </li>
<li>There <bcp14>MUST NOT</bcp14> be two patches in the PatchObject
where the pointer of one is the prefix
of the pointer of the other, e.g., "addresses/1/city" and "address
es".
</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 restrictions), or if null, the proper
ty <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 <li>If null, remove the property from the patched object. If the key
y is not present in the parent, this is a no-op.</li> is not present in the parent, this is a
<li>If non-null, set the value given as the value for this property no-op.
(this may be a replacement or addition to the object being patched).</li> </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">@typ
@type</tt></xref> property. Instead, a <tt>@type</tt> property in a patch <bcp1 e</xref> property. Instead, the @type
4>MUST</bcp14> be handled as any other patched property value.</t> property in a patch <bcp14>MUST</bcp14> be handled as any other patc
<t>Implementations <bcp14>MUST</bcp14> reject in its entirety a PatchO hed property value.
bject if any of its patches are invalid. Implementations <bcp14>MUST NOT</bcp1 </t>
4> apply partial patches.</t> <t>Implementations <bcp14>MUST</bcp14> reject a PatchObject in its ent
irety if any of its patches are invalid.
Implementations <bcp14>MUST NOT</bcp14> 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 <!--[rfced] When the term "Card" is referred to in the running text,
ented by this Card, identified by a URI <xref target="RFC3986" format="default"/ there is a mix of "this Card" and "the Card". For consistency and
>. Several property definitions later in this document refer to the Resource da clarity, we updated several instances of "this Card" to "the
ta type as the basis for their property-specific value types. The Resource data Card". Please review and let us know if any further updates are
type defines the properties that are common to all of them. Property definitio needed.
ns making use of Resource <bcp14>MAY</bcp14> define additional properties for th
eir value types.</t> One example
<t>The <tt>@type</tt> property value <bcp14>MUST NOT</bcp14> be <tt>Re
source</tt>, instead it <bcp14>MUST</bcp14> be the name of a concrete resource t Original:
ype (see <xref target="resource-properties"/>). A Resource object has the follo The date and time when the data in this Card was last
wing properties.</t> modified.
<ul spacing="normal">
<li> Current:
<t>@type: <tt>String</tt>. Specifies the type of this resource ob The date and time when the data in the Card was last
ject. The allowed value is defined in later sections of this document for each modified.
concrete resource type (<xref target="resource-properties"/>).</t> -->
</li> <t>The Resource data type defines a resource associated with the entit
<li> y represented by the Card, identified by
<t>kind: <tt>String</tt> (optional). a URI <xref target="RFC3986" format="default"/>. Later in this docum
The kind of the resource. The allowed values are defined in the property defini ent, several property definitions refer
tion that makes use of the Resource type. Some property definitions may change to the Resource type as the basis for their property-specific value
this property from being optional to mandatory. types. The Resource type defines the
</t> properties that are common to all of them. Property definitions maki
</li> ng use of Resource <bcp14>MAY</bcp14> define
<li>uri: <tt>String</tt> (mandatory). additional properties for their value types.
The resource value. This <bcp14>MUST</bcp14> be a <em>URI</em> as defined in Se </t>
ction 3 of <xref target="RFC3986" format="default"/>.</li> <t>A Resource object has the following properties:</t>
<li>mediaType: <tt>String</tt> (optional). <dl spacing="normal">
Used for URI resource values. Provides the media type <xref target="RFC2046" fo <dt>@type: String.</dt>
rmat="default"/> of the resource identified by the URI.</li> <dd>The JSContact type of the object. The value <bcp14>MUST NOT</bc
<li>contexts: <tt>String[Boolean]</tt> (optional). p14> be "Resource"; instead, the value <bcp14>MUST</bcp14> be the name
The contexts in which to use this resource. Also see <xref target="prop-context of a concrete resource type (see <xref target="resource-properties"/
s"/>.</li> >).</dd>
<li>pref: <tt>UnsignedInt</tt> (optional). <dt>kind: String (optional).</dt>
The preference of this resource in relation to other resources. Als <dd>
o see <xref target="prop-pref"/>.</li> The kind of the resource. The allowed values are defined in the pr
<li>label: <tt>String</tt> (optional). operty definition that makes use of the
A custom label for the value, see <xref target="prop-label"/>.</li> Resource type. Some property definitions may change this property
</ul> from being optional to mandatory.
</dd>
<dt>uri: String (mandatory).</dt>
<dd>
The resource value. This <bcp14>MUST</bcp14> be a <em>URI</em> as
defined in <xref target="RFC3986" sectionFormat="of" section="3"/>.
</dd>
<dt>mediaType: String (optional).</dt>
<dd>
The media type <xref target="RFC2046" format="default"/> of the re
source identified by the uri property value.
</dd>
<dt>contexts: String[Boolean] (optional).</dt>
<dd>
The contexts in which to use this resource. Also see <xref target=
"prop-contexts"/>.
</dd>
<dt>pref: UnsignedInt (optional).</dt>
<dd>
The preference of the resource in relation to other resources. Als
o see <xref target="prop-pref"/>.
</dd>
<dt>label: String (optional).</dt>
<dd>
A custom label for the value. Also see <xref target="prop-label"/>
.
</dd>
</dl>
</section> </section>
<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>The UTCDateTime type is a String in "date-time" format <xref target
ate-time</tt> format, with the further restrictions that any letters <bcp14>MUST ="RFC3339" format="default"/>, with
</bcp14> be in uppercase, and the time offset <bcp14>MUST</bcp14> be the charact further restrictions that any letters <bcp14>MUST</bcp14> be in uppe
er <tt>Z</tt>. Fractional second values <bcp14>MUST NOT</bcp14> be included unl rcase and the time offset <bcp14>MUST
ess non-zero and <bcp14>MUST NOT</bcp14> have trailing zeros, to ensure there is </bcp14> be the character "Z". Fractional second values <bcp14>MUST
only a single representation for each date-time.</t> NOT</bcp14> be included unless they are
<t>For example, <tt>2010-10-10T10:10:10.003Z</tt> is conformant, but < non-zero, and they <bcp14>MUST NOT</bcp14> have trailing zeros to en
tt>2010-10-10T10:10:10.000Z</tt> is invalid and is correctly encoded as <tt>2010 sure there is only a single
-10-10T10:10:10Z</tt>.</t> representation for each date-time.
</t>
<t>For example, "2010-10-10T10:10:10.003Z" is conformant, but "2010-10
-10T10:10:10.000Z" is invalid; the
correct encoding is "2010-10-10T10:10:10Z".
</t>
</section> </section>
</section> </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
type. The properties in this section are common to multiple data types and are defined along with the respective object type. The properties in this
defined here to avoid repetition. Note that these properties <bcp14>MUST</bcp1 section are common to multiple data
4> only be set for a JSContact object if they are explicitly mentioned to be all types and are defined here to avoid repetition. Note that these proper
owed for this object type.</t> ties <bcp14>MUST</bcp14> only be set for
a JSContact object if they are explicitly mentioned as allowable for t
his 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 instance
s.
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 conte
xts
in which it should be used.
Perhaps:
1.5.1 contexts
Type: String[Boolean]
The contexts property associates contact information with one or mo
re
contexts in which it should be used.
...
Original:
2.3.4 preferredLanguages
Type: Id{LanguagePref] (optional).
Defines the preferred languages for contacting the entity associate
d
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> <dl spacing="normal">
<t>This property associates contact information with one or more conte <dt>contexts: String[Boolean].</dt>
xts in which it should be used. For example, someone might have distinct phone <dd>
numbers for work and private contexts, and may set the desired context on the re <t>The contexts in which to use the contact information. For examp
spective phone number in the <xref target="phones"><tt>phones</tt></xref> proper le, someone might have distinct phone numbers for work and private contexts and
ty.</t> may set the desired context on the respective phone number in the <xref target="
<t>This section defines common contexts. Additional contexts may be d phones"> phones </xref> property. </t>
efined in the properties or data types that make use of this property. The <xre <t>This section defines common contexts. Additional contexts may b
f target="enumerated-values">enumerated</xref> common context values are:</t> e defined in the properties or data
<ul spacing="normal"> types that make use of this property. The <xref target="enumerat
<li><tt>private</tt>: the contact information may be used in a priva ed-values">enumerated
te context.</li> </xref> common context values are:
<li><tt>work</tt>: the contact information may be used in a professi </t>
onal context.</li> <ul spacing="normal">
</ul> <li>private: the contact information that may be used in a priva
</section> te context.</li>
<section anchor="prop-extra" numbered="true" toc="default"> <li>work: the contact information that may be used in a professi
<name>extra</name> onal context.</li>
<t>This is a reserved property name. Implementations <bcp14>MUST NOT</ </ul>
bcp14> set this property in a JSContact object. Any JSContact object including </dd>
a property with this name <bcp14>MUST</bcp14> be considered invalid.</t> </dl>
<t>The purpose of this reserved property name is to provide implemento
rs with a name which is certain to never occur as a property name in a JSContact
object. Implementations might want to map unknown or vendor-specific propertie
s 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> <dl spacing="normal">
<t>This property allows associating contact data with user-defined lab <dt>label: String.</dt>
els. Such labels may be set for phone numbers, email addresses and resources. <dd>The labels associated with the contact data. Such labels may be
Typically, these labels are displayed along with their associated contact data i set for
n graphical user interfaces. Such labels best be succinct to properly display o phone numbers, email addresses, and other resources. Typically, th
n small graphical interfaces and screens.</t> ese labels are displayed along with their
associated contact data in graphical user interfaces. Note that su
ccinct labels are best for proper
display on small graphical interfaces and screens.
</dd>
</dl>
</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> <dl spacing="normal">
<t>This property allows defining a preference order for contact inform <dt>pref: UnsignedInt.</dt>
ation. For example, a person may have two email addresses and prefer to be cont <dd>
acted with one of them.</t> <t>A preference order for contact information. For example, a pers
<t>Its value <bcp14>MUST</bcp14> be in the range 1 and 100. Lower val on may
ues correspond to a higher level of preference, with 1 being most preferred. If have two email addresses and prefer to be contacted with one of
no preference is set, then the contact information <bcp14>MUST</bcp14> be inter them.
preted as being least preferred.</t> </t>
<t>Note that the preference only is defined in relation to contact inf <t>The value <bcp14>MUST</bcp14> be in the range of 1 to 100. Lowe
ormation of the same type. For example, the preference orders within emails and r values correspond to a higher level of
phone numbers are independent of each other.</t> preference, with 1 being most preferred. If no preference is set
, then the contact information <bcp14>
MUST
</bcp14> be interpreted as being least preferred.
</t>
<t>Note that the preference is only defined in relation to contact
information of the same type. For
example, the preference orders within emails and phone numbers a
re independent of each other.
</t>
</dd>
</dl>
</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 following properties define how to pronounce a value in the lan
cated in the Card <xref target="language">language</xref> property or the langua guage indicated in the Card <xref target="language">language
ge tag of its <xref target="localizations">localizations</xref>. Exemplary uses </xref> property or the language tag of its <xref target="localization
are to define how to pronounce Japanese names, or for romanization of Mandarin s">localizations</xref>. Exemplary uses
or Cantonese name and address components. The properties are defined as follows of these properties are defining how to pronounce Japanese names and
:</t> romanizing Mandarin or Cantonese name
<ul spacing="normal"> and address components. The properties are defined as follows:
<li> </t>
<t>phonetic: <tt>String</tt>. <dl spacing="normal">
Contains the phonetic representation of a value. Any script lan <dt>phonetic: String.</dt>
guage subtag in the Card <xref target="language">language</xref> property <bcp14 <dd>
>MUST</bcp14> be ignored for use with the <tt>phonetic</tt> property. If this p The phonetic representation of a value.
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> <!--[rfced] Can "ignored for use with" be updated as "ignored and
</li> not
<li> used with" for clarity as shown below?
<t>phoneticScript: <tt>String</tt>.
The script used in the value of the related <tt>phonetic</tt> pr Original:
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 for use with the phonetic property.
</li>
<li> Perhaps:
<t>phoneticSystem: <tt>String</tt>. Any script language subtag in the Card language (Section 2.1.5)
The phonetic system used in the related value of the <tt>phonetic< property MUST be ignored and not used with the phonetic propert
/tt> property. The <xref target="enumerated-values">enumerated values</xref> ar y.
e:</t> -->
Any script language subtag in the Card <xref target="language">lan
guage</xref> property <bcp14>MUST
</bcp14> be ignored and not used with the phonetic property. If this
property is set, then at least one of
the phoneticScript or phoneticSystem properties that relate to thi
s value <bcp14>MUST</bcp14> be set.
</dd>
<dt>phoneticScript: String.</dt>
<dd>
The script used in the value of the related phonetic property. Thi
s <bcp14>MUST</bcp14> be a valid script
subtag as defined in <xref target="RFC5646" section="2.2.3"/>.
</dd>
<dt>phoneticSystem: String.</dt>
<dd>
<t>
The phonetic system used in the related value of the phonetic pr
operty. The <xref target="enumerated-values">enumerated
</xref> values are:
</t>
<ul> <ul>
<li><tt>ipa</tt>: denotes the <xref target="IPA">International P <li>ipa: denotes the <xref target="IPA">International Phonetic A
honetic Alphabet</xref>.</li> lphabet</xref>.
<li><tt>jyut</tt>: denotes the Cantonese romanization system "Jy </li>
utping".</li> <li>jyut: denotes the Cantonese romanization system "Jyutping".<
<li><tt>piny</tt>: denotes the Standard Mandarin romanization sy /li>
stem "Hanyu Pinyin".</li> <li>piny: denotes the Standard Mandarin romanization system "Han
yu Pinyin".</li>
</ul> </ul>
</li> </dd>
</ul> </dl>
<t>The relation between the <tt>phoneticSystem</tt>, <tt>phoneticScrip <t>The relation between the phoneticSystem, phoneticScript, and phonet
t</tt> and <tt>phonetic</tt> properties is type-specific. This specification de ic properties is type-specific. This
fines this relation in the <xref target="name">Name</xref> and <xref target="add specification defines this relation in the <xref target="name">Name<
resses">Address</xref> object types, respectively.</t> /xref> and <xref target="address">
<t>The following example illustrates the <tt>phonetic</tt> property fo Address
r a <xref target="name">name</xref>:</t> </xref> object types, respectively.
</t>
<t>The following example illustrates the phonetic property for a <xref
target="name-prop">name</xref>:
</t>
<figure anchor="example-phonetic"> <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 phonetic Property for the Name "John Smith" as Pr onounced 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 <t>JSContact aims to be used for international contacts and address book
data. Notably text values such as names and addresses are likely to cover a wide data. Notably, text values such as
range of languages and cultures. This section describes internationalization f names and addresses are likely to cover a wide range of languages and
or free-form text values, as well as for Uniform Resource Identifiers (URIs).</t cultures. This section describes
> internationalization for free-form text values as well as Uniform Reso
urce 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
can contain unidirectional left-to-right and right-to-left text, as well as bidi encoded as a JSON string. Such values can contain unidirectional lef
rectional text using Unicode Directional Formatting Characters described in Sect t-to-right and right-to-left text, as
ion 2 of <xref target="UBiDi"/>. Implementations setting bidirectional text <bcp well as bidirectional text using Unicode Directional Formatting Char
14>MUST</bcp14> make sure that each property value complies with the requirement acters as described in Section 2 of <xref target="UBiDi"/>. Implementations sett
s of the Unicode Bidirectional Algorithm. Implementations <bcp14>MUST NOT</bcp1 ing bidirectional text <bcp14>MUST</bcp14> make sure that each
4> assume that text values of adjacent properties are processed or displayed as property value complies with the requirements of the Unicode Bidirec
a combined string, for example the values of a given name component and a surnam tional Algorithm. Implementations <bcp14>
e component may or may not to be rendered together.</t> MUST NOT
</bcp14> assume that text values of adjacent properties are processe
d or displayed as a combined string; for
example, the values of a given name component and a surname componen
t 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"/>.
use proper percent-encoding for URIs that can not be represented using unreserv Implementations <bcp14>MUST</bcp14> make sure to use proper percent-
ed URI characters. <xref target="RFC3987" section="3.1"/> defines how to conver encoding for URIs that cannot be
t Internationalized Resource Identifiers to URIs. JSContact makes no recommenda represented using unreserved URI characters.
tion how to display URIs, but section "4.8.3 Internationalization and special ch <xref target="RFC3987" section="3.1"/>
aracters" of the <xref target="W3C-URL">W3C URL Standard</xref> provides guidanc defines how to convert Internationalized Resource Identifiers to URI
e for URLs found in context of a web browser.</t> s.
<!--[rfced] We notice that "URL Living Standard"
<https://url.spec.whatwg.org> is from the WHATWG and not the
W3C. We updated the running text and reference entry to reflect
this as shown below. Please let us know if any further changes
are needed.
Original:
JSContact makes no recommendation how to display URIs, but
section "4.8.3 Internationalization and special characters"
of the W3C URL Standard [W3C-URL] provides guidance for URLs
found in context of a web browser.
[W3C-URL] "W3C WG URL - Living Standard - Last Updated 21 August
2023", <https://url.spec.whatwg.org>.
Current:
JSContact makes no recommendation on how to display URIs, but the
WHATWG URL Living Standard (see "Internationalization and special
characters"
(Section 4.8.3) of [WHATWG-URL]) provides guidance for URLs found
in
the context of a web browser.
[WHATWG-URL] WHATWG, "URL Living Standard", January 2024,
<https://url.spec.whatwg.org>.
-->
JSContact makes no recommendation on how to display URIs, but the WH
ATWG URL Living Standard (see
"Internationalization and special characters" (Section 4.8.3) of <xr
ef 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
d in this section, while vendor-specific properties are defined in <xref target= properties and unknown properties, which are defined in this section,
"vendor-specific-properties"/>. A JSContact object is invalid if any of its pro and vendor-specific properties, which
perties are invalid.</t> are defined in <xref target="vendor-specific-properties"/>. A JSContac
<t>This document defines for each property if it is mandatory or optiona t object is invalid if any of its
l. A mandatory property <bcp14>MUST</bcp14> be present for a JSContact object t properties are invalid.
o be valid. An optional property does not need to be present. The values of bo </t>
th required and optional properties <bcp14>MUST</bcp14> adhere to the data type <t>This document defines whether each property is mandatory or optional.
and definition of that property.</t> A mandatory property <bcp14>MUST
</bcp14> be present for a JSContact object to be valid. An optional prop
erty does not need to be present. The
values of both required and optional properties <bcp14>MUST</bcp14> ad
here to the data type and 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 <t>All property names, object type names, and enumerated values are ca
e-sensitive, if not explicitly stated otherwise in their according definition. se-sensitive, unless explicitly stated
Implementations <bcp14>MUST</bcp14> handle a JSContact object as invalid if a ty otherwise in their definitions. Implementations <bcp14>MUST</bcp14>
pe name, property name or enumerated value only differs in case from one defined handle a JSContact object as invalid if
for any JSContact version known to that implementation. This applies regardles a type name, property name, or enumerated value only differs in case
s of what JSContact version the Card object defines in its <xref target="prop-ve from one defined for any JSContact
rsion"><tt>version</tt></xref> property. <xref target="unknown-properties"/> de version known to that implementation. This applies regardless of wha
fines how to handle unknown properties.</t> t JSContact version the Card object
defines in its <xref target="prop-version">version</xref> property.
<xref target="unknown-properties"/>
defines how to handle unknown properties.
</t>
</section> </section>
<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>
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>
Implementations <bcp14>MUST</bcp14> validate IANA-registered properties An IANA-registered property is any property that has been registered
in JSContact data, unless they are unknown to the implementation (see <xref targ according to the IANA property registry
et="unknown-properties"/>). They <bcp14>MUST</bcp14> reject invalid IANA-regist rules as outlined in <xref target="iana-considerations"/>. All prope
ered properties. A property is invalid if its name matches the name of an IANA- rties defined in this specification,
registered property but the value violates its definition according to the JSCon including their object value types and enumerated values, are regist
tact specification version defined in the Card <tt>version</tt> property (<xref ered at IANA.
target="prop-version"/>). </t>
</t>
<t> <t>
IANA-registered property names <bcp14>MUST NOT</bcp14> contain US-AS Implementations <bcp14>MUST</bcp14> validate IANA-registered propert
CII control characters (U+0000 to U+001F, U+007F), the <tt>COLON</tt> (U+003A) o ies in JSContact data, unless they are
r <tt>QUOTATION MARK</tt> (U+0022) characters. They <bcp14>MUST</bcp14> only co unknown to the implementation (<xref target="unknown-properties"/>).
ntain US-ASCII alphanumeric characters that match the ALPHA and DIGIT rules defi They <bcp14>MUST</bcp14> reject invalid
ned in <xref target="RFC5234" section="B.1"/>) or the <tt>COMMERCIAL AT</tt> (U+ IANA-registered properties. A property is invalid if its name matche
0040) character. IANA-registered property names <bcp14>MUST</bcp14> be notated s the name of an IANA-registered
in lower camel case. property but the value violates its definition according to the JSCo
</t> ntact specification version defined in
the Card <xref target="prop-version">version</xref> property.
</t>
<t><!-- [rfced] The RFC Production Center has been advised that "ASCII
"
and not "US-ASCII" should be used. May we change two instances
of "US-ASCII" in this document to "ASCII"?
Original:
IANA-registered property names MUST NOT contain US-ASCII control
characters (U+0000 to U+001F, U+007F), the COLON (U+003A) or
QUOTATION MARK (U+0022) characters. They MUST only contain US-AS
CII
alphanumeric characters that match the ALPHA and DIGIT rules defi
ned
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 defi
ned
in Appendix B.1 of [RFC5234]) or the COMMERCIAL AT (U+0040)
character.
-->
IANA-registered property names <bcp14>MUST NOT</bcp14> contain ASCII
control characters (U+0000 to U+001F,
U+007F), the COLON (U+003A), or the QUOTATION MARK (U+0022). They <b
cp14>MUST</bcp14> only contain ASCII
alphanumeric characters that match the ALPHA and DIGIT rules defined
in
<xref target="RFC5234" section="B.1"/>
or the COMMERCIAL AT (U+0040) character. IANA-registered property na
mes <bcp14>MUST</bcp14> be notated in
lower camel case.
</t>
</section>
<section anchor="reserved-properties">
<name>Reserved Properties</name>
<t>IANA-registered properties can be reserved (<xref target="iana-regi
stry-policy"/>). Implementations <bcp14>MUST NOT</bcp14> set properties having
a reserved name in JSContact
objects for which this property is reserved or all objects if the pr
operty context in the registry is "not applicable".
Reserved properties have no type, and their type signature is "not a
pplicable". Any JSContact object including a property that is reserved in conte
xt of this object <bcp14>MUST</bcp14> be considered invalid.</t>
<t>This document reserves one property:</t>
<section anchor="prop-extra" numbered="true" toc="default">
<name>extra</name>
<dl spacing="normal">
<dt>extra: not applicable.</dt>
<dd>The reserved property "extra" provides implementors with a pro
perty name that is certain to never
occur as a property in any JSContact object. Implementations mig
ht want to map unknown or vendor-specific
properties to a variable with this name, but this is implementat
ion-specific.
</dd>
</dl>
</section>
</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
ions of IANA-registered property names. Implementations <bcp14>MUST</bcp14> mak name adheres to the syntactic restrictions of IANA-registered proper
e sure that such a name does not violate the case-sensitivity rules defined in < ty names. Implementations <bcp14>MUST
xref target="case-sensitivity"/>. If the property name is valid, then implement </bcp14> make sure that such a name does not violate the case-sensitiv
ations <bcp14>MUST NOT</bcp14> treat such properties as invalid. Instead, they ity rules defined in <xref target="case-sensitivity"/>. If the property name is
<bcp14>MUST</bcp14> preserve them in the JSContact object.</t> valid, then implementations <bcp14>MUST NOT
<t>Implementations that create or update JSContact data <bcp14>MUST</b </bcp14> treat such properties as invalid. Instead, they <bcp14>MUST</
cp14> only set IANA-registered properties or vendor-specific properties. Preser bcp14> preserve them in the JSContact
ving properties that are unknown to the implementation, is to allow applications object.
and services to interoperate without data loss, even if not all of them impleme </t>
nt the same set of JSContact extensions. <t>Implementations that create or update JSContact data <bcp14>MUST</b
</t> cp14> only set IANA-registered
properties or vendor-specific properties. Preserving properties that
are unknown to the implementation is to
allow applications and services to interoperate without data loss, e
ven if not all of them implement the
same set of JSContact extensions.
</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 <t>Several properties in this document restrict their allowed values t
to be from a list of String values. These values are case-sensitive. If not no o a list of String values. These values
ted otherwise for a specific property, the initial list of values for such prope are case-sensitive. If not noted otherwise for a specific property,
rties is registered at IANA in the <xref target="iana-enum-registry">JSContact E the initial list of values for such
num Values Registry</xref>. Implementations <bcp14>MUST</bcp14> only set IANA-r properties is registered at IANA in the <xref target="iana-enum-regi
egistered or <xref target="vendor-specific-values">vendor-specific</xref> values stry">"JSContact Enum Values"
for such properties.</t> registry</xref>. Implementations <bcp14>MUST</bcp14> only set IANA
-registered or <xref target="vendor-specific-values">vendor-specific
</xref> values for such properties.
</t>
</section> </section>
</section> </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 <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 ore contacts data that is only useful
extensions are not meant for interoperation. If instead interoperation is desi for a single service or application. Such extensions are not meant for
red, vendors are strongly encouraged to define and register new properties, type interoperation. If, instead,
s and values at IANA. <xref target="iana-considerations"/> defines how to regis interoperation is desired, vendors are strongly encouraged to define a
ter new properties, types or values at IANA. <xref target="iana-registered-prop nd register new properties, types, and
erties"/> defines the naming conventions for IANA-registered elements.</t> values at IANA as defined in <xref target="iana-considerations"/>.
<xref target="iana-registered-properties"/>
defines the naming conventions for IANA-registered elements.
</t>
<section anchor="vendor-specific-properties" numbered="true" toc="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 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 or-specific prefix followed by a name,
BNF below. The prefix and name together form the property name. The vendor-spe as produced by the "v-extension" ABNF below. The prefix and name tog
cific prefix <bcp14>MUST</bcp14> be a domain name under control of the service o ether form the property name. The
r application that sets the property, but it need not resolve in the Domain Name vendor-specific prefix <bcp14>MUST</bcp14> be a domain name under co
System <xref target="RFC1034"/> and <xref target="RFC1035"/>. The prefix <tt>i ntrol of the service or application that
etf.org</tt> and its subdomain names are reserved for IETF specifications. The sets the property, but it need not resolve in the Domain Name System
name <bcp14>MUST NOT</bcp14> contain the <tt>TILDE</tt> (U+007E) and <tt>SOLIDUS <xref target="RFC1034"/>
</tt> (U+002F) characters, as these require special-escaping when encoding a JSO <xref target="RFC1035"/>. The prefix "ietf.org" and its subdomain na
N Pointer <xref target="RFC6901"/> for that property. mes are reserved for IETF
</t> specifications. The name <bcp14>MUST NOT</bcp14> contain the TILDE (
U+007E) and SOLIDUS (U+002F) characters,
as these require special escaping when encoding a JSON Pointer
<xref target="RFC6901"/>
for that property.
</t>
<t> <t>
Vendor-specific properties <bcp14>MAY</bcp14> be set in any JSContact ob Vendor-specific properties <bcp14>MAY</bcp14> be set in any JSContac
ject. Implementations <bcp14>MUST</bcp14> preserve vendor-specific properties i t object. Implementations <bcp14>MUST
n JSContact data, irrespective if they know their use. They <bcp14>MUST NOT</bc </bcp14> preserve vendor-specific properties in JSContact data, irresp
p14> reject the property value as invalid, unless they are in control of the ven ective if they know their use. They <bcp14>
dor-specific property as outlined in the above paragraph. MUST NOT
</t> </bcp14> reject the property value as invalid, unless they are in cont
<t>The ABNF rule <tt>v-extension</tt> formally defines valid vendor-sp rol of the vendor-specific property as
ecific property names. Note that the vendor prefix allows for more values than outlined in the above paragraph.
are allowed as Internationalized Domain Names (IDN) <xref target="RFC8499"/>. T </t>
his is to allow JSContact implementations simply validate property names without <t>The ABNF rule "v-extension" formally defines valid vendor-specific
implementing the full set of rules that apply to domain names.</t> property names. Note that the vendor
prefix allows for more values than Internationalized Domain Names (I
DNs) <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, 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 and naming restrictions do not apply to
erty value is a JSON object then the keys of such objects need not be named as v such values. Specifically, if the property value is a JSON object, t
endor-specific properties. The example in <xref target="vendor-property-example hen the keys of such objects need not be
"/> illustrates this: named as vendor-specific properties, as illustrated in <xref target=
</t> "vendor-property-example"/>:
</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 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 endor-specific. One such example is the <xref target="kind">"kind"
nd"/>, which enumerates its standard values but also allows for arbitrary vendor </xref> property, which enumerates its standard values but also allows
-specific values. Such vendor-specific values <bcp14>MUST</bcp14> be valid <tt> for arbitrary vendor-specific values.
v-extension</tt> values as defined in <xref target="vendor-specific-properties"/ Such vendor-specific values <bcp14>MUST</bcp14> be valid "v-extensio
>. The example in <xref target="vendor-value-example"/> illustrates this: n" values as defined in <xref target="vendor-specific-properties"/>. The example
</t> in
<xref target="vendor-value-example"/>
illustrates this:
</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 Vendors are strongly encouraged to specify a new standard value once
dor-specific one turns out to be useful also for other systems. a vendor-specific one turns out to also
</t> be useful for other systems.
</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
n. The version is indicated both in the <xref target="prop-version"><tt>version IANA-registered properties and values are based on.
</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?
<section>
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">versi
on</xref> property within the Card and
in the <xref target="iana-media-type">version</xref> parameter of the
JSContact media type. All
IANA-registered elements indicate the version at which they were intro
duced or obsoleted.
</t>
<t>A JSContact version consists of a major and minor version.</t>
<t>Differing major version values indicate substantial differences in JS
Contact semantics and format.
Implementations <bcp14>MUST</bcp14> be prepared for property definitio
ns and other JSContact elements that
differ in a backwards-incompatible manner.
</t>
<t>Differing minor version values indicate additions that enrich JSConta
ct data but do not introduce
backwards-incompatible changes. Typically, these are new property enum
values or properties with a narrow
semantic scope. A new minor version <bcp14>MUST NOT</bcp14> require im
plementations to change their processing
of JSContact data. Changing the major version number resets the minor
version number to zero.
</t>
<section anchor="version-format-and-reqs">
<name>Version Format and Requirements</name> <name>Version Format and Requirements</name>
<t>A JSContact version consists of a numeric major and minor version, <t>A version value starts with the numeric major version, followed by
separated by the <tt>FULL STOP</tt> character (U+002E). Later versions are nume the FULL STOP character (U+002E),
rically higher than former versions, with the major version being more significa followed by the numeric minor version. Later versions are numericall
nt than the minor version. A version value is produced by the ABNF</t> y higher than former versions, with the
<sourcecode name="" type="abnf"><![CDATA[ major version being more significant than the minor version. A versi
on value is produced by the following
ABNF:
</t>
<!--[rfced] Should Figure 5 have a title? Please review, and provide
a title if desired.
-->
<figure>
<name>The ABNF for JSContact Version Values</name>
<sourcecode name="" type="abnf"><![CDATA[
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
that property definitions and other JSContact elements differ in a backwards-in
compatible manner.</t>
<t>Differing minor version values indicate additions that enrich JSCon
tact data, but do not introduce backwards-incompatible changes. Typically, thes
e are new property enum values or properties with narrow semantic scope. A new
minor version <bcp14>MUST NOT</bcp14> require implementations to change their pr
ocessing 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> ( <t>This specification registers JSContact version value "1.0" (<xref t
<xref target="tab-iana-version-registry"/>).</t> arget="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 <t>This section defines the JSContact object type Card. A Card stores cont
act information, typically that of a person, organization or company.</t> act information, typically that of a
<t>Its media type is defined in <xref target="iana-media-type"/>.</t> person, organization, or company.
<t><xref target="example-card"/> basic Card for the person "John Doe". A </t>
s the object is the topmost object in the JSON data it has the <tt>@type</tt> pr <t>Its media type is defined in <xref target="iana-media-type"/>.
operty set according to the rules defined <xref target="prop-type"/>.</t> </t>
<t><xref target="example-card"/>
shows a basic Card for the person "John Doe". As the object is the topmo
st object in the JSON data, it has the
@type 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 Card</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 <t>This section defines properties about this instance of a Card such as
s its unique identifier, its creation date, how it relates to other Cards and ot its unique identifier, its creation
her metadata information.</t> 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> <dl spacing="normal">
<t>This <bcp14>MUST</bcp14> be <tt>Card</tt>, if set.</t> <dt>@type: String (mandatory).</dt>
<dd>The JSContact type of the Card object. The value <bcp14>MUST</bc
p14> be "Card".
</dd>
</dl>
</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> <dl spacing="normal">
<t>Specifies the JSContact version used to define this Card. The valu <dt>version: String (mandatory).</dt>
e <bcp14>MUST</bcp14> be one of the IANA-registered JSContact Enum Values for th <dd>The JSContact version of this Card. The value <bcp14>MUST</bcp14
e <tt>version</tt> property. Also see <xref target="current-version"/>.</t> > be one of
the IANA-registered JSContact Version values for the version prope
rty. Also see <xref target="current-version"/>.
</dd>
</dl>
<figure anchor="example-version"> <figure anchor="example-version">
<name><tt>version</tt> example</name> <name>Example for the version Property</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> <dl spacing="normal">
<t>The date and time when this Card was created.</t> <dt>created: UTCDateTime (optional).</dt>
<dd>The date and time when the Card was created.</dd>
</dl>
<figure anchor="example-created"> <figure anchor="example-created">
<name><tt>created</tt> example</name> <name>Example for the created Property</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 <dl spacing="normal">
e kind of the entity the Card represents.</t> <dt>kind: String (optional; default: "individual").</dt>
<t>The <xref target="enumerated-values">enumerated</xref> values are:< <dd>
/t> <t>The kind of the entity the Card represents.</t>
<ul spacing="normal"> <t>The <xref target="enumerated-values">enumerated</xref> values a
<li><tt>individual</tt>: a single person</li> re:
<li><tt>group</tt>: a group person of persons or entities</li> </t>
<li><tt>org</tt>: an organization</li> <ul spacing="normal">
<li><tt>location</tt>: a named location</li> <!--[rfced] In Section 2.1.4 under the definition of "device", w
<li><tt>device</tt>: a device, such as appliances, computers, or net e made
work elements</li> the examples singular since "device" is singular. If you prefer
<li><tt>application</tt>: a software application</li> otherwise, please let us know.
</ul>
Original:
* device: a device, such as appliances, computers, or networ
k
elements
Current:
* device: a device such as an appliance, a computer, or a ne
twork
element
-->
<li>individual: a single person</li>
<li>group: a group of people or entities</li>
<li>org: an organization</li>
<li>location: a named location</li>
<li>device: a device such as an appliance, a computer, or a netw
ork element</li>
<li>application: a software application</li>
</ul>
</dd>
</dl>
<figure anchor="example-kind"> <figure anchor="example-kind">
<name><tt>kind</tt> example</name> <name>Example for the kind Property</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> <dl spacing="normal">
<t>This is the language tag, as defined in <xref target="RFC5646"/>, t <dt>language: String (optional).</dt>
hat best describes the language used for text in the Card, optionally including <dd>
additional information such as the script. Note that values <bcp14>MAY</bcp14> <t>The language tag, as defined in <xref target="RFC5646"/>, that
be localized in the <tt>localizations</tt> property <xref target="localizations" best describes the language used
/>.</t> for text in the Card, optionally including additional informatio
n such as the script. Note that values <bcp14>
MAY
</bcp14> be localized in the <xref target="localizations">
localizations
</xref> property.
</t>
</dd>
</dl>
<figure anchor="example-language"> <figure anchor="example-language">
<name><tt>language</tt> example</name> <name>Example for the language Property</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> <dl spacing="normal">
<t>This identifies the set of Cards that are members of this group Car <dt>members: String[Boolean] (optional).</dt>
d. Each key in the set is the <tt>uid</tt> property value of the member, each b <dd>
oolean value <bcp14>MUST</bcp14> be <tt>true</tt>. If this property is set, then <t>The set of Cards that are members of this group Card. Each key
the value of the <tt>kind</tt> property <bcp14>MUST</bcp14> be <tt>group</tt>.< in the set is the uid
/t> property value of the member, and each boolean value <bcp14>MUST
<t>The opposite is not true. A group Card will usually contain the <t </bcp14> be "true". If this property is
t>members</tt> property to specify the members of the group, but it is not requi set, then the value of the kind property <bcp14>MUST</bcp14> be
red to. A group Card without the <tt>members</tt> property can be considered an "group".
abstract grouping, or one whose members are known empirically (e.g., "IETF Par </t>
ticipants").</t> <t>The opposite is not true. A group Card will usually contain the
members property to specify the members
of the group, but it is not required to. A group Card without th
e members property can be considered an
abstract grouping or one whose members are known empirically (e.
g., "IETF Participants").
</t>
</dd>
</dl>
<figure anchor="example-members"> <figure anchor="example-members">
<name><tt>members</tt> example</name> <name>Example for the members Property</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> <dl spacing="normal">
<t>The identifier for the product that created the Card. If set, the <dt>prodId: String (optional).</dt>
value <bcp14>MUST</bcp14> be at least one character long.</t> <dd>
<t>The identifier for the product that created the Card. If set, t
he value <bcp14>MUST</bcp14> be at least
one character long.
</t>
</dd>
</dl>
<figure anchor="example-prodId"> <figure anchor="example-prodId">
<name><tt>prodId</tt> example</name> <name>Example for the prodId Property</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> <dl spacing="normal">
<t>Relates the object to other Cards. This is represented as a map, w <dt>relatedTo: String[Relation] (optional).</dt>
here each key is the <tt>uid</tt> of the related Card and the value defines the <dd>
relation. The Relation object has the following properties:</t> <t>The set of Card objects that relate to the Card. The value is a
<ul spacing="normal"> map, where each key is the uid property
<li>@type: <tt>String</tt>. value of the related Card, and the value defines the relation.
This <bcp14>MUST</bcp14> be <tt>Relation</tt>, if set. </t>
</li> </dd>
<li> </dl>
<t>relation: <tt>String[Boolean]</tt> (optional, default: empty Ob <t>The Relation object has the following properties:</t>
ject) <dl spacing="normal">
Describes how the linked object is related to the linking object <dt>@type: String.</dt>
. The relation is defined as a set of relation types. The key in the set defin <dd>
es the relation type, the value for each key in the set <bcp14>MUST</bcp14> be < The JSContact type of the object. The value <bcp14>MUST</bcp14> be
tt>true</tt>. The relationship between the two objects is undefined if the set "Relation", if set.
is empty.</t> </dd>
<t>The initial list of <xref target="enumerated-values">enumerated <dt>relation: String[Boolean] (optional; default: empty Object).</dt
</xref> relation types matches the IANA-registered <xref target="IANAvCard">TYPE >
parameter</xref> values of the vCard RELATED property (<xref target="RFC6350" s <dd>
ection="6.6.6"/>):</t> <t>The relationship of the related Card to the Card, defined as a
set of relation types.
The keys in the set define the relation type; the values for each
key in the set <bcp14>MUST</bcp14> be "true".
The relationship between the two objects is undefined if the set i
s empty.
</t>
<t>The initial list of <xref target="enumerated-values">enumerated
</xref> relation types matches the
IANA-registered <xref target="IANA-vCard">TYPE</xref> parameter
values of the vCard RELATED property
(<xref target="RFC6350" section="6.6.6"/>):
</t>
<!--[rfced] In Section 2.1.8, we updated the order of the enumerat
ed
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 l
et
us know if any other terms should be placed in alphabetical order.
-->
<ul> <ul>
<li> <li>
<tt>acquaintance</tt> acquaintance
</li> </li>
<li> <li>
<tt>agent</tt> agent
</li> </li>
<li> <li>
<tt>child</tt> child
</li> </li>
<li> <li>
<tt>colleague</tt> co-resident
</li> </li>
<li> <li>
<tt>contact</tt> co-worker
</li> </li>
<li> <li>
<tt>co-resident</tt> colleague
</li> </li>
<li> <li>
<tt>co-worker</tt> contact
</li> </li>
<li> <li>
<tt>crush</tt> crush
</li> </li>
<li> <li>
<tt>date</tt> date
</li> </li>
<li> <li>
<tt>emergency</tt> emergency
</li> </li>
<li> <li>
<tt>friend</tt> friend
</li> </li>
<li> <li>
<tt>kin</tt> kin
</li> </li>
<li> <li>
<tt>me</tt> me
</li> </li>
<li> <li>
<tt>met</tt> met
</li> </li>
<li> <li>
<tt>muse</tt> muse
</li> </li>
<li> <li>
<tt>neighbor</tt> neighbor
</li> </li>
<li> <li>
<tt>parent</tt> parent
</li> </li>
<li> <li>
<tt>sibling</tt> sibling
</li> </li>
<li> <li>
<tt>spouse</tt> spouse
</li> </li>
<li> <li>
<tt>sweetheart</tt> sweetheart
</li> </li>
</ul> </ul>
</li> </dd>
</ul> </dl>
<figure anchor="example-relatedto"> <figure anchor="example-relatedto">
<name><tt>relatedTo</tt> example</name> <name>Example for the relatedTo Property</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> <dl spacing="normal">
<t>An identifier, used to associate the object as the same across diff <dt>uid: String (mandatory).</dt>
erent systems, address books and views. The value <bcp14>SHOULD</bcp14> be a UR <dd>
N <xref target="RFC8141"/> but for compatibility with <xref target="RFC6350"/> i <t>An identifier that associates the object as the same across dif
t <bcp14>MAY</bcp14> also be a URI <xref target="RFC3986"/> or free-text value. ferent systems, address books,
The value of the URN <bcp14>SHOULD</bcp14> be in the <tt>uuid</tt> namespace <x and views. The value <bcp14>SHOULD</bcp14> be a URN <xref target
ref target="RFC4122" format="default"/>. As of this writing, a <xref target="I- ="RFC8141"/>, but for compatibility with
D.ietf-uuidrev-rfc4122bis">revision</xref> of the UUID standard document is bein <xref target="RFC6350"/>, it <bcp14>MAY</bcp14> also be a URI
g worked on and is likely to introduce new UUID versions and best practices to g <xref target="RFC3986"/>
enerate global unique identifiers. Implementors <bcp14>SHOULD</bcp14> follow an or free-text value. The value of the URN <bcp14>SHOULD</bcp14> b
y recommendations described there. Until then, implementations <bcp14>SHOULD</b e in the "uuid" namespace <xref target="RFC4122" format="default"/>.
cp14> generate identifiers using the random or pseudo-random UUID version descri </t>
bed in <xref target="RFC4122" section="4.4"/>.</t> <!--[rfced] FYI: For clarity and ease of reading, we added a refer
ence
to RFC 4122 as shown below.
Original:
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 glob
al
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].
-->
<t>As of this writing, a <xref target="I-D.ietf-uuidrev-rfc4122bis
">revision</xref> of the Universally
Unique Identifier (UUID) Standards Track document
<xref target="RFC4122" format="default"/>
is in progress and will likely introduce new UUID versions and b
est practices to generate global unique
identifiers. Implementors <bcp14>SHOULD</bcp14> follow any recom
mendations 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>
</dd>
</dl>
<figure anchor="example-uid"> <figure anchor="example-uid">
<name><tt>uid</tt> example</name> <name>Example for the uid Property</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> <dl spacing="normal">
<t>The date and time when the data in this Card was last modified.</t> <dt>updated: UTCDateTime (optional).</dt>
<dd>The date and time when the data in the Card was last modified.</
dd>
</dl>
<figure anchor="example-updated"> <figure anchor="example-updated">
<name><tt>updated</tt> example</name> <name>Example for the updated Property</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 <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 he Card and its related organizations
y represented by this Card in spoken or written language.</t> and roles. It also describes how to refer to the entity represented by
<section anchor="name" numbered="true" toc="default"> the Card in spoken or written language.
</t>
<section anchor="name-prop" numbered="true" toc="default">
<name>name</name> <name>name</name>
<t>Type: <tt>Name</tt> (optional).</t> <dl spacing="normal">
<t>The name of the entity represented by this Card. This can be any t <dt>name: Name (optional).</dt>
ype of name, e.g., it can but need not be the legal name of a person.</t> <dd>The name of the entity represented by the Card. This can be any
<section> type of name, e.g., it can, but need
<name>Name object</name> not, be the legal name of a person.
<t>A Name object has the following properties</t> </dd>
<ul spacing="normal"> </dl>
<li>@type: <tt>String</tt>. <section anchor="name">
This <bcp14>MUST</bcp14> be <tt>Name</tt>, if set. <name>Name Object</name>
</li> <t>A Name object has the following properties:</t>
<li> <dl spacing="normal">
<t>components: <tt>NameComponent[]</tt> (optional). The <xref t <dt>@type: String.</dt>
arget="namecomponent">components</xref> making up this name. This property <bcp <dd>
14>MUST</bcp14> be set if the <tt>full</tt> property is not set, otherwise it <b The JSContact type of the object. The value <bcp14>MUST</bcp14>
cp14>SHOULD</bcp14> be set. The component list <bcp14>MUST</bcp14> have at leas be "Name", if set.
t one entry having a different <tt>kind</tt> than <tt>separator</tt>.</t> </dd>
<t>Name components <bcp14>SHOULD</bcp14> be ordered such that th <dt>components: NameComponent[] (optional).</dt>
eir values joined as a String produce a valid full name of this entity. If so, <dd>
implementations <bcp14>MUST</bcp14> set the <tt>isOrdered</tt> property value to <t>The <xref target="namecomponent">components</xref> making up
<tt>true</tt>.</t> this name. The components property <bcp14>
<t>If the name components are ordered, then the <tt>defaultSepar MUST
ator</tt> property and name components of kind <tt>separator</tt> give guidance </bcp14> be set if the full property is not set; otherwise, it <
on what characters to insert between components, but implementations are free to bcp14>SHOULD</bcp14> be set. The
choose any others. In lack of a separator, inserting a single Space character component list <bcp14>MUST</bcp14> have at least one entry hav
in between name component values is a good choice.</t> ing a different kind property value than
<t>If instead the name components follow no particular order, th "separator".
en the <tt>isOrdered</tt> property value <bcp14>MUST</bcp14> be <tt>false</tt>, </t>
the <tt>components</tt> property <bcp14>MUST NOT</bcp14> contain a NameComponent <t>Name components <bcp14>SHOULD</bcp14> be ordered such that wh
of kind <tt>separator</tt> and the <tt>defaultSeparator</tt> property <bcp14>MU en their values are joined as a String,
ST NOT</bcp14> be set.</t> a valid full name of the entity is produced. If so, implementa
<t><xref target="example-name-twoword"/> is an example for the n tions <bcp14>MUST</bcp14> set the
ame "Vincent van Gogh". Note how a single name component value may consist of m isOrdered property value to "true".
ultiple words. <xref target="example-name-surname2"/> illustrates a name with a </t>
second surname, such as a Spanish name. Additional examples are shown in <xref <t>If the name components are ordered, then the defaultSeparator
target="example-name-sortas"/> and <xref target="example-localizations-replace" property and name components with the
/>.</t> kind property value set to "separator" give guidance on what c
haracters to insert between components,
but implementations are free to choose any others. When lackin
g a separator, inserting a single space
character in between the name component values is a good choic
e.
</t>
<t>If, instead, the name components follow no particular order,
then the isOrdered property value <bcp14>
MUST
</bcp14> be "false", the components property <bcp14>MUST NOT</bc
p14> contain a NameComponent with the
kind property value set to "separator", and the defaultSeparat
or property <bcp14>MUST NOT</bcp14> be
set.
</t>
<t><xref target="example-name-twoword"/>
shows an example for the name "Vincent van Gogh". Note how a s
ingle name component value may consist
of multiple words.
</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>
<!--[rfced] FYI: The text that describes Figure 16 was located a
bove
Figure 15, so we placed it above Figure 16 instead. The update i
s
shown in Section 2.2.1.1.
-->
<t><xref target="example-name-surname2"/>
illustrates a name with a second surname such as a Spanish nam
e. Additional examples are shown in
Figures
<xref target="example-name-sortas" format="counter"/>
and <xref target="example-localizations-replace" format="count
er"/>.
</t>
<figure anchor="example-name-surname2"> <figure anchor="example-name-surname2">
<name>Example for a second surname</name> <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: Boolean (optional; default: "false").</dt>
). This indicates if the name component sequence in the <tt>components</tt> pro <dd>The indicator if the name components in the components propert
perty is ordered.</li> y are ordered.</dd>
<li>defaultSeparator: <tt>String</tt> (optional). <dt>defaultSeparator: String (optional).</dt>
The default separator to insert between name component values wh <dd>
en concatenating all name component values to a single String. Also see the def The default separator to insert between name component values wh
inition of the <tt>separator</tt> kind for the NameComponent object. This prope en concatenating all name component
rty <bcp14>MUST NOT</bcp14> be set if the Name <tt>isOrdered</tt> property value values to a single String.
is <tt>false</tt> or if the <tt>components</tt> property is not set.</li>
<li> <!--[rfced] FYI: For ease, we added links to Sections 2.2.1.2
<t>full: <tt>String</tt> (optional). (NameComponent) and 2.5.1.2 (AddressComponent) in the text
This is the full name representation of this Name. This property <b shown below. If any further updates are needed, please let us
cp14>MUST</bcp14> be set if the <tt>components</tt> property is not set.</t> know.
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 kind property value "separ
ator" for the <xref target="namecomponent">
NameComponent
</xref> object. The defaultSeparator property <bcp14>MUST NOT</bcp
14> be set if the Name isOrdered
property value is "false" or if the components property is not s
et.
</dd>
<dt>full: String (optional).</dt>
<dd>
<t>
The full name representation of the Name. The full property <b
cp14>MUST</bcp14> be set if the
components property is not set.
</t>
<figure anchor="example-full"> <figure anchor="example-full">
<name><tt>full</tt> example</name> <name>Example for the full Property</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: String[String] (optional).
<t>This defines how this name lexicographically sorts in relatio </dt>
n to other names when compared by a name component type. The key in the map def <dd>
ines the name component type. The value for that key defines the verbatim strin <t>The value to lexicographically sort the name in relation to o
g to compare when sorting by this name component type. Absence of a key indicat ther names when compared by a name
es that this name component type <bcp14>SHOULD NOT</bcp14> be considered during component type. The keys in the map define the name component
sort. Sorting by that missing name component type or if the <tt>sortAs</tt> pro type. The values define the
perty is not set is implementation-specific. This property <bcp14>MUST NOT</bcp verbatim string to compare when sorting by the name component
14> be set if the <tt>components</tt> property is not set.</t> type. Absence of a key indicates that
<t>Each key in the map <bcp14>MUST</bcp14> be a valid name compo the name component type <bcp14>SHOULD NOT</bcp14> be considere
nent type value as defined for the <tt>kind</tt> property of the NameComponent o d during sort. Sorting by that missing
bject (see below). For each key in the map there <bcp14>MUST</bcp14> exist at l name component type, or if the sortAs property is not set, is
east one NameComponent object having that type in the <tt>components</tt> proper implementation-specific. The sortAs
ty of this name.</t> property <bcp14>MUST NOT</bcp14> be set if the components prop
<t><xref target="example-name-sortas"/> illustrates the use of s erty is not set.
ortAs. The property value indicates that the middle name followed by both surna </t>
mes should be used when sorting this name by surname. The absence of the <tt>mi <t>Each key in the map <bcp14>MUST</bcp14> be a valid name compo
ddle</tt> indicates that the middle name on its own should be disregarded during nent type value as defined for the kind
sort. Even though the name only contains one name component for the given name property of the NameComponent object (see below). For each key
, the sortAs property still explicitly defines how to sort by given name as othe in the map, there <bcp14>MUST</bcp14> exist
rwise sorting by it would be undefined.</t> at least one NameComponent object that has the type in the com
</li> ponents property of the name.
<li> </t>
<t>phoneticScript: <tt>String</tt> (optional). <t><xref target="example-name-sortas"/>
The script used in the value of the NameComponent <tt>phonetic</ illustrates the use of the sortAs property. The property value
tt> property. Also see <xref target="prop-phonetic"/>. See <xref target="examp indicates that the middle name followed
le-name-phonetic"/> for an example.</t> by both surnames should be used when sorting the name by surna
</li> me. The absence of "middle" indicates
<li> that the middle name on its own should be disregarded during s
<t>phoneticSystem: <tt>String</tt> (optional). ort. Even though the name only contains
The phonetic system used in the NameComponent <tt>phonetic</tt> pr one name component for the given name, the sortAs property sti
operty. Also see <xref target="prop-phonetic"/>. See <xref target="exampl ll explicitly defines how to sort by the
e-name-phonetic"/> for an example.</t> given name; otherwise, sorting by it would be undefined.
</li> </t>
</ul> </dd>
<dt>
<figure anchor="example-name-sortas"> phoneticScript: String (optional).
<name>Example for <tt>sortAs</tt></name> </dt>
<sourcecode name="" type="json"><![CDATA[ <dd>
The script used in the value of the NameComponent phonetic prope
rty. See
<xref target="prop-phonetic"/>
for more information and
<xref target="example-name-phonetic"/>
for an example.
</dd>
<dt>
phoneticSystem: String (optional).
</dt>
<dd>
<t>
The phonetic system used in the NameComponent phonetic propert
y. See
<xref target="prop-phonetic"/>
for more information and
<xref target="example-name-phonetic"/>
for an example.
</t>
</dd>
</dl>
<figure anchor="example-name-sortas">
<name>Example for the sortAs Property</name>
<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 the phonetic and localizations Properties</name>
<name>Example for <tt>phonetic</tt> and <tt>localizations</tt></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 1569
"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: String.</dt>
This <bcp14>MUST</bcp14> be <tt>NameComponent</tt>, if set. <dd>
</li> The JSContact type of the object. The value <bcp14>MUST</bcp14>
<li>value: <tt>String</tt> (mandatory). be "NameComponent", if set.
The value of this name component. This can be composed of one or multiple words </dd>
, such as "Poe" or "van Gogh".</li> <dt>value: String (mandatory).</dt>
<li> <dd>
<t>kind: <tt>String</tt> (mandatory). The value of the name component. This can be composed of one or
The kind of this name component. The <xref target="enumerated-val multiple words such as "Poe" or "van
ues">enumerated</xref> values are: Gogh".
</t> </dd>
<dt>kind: String (mandatory).</dt>
<dd>
<t>
The kind of the name component. The <xref target="enumerated-v
alues">enumerated</xref> values are:
</t>
<ul spacing="normal"> <ul spacing="normal">
<li><tt>title</tt>: an honorific title or prefix, e.g., "Mr", <li>title: an honorific title or prefix, e.g., "Mr.", "Ms.", o
"Ms", "Dr".</li> r "Dr.".</li>
<li><tt>given</tt>: a given name, also known as "first name", <li>given: a given name, also known as "first name" or "person
"personal name".</li> al name".</li>
<li><tt>given2</tt>: a name that appears between the given and <li>given2: a name that appears between the given and surname
surname, such as a middle name or patronymic name.</li> such as a middle name or patronymic
<li><tt>surname</tt>: a surname, also known as "last name", "f name.
amily name".</li> </li>
<li><tt>surname2</tt>: a secondary surname (used in some cultu <li>surname: a surname, also known as "last name" or "family n
res), also known as "maternal surname".</li> ame".</li>
<li><tt>credential</tt>: a credential, also known as "accredi <li>surname2: a secondary surname (used in some cultures), als
tation qualifier" or "honorific suffix", e.g., "B.A.", "Esq.".</li> o known as "maternal surname".</li>
<li><tt>generation</tt>: a generation marker or qualifier, e.g <li>credential: a credential, also known as "accreditation qua
., “Jr.” or “III”.</li> lifier" or "honorific suffix", e.g.,
<li><tt>separator</tt>: a formatting separator between two ord "B.A.", "Esq.".
ered name non-separator components. The <tt>value</tt> property of the componen </li>
t includes the verbatim separator, for example a hyphen character or even an emp <li>generation: a generation marker or qualifier, e.g., "Jr."
ty string. This value has higher precedence than the <tt>defaultSeparator</tt> or "III".</li>
property of the Name. Implementations <bcp14>MUST NOT</bcp14> insert two consec <li>separator: a formatting separator between two ordered name
utive separator components, instead they <bcp14>SHOULD</bcp14> insert a single s non-separator components. The value
eparator component with the combined value. This component kind <bcp14>MUST NOT property of the component includes the verbatim separator, f
</bcp14> be set if the Name <tt>isOrdered</tt> property value is <tt>false</tt>. or example, a hyphen character or even
</li> an empty string. This value has higher precedence than the d
efaultSeparator property of the Name.
Implementations <bcp14>MUST NOT</bcp14> insert two consecuti
ve separator components; instead, they <bcp14>
SHOULD
</bcp14> insert a single separator component with the combin
ed value. This component kind <bcp14>
MUST NOT
</bcp14> be set if the Name isOrdered property value is "fal
se".
</li>
</ul> </ul>
</li> </dd>
<li>phonetic: <tt>String</tt> (optional). This defines how to pro <dt>phonetic: String (optional).</dt>
nounce this name component. If this property is set, then at least one of the N <dd>The pronounciation of the name component. If this property is
ame object <tt>phoneticSystem</tt> or <tt>phoneticScript</tt> properties <bcp14> set, then at least one of the Name
MUST</bcp14> be set. Also see <xref target="prop-phonetic"/>.</li> object properties, phoneticSystem or phoneticScript, <bcp14>MUST
</ul> </bcp14> be set. Also see <xref target="prop-phonetic"/>.
</dd>
</dl>
</section> </section>
<section anchor="nicknames" numbered="true" toc="default"> </section>
<name>nicknames</name> <section anchor="nicknames" numbered="true" toc="default">
<t>Type: <tt>Id[Nickname]</tt> (optional).</t> <name>nicknames</name>
<t>The nicknames of the entity represented by this Card. A Nickname <dl spacing="normal">
object has the following properties:</t> <dt>nicknames: Id[Nickname] (optional).</dt>
<ul spacing="normal"> <dd>The nicknames of the entity represented by the Card.</dd>
<li>@type: <tt>String</tt>. </dl>
This <bcp14>MUST</bcp14> be <tt>Nickname</tt>, if set. <t>A Nickname object has the following properties:</t>
</li> <dl spacing="normal">
<li>name: <tt>String</tt> (mandatory). <dt>@type: String.</dt>
The nickname. <dd>
</li> The JSContact type of the object. The value <bcp14>MUST</bcp14> be
<li>contexts: <tt>String[Boolean]</tt> (optional) "Nickname", if set.
The contexts in which to use this nickname. Also see <xref target="prop-context </dd>
s"/>.</li> <dt>name: String (mandatory).</dt>
<li>pref: <tt>UnsignedInt</tt> (optional). <dd>
The preference of this nickname in relation to other nicknames. Als The nickname.
o see <xref target="prop-pref"/>.</li> </dd>
</ul> <dt>contexts: String[Boolean] (optional).</dt>
<figure anchor="example-nicknames"> <dd>The contexts in which to use the nickname. Also see <xref target
<name><tt>nicknames</tt> example</name> ="prop-contexts"/>.
<sourcecode name="" type="json"><![CDATA[ </dd>
<dt>pref: UnsignedInt (optional).</dt>
<dd>
The preference of the nickname in relation to other nicknames. Als
o see <xref target="prop-pref"/>.
</dd>
</dl>
<figure anchor="example-nicknames">
<name>Example for the nicknames Property</name>
<sourcecode name="" type="json"><![CDATA[
"nicknames": { "nicknames": {
"k391": { "k391": {
"name": "Johnny" "name": "Johnny"
} }
} }
]]></sourcecode> ]]></sourcecode>
</figure> </figure>
</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> <dl spacing="normal">
<t>The companies or organizations names and units associated with this <dt>organizations: Id[Organization] (optional).</dt>
Card. An Organization object has the following properties, of which at least o <dd>The company or organization names and units associated with the
ne of the <tt>name</tt> and <tt>units</tt> properties <bcp14>MUST</bcp14> be set Card.</dd>
:</t> </dl>
<ul spacing="normal"> <t>An Organization object has the following properties, of which at le
<li>@type: <tt>String</tt>. ast one of the name and units properties <bcp14>
This <bcp14>MUST</bcp14> be <tt>Organization</tt>, if set. MUST
</li> </bcp14> be set:
<li>name: <tt>String</tt> (optional). </t>
The name of this organization. <dl spacing="normal">
</li> <dt>@type: String.</dt>
<li>units: <tt>OrgUnit[]</tt> (optional). <dd>
A list of organizational units, ordered descending by hierarchy (e.g The JSContact type of the object. The value <bcp14>MUST</bcp14> be
., a geographic or functional division sorts before a department within that div "Organization", if set.
ision). If set, the list <bcp14>MUST</bcp14> contain at least one entry. </dd>
</li> <dt>name: String (optional).</dt>
<li>sortAs: <tt>String</tt> (optional). <dd>
This defines how this organization name lexicographically sorts in r The name of the organization.
elation to other organizations when compared by name. The value defines the ver </dd>
batim string value to compare. In absence of this property, the <tt>name</tt> p <dt>units: OrgUnit[] (optional).</dt>
roperty value <bcp14>MAY</bcp14> be used for comparison. <dd>A list of organizational units, ordered as descending by hierarc
</li> hy (e.g., a geographic or functional
<li>contexts: <tt>String[Boolean]</tt> (optional). division sorts before a department within that division). If set,
The contexts in which association with this organization apply. For example, me the list <bcp14>MUST</bcp14> contain at
mbership in a choir may only apply in a private context. Also see <xref target= least one entry.
"prop-contexts"/>.</li> </dd>
</ul> <dt>sortAs: String (optional).</dt>
<t>A OrgUnit object has the following properties:</t> <dd>
<ul spacing="normal"> The value to lexicographically sort the organization in relation t
<li>@type: <tt>String</tt>. o other organizations when compared
This <bcp14>MUST</bcp14> be <tt>OrgUnit</tt>, if set. by name. The value defines the verbatim string value to compare. I
</li> n absence of this property, the name
<li>name: <tt>String</tt> (mandatory). property value <bcp14>MAY</bcp14> be used for comparison.
The name of this organizational unit. </dd>
</li> <dt>contexts: String[Boolean] (optional).</dt>
<li>sortAs: <tt>String</tt> (optional). <dd>The contexts in which association with the organization applies.
This defines how this organization unit name lexicographically sorts For example, membership in a choir may
in relation to other organizational units of the same level when compared by na only apply in a private context. Also see <xref target="prop-conte
me. The level is defined by the array index of this organizational unit in the xts"/>.
<tt>units</tt> property of the Organization object. The property value defines </dd>
the verbatim string value to compare. In absence of this property, the <tt>name </dl>
</tt> property value <bcp14>MAY</bcp14> be used for comparison. <t>An OrgUnit object has the following properties:</t>
</li> <dl spacing="normal">
</ul> <dt>@type: String.</dt>
<dd>
The JSContact type of the object. The value <bcp14>MUST</bcp14> be
"OrgUnit", if set.
</dd>
<dt>name: String (mandatory).</dt>
<dd>
The name of the organizational unit.
</dd>
<dt>sortAs: String (optional).</dt>
<dd>
The value to lexicographically sort the organizational unit in rel
ation to other organizational units
of the same level when compared by name. The level is defined by t
he array index of the organizational
unit in the units property of the Organization object. The propert
y value defines the verbatim string
value to compare. In absence of this property, the name property v
alue <bcp14>MAY</bcp14> be used for
comparison.
</dd>
</dl>
<figure anchor="example-organizations"> <figure anchor="example-organizations">
<name><tt>organizations</tt> example</name> <name>Example for the organizations Property</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> <dl spacing="normal">
<t>Provides information how to address, speak to or refer to the entit <dt>speakToAs: SpeakToAs (optional).</dt>
y that is represented by this Card. A SpeakToAs object has the following proper <dd>The information how to address, speak to, or refer to the entity
ties, of which at least one of the <tt>grammaticalGender</tt> and <tt>pronouns</ that is represented by the
tt> properties <bcp14>MUST</bcp14> be set:</t> Card.
<ul spacing="normal"> </dd>
<li>@type: <tt>String</tt>. </dl>
This <bcp14>MUST</bcp14> be <tt>SpeakToAs</tt>, if set. <t>A SpeakToAs object has the following properties, of which at least
</li> one of the grammaticalGender and
<li> pronouns properties <bcp14>MUST</bcp14> be set:
<t>grammaticalGender: <tt>String</tt> (optional). </t>
Defines which grammatical gender to use in salutations and other g <dl spacing="normal">
rammatical constructs. <dt>@type: String.</dt>
For example, the German language distinguishes by grammatical gend <dd>
er in salutations such as "Sehr geehrte" (feminine) and "Sehr geehrter" (masculi The JSContact type of the object. The value <bcp14>MUST</bcp14> be
ne). "SpeakToAs", if set.
The <xref target="enumerated-values">enumerated</xref> values are: </dd>
</t> <dt>
<ul spacing="normal"> grammaticalGender: String (optional).
</dt>
<dd>
<t>
The grammatical gender to use in salutations and other grammatic
al constructs. For example,
the German language distinguishes by grammatical gender in salut
ations such as "Sehr geehrte" (feminine)
and "Sehr geehrter" (masculine). The <xref target="enumerated-va
lues">enumerated</xref> values are:
</t>
<ul spacing="compact">
<li> <li>
<tt>animate</tt> animate
</li> </li>
<li> <li>
<tt>common</tt> common
</li> </li>
<li> <li>
<tt>feminine</tt> feminine
</li> </li>
<li> <li>
<tt>inanimate</tt> inanimate
</li> </li>
<li> <li>
<tt>masculine</tt> masculine
</li> </li>
<li> <li>
<tt>neuter</tt> neuter
</li> </li>
</ul> </ul>
<t>Note that the grammatical gender does not allow inferring the g <t>Note that the grammatical gender does not allow inferring the g
ender identities or assigned sex of the contact.</t> ender identities or assigned sex of the
</li> contact.
<li> </t>
<t>pronouns: <tt>Id[Pronouns]</tt> (optional). </dd>
Defines the pronouns that the contact chooses to use for themselves <dt>pronouns: Id[Pronouns] (optional).</dt>
.</t> <dd>
</li> <t>
</ul> The pronouns that the contact chooses to use for themselves.
</t>
</dd>
</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: String.</dt>
This <bcp14>MUST</bcp14> be <tt>Pronouns</tt>, if set. <dd>
</li> The JSContact type of the object. The value <bcp14>MUST</bcp14> be
<li>pronouns: <tt>String</tt> (mandatory). "Pronouns", if set.
Defines the pronouns. Any value or form is allowed. Examples in </dd>
English include <tt>she/her</tt> and <tt>they/them/theirs</tt>. The value <bcp1 <dt>pronouns: String (mandatory).</dt>
4>MAY</bcp14> be overridden in the <tt>localizations</tt> property (<xref target <dd>
="localizations"/>).</li> The pronouns. Any value or form is allowed. Examples in English in
<li>contexts: <tt>String[Boolean]</tt> (optional). clude "she/her" and
The contexts in which to use these pronouns. Also see <xref target="prop-contex "they/them/theirs". The value <bcp14>MAY</bcp14> be overridden in
ts"/>.</li> the <xref target="localizations">
<li>pref: <tt>UnsignedInt</tt> (optional). localizations
The preference of these pronouns in relation to other pronouns in th </xref> property.
e same context. Also see <xref target="prop-pref"/>.</li> </dd>
</ul> <dt>contexts: String[Boolean] (optional).</dt>
<dd>The contexts in which to use the pronouns. Also see <xref target
="prop-contexts"/>.
</dd>
<dt>pref: UnsignedInt (optional).</dt>
<dd>
The preference of the pronouns in relation to other pronouns in th
e same context. Also see <xref target="prop-pref"/>.
</dd>
</dl>
<figure anchor="example-speakToAs"> <figure anchor="example-speakToAs">
<name><tt>speakToAs</tt> example</name> <name>Example for the speakToAs Property</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> <dl spacing="normal">
<t>The job titles or functional positions of the entity represented by <dt>titles: Id[Title] (optional).</dt>
this Card. A Title object has the following properties:</t> <dd>The job titles or functional positions of the entity represented
<ul spacing="normal"> by the Card.</dd>
<li>@type: <tt>String</tt>. </dl>
This <bcp14>MUST</bcp14> be <tt>Title</tt>, if set. <t>A Title object has the following properties:</t>
</li> <dl spacing="normal">
<li>name: <tt>String</tt> (mandatory). <dt>@type: String.</dt>
The title or role name of the entity represented by this Card. <dd>
</li> The JSContact type of the object. The value <bcp14>MUST</bcp14> be
<li> "Title", if set.
<t>kind: <tt>String</tt> (optional, default <tt>title</tt>). </dd>
Describes the organizational or situational kind of this title. Some <dt>name: String (mandatory).</dt>
organizations and individuals distinguish between <em>titles</em> as organizatio <dd>
nal positions and <em>roles</em> as more temporary assignments, such as in proje The title or role name of the entity represented by the Card.
ct management.</t> </dd>
<t>The <xref target="enumerated-values">enumerated</xref> values a <dt>kind: String (optional; default: "title").</dt>
re:</t> <dd>
<ul> <t>
<li> The organizational or situational kind of the title. Some organi
<tt>title</tt> zations and individuals
</li> distinguish between <em>titles</em> as organizational positions
<li> and <em>roles</em> as more temporary
<tt>role</tt> assignments such as in project management.
</li> </t>
<t>The <xref target="enumerated-values">enumerated</xref> values a
re:
</t>
<ul spacing="compact">
<li>title</li>
<li>role</li>
</ul> </ul>
</li> </dd>
<li>organizationId: <tt>Id</tt> (optional). <dt>organizationId: Id (optional).</dt>
The identifier of the organization in which this title is held. <dd>
</li> The identifier of the organization in which this title is held.
</ul> </dd>
</dl>
<figure anchor="example-titles"> <figure anchor="example-titles">
<name><tt>titles</tt> example</name> <name>Example for the titles Property</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 1881
"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> <dl spacing="normal">
<t>The email addresses to contact the entity represented by this Card. <dt>emails: Id[EmailAddress] (optional).</dt>
An EmailAddress object has the following properties:</t> <dd>The email addresses in which to contact the entity represented b
<ul spacing="normal"> y the Card.</dd>
<li>@type: <tt>String</tt>. </dl>
This <bcp14>MUST</bcp14> be <tt>EmailAddress</tt>, if set. <t>An EmailAddress object has the following properties:</t>
</li> <dl spacing="normal">
<li>address: <tt>String</tt> (mandatory). <dt>@type: String.</dt>
The email address. This <bcp14>MUST</bcp14> be an <em>addr-spec</em> value as d <dd>
efined in Section 3.4.1 of <xref target="RFC5322" format="default"/>.</li> The JSContact type of the object. The value <bcp14>MUST</bcp14> be
<li>contexts: <tt>String[Boolean]</tt> (optional). "EmailAddress", if set.
The contexts in which to use this email address. Also see <xref target="prop-co </dd>
ntexts"/>.</li> <dt>address: String (mandatory).</dt>
<li>pref: <tt>UnsignedInt</tt> (optional). <dd>
The preference of this email address in relation to other email addr The email address. This <bcp14>MUST</bcp14> be an <em>addr-spec</e
esses. Also see <xref target="prop-pref"/>.</li> m> value as defined in <xref target="RFC5322" sectionFormat="of" section="3.4.1"
<li>label: <tt>String</tt> (optional). />.
A custom label for the value, see <xref target="prop-label"/>.</li> </dd>
</ul> <dt>contexts: String[Boolean] (optional).</dt>
<dd>The contexts in which to use this email address. Also see <xref
target="prop-contexts"/>.
</dd>
<dt>pref: UnsignedInt (optional).</dt>
<dd>
The preference of the email address in relation to other email add
resses. Also see <xref target="prop-pref"/>.
</dd>
<dt>label: String (optional).</dt>
<dd>
A custom label for the value. Also see <xref target="prop-label"/>
.
</dd>
</dl>
<figure anchor="example-emails"> <figure anchor="example-emails">
<name><tt>emails</tt> example</name> <name>Example for the emails Property</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> <dl spacing="normal">
<t>The online services that are associated with the entity represented <dt>onlineServices: Id[OnlineService] (optional).</dt>
by this Card. This can be messaging services, social media profiles, and other <dd>The online services that are associated with the entity represen
. An OnlineService object has the following properties, of which at least the < ted by the Card. This can be messaging
tt>uri</tt> or <tt>user</tt> property <bcp14>MUST</bcp14> be set:</t> services, social media profiles, and other.
<ul spacing="normal"> </dd>
<li>@type: <tt>String</tt>. </dl>
This <bcp14>MUST</bcp14> be <tt>OnlineService</tt>, if set. <t>An OnlineService object has the following properties, of which at l
</li> east the uri or user property <bcp14>
<li>service: <tt>String</tt> (optional). MUST
The name of the online service or protocol. The name <bcp14>MAY</ </bcp14> be set:
bcp14> be capitalized the same as on the service's website, app or publishing ma </t>
terial, but names <bcp14>MUST</bcp14> be considered equal is they match case-ins <dl spacing="normal">
ensitively. Examples are <tt>GitHub</tt>, <tt>kakao</tt>, <tt>Mastodon</tt>.</l <dt>@type: String.</dt>
i> <dd>
<li>uri: <tt>String</tt> (optional). The JSContact type of the object. The value <bcp14>MUST</bcp14> be
This identifies the entity represented by this card at the online service. This "OnlineService", if set.
<bcp14>MUST</bcp14> be a <em>URI</em> as defined in Section 3 of <xref target=" </dd>
RFC3986" format="default"/>.</li> <dt>service: String (optional).</dt>
<li>user: <tt>String</tt> (optional). <dd>
This names the entity represented by this Card at the online servi The name of the online service or protocol. The name <bcp14>MAY</b
ce. Any free-text value is allowed. The <tt>service</tt> property <bcp14>SHOUL cp14> be capitalized the same as on the
D</bcp14> be set.</li> service's website, app, or publishing material, but names <bcp14>M
<li>contexts: <tt>String[Boolean]</tt> (optional). UST</bcp14> be considered equal if they
The contexts in which to use this service. Also see <xref target="prop-contexts match case-insensitively. Examples are "GitHub", "kakao", and "Mas
"/>.</li> todon".
<li>pref: <tt>UnsignedInt</tt> (optional). </dd>
The preference of this service in relation to other services. Also <dt>uri: String (optional).</dt>
see <xref target="prop-pref"/>.</li> <dd>
<li>label: <tt>String</tt> (optional). The identifier for the entity represented by the Card at the onlin
A custom label for the value, see <xref target="prop-label"/>.</li> e service. This <bcp14>MUST</bcp14> be a <em>
</ul> URI
</em> as defined in <xref target="RFC3986" sectionFormat="of" sectio
n="3"/>.
</dd>
<dt>user: String (optional).</dt>
<dd>
The name the entity represented by the Card at the online service.
Any free-text value is allowed. The
service property <bcp14>SHOULD</bcp14> be set.
</dd>
<dt>contexts: String[Boolean] (optional).</dt>
<dd>The contexts in which to use the service. Also see <xref target=
"prop-contexts"/>.
</dd>
<dt>pref: UnsignedInt (optional).</dt>
<dd>
The preference of the service in relation to other services. Also
see <xref target="prop-pref"/>.
</dd>
<dt>label: String (optional).</dt>
<dd>
A custom label for the value. Also see <xref target="prop-label"/>
.
</dd>
</dl>
<figure anchor="example-onlineServices"> <figure anchor="example-onlineServices">
<name><tt>onlineServices</tt> example</name> <name>Example for the onlineServices Property</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> <dl spacing="normal">
<t>The phone numbers to contact the entity represented by this Card. <dt>phones: Id[Phone] (optional).</dt>
A Phone object has the following properties:</t> <dd>The phone numbers by which to contact the entity represented by
<ul spacing="normal"> the Card.</dd>
<li>@type: <tt>String</tt>. </dl>
This <bcp14>MUST</bcp14> be <tt>Phone</tt>, if set. <t>Phone object has the following properties:</t>
</li> <dl spacing="normal">
<li>number: <tt>String</tt> (mandatory). <dt>@type: String.</dt>
The phone number, as either a URI or free-text. Typical URI schemes are the <xr <dd>
ef target="RFC3966" format="default"/> <tt>tel</tt> or <xref target="RFC3261" fo The JSContact type of the object. The value <bcp14>MUST</bcp14> be
rmat="default"/> <tt>sip</tt> schemes, but any URI scheme is allowed.</li> "Phone", if set.
<li> </dd>
<t>features: <tt>String[Boolean]</tt> (optional). <dt>number: String (mandatory).</dt>
The set of contact features that this phone number may be used for <dd>
. The set is represented as an object, with each key being a method type. The The phone number as either a URI or free text. Typical URI schemes
boolean value <bcp14>MUST</bcp14> be <tt>true</tt>. The <xref target="enumerate are "tel"
d-values">enumerated</xref> method type values are: <xref target="RFC3966" format="default"/>
</t> or "sip" <xref target="RFC3261" format="default"/>, but any URI sc
<ul spacing="normal"> heme is allowed.
<li><tt>mobile</tt>: the number is for a mobile phone.</li> </dd>
<li><tt>voice</tt>: the number is for calling by voice.</li> <dt>features: String[Boolean] (optional).</dt>
<li><tt>text</tt>: the number supports text messages (SMS).</li> <dd>
<li><tt>video</tt>: the number supports video conferencing.</li> <t>
<li><tt>main-number</tt>: this number is the main phone number, The set of contact features that the phone number may be used fo
such as the number of the front-desk at a company, as opposed to a direct-dial n r. The set is represented as an object,
umber of an individual employee.</li> with each key being a method type. The boolean value <bcp14>MUST
<li><tt>textphone</tt>: the number is for a device for people wi </bcp14> be "true". The <xref target="enumerated-values">enumerated
th hearing or speech difficulties.</li> </xref> method type values are:
<li><tt>fax</tt>: the number is for sending faxes.</li> </t>
<li><tt>pager</tt>: the number is for a pager or beeper.</li> <ul spacing="compact">
<li>mobile: this number is for a mobile phone.</li>
<li>voice: this number supports calling by voice.</li>
<li>text: this number supports text messages (SMS).</li>
<li>video: this number supports video conferencing.</li>
<li>main-number: this number is a main phone number such as the
number of the front desk at a company,
as opposed to a direct-dial number of an individual employee.
</li>
<li>textphone: this number is for a device for people with heari
ng or speech difficulties.</li>
<li>fax: this number supports sending faxes.</li>
<li>pager: this number is for a pager or beeper.</li>
</ul> </ul>
</li> </dd>
<li>contexts: <tt>String[Boolean]</tt> (optional). <dt>contexts: String[Boolean] (optional).</dt>
The contexts in which to use this number. Also see <xref target="prop-contexts" <dd>The contexts in which to use the number. Also see <xref target="
/>.</li> prop-contexts"/>.
<li>pref: <tt>UnsignedInt</tt> (optional). </dd>
The preference of this number in relation to other numbers. Also se <dt>pref: UnsignedInt (optional).</dt>
e <xref target="prop-pref"/>.</li> <dd>
<li>label: <tt>String</tt> (optional). The preference of the number in relation to other numbers. Also se
A custom label for the value, see <xref target="prop-label"/>.</li> e <xref target="prop-pref"/>.
</ul> </dd>
<dt>label: String (optional).</dt>
<dd>
A custom label for the value. Also see <xref target="prop-label"/>
.
</dd>
</dl>
<figure anchor="example-phones"> <figure anchor="example-phones">
<name><tt>phones</tt> example</name> <name>Example for the phones Property</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 2066
"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> <dl spacing="normal">
<t>Defines the preferred languages for contacting the entity associate <dt>preferredLanguages : Id[LanguagePref] (optional).</dt>
d with this Card.</t> <dd>The preferred languages for contacting the entity associated wit
h the Card.</dd>
</dl>
<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: String.</dt>
This <bcp14>MUST</bcp14> be <tt>LanguagePref</tt>, if set. <dd>
</li> The JSContact type of the object. The value <bcp14>MUST</bcp14> be
<li>language: <tt>String</tt> (mandatory). The preferred language. "LanguagePref", if set.
This <bcp14>MUST</bcp14> a language tag as defined in <xref target="RFC5646"/>. </dd>
</li> <dt>language: String (mandatory).</dt>
<li>contexts: <tt>String[Boolean]</tt> (optional). <dd>The preferred language. This <bcp14>MUST</bcp14> be a language t
Defines the contexts in which to use this language. Also see <xref target="prop ag as defined in <xref target="RFC5646"/>
-contexts"/>.</li> .
<li>pref: <tt>UnsignedInt</tt> (optional). </dd>
Defines the preference of this language in relation to other languages of the sa <dt>contexts: String[Boolean] (optional).</dt>
me contexts. Also see <xref target="prop-pref"/>.</li> <dd>The contexts in which to use the language. Also see <xref target
</ul> ="prop-contexts"/>.
</dd>
<dt>pref: UnsignedInt (optional).</dt>
<dd>The preference of the language in relation to other languages of
the same contexts. Also see <xref target="prop-pref"/>.
</dd>
</dl>
<figure anchor="example-preferredLanguages"> <figure anchor="example-preferredLanguages">
<name><tt>preferredLanguages</tt> example</name> <name>Example for the preferredLanguages Property</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 2118
"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> <dl spacing="normal">
<t>These are resources for calendaring, such as calendars to lookup fr <dt>calendars: Id[Calendar] (optional).</dt>
ee-busy information for the entity represented by this Card. A Calendar object <dd>The calendaring resources of the entity represented by the Card,
has all properties of the <xref target="resource">Resource</xref> data type, wit such as to look up free-busy information.</dd>
h the following additional definitions:</t> </dl>
<t>A Calendar object has all properties of the <xref target="resource"
>Resource</xref> data type, with the
following additional definitions:
</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Cal <li>The @type property value <bcp14>MUST</bcp14> be "Calendar", if s
endar</tt>, if set.</li> et.
<li><t>The <tt>kind</tt> property is mandatory. Its <xref target="e </li>
numerated-values">enumerated</xref> values are:</t> <li>
<ul> <t>The kind property is mandatory. Its <xref target="enumerated-va
lues">enumerated</xref> values are:
</t>
<ul spacing="normal">
<li> <li>
<tt>calendar</tt>: the resource is a calendar that contains en calendar: The resource is a calendar that contains entries suc
tries such as calendar events or tasks.</li> h as calendar events or tasks.
</li>
<li> <li>
<tt>freeBusy</tt>: the resource allows for free-busy lookups, freeBusy: The resource allows for free-busy lookups, for examp
for example to schedule group events.</li> le, 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>Example for the calendars Property</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> <dl spacing="normal">
<t>The scheduling addresses by which the entity may receive calendar s <dt>schedulingAddresses: Id[SchedulingAddress] (optional).</dt>
cheduling invitations. A SchedulingAddress object has the following properties: <dd>The scheduling addresses by which the entity may receive calenda
</t> r scheduling invitations.</dd>
<ul spacing="normal"> </dl>
<li> <t>A SchedulingAddress object has the following properties:</t>
<t>@type: <tt>String</tt>. <dl spacing="normal">
This <bcp14>MUST</bcp14> be <tt>SchedulingAddress</tt>, if set.</t <dt>@type: String.</dt>
> <dd>
</li> The JSContact type of the object. The value <bcp14>MUST</bcp14> be
<li>uri: <tt>String</tt> (mandatory). "SchedulingAddress", if set.
The address to use for calendar scheduling with this contact. This <bcp14>MUST< </dd>
/bcp14> be a URI as defined in Section 3 of <xref target="RFC3986" format="defau <dt>uri: String (mandatory).</dt>
lt"/>.</li> <dd>
<li>contexts: <tt>String[Boolean]</tt> (optional). The address to use for calendar scheduling with the contact. This
The contexts in which to use this scheduling address. Also see <xref target="pr <bcp14>MUST</bcp14> be a URI as defined
op-contexts"/>.</li> in <xref target="RFC3986" sectionFormat="of" section="3"/>.
<li>pref: <tt>UnsignedInt</tt> (optional). </dd>
The preference of this scheduling address in relation to other sched <dt>contexts: String[Boolean] (optional).</dt>
uling address. Also see <xref target="prop-pref"/>.</li> <dd>The contexts in which to use the scheduling address. Also see <x
<li>label: <tt>String</tt> (optional). ref target="prop-contexts"/>.
A custom label for the scheduling address, see <xref target="prop-la </dd>
bel"/>.</li> <dt>pref: UnsignedInt (optional).</dt>
</ul> <dd>
The preference of the scheduling address in relation to other sche
duling addresses. Also see <xref target="prop-pref"/>.
</dd>
<dt>label: String (optional).</dt>
<dd>
A custom label for the scheduling address. Also see <xref target="
prop-label"/>.
</dd>
</dl>
<figure anchor="example-schedulingAddresses"> <figure anchor="example-schedulingAddresses">
<name><tt>schedulingAddresses</tt> example</name> <name>Example for the schedulingAddresses Property</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 <t>This section defines properties for postal addresses and geographical
locations associated with the entity represented by this Card.</t> locations associated with the entity
<section anchor="addresses" numbered="true" toc="default"> represented by the Card.
</t>
<section anchor="addresses-prop" numbered="true" toc="default">
<name>addresses</name> <name>addresses</name>
<t>Type: <tt>Id[Address]</tt> (optional).</t> <dl spacing="normal">
<t>A map of address identifiers to Address objects, containing physica <dt>addresses: Id[Address] (optional).</dt>
l locations.</t> <dd>The addresses of the entity represented by the Card, such as pos
<section> tal addresses or geographic locations.</dd>
<name>Address object</name> </dl>
<t>An Address object has the following properties:</t> <section anchor="address">
<ul spacing="normal"> <name>Address Object</name>
<li>@type: <tt>String</tt>. <t>An Address object has the following properties, of which at least
This <bcp14>MUST</bcp14> be <tt>Address</tt>, if set. one of components, coordinates,
</li> countryCode, full or timeZone <bcp14>MUST</bcp14> be set:
<li> </t>
<t>components: <tt>AddressComponent[]</tt> (optional). The <xre <dl spacing="normal">
f target="addresscomponent">components</xref> making up this address. This prop <dt>@type: String.</dt>
erty <bcp14>MUST</bcp14> be set if the <tt>full</tt> property is not set, otherw <dd>
ise it <bcp14>SHOULD</bcp14> be set. The component list <bcp14>MUST</bcp14> hav The JSContact type of the object. The value <bcp14>MUST</bcp14>
e at least one entry having a different <tt>kind</tt> than <tt>separator</tt>.</ be "Address", if set.
t> </dd>
<t>Address components <bcp14>SHOULD</bcp14> be ordered such that <dt>
their values joined as a String produce a valid full address. If so, implement components: AddressComponent[] (optional).
ations <bcp14>MUST</bcp14> set the <tt>isOrdered</tt> property value to <tt>true </dt>
</tt>.</t> <dd>
<t>If the address components are ordered, then the <tt>defaultSe <t>The <xref target="addresscomponent">components</xref> that ma
parator</tt> property and address components of kind <tt>separator</tt> give gui ke up the address. The component list <bcp14>
dance what characters to insert between components, but implementations are free MUST
to choose any others. In lack of a separator, inserting a single Space charact </bcp14> have at least one entry that has a kind property value
er in between address component values is a good choice.</t> other than "separator".
<t>If instead the address components follow no particular order, </t>
then the <tt>isOrdered</tt> property value <bcp14>MUST</bcp14> be <tt>false</tt <t>Address components <bcp14>SHOULD</bcp14> be ordered such that
>, the <tt>components</tt> property <bcp14>MUST NOT</bcp14> contain a AddressCom when their values are joined as a
ponent of kind <tt>separator</tt> and the <tt>defaultSeparator</tt> property <bc String, a valid full address is produced. If so, implementatio
p14>MUST NOT</bcp14> be set.</t> ns <bcp14>MUST</bcp14> set the isOrdered
</li> property value to "true".
<li>isOrdered: <tt>Boolean</tt> (optional, default: <tt>false</tt> </t>
). This indicates if the address component sequence in the <tt>components</tt> <t>If the address components are ordered, then the defaultSepara
property is ordered.</li> tor property and address components with
<li>countryCode: <tt>String</tt> (optional). the kind property value set to "separator" give guidance on wh
The Alpha-2 country code <xref target="ISO.3166-1.2006"/>.</li> at characters to insert between
<li>coordinates: <tt>String</tt> (optional). A <xref target="RFC5 components, but implementations are free to choose any others.
870" format="default"/> "geo:" URI for the address.</li> When lacking a separator, inserting a
<li>timeZone: <tt>String</tt> (optional). Identifies the time zon single space character in between address component values is
e this address is located in. This <bcp14>MUST</bcp14> be a time zone name regi a good choice.
stered in the <xref target="IANATZ">IANA Time Zone Database</xref>.</li> </t>
<li> <t>If, instead, the address components follow no particular orde
<t>contexts: <tt>String[Boolean]</tt> (optional). r, then the isOrdered property value <bcp14>
The contexts of the address information. The boolean value <bcp14>MUST</bcp14> MUST
be <tt>true</tt>. In addition to the common contexts (<xref target="prop-contex </bcp14> be "false", the components property <bcp14>MUST NOT</bc
ts"/>), allowed key values are: p14> contain an AddressComponent with
</t> the kind property value set to "separator", and the defaultSep
<ul spacing="normal"> arator property <bcp14>MUST NOT</bcp14> be
<li><tt>billing</tt>: an address to be used for billing.</li> set.
<li><tt>delivery</tt>: an address to be used for delivering ph </t>
ysical items.</li> </dd>
<dt>isOrdered: Boolean (optional; default: "false").</dt>
<dd>The indicator if the address components in the components prop
erty are ordered.</dd>
<dt>countryCode: String (optional).</dt>
<dd>
The Alpha-2 country code <xref target="ISO.3166-1"/>.
</dd>
<dt>coordinates: String (optional).</dt>
<dd>A "geo:" URI
<xref target="RFC5870" format="default"/>
for the address.
</dd>
<dt>timeZone: String (optional).</dt>
<dd>The time zone in which the address is located. This <bcp14>MUS
T</bcp14> be a time zone name
registered in the IANA <xref target="IANA-TZ">Time Zone Database
</xref>.
</dd>
<dt>
contexts: String[Boolean] (optional).
</dt>
<dd>
<t>
The contexts in which to use this address. The boolean value <
bcp14>MUST</bcp14> be "true". In addition
to the common contexts (<xref target="prop-contexts"/>), allow
ed key values are:
</t>
<ul spacing="compact">
<li>billing: an address to be used for billing.</li>
<li>delivery: an address to be used for delivering physical it
ems.</li>
</ul> </ul>
</li> </dd>
<li>full: <tt>String</tt> (optional). <dt>full: String (optional).</dt>
This is the full address, including street, region or country. Th <dd>
e purpose of this property is to define an address, even if the individual addre The full address, including street, region, or country. The purp
ss components are not known. If the <tt>street</tt> property is set, the <tt>fu ose of this property is to define an
ll</tt> property <bcp14>SHOULD NOT</bcp14> be set. address, even if the individual address components are not known
</li> .
<li>defaultSeparator: <tt>String</tt> (optional). </dd>
The default separator to insert between address component values w <dt>defaultSeparator: String (optional).</dt>
hen concatenating all address component values to a single String. Also see the <dd>
definition of the <tt>separator</tt> kind for the AddressComponent object. Thi The default separator to insert between address component values
s property <bcp14>MUST NOT</bcp14> be set if the Address <tt>isOrdered</tt> prop when concatenating all address
erty value is <tt>false</tt> or if the <tt>components</tt> property is not set.< component values to a single String. Also see the definition of
/li> the kind property value "separator" for
<li>pref: <tt>UnsignedInt</tt> (optional). the <xref target="addresscomponent">AddressComponent</xref> obje
The preference of this address in relation to other addresses. Also ct. The defaultSeparator property <bcp14>
see <xref target="prop-pref"/>.</li> MUST NOT
<li> </bcp14> be set if the Address isOrdered property value is "false"
<t>phoneticScript: <tt>String</tt> (optional). or if the components property is not
The script used in the value of the AddressComponent <tt>phoneti set.
c</tt> property. Also see <xref target="prop-phonetic"/>.</t> </dd>
</li> <dt>pref: UnsignedInt (optional).</dt>
<li> <dd>
<t>phoneticSystem: <tt>String</tt> (optional). The preference of the address in relation to other addresses. Al
The phonetic system used in the AddressComponent <tt>phonetic</tt> so see <xref target="prop-pref"/>.
property. Also see <xref target="prop-phonetic"/>.</t> </dd>
</li> <dt>
</ul> phoneticScript: String (optional).
<t>The following example illustrates the use of the <tt>address</tt> </dt>
property. Additional examples are in <xref target="address-examples"/>.</t> <dd>
The script used in the value of the AddressComponent phonetic pr
operty. Also see <xref target="prop-phonetic"/>.
</dd>
<dt>
phoneticSystem: String (optional).
</dt>
<dd>
The phonetic system used in the AddressComponent phonetic proper
ty. Also see <xref target="prop-phonetic"/>.
</dd>
</dl>
<t>The following example illustrates the use of the address property
for "54321 Oak St, Reston, CA 20190,
USA". Additional examples are shown in <xref target="address-examp
les"/>.
</t>
<figure anchor="example-address-us"> <figure anchor="example-address-us">
<name>Example of the address "54321 Oak St, Reston, VA 20190, USA" <!--[rfced] Titles for Figures 30-32
</name>
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 proper
ty.
Additional examples are in Section 2.5.1.3.
Figure 30: Example of the address "54321 Oak St, Reston, CA 201
90, 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 proper
ty 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 proper
ty for
"46, 1 Sukhumvit 51 Alley, Khlong Tan Nuea, Watthana, Bangkok 1
0110,
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 ti
tle 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 Toky
o 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 an Address in the 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 2385
], ],
"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: String.</dt>
This <bcp14>MUST</bcp14> be <tt>AddressComponent</tt>, if set. <dd>
</li> The JSContact type of the object. The value <bcp14>MUST</bcp14>
<li>value: <tt>String</tt> (mandatory). be "AddressComponent", if set.
The value of this address component.</li> </dd>
<li> <dt>value: String (mandatory).</dt>
<t>kind: <tt>String</tt> (mandatory). <dd>
The kind of this address component. The <xref target="enumerated- The value of the address component.
values">enumerated</xref> values are: </dd>
</t> <dt>
<ul spacing="normal"> kind: String (mandatory).
<li><tt>room</tt>: the room or suite number or identifier.</li </dt>
> <dd>
<li><tt>apartment</tt>: the extension designation, such as apa <t>
rtment number or unit or box number.</li> The kind of the address component. The <xref target="enumerate
<li><tt>floor</tt>: the floor or level this address is located d-values">enumerated</xref> values are:
on.</li> </t>
<li><tt>building</tt>: the building, tower, or condominium thi <ul spacing="compact">
s address is located in.</li> <li>room: the room, suite number, or identifier.</li>
<li><tt>number</tt>: the street number, e.g., "123". This val <li>apartment: the extension designation such as the apartment
ue is not restricted to numeric values, and can include any value such as number number, unit, or box number.</li>
ranges ("112–10"), grid style ("39.2 RD"), alphanumerics ("N6W23001") or fracti <li>floor: the floor or level the address is located on.</li>
onals ("123 1/2").</li> <li>building: the building, tower, or condominium the address
<li><tt>name</tt>: the street name.</li> is located in.</li>
<li><tt>block</tt>: the block name or number.</li> <li>number: the street number, e.g., "123". This value is not
<li><tt>subdistrict</tt>: the subdistrict, ward or other subun restricted to numeric values and can
it of a district.</li> include any value such as number ranges ("112-10"), grid sty
<li><tt>district</tt>: the district name.</li> le ("39.2 RD"), alphanumerics
<li><tt>locality</tt>: the municipality, city, town, village, ("N6W23001"), or fractionals ("123 1/2").
post-town, or another locality.</li> </li>
<li><tt>region</tt>: the administrative area, such as province <li>name: the street name.</li>
, state, prefecture, county, canton.</li> <li>block: the block name or number.</li>
<li><tt>postcode</tt>: the postal code, post code, ZIP code or <li>subdistrict: the subdistrict, ward, or other subunit of a
other short code associated with the address by the relevant country's postal s district.</li>
ystem.</li> <li>district: the district name.</li>
<li><tt>country</tt>: the country name.</li> <li>locality: the municipality, city, town, village, post town
<li><tt>direction</tt>: the Cardinal direction or quadrant, e. , or other locality.</li>
g., "North".</li> <li>region: the administrative area such as province, state, p
<li><tt>landmark</tt>: the publicly known prominent feature th refecture, county, or canton.</li>
at can substitute the street name and number, e.g., White House, Taj Mahal.</li> <li>postcode: the postal code, post code, ZIP code, or other s
<li><tt>postOfficeBox</tt>: the post office box number or iden hort code associated with the address by
tifier.</li> the relevant country's postal system.
<li><tt>separator</tt>: a formatting separator between two ord </li>
ered address non-separator components. The <tt>value</tt> property of the compo <li>country: the country name.</li>
nent includes the verbatim separator, for example a hyphen character or even an <li>direction: the cardinal direction or quadrant, e.g., "nort
empty string. This value has higher precedence than the <tt>defaultSeparator</t h".</li>
t> property of the Address. Implementations <bcp14>MUST NOT</bcp14> insert two <li>landmark: the publicly known prominent feature that can su
consecutive separator components, instead they <bcp14>SHOULD</bcp14> insert a si bstitute the street name and number,
ngle separator component with the combined value. This component kind <bcp14>MU e.g., "White House" or "Taj Mahal".
ST NOT</bcp14> be set if the Address <tt>isOrdered</tt> property value is <tt>fa </li>
lse</tt>.</li> <li>postOfficeBox: the post office box number or identifier.</
li>
<li>separator: a formatting separator between two ordered addr
ess non-separator components. The value
property of the component includes the verbatim separator, f
or example, a hyphen character or even
an empty string. This value has higher precedence than the d
efaultSeparator property of the Address.
Implementations <bcp14>MUST NOT</bcp14> insert two consecuti
ve separator components; instead, they <bcp14>
SHOULD
</bcp14> insert a single separator component with the combin
ed value. This component kind <bcp14>
MUST NOT
</bcp14> be set if the Address isOrdered property value is "
false".
</li>
</ul> </ul>
</li> </dd>
<li>phonetic: <tt>String</tt> (optional). This defines how to pro <dt>phonetic: String (optional).</dt>
nounce this name component. If this property is set, then at least one of the A <dd>The pronounciation of the name component. If this property is
ddress object <tt>phoneticSystem</tt> or <tt>phoneticScript</tt> properties <bcp set, then at least one of the Address
14>MUST</bcp14> be set. Also see <xref target="prop-phonetic"/>.</li> object phoneticSystem or phoneticScript properties <bcp14>MUST</
</ul> bcp14> be set. Also see <xref target="prop-phonetic"/>.
</dd>
</dl>
</section> </section>
<section anchor="address-examples"> <section anchor="address-examples">
<name>Address examples</name> <name>Additional Address Examples</name>
<t>The following are examples of addresses, in addition to <xref tar <t>The following example illustrates the use of the address property
get="example-address-us"/>.</t> for "46, 1 Sukhumvit 51 Alley, Khlong
Tan Nuea, Watthana, Bangkok 10110, Thailand".
</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 an Address in 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 the address property
for "2-7-2 Marunouchi, Chiyoda-ku, Tokyo
100-8994" and its Japanese localization (<xref target="localizatio
ns"/>).
</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 2519
} }
} }
} }
]]></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> <dl spacing="normal">
<t>These are cryptographic resources such as public keys and certifica <dt>cryptoKeys: Id[CryptoKey] (optional).</dt>
tes associated with the entity represented by this Card. A CryptoKey object has <dd>The cryptographic resources such as public keys and certificates
all properties of the <xref target="resource">Resource</xref> data type, with t associated with the entity
he following additional definitions:</t> represented by the Card.
</dd>
</dl>
<t>A CryptoKey object has all properties of the <xref target="resource
">Resource</xref> data type, with the
following additional definition:
</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Cry <li>The @type property value <bcp14>MUST</bcp14> be "CryptoKey", if
ptoKey</tt>, if set.</li> 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 cryptoKeys 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. <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 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 cryptoKeys with Embedded Data</name>
<!--[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": {
"mykey2": {
"uri": "data:application/pgp-keys;base64,LS0tLS1CRUdJTiBSU0EgUFV
CTElDIEtF
WS0tLS0tCk1JSUJDZ0tDQVFFQSt4R1ovd2N6OXVnRnBQMDdOc3BvNlUx
N2wwWWhGa
UZweHhVNHBUazNMaWZ6OVIzenNJc3UKRVJ3dGE3K2ZXSWZ4T28yMDhld
HQvamhza2
lWb2RTRXQzUUJHaDRYQmlweVdvcEt3WjkzSEhhRFZaQUFMaS8yQQoreF
RCdFdkRW8
3WEdVdWpLRHZDMi9hWkt1a2ZqcE9pVUk4QWhMQWZqbWxjRC9VWjFRUGg
wbUhzZ2xS
TkNtcEN3Cm13U1hBOVZObWh6K1BpQitEbWw0V1duS1cvVkhvMnVqVFh4
cTcrZWZNV
TRIMmZueTNTZTNLWU9zRlBGR1oxVE4KUVNZbEZ1U2hXckhQdGlMbVVkU
G9QNkNWMm
1NTDF0aytsN0RJSXFYclFoTFVLREFDZU01cm9NeDBrTGhVV0I4UAorMH
VqMUNObE5
ONEpSWmxDN3hGZnFpTWJGUlU5WjRONll3SURBUUFCCi0tLS0tRU5EIFJ
TQSBQVUJM
SUMgS0VZLS0tLS0K"
}
}
Current:
"cryptoKeys": {
"mykey2": {
"uri": "data:application/pgp-keys;base64,LS0tLS1CRUdJTiBSU0EgUFV
C
TElDIEtFWS0tLS0tCk1JSUJDZ0tDQVFFQSt4R1ovd2N6OXVnRnBQMDdO
c
3BvNlUxN2wwWWhGaUZweHhVNHBUazNMaWZ6OVIzenNJc3UKRVJ3dGE3K
2
ZXSWZ4T28yMDhldHQvamhza2lWb2RTRXQzUUJHaDRYQmlweVdvcEt3Wj
k
zSEhhRFZaQUFMaS8yQQoreFRCdFdkRW83WEdVdWpLRHZDMi9hWkt1a2Z
q
cE9pVUk4QWhMQWZqbWxjRC9VWjFRUGgwbUhzZ2xSTkNtcEN3Cm13U1hB
O
VZObWh6K1BpQitEbWw0V1duS1cvVkhvMnVqVFh4cTcrZWZNVTRIMmZue
T
NTZTNLWU9zRlBGR1oxVE4KUVNZbEZ1U2hXckhQdGlMbVVkUG9QNkNWMm
1
NTDF0aytsN0RJSXFYclFoTFVLREFDZU01cm9NeDBrTGhVV0I4UAorMHV
q
MUNObE5ONEpSWmxDN3hGZnFpTWJGUlU5WjRONll3SURBUUFCCi0tLS0t
R
U5EIFJTQSBQVUJMSUMgS0VZLS0tLS0K"
}
}
-->
<sourcecode name="" type="json"><![CDATA[ <sourcecode name="" type="json"><![CDATA[
"cryptoKeys": { "cryptoKeys": {
"mykey2": { "mykey2": {
"uri": "data:application/pgp-keys;base64,LS0tLS1CRUdJTiBSU0EgUFVCTElDIEtF "uri": "data:application/pgp-keys;base64,LS0tLS1CRUdJTiBSU0EgUFVC
WS0tLS0tCk1JSUJDZ0tDQVFFQSt4R1ovd2N6OXVnRnBQMDdOc3BvNlUxN2wwWWhGa TElDIEtFWS0tLS0tCk1JSUJDZ0tDQVFFQSt4R1ovd2N6OXVnRnBQMDdOc
UZweHhVNHBUazNMaWZ6OVIzenNJc3UKRVJ3dGE3K2ZXSWZ4T28yMDhldHQvamhza2 3BvNlUxN2wwWWhGaUZweHhVNHBUazNMaWZ6OVIzenNJc3UKRVJ3dGE3K2
lWb2RTRXQzUUJHaDRYQmlweVdvcEt3WjkzSEhhRFZaQUFMaS8yQQoreFRCdFdkRW8 ZXSWZ4T28yMDhldHQvamhza2lWb2RTRXQzUUJHaDRYQmlweVdvcEt3Wjk
3WEdVdWpLRHZDMi9hWkt1a2ZqcE9pVUk4QWhMQWZqbWxjRC9VWjFRUGgwbUhzZ2xS zSEhhRFZaQUFMaS8yQQoreFRCdFdkRW83WEdVdWpLRHZDMi9hWkt1a2Zq
TkNtcEN3Cm13U1hBOVZObWh6K1BpQitEbWw0V1duS1cvVkhvMnVqVFh4cTcrZWZNV cE9pVUk4QWhMQWZqbWxjRC9VWjFRUGgwbUhzZ2xSTkNtcEN3Cm13U1hBO
TRIMmZueTNTZTNLWU9zRlBGR1oxVE4KUVNZbEZ1U2hXckhQdGlMbVVkUG9QNkNWMm VZObWh6K1BpQitEbWw0V1duS1cvVkhvMnVqVFh4cTcrZWZNVTRIMmZueT
1NTDF0aytsN0RJSXFYclFoTFVLREFDZU01cm9NeDBrTGhVV0I4UAorMHVqMUNObE5 NTZTNLWU9zRlBGR1oxVE4KUVNZbEZ1U2hXckhQdGlMbVVkUG9QNkNWMm1
ONEpSWmxDN3hGZnFpTWJGUlU5WjRONll3SURBUUFCCi0tLS0tRU5EIFJTQSBQVUJM NTDF0aytsN0RJSXFYclFoTFVLREFDZU01cm9NeDBrTGhVV0I4UAorMHVq
SUMgS0VZLS0tLS0K" 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> <dl spacing="normal">
<t>These are directory service resources, such as entries in a directo <dt>directories: Id[Directory] (optional).</dt>
ry or organizational directories for lookup. A Directory object has all propert <dd>The directories containing information about the entitity repres
ies of the <xref target="resource">Resource</xref> data type, with the following ented by the Card.</dd>
additional definitions:</t> </dl>
<t>A Directory object has all properties of the <xref target="resource
">Resource</xref> data type, with the
following additional definitions:
</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Dir <li>The @type property value <bcp14>MUST</bcp14> be "Directory", if
ectory</tt>, if set.</li> set.
</li>
<li> <li>
<t>The <tt>kind</tt> property is mandatory. Its <xref target="enu <t>The kind property is mandatory. Its <xref target="enumerated-va
merated-values">enumerated</xref> values are:</t> lues">enumerated</xref> values are:
</t>
<ul> <ul>
<li><tt>directory</tt>: the resource is a directory service wher <li>directory: the resource is a directory service that the enti
e the entity represented by this Card is part of. This typically is an organiza ty represented by the Card is a part of.
tional directory that also contains associated entities, e.g., co-workers and m This typically is an organizational directory that also contai
anagement in a company directory.</li> ns associated entities, e.g., co-workers
<li><tt>entry</tt>: the resource is a directory entry of the ent and management in a company directory.
ity represented by this Card. In contrast to the <tt>directory</tt> type, this </li>
is the specific URI for the entity <em>within</em> a directory.</li> <li>entry: the resource is a directory entry of the entity repre
sented by the Card. In contrast to the
"directory" type, this is 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: UnsignedInt (optional).</dt>
This defines the position of this directory resource in the list of al <dd>
l Directory objects having the same <tt>kind</tt> in this Card. If set, the <tt The position of the directory resource in the list of all Director
>listAs</tt> value <bcp14>MUST</bcp14> be higher than zero. Multiple directory y objects having the same kind
resources <bcp14>MAY</bcp14> have the same <tt>listAs</tt> property value, or no property value in the Card. If set, the listAs value <bcp14>MUST</
ne. Sorting such entries is implementation-specific. bcp14> be higher than zero. Multiple
</li> directory resources <bcp14>MAY</bcp14> have the same listAs proper
</ul> ty value or none. Sorting such
same-valued entries is implementation-specific.
</dd>
</dl>
<figure anchor="example-directories"> <figure anchor="example-directories">
<name><tt>directories</tt> example</name> <name>Example for the directories Property</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> <dl spacing="normal">
<t>These are links to resources that do not fit any of the other use-c <dt>links: Id[Link] (optional).</dt>
ase specific resource properties. A Link object has all properties of the <xref <dd>The links to resources that do not fit any of the other use-case
target="resource">Resource</xref> data type, with the following additional defi -specific resource properties.
nitions:</t> </dd>
</dl>
<t>A Link object has all properties of the <xref target="resource">Res
ource</xref> data type, with the
following additional definitions:
</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Lin <li>The @type property value <bcp14>MUST</bcp14> be "Link", if set.
k</tt>, if set.</li> </li>
<li><t>The <tt>kind</tt> property is optional. Its <xref target="en <li>
umerated-values">enumerated</xref> values are:</t> <t>The kind property is optional. Its <xref target="enumerated-val
ues">enumerated</xref> values are:
</t>
<ul> <ul>
<li><tt>contact</tt>: the resource is a URI by which the entity <li>contact: the resource is a URI by which the entity represent
represented by this Card may be contacted, including web forms or other media th ed by the Card may be contacted; this
at require user interaction.</li> includes web forms or other media that require user interactio
n.
</li>
</ul> </ul>
</li> </li>
</ul> </ul>
<figure anchor="example-links"> <figure anchor="example-links">
<name><tt>links</tt> example</name> <name>Example for the links Property</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> <dl spacing="normal">
<t>These are media resources such as photographs, avatars, or sounds a <dt>media: Id[Media] (optional).</dt>
ssociated with the entity represented by this Card. A Media object has all prop <dd>The media resources such as photographs, avatars, or sounds that
erties of the <xref target="resource">Resource</xref> data type, with the follow are associated with the entity
ing additional definitions:</t> represented by the Card.
</dd>
</dl>
<t>A Media object has all properties of the <xref target="resource">Re
source</xref> data type, with the
following additional definitions:
</t>
<ul> <ul>
<li>The <tt>@type</tt> property value <bcp14>MUST</bcp14> be <tt>Med <li>The @type property value <bcp14>MUST</bcp14> be "Media", if set.
ia</tt>, if set.</li> </li>
<li> <li>
<t>The <tt>kind</tt> property is mandatory. Its <xref target="enu <t>The kind property is mandatory. Its <xref target="enumerated-va
merated-values">enumerated</xref> values are:</t> lues">enumerated</xref> values are:
<ul> </t>
<li><tt>photo</tt>: the resource is a photograph or avatar.</li> <ul spacing="normal">
<li><tt>sound</tt>: the resource is audio media, e.g., to speci <li>photo: the resource is a photograph or avatar.</li>
fy the proper pronunciation of the name property contents.</li> <li>sound: the resource is audio media, e.g., to specify the pro
<li><tt>logo</tt>: the resource is a graphic image or logo assoc per pronunciation of the name property
iated with the entity represented by this Card.</li> contents.
</li>
<li>logo: the resource is a graphic image or logo associated wit
h 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>Example for the media Property</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 2746
"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> <dl spacing="normal">
<t>This localizes property values in this Card to languages other than <dt>localizations: String[PatchObject] (optional).</dt>
the main language. Localizations provide language-specific alternatives for ex <dd>
isting property values and <bcp14>SHOULD NOT</bcp14> add new properties.</t> <t>The property values localized to languages other than the <xref
<t>The keys in the localizations property object are language tags <xr target="language">main language</xref> of
ef target="RFC5646"/>. The values are patch objects which localize the Card in t the Card. Localizations provide language-specific alternatives f
he respective language tag. The paths in the PatchObject are relative to the Ca or existing property values and <bcp14>
rd that includes the <tt>localizations</tt> property. A patch <bcp14>MUST NOT</ SHOULD NOT
bcp14> target the <tt>localizations</tt> property.</t> </bcp14> add new properties. The keys in the localizations prope
rty value are language tags <xref target="RFC5646"/>; the values are of type Pat
chObject and localize the Card in that language
tag. The paths in the PatchObject are relative to the Card that
includes the localizations property. A
patch <bcp14>MUST NOT</bcp14> target the localizations property.
</t>
</dd>
</dl>
<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 <li>Determine the language tag in which the Card should be localized
d in.</li> .</li>
<li>If the localizations property includes a key for that language, <li>If the localizations property includes a key for that language,
obtain the PatchObject value. If there is no such key, stop.</li> 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 language property in the copy of the 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 < <t>A patch in the PatchObject may contain any value type. Its value <b
bcp14>MUST</bcp14> be a valid value according to the definition of the patched p cp14>MUST</bcp14> be a valid value
roperty.</t> according to the definition of the patched property.
<t><xref target="example-localizations-replace"/> localizes the <tt>na </t>
me</tt> property by completely replacing its contents in Ukrainian language with <t><xref target="example-localizations-replace"/>
Cyrillic script.</t> localizes the name 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 2803
"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 <t><xref target="example-localizations-patch"/>
me by patching <em>inside</em> the <tt>titles</tt> property. All properties but localizes the title name by patching <em>inside</em> the titles prop
the <tt>name</tt> property in the Title object are left as-is.</t> erty. All properties, except the name
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": "escritor"
} }
} }
]]></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> <dl spacing="normal">
<t>These are memorable dates and events for the entity represented by <dt>anniversaries: Id[Anniversary] (optional).</dt>
this Card. An Anniversary object has the following properties:</t> <dd>The memorable dates and events for the entity represented by the
<ul spacing="normal"> Card.</dd>
<li>@type: <tt>String</tt>. </dl>
This <bcp14>MUST</bcp14> be <tt>Anniversary</tt>, if set. <t>An Anniversary object has the following properties:</t>
</li> <dl spacing="normal">
<li> <dt>@type: String.</dt>
<t>kind: <tt>String</tt> (mandatory). <dd>
Specifies the kind of the anniversary. The <xref target="enumerat The JSContact type of the object. The value <bcp14>MUST</bcp14> be
ed-values">enumerated</xref> values are: "Anniversary", if set.
</t> </dd>
<ul spacing="normal"> <dt>
<li><tt>birth</tt>: a birthday anniversary</li> kind: String (mandatory).
<li><tt>death</tt>: a deathday anniversary</li> </dt>
<li><tt>wedding</tt>: a wedding day anniversary</li> <dd>
<t>
The kind of anniversary. The <xref target="enumerated-values">en
umerated</xref> values are:
</t>
<ul spacing="compact">
<li>birth: a birthday anniversary</li>
<li>death: a deathday anniversary</li>
<li>wedding: a wedding day anniversary</li>
</ul> </ul>
</li> </dd>
<li> <dt>
<t>date: <tt>PartialDate|Timestamp</tt> (mandatory, defaultType: < date: PartialDate|Timestamp (mandatory; defaultType: PartialDate).
tt>PartialDate</tt>).</t> </dt>
<t>The date of this anniversary in the Gregorian calendar. This < <dd>
bcp14>MUST</bcp14> either be a whole or partial calendar date or a complete UTC <t>The date of the anniversary in the Gregorian calendar. This <bc
timestamp (see the definition of the Timestamp and PartialDate object types belo p14>MUST</bcp14> be either a whole or
w).</t> partial calendar date or a complete UTC timestamp (see the defin
</li> ition of the Timestamp and PartialDate
<li>place: Address (optional). object types below).
An address associated with this anniversary, e.g., the place of bir </t>
th or death.</li> </dd>
</ul> <dt>place: Address (optional).</dt>
<t>A PartialDate object represents a complete or partial calendar date <dd>An address associated with this anniversary, e.g., the place of
in the Gregorian calendar. It represents either a complete date, or a year, or birth or death.</dd>
a month in a year, or a day in a month. It has the following properties, of wh </dl>
ich at least <tt>year</tt> or <tt>month</tt> and <tt>day</tt> <bcp14>MUST</bcp14 <t>A PartialDate object represents a complete or partial calendar date
> be set:</t> in the Gregorian calendar. It
<ul spacing="normal"> represents a complete date, a year, a month in a year, or a day in a
<li>@type: <tt>String</tt>. month. It has the following properties:
This <bcp14>MUST</bcp14> be <tt>PartialDate</tt>, if set. </t>
</li> <dl spacing="normal">
<li>year: <tt>UnsignedInt</tt> (optional). This is the calendar yea <dt>@type: String.</dt>
r.</li> <dd>
<li>month: <tt>UnsignedInt</tt> (optional). This is the calendar mo The JSContact type of the object. The value <bcp14>MUST</bcp14> be
nth, represented as the integers 1 &lt;= month &lt;= 12. If this property is se "PartialDate", if set.
t then either <tt>year</tt> or <tt>day</tt> <bcp14>MUST</bcp14> be set.</li> </dd>
<li>day: <tt>UnsignedInt</tt> (optional). This is the calendar mont <dt>year:</dt>
h day, represented as the integers 1 &lt;= day &lt;= 31, depending on the validi <dd>UnsignedInt (optional). The calendar year.</dd>
ty within the month and year. If this property is set then <tt>month</tt> <bcp1 <dt>month: UnsignedInt (optional).</dt>
4>MUST</bcp14> be set.</li> <dd>The calendar month, represented as the integers 1 &lt;= month &l
<li>calendarScale: <tt>String</tt> (optional). This is the calendar t;= 12. If this property is set, then
system in which this date occurs, in lowercase. This <bcp14>MUST</bcp14> be ei either the year or the day property <bcp14>MUST</bcp14> be set.
ther a CLDR-registered calendar system name <xref target="RFC7529" format="defau </dd>
lt"/> or a vendor-specific value. The year, month and day still <bcp14>MUST</bc <dt>day: UnsignedInt (optional).</dt>
p14> be represented in the Gregorian calendar. Note that the <tt>year</tt> prop <dd>The calendar month day, represented as the integers 1 &lt;= day
erty might be required to convert the date between the Gregorian calendar and th &lt;= 31, depending on the validity
e respective calendar system.</li> within the month and year. If this property is set, then the month
</ul> property <bcp14>MUST</bcp14> be set.
</dd>
<dt>calendarScale: String (optional).</dt>
<dd>The calendar system in which this date occurs, in lowercase. Thi
s <bcp14>MUST</bcp14> be either a
calendar system name registered as a Common Locale Data Repository
(CLDR)
<xref target="RFC7529" format="default"/>
or a vendor-specific value. The year, month, and day still <bcp14>
MUST</bcp14> be represented in the
Gregorian calendar. Note that the year property might be required
to convert the date between the
Gregorian calendar and the respective calendar system.
</dd>
</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: String.</dt>
This <bcp14>MUST</bcp14> be <tt>Timestamp</tt>, if set. <dd>The JSContact type of the object. The value <bcp14>MUST</bcp14>
</li> be "Timestamp", if set.
<li>utc: <tt>UTCDateTime</tt> (mandatory). Specifies the point in t </dd>
ime in UTC time. <dt>utc: UTCDateTime (mandatory).</dt>
</li> <dd>The point in time in UTC time.
</ul> </dd>
<t><xref target="example-anniversaries"/> illustrates anniversaries wi </dl>
th partial dates and timestamp. Note how the <tt>@type</tt> property is set for <t><xref target="example-anniversaries"/>
the <tt>Timestamp</tt> object value according to the rules defined <xref target illustrates anniversaries with partial dates and a timestamp. Note h
="prop-type"/>.</t> ow the @type property is set for the
Timestamp object value according to the rules defined in <xref targe
t="prop-type"/>.
</t>
<figure anchor="example-anniversaries"> <figure anchor="example-anniversaries">
<name><tt>anniversaries</tt> example</name> <name>Example for the anniversaries Property</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 2944
"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). <dl spacing="normal">
A set of free-text keywords, also known as <em>tags</em>. The set is represente <dt>keywords: String[Boolean] (optional).</dt>
d as an object, with each key being a keyword. The boolean value <bcp14>MUST</b <dd>
cp14> be <tt>true</tt>.</t> <t>The set of free-text keywords, also known as <em>tags</em>. Eac
h key in the set is a keyword, each boolean value <bcp14>MUST</bcp14> be "true".
</t>
</dd>
</dl>
<figure anchor="example-keywords"> <figure anchor="example-keywords">
<name><tt>keywords</tt> example</name> <name>Example for the keywords Property</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> <dl spacing="normal">
<t>Free-text notes associated with this Card. A Note object has the f <dt>notes: Id[Note] (optional).</dt>
ollowing properties:</t> <dd>The free-text notes that are associated with the Card.</dd>
<ul spacing="normal"> </dl>
<li>@type: <tt>String</tt>. <t>A Note object has the following properties:</t>
This <bcp14>MUST</bcp14> be <tt>Note</tt>, if set. <dl spacing="normal">
</li> <dt>@type: String.</dt>
<li> <dd>
<t>note: <tt>String</tt> (mandatory). The free text value of this The JSContact type of the object. The value <bcp14>MUST</bcp14> be
note.</t> "Note", if set.
</li> </dd>
<li> <dt>
<t>created: <tt>UTCDateTime</tt> (optional). The date and time wh note: String (mandatory).
en this note was created.</t> </dt>
</li> <dd>The free-text value of this note.
<li> </dd>
<t>author: <tt>Author</tt> (optional). The author of this note.</ <dt>
t> created: UTCDateTime (optional).
</li> </dt>
</ul> <dd>The date and time when this note was created.
<t>An Author object has the following properties, of which at least on </dd>
e other than <tt>@type</tt> <bcp14>MUST</bcp14> be set:</t> <dt>
<ul spacing="normal"> author: Author (optional).
<li>@type: <tt>String</tt>. </dt>
This <bcp14>MUST</bcp14> be <tt>Author</tt>, if set. <dd>The author of this note.
</li> </dd>
<li> </dl>
<t>name: <tt>String</tt> (optional). The name of this author.</t> <t>An Author object has the following properties, of which at least on
</li> e property other than @type <bcp14>
<li> MUST
<t>uri: <tt>String</tt> (optional). A URI value that identifies t </bcp14> be set:
he author.</t> </t>
</li> <dl spacing="normal">
</ul> <dt>@type: String.</dt>
<dd>
The JSContact type of the object. The value <bcp14>MUST</bcp14> be
"Author", if set.
</dd>
<dt>
name: String (optional).
</dt>
<dd>The name of this author.
</dd>
<dt>
uri: String (optional).
</dt>
<dd>
<t>The URI value that identifies the author.</t>
</dd>
</dl>
<figure anchor="example-notes"> <figure anchor="example-notes">
<name><tt>notes</tt> example</name> <name>Example for the notes Property</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> <dl spacing="normal">
<t>Defines personal information about the entity represented by this C <dt>personalInfo: Id[PersonalInfo] (optional).</dt>
ard. <dd>The personal information of the entity represented by the Card.<
A PersonalInfo object has the following properties:</t> /dd>
<ul spacing="normal"> </dl>
<li>@type: <tt>String</tt>. <t>A PersonalInfo object has the following properties:</t>
This <bcp14>MUST</bcp14> be <tt>PersonalInfo</tt>, if set. <dl spacing="normal">
</li> <dt>@type: String.</dt>
<li> <dd>
<t>kind: <tt>String</tt> (mandatory). The JSContact type of the object. The value <bcp14>MUST</bcp14> be
Specifies the kind of this personal information. The <xref target "PersonalInfo", if set.
="enumerated-values">enumerated</xref> values are: </dd>
</t> <dt>
kind: String (mandatory).
</dt>
<dd>
<t>
The kind of personal information. The <xref target="enumerated-v
alues">enumerated</xref> values
are:
</t>
<ul spacing="normal"> <ul spacing="normal">
<li><tt>expertise</tt>: a field of expertise or credential</li> <li>expertise: a field of expertise or a credential</li>
<li><tt>hobby</tt>: a hobby</li> <li>hobby: a hobby</li>
<li><tt>interest</tt>: an interest</li> <li>interest: an interest</li>
</ul> </ul>
</li> </dd>
<li>value: <tt>String</tt> (mandatory). <dt>value: String (mandatory).</dt>
The actual information.</li> <dd>
<li> The actual information.
<t>level: <tt>String</tt> (optional). </dd>
Indicates the level of expertise, or engagement in hobby or intere <dt>
st. level: String (optional).
The <xref target="enumerated-values">enumerated</xref> values ar </dt>
e:</t> <dd>
<t>
The level of expertise or engagement in hobby or interest. The <
xref target="enumerated-values">enumerated</xref> values are:</t>
<ul spacing="normal"> <ul spacing="normal">
<li> <li>
<tt>high</tt> high
</li> </li>
<li> <li>
<tt>medium</tt> medium
</li> </li>
<li> <li>
<tt>low</tt> low
</li> </li>
</ul> </ul>
</li> </dd>
<li>listAs: <tt>UnsignedInt</tt> (optional). <dt>listAs: UnsignedInt (optional).</dt>
This defines the position of this personal information in the list o <dd>
f all PersonalInfo objects having the same <tt>kind</tt> in this Card. If set, The position of the personal information in the list of all Person
the <tt>listAs</tt> value <bcp14>MUST</bcp14> be higher than zero. Multiple per alInfo objects that have the
sonal information entries <bcp14>MAY</bcp14> have the same <tt>listAs</tt> prope same kind property value in the Card. If set, the listAs value <bc
rty value, or none. Sorting such entries is implementation-specific. p14>MUST</bcp14> be higher than zero.
</li> Multiple personal information entries <bcp14>MAY</bcp14> have the
<li>label: <tt>String</tt> (optional). same listAs property value or none.
A custom label. See <xref target="prop-label"/>.</li> Sorting such same-valued entries is implementation-specific.
</ul> </dd>
<dt>label: String (optional).</dt>
<dd>
A custom label. See <xref target="prop-label"/>.
</dd>
</dl>
<figure anchor="example-personalInfo"> <figure anchor="example-personalInfo">
<name><tt>personalInfo</tt> example</name> <name>Example for the personalInfo Property</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 3114
} }
]]></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 <!-- [rfced] We have included some specific questions about the IANA
se with JSContact data formatted in JSON.</t> text below. In addition to responding to those questions, please
<dl newline="true" spacing="normal"> 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>
<dl newline="false" spacing="normal"> <t>version</t>
<dt>version</dt> <t>This parameter conveys the version of the JSContact data in the b
<dd>This parameter conveys the version of the JSContact data in th ody part. It <bcp14>MUST NOT</bcp14> occur
e body part. It <bcp14>MUST NOT</bcp14> occur more than once. If this paramete more than once. If this parameter is set, then the values of all J
r is set, then the values of all JSContact <xref target="iana-property-registry- SContact <xref target="iana-property-registry-version">version
version"><tt>version</tt></xref> properties in the body part <bcp14>MUST</bcp14> </xref> properties in the body part <bcp14>MUST</bcp14> match the
match the parameter value.</dd> parameter value.
</dl> </t>
</dd> </dd>
<dt>Encoding considerations:</dt> <dt>Encoding considerations:</dt>
<dd>This is the same as the encoding considerations of application/jso <dd>This is the same as the encoding considerations of application/jso
n, as specified in <xref target="RFC8259" sectionFormat="of" section="11"/>.</dd 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 <dd>See
<xref target="I-D.ietf-calext-jscontact"/>.</dd> <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 <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 le, when converting objects from other
possible that differing representations for the same logical data or ambiguities contact formats to/from JSContact, it is possible that differing rep
in interpretation might arise. The semantic equivalence of two JSContact objec resentations for the same logical data
ts may be determined differently by different applications, for example, where U or ambiguities in interpretation might arise. The semantic equivalen
RL values differ in case between the two objects.</dd> ce of two JSContact objects may be
determined differently by different applications, for example, where
URL 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 <dd>A JSON Pointer fragment identifier may be used, as defined in <xre
f target="RFC6901" sectionFormat="comma" section="6"/>.</dd> f target="RFC6901" sectionFormat="comma" section="6"/>.
</dd>
<dt>Additional information:</dt> <dt>Additional information:</dt>
<dd> <dd>
<dl newline="false" spacing="normal"> <t>
<br/>
</t>
<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 def
stry definitions in the following sections all belong to that group.</t> initions 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 <!--[rfced] Since "backwards-incompatibility" is mentioned in Section
ds-incompatible</xref> changes require the JSContact major version to change, ot 1.9.1, should the reference below be updated from Section 1.9 to
her changes only require to change the minor version. The registry policy for a Section 1.9.1?
ssignments that require the JSContact major version to change is Standards Actio
n (<xref target="RFC8126" sectionFormat="comma" section="4.9"/>). The registry Original:
policy for other assignments is Specification Required (<xref target="RFC8126" s Registry assignments that introduce backwards-incompatible
ectionFormat="comma" section="4.6"/>).</t> (Section 1.9) changes require the JSContact major version
<t>The Designated Expert decides if a major or minor version change is r to change, other changes only require to change the minor
equired and assigns the new version to the <xref target="iana-version-registry"> version.
Version Registry</xref>. Version numbers increment by one, and a major version
change resets the minor version to zero. An assignment may apply multiple chang Perhaps:
es and to more than one registry at once, in which case a single version change Registry assignments that introduce backwards-incompatible
is sufficient. If the registry policy is Specification Required, then the Desig (Section 1.9.1) changes require the JSContact major version
nated Expert may decide that it is enough to document the new assignment in the to change; other changes only require a change to the minor
Description item of the respective registry.</t> version.
<t>A registration <bcp14>MUST</bcp14> have an intended usage of <tt>comm -->
on</tt>, <tt>reserved</tt>, or <tt>obsolete</tt>.</t> <t>Registry assignments that introduce <xref target="versioning">backwar
ds-incompatible</xref> changes require
the JSContact major version to change; other changes only require a ch
ange to the minor version. The registry
policy for assignments that require the JSContact major version to cha
nge is Standards Action (<xref target="RFC8126" sectionFormat="comma" section="4
.9"/>). The registry policy for other assignments is
Specification Required (<xref target="RFC8126" sectionFormat="comma" s
ection="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-registry">"JSContact Version" regist
ry</xref>. Version numbers increment by
one, and a major version change resets the minor version to zero. An a
ssignment may apply multiple changes and
to more than one registry at once, in which case a single version chan
ge is sufficient. If the registry policy
is Specification Required, then the DE may decide that it is enough to
document the new assignment in the
Description item of the respective registry.
</t>
<t>A registration <bcp14>MUST</bcp14> have an intended usage of "common"
, "reserved", or "obsolete".
</t>
<ul> <ul>
<li>A <tt>common</tt> usage denotes an item with shared semantics and <li>A "common" usage denotes an item with shared semantics and syntax
syntax across systems. Up-to-date systems <bcp14>MUST</bcp14> expect such items across systems. Up-to-date systems <bcp14>
to occur in JSContact data.</li> MUST
<li>A <tt>reserved</tt> usage reserves an item in the registry without </bcp14> expect such items to occur in JSContact data.
assigning semantics to avoid name collisions with future extensions or protocol </li>
use.</li> <li>A "reserved" usage reserves an item in the registry without assign
<li>An <tt>obsolete</tt> usage denotes an item that is no longer expec ing semantics to avoid name collisions
ted to be added by up-to-date systems. A new assignment has probably been defin with future extensions or protocol use. Implementations <bcp14>MUST
ed covering the obsolete item's semantics.</li> NOT</bcp14> expect or add items with
such names outside the protocols or extensions that use them; otherw
ise, any such JSContact data is invalid.
</li>
<li>An "obsolete" usage denotes an item that is no longer expected to
be added by up-to-date systems. A new
assignment has probably been defined, covering the obsolete item's s
emantics. Implementations <bcp14>MUST
</bcp14> expect such items to occur in JSContact data up to the "Unt
il Version" registry field, inclusively.
They <bcp14>MUST NOT</bcp14> add such items for any version after wh
ich the item got obsolete; otherwise,
any such JSContact data is invalid.
</li>
</ul> </ul>
<t>The registration procedure is not a formal standards process but rath <t>The intended usage of registry items may change between versions, but
er an administrative procedure intended to allow community comment and check whe the DE must carefully
ther it is coherent without excessive time delay. It is designed to encourage v consider the impact on existing implementations and standards before d
endors to document and register new items they add for use cases not covered by oing so.
the original specification, leading to increased interoperability.</t> </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 withou
t excessive time delay. It is designed
to encourage vendors to document and register new items they add for u
se 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;
&lt;calsify@ietf.org&gt; for review. This mailing list is appropriat for review. This mailing list is appropriate for soliciting communit
e to solicit community feedback y feedback on a proposed registry
on a proposed registry assignment.</t> assignment.
<t>The intent of the public posting to this list is to solicit comment </t>
s and feedback on the choice of <t>The intent of the public posting to this list is to solicit comment
the item name or value, the unambiguity of its description, and a rev s and feedback on the choice of the item
iew of any name or value, the unambiguity of its description, and a review of a
interoperability or security considerations. The submitter may sub ny interoperability or security
mit a revised registration proposal considerations. The submitter may submit a revised registration prop
or abandon the registration completely at any time.</t> osal 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
iderations.</t> security and privacy considerations.
<t>A new type name, property name or enumerated value <bcp14>MUST NOT< </t>
/bcp14> differ only in case from an already registered name or value.</t> <t>A new type name, property name, or enumerated value <bcp14>MUST NOT
<t>For a common-use registration, the DE </bcp14> differ only in case from an
is expected to confirm that suitable documentation is available to already-registered name or value.
ensure interoperability. </t>
The DE should also verify that <t>For a common-use registration, the DE is expected to confirm that s
the new assignment does not conflict with work that is active or alr uitable documentation is available to
eady published within the IETF.</t> ensure interoperability. The DE should also verify that the new assi
<t>The DE will either approve or deny the registration request and pub gnment does not conflict with work that
lish a notice of the decision is active or already published within the IETF.
to the Calext WG mailing list or its successor, as well as inform IAN </t>
A. A denial notice must be <t>The DE will either approve or deny the registration request and pub
justified by an explanation, and, in the cases where it is possible lish a notice of the decision to the
, concrete suggestions on how the Calext WG mailing list or its successor, as well as inform IANA. A d
request can be modified to become acceptable should be provided.< enial notice must be justified by an
/t> explanation, and in the cases where it is possible, concrete suggest
ions on how the 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 <t>Once a JSContact registry group item has been published by IANA, th
e change controller may request a e Change Controller may request a change
change to its definition. The same procedure that would be appropria to its definition. The same procedure that would be appropriate for
te for the original registration the original registration request is
request is used to process a change request.</t> used to process a change request.
<t>JSContact registrations dot not get deleted; instead, items that ar </t>
e no longer believed appropriate for use are declared obsolete by a change to th <t>JSContact registrations do not get deleted; instead, items that are
eir "intended usage" field; such items will be clearly marked in the IANA regist no longer believed appropriate for use
ry.</t> are declared obsolete by a change to their "Intended Usage" field; s
uch items will be clearly marked in the
IANA registry.
</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 serious omissions or errors in the published specification, as such
hanges may cause changes may cause interoperability
interoperability issues. When review is required, a change request issues. When review is required, a change request may be denied if i
may be denied if it renders t renders entities that were valid under
entities that were valid under the previous definition invalid un the previous definition invalid under the new definition.
der the new definition.</t> </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 thi
e of this new registry is to define the allowed value range of JSContact major a s new registry is to define the allowed
nd minor version numbers.</t> value range of JSContact major and minor version numbers.
<t>The registry entries sort numerically ascending by the "Major Version </t>
" column.</t> <t>The registry entries sort numerically in ascending order by the "Majo
<t>The registry process is outlined in <xref target="iana-registry-polic r Version" column, entries with equal "Major Version" sort numerically in ascend
y" format="default"/>.</t> ing order by the "Minor Version" column.</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. <dd>The numeric value of a JSContact major version number. It <bcp14
It <bcp14>MUST</bcp14> be a positive integer.</dd> >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 <dd>The maximum numeric value of a JSContact minor version for the g
for the given major version. It <bcp14>MUST</bcp14> be zero or a positive integ iven major version. It <bcp14>MUST
er. All numbers less than or equal this value are valid minor version values fo </bcp14> be zero or a positive integer. All numbers less than or equ
r the given major version.</dd> al 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
t objects</t> interoperability of extensions to JSContact objects.
<t>The registry entries sort alphabetically ascending by the "Property N </t>
ame" column first, "Property Context" second, "Since Version" third. Equal entr <t>The registry entries sort alphabetically in ascending order by the fo
ies sort in any order.</t> llowing columns: "Property Name" first,
<t>The registry process for a new property is outlined in <xref target=" "Property Context" second, and "Since Version" third. Equal entries so
iana-registry-policy" format="default"/>.</t> rt in any order.
</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 any of the
registered for object types listed in the "Property Context" field of this regist
any of the object types listed in the "Property Context" ration. Other object types <bcp14>MAY
field of this registration. Other object </bcp14> have already registered a different property with the sam
types <bcp14>MAY</bcp14> already have registered a di e name; however, the same name <bcp14>
fferent property with the same name; however, MUST
the same name <bcp14>MUST</bcp14> only be used wh </bcp14> only be used when the semantics are analogous.
en the semantics are analogous.</dd> </dd>
<dt>Property Type:</dt> <dt>Property Type:</dt>
<dd> This is the type of this property, using type signatures, as sp <dd>For properties with intended usage other than "reserved", this i
ecified in <xref target="type-signatures" format="default"/>. s the type of this property, using type
The property type <bcp14>MUST</bcp14> be registered in the "J signatures as specified in <xref target="type-signatures" format="
SContact Types" registry.</dd> default"/>. The property type <bcp14>
MUST
</bcp14> be registered in the "JSContact Types" registry. For rese
rved property names, the value MUST be
the verbatim string "not applicable".
</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
<dt>Reference or Description:</dt> contain the property. For reserved property names, the value MAY b
<dd>This is a brief description or RFC number and section reference e the verbatim string "not applicable".
where the property is specified (omitted for "reserved" property names). This mu </dd>
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 <dd>The JSContact version on which the property definition is based.
tion is based on. The version <bcp14>MUST</bcp14> be one of the allowed values The version <bcp14>MUST</bcp14> be one
of the <tt>version</tt> property in the JSContact Enum Value registry (see <xref of the allowed values of the version property in the "JSContact Ve
target="tab-iana-version-registry"/>).</dd> rsion" 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 property got <dd>The JSContact version after which the property was obsoleted; th
obsoleted and <bcp14>MUST NOT</bcp14> be used in later versions. The Until Ver erefore, it <bcp14>MUST NOT</bcp14> be
sion value either <bcp14>MUST NOT</bcp14> be set, or be one of the allowed value used in later versions. The Until Version value either <bcp14>MUST
s of the <tt>version</tt> property in the JSContact Enum Value registry (see <xr NOT</bcp14> be set or <bcp14>MUST
ef target="tab-iana-version-registry"/>).</dd> </bcp14> be one of the allowed values of the version property in t
he "JSContact Version" 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>Person or entity responsible for requesting a change to the entr
>IETF</tt> for RFCs from the IETF stream).</dd> y's definition ("IETF" 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. This must
include references to all RFC documents where this property is int
roduced or updated. For reserved
property names, the reference or description <bcp14>MAY</bcp14> be
omitted.
</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 "common" usage entries of the
of the "JSContact Properties" registry. The Since Version for all properties i "JSContact Properties" registry. For
s <tt>1.0</tt>. The Until Version for all properties is not set. All RFC secti all properties, the Since Version is "1.0", the Until Version is not
on references are for <xref target="I-D.ietf-calext-jscontact"/>. The change co set, the Change Controller is "IETF",
ntroller for all these properties is <tt>IETF</tt>.</t> and RFC section references are for RFC 9553.
</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>
</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 -->
<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 (<xref target="address"/>), AddressComp
Card, Calendar, CryptoKey, Directory, EmailAddress, LanguagePref, Link, Media, onent (<xref target="addresscomponent"/>), Anniversary (<xref target="anniversar
Name, NameComponent, Nickname, Note, OnlineService, Organization, OrgUnit, Part ies"/>), Author (<xref target="notes" format="default"/>), Card (<xref target="c
ialDate,PersonalInfo, Phone, Pronouns, Relation, SchedulingAddress, SpeakToAs, T ardtype"/>), Calendar (<xref target="calendars"/>), CryptoKey (<xref target="cry
imestamp, Title</td> ptoKeys"/>), Directory (<xref target="directories"/>), EmailAddress (<xref targe
<td align="left"><xref target="addresses" format="default"/>, <x t="emails"/>), LanguagePref (<xref target="preferredLanguages"/>), Link <xref ta
ref target="anniversaries" format="default"/>, <xref target="cardtype" format="d rget="links"/>), Media (<xref target="media"/>), Name (<xref target="name"/>), N
efault"/>, <xref target="calendars" format="default"/>, <xref target="cryptoKeys ameComponent (<xref target="namecomponent"/>), Nickname (<xref target="nicknames
" format="default"/>, <xref target="directories" format="default"/>, <xref targe "/>), Note (<xref target="notes"/>), OnlineService (<xref target="onlineServices
t="emails" format="default"/>, <xref target="preferredLanguages" format="default "/>), Organization (<xref target="organizations"/>), OrgUnit (<xref target="orga
"/>, <xref target="links" format="default"/>, <xref target="media" format="defau nizations"/>), PartialDate (<xref target="anniversaries"/>), PersonalInfo (<xref
lt"/>, <xref target="name" format="default"/>, <xref target="nicknames" format=" target="personalInfo"/>), Phone (<xref target="phones"/>), Pronouns (<xref targ
default"/>, <xref target="notes" format="default"/>, <xref target="onlineService et="speakToAs"/>), Relation (<xref target="relatedTo"/>), SchedulingAddress (<xr
s" format="default"/>, <xref target="organizations" format="default"/>, <xref ta ef target="schedulingAddresses"/>), SpeakToAs (<xref target="speakToAs"/>), Time
rget="personalInfo" format="default"/>, <xref target="phones" format="default"/> stamp (<xref target="anniversaries" format="default"/>), Title (<xref target="ti
, <xref target="speakToAs" format="default"/>, <xref target="relatedTo" format=" tles"/>)
default"/>, <xref target="schedulingAddresses" format="default"/>, <xref target=
"titles" format="default"/></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> </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 (<xref target="emails" format="def
<td align="left"> ault"/>)</td>
<xref target="emails" format="default"/>