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 " "> | |||
e="IETF" category="std" xml:lang="en" consensus="true" docName="draft-ietf-calex | <!ENTITY zwsp "​"> | |||
t-jscontact-16" obsoletes="" updates="" tocInclude="true" symRefs="true" sortRef | <!ENTITY nbhy "‑"> | |||
s="true" version="3"> | <!ENTITY wj "⁠"> | |||
]> | ||||
<rfc xmlns:xi="http://www.w3.org/2001/XInclude" ipr="trust200902" docName="draft | ||||
-ietf-calext-jscontact-16" number="9553" submissionType="IETF" consensus="true" | ||||
category="std" xml:lang="en" obsoletes="" updates="" tocInclude="true" symRefs=" | ||||
true" sortRefs="true" version="3"> | ||||
<!-- xml2rfc v2v3 conversion 3.6.0 --> | <!-- 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 <= value <= 2<sup>53</sup>-1, the safe range f | ge -2<sup>53</sup>+1 <= value <= 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 <= value <= 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 <= value <= 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 <= month <= 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 <= day <= 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 <= 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 <= day | |||
erty might be required to convert the date between the Gregorian calendar and th | <= 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 & email address to contact for further information:</dt > | <dt>Person & 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 <calsify@ietf.org> | |||
<calsify@ietf.org> 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 <iana@iana.org>.</t> | <t>Registration requests can be sent to IANA <iana@iana.org>.</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"/> | ||||