RFC 9553 | JSContact | May 2024 |
Stepanek & Loffredo | Standards Track | [Page] |
This specification defines a data model and JavaScript Object Notation (JSON) representation of contact card information that can be used for data storage and exchange in address book or directory applications. It aims to be an alternative to the vCard data format and to be unambiguous, extendable, and simple to process. In contrast to the JSON-based jCard format, it is not a direct mapping from the vCard data model and expands semantics where appropriate. Two additional specifications define new vCard elements and how to convert between JSContact and vCard.¶
This is an Internet Standards Track document.¶
This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 7841.¶
Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at https://www.rfc-editor.org/info/rfc9553.¶
Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
This document defines a data model for contact card data normally used in address book or directory applications and services. It aims to be an alternative to the vCard data format [RFC6350].¶
The key design considerations for this data model are as follows:¶
The representation of this data model is defined in the Internet JSON (I-JSON) format [RFC7493], which is a strict subset of the JSON data interchange format [RFC8259]. Using JSON is mostly a pragmatic choice: its widespread use makes JSContact easier to adopt, and the availability of production-ready JSON implementations eliminates a whole category of parser-related interoperability issues.¶
The vCard data format [RFC6350] is an interchange format for contacts data between address book service providers and vendors. However, this format has gone through multiple specification iterations with only a subset of its deprecated version 3 [RFC2426] being widely in use. Consequently, products and services use an internal contact data model that is richer than what they expose when serializing that information to vCard. In addition, service providers often use a proprietary JSON representation of contact data in their APIs.¶
JSContact provides a standard JSON-based data model and representation of contact data as an alternative to proprietary formats.¶
At the time of writing this document, several missing features in vCard were brought to the attention of the authors such as social media contacts, gender pronouns, and others. This highlights how vCard is not perceived as an evolving format and, consequently, hasn't been updated for about ten years. JSContact addresses these unmet demands and defines new vCard properties and parameters to allow interchanging them in both formats.¶
Two additional documents define the relation of JSContact and vCard: [RFC9554] defines new vCard properties and parameters, and [RFC9555] defines how to convert JSContact data from and to vCard.¶
The xCard [RFC6351] and jCard [RFC7095] specifications define alternative representations for vCard data in XML and JSON formats, respectively. Both explicitly aim to not change the underlying data model. Accordingly, they are regarded as equal to vCard in the context of this document.¶
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.¶
The ABNF definitions in this document use the notations of [RFC5234]. ABNF rules not defined in this document are defined in either [RFC5234] (such as the ABNF for CRLF, WSP, DQUOTE, VCHAR, ALPHA, and DIGIT) or [RFC6350].¶
This section introduces the notations and terminology used to define data types in JSContact.¶
The underlying format for JSContact is JSON, so its data types also build on JSON values. The terms "object" and "array" as well as the four primitive types ("strings", "numbers", "booleans", and "null") are to be interpreted as described in Section 1 of [RFC8259]. All JSContact data MUST be valid according to the constraints given in I-JSON [RFC7493]. Unless otherwise noted, all member names in JSON objects and all string values are case-sensitive. Within the context of JSON objects, the term "key" is synonymous with "member name" as defined in Section 1 of [RFC8259].¶
JSContact defines data types for contact information such as addresses or names. This information typically consists of multiple related elements; for example, a personal name and surname together form a name. These related elements are organized in JSContact objects. A JSContact object is a JSON object that has the following:¶
The following sections specify how to define JSContact object types. Sections 1.7 and 1.8 then define the exact requirements for property names.¶
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.¶
A Foo object has the following properties:¶
The above paragraph illustrates the following:¶
Type signatures are given for all JSON values and JSContact definitions in this document. The following conventions are used:¶
Section 1.4 defines common data types, including signed or unsigned integers and dates.¶
Object properties may also have a set of attributes defined along with the type signature. These have the following meanings:¶
The purpose of the @type property is to help implementations identify which JSContact object type a given JSON object represents. Implementations MUST validate that JSON objects with this property conform to the specification of the JSContact object type of that name.¶
In many cases, the @type property value is implied by where its object occurs in JSContact data. Assuming that both A and B are JSContact object types:¶
In addition to the standard JSON data types, a couple of additional data types are common to the definitions of JSContact objects and properties.¶
Where "Id" is given as a data type, it means a String of at least 1 and a maximum of 255 octets in size, and it MUST only contain characters from the "URL and Filename Safe" base64url alphabet, as defined in Section 5 of [RFC4648], excluding the pad character ("="). This means the allowed characters are the ASCII alphanumeric characters ("A-Za-z0-9"), hyphen ("-"), and underscore ("_").¶
In many places in JSContact, a JSON map is used where the map keys are of type Id and the map values are all the same type of object. This construction represents an unordered set of objects, with the added advantage that each entry has a name (the corresponding map key). This allows for more concise patching of objects and, when applicable, for the objects in question to be referenced from other objects within the JSContact object. The map keys MUST be preserved across multiple versions of the JSContact object.¶
Unless otherwise specified for a particular property, there are no uniqueness constraints on an Id value (other than, of course, the requirement that you cannot have two values with the same key within a single JSON map). For example, two Card (Section 2) objects might use the same Ids in their respective photos properties. Or within the same Card, the same Id could appear in the emails and phones properties. These situations do not imply any semantic connections among the objects.¶
Where "Int" is given as a data type, it means an integer in the range -253+1 <= value <= 2 53-1, which is the safe range for integers stored in a floating-point double, represented as a JSON Number.¶
Where "UnsignedInt" is given as a data type, it means an integer in the range 0 <= value <= 2 53-1 represented as a JSON Number.¶
A PatchObject is of type "String[*]" and represents an unordered set of patches on a JSON object. Each key is a path represented in a subset of the JSON Pointer format [RFC6901]. The paths have an implicit leading "/", so each key is prefixed with "/" before applying the JSON Pointer evaluation algorithm.¶
A patch within a PatchObject is only valid if all the following conditions apply:¶
The value associated with each pointer determines how to apply that patch:¶
A PatchObject does not define its own @type (Section 1.3.4) property. Instead, the @type property in a patch MUST be handled as any other patched property value.¶
Implementations MUST reject a PatchObject in its entirety if any of its patches are invalid. Implementations MUST NOT apply partial patches.¶
The Resource data type defines a resource associated with the entity represented by the Card, identified by a URI [RFC3986]. Later in this document, several property definitions refer to the Resource type as the basis for their property-specific value types. The Resource type defines the properties that are common to all of them. Property definitions making use of Resource MAY define additional properties for their value types.¶
A Resource object has the following properties:¶
The UTCDateTime type is a String in "date-time" format [RFC3339], with further restrictions that any letters MUST be in uppercase and the time offset MUST be the character "Z". Fractional second values MUST NOT be included unless they are non-zero, and they MUST NOT have trailing zeros to ensure there is only a single representation for each date-time.¶
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".¶
Most of the properties in this document are specific to a single JSContact object type. Such properties are defined along with the respective object type. The properties in this section are common to multiple data types and are defined here to avoid repetition. Note that these properties MUST only be set for a JSContact object if they are explicitly mentioned as allowable for this object type.¶
The contexts in which to use the contact information. For example, someone might have distinct phone numbers for work and private contexts and may set the desired context on the respective phone number in the phones (Section 2.3.3) property.¶
This section defines common contexts. Additional contexts may be defined in the properties or data types that make use of this property. The enumerated (Section 1.7.5) common context values are:¶
A preference order for contact information. For example, a person may have two email addresses and prefer to be contacted with one of them.¶
The value MUST be in the range of 1 to 100. Lower values correspond to a higher level of preference, with 1 being most preferred. If no preference is set, then the contact information MUST be interpreted as being least preferred.¶
Note that the preference is only defined in relation to contact information of the same type. For example, the preference orders within emails and phone numbers are independent of each other.¶
The following properties define how to pronounce a value in the language indicated in the Card language (Section 2.1.5) property or the language tag of its localizations (Section 2.7.1). Exemplary uses of these properties are defining how to pronounce Japanese names and romanizing Mandarin or Cantonese name and address components. The properties are defined as follows:¶
The phonetic system used in the related value of the phonetic property. The enumerated (Section 1.7.5) values are:¶
The relation between the phoneticSystem, phoneticScript, and phonetic properties is type-specific. This specification defines this relation in the Name (Section 2.2.1.1) and Address (Section 2.5.1.1) object types, respectively.¶
The following example illustrates the phonetic property for a name (Section 2.2.1):¶
JSContact aims to be used for international contacts and address book data. Notably, text values such as names and addresses are likely to cover a wide range of languages and cultures. This section describes internationalization for free-form text values as well as Uniform Resource Identifiers (URIs).¶
Properties having free-form text values MAY contain any valid sequence of Unicode characters encoded as a JSON string. Such values can contain unidirectional left-to-right and right-to-left text, as well as bidirectional text using Unicode Directional Formatting Characters as described in Section 2 of [UBiDi]. Implementations setting bidirectional text MUST make sure that each property value complies with the requirements of the Unicode Bidirectional Algorithm. Implementations MUST NOT assume that text values of adjacent properties are processed or displayed as a combined string; for example, the values of a given name component and a surname component may or may not be rendered together.¶
Several properties require their string value to be a URI as defined in [RFC3986]. Implementations MUST make sure to use proper percent-encoding for URIs that cannot be represented using unreserved URI characters. Section 3.1 of [RFC3987] defines how to convert Internationalized Resource Identifiers to URIs. 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.¶
This specification distinguishes between three kinds of properties regarding validation: IANA-registered properties and unknown properties, which are defined in this section, and vendor-specific properties, which are defined in Section 1.8.1. A JSContact object is invalid if any of its properties are invalid.¶
This document defines whether each property is mandatory or optional. A mandatory property MUST be present for a JSContact object to be valid. An optional property does not need to be present. The values of both required and optional properties MUST adhere to the data type and definition of that property.¶
All property names, object type names, and enumerated values are case-sensitive, unless explicitly stated otherwise in their definitions. Implementations MUST handle a JSContact object as invalid if a type name, property name, or enumerated value only differs in case from one defined for any JSContact version known to that implementation. This applies regardless of what JSContact version the Card object defines in its version (Section 2.1.2) property. Section 1.7.4 defines how to handle unknown properties.¶
An IANA-registered property is any property that has been registered according to the IANA property registry rules as outlined in Section 3. All properties defined in this specification, including their object value types and enumerated values, are registered at IANA.¶
Implementations MUST validate IANA-registered properties in JSContact data, unless they are unknown to the implementation (Section 1.7.4). They MUST reject invalid IANA-registered properties. A property is invalid if its name matches the name of an IANA-registered property but the value violates its definition according to the JSContact specification version defined in the Card version (Section 2.1.2) property.¶
IANA-registered property names MUST NOT contain ASCII control characters (U+0000 to U+001F, U+007F), the COLON (U+003A), or the QUOTATION MARK (U+0022). They MUST only contain ASCII alphanumeric characters that match the ALPHA and DIGIT rules defined in Appendix B.1 of [RFC5234] or the COMMERCIAL AT (U+0040) character. IANA-registered property names MUST be notated in lower camel case.¶
IANA-registered properties can be reserved (Section 3.3). Implementations MUST NOT set properties having a reserved name in JSContact objects for which this property is reserved or all objects if the property context in the registry is "not applicable". Reserved properties have no type, and their type signature is "not applicable". Any JSContact object including a property that is reserved in context of this object MUST be considered invalid.¶
This document reserves one property as described below.¶
Implementations may encounter JSContact data where a property name is unknown to that implementation but the name adheres to the syntactic restrictions of IANA-registered property names. Implementations MUST make sure that such a name does not violate the case-sensitivity rules defined in Section 1.7.1. If the property name is valid, then implementations MUST NOT treat such properties as invalid. Instead, they MUST preserve them in the JSContact object.¶
Implementations that create or update JSContact data MUST only set IANA-registered properties or vendor-specific properties. Preserving properties that are unknown to the implementation is to allow applications and services to interoperate without data loss, even if not all of them implement the same set of JSContact extensions.¶
Several properties in this document restrict their allowed values to a list of String values. These values are case-sensitive. If not noted otherwise for a specific property, the initial list of values for such properties is registered at IANA in the "JSContact Enum Values" registry (Section 3.7). Implementations MUST only set IANA-registered or vendor-specific (Section 1.8.2) values for such properties.¶
Vendors may extend properties and values for experimentation or to store contacts data that is only useful for a single service or application. Such extensions are not meant for interoperation. If, instead, interoperation is desired, vendors are strongly encouraged to define and register new properties, types, and values at IANA as defined in Section 3. Section 1.7.2 defines the naming conventions for IANA-registered elements.¶
Vendor-specific property names MUST start with a vendor-specific prefix followed by a name, as produced by the "v-extension" ABNF below. The prefix and name together form the property name. The vendor-specific prefix MUST be a domain name under control of the service or application that sets the property, but it need not resolve in the Domain Name System [RFC1034] [RFC1035]. The prefix "ietf.org" and its subdomain names are reserved for IETF specifications. The name MUST NOT contain the TILDE (U+007E) and SOLIDUS (U+002F) characters, as these require special escaping when encoding a JSON Pointer [RFC6901] for that property.¶
Vendor-specific properties MAY be set in any JSContact object. Implementations MUST preserve vendor-specific properties in JSContact data, irrespective if they know their use. They MUST NOT reject the property value as invalid, unless they are in control of the vendor-specific property as outlined in the above paragraph.¶
The ABNF rule "v-extension" formally defines valid vendor-specific property names. Note that the vendor prefix allows for more values than Internationalized Domain Names (IDNs) [RFC9499]; therefore, JSContact implementations can simply validate property names without implementing the full set of rules that apply to domain names.¶
The value of vendor-specific properties can be any valid JSON value, and naming restrictions do not apply to such values. Specifically, if the property value is a JSON object, then the keys of such objects need not be named as vendor-specific properties, as illustrated in Figure 3:¶
Some JSContact IANA-registered properties allow their values to be vendor-specific. One such example is the "kind" (Section 2.1.4) property, which enumerates its standard values but also allows for arbitrary vendor-specific values. Such vendor-specific values MUST be valid "v-extension" values as defined in Section 1.8.1. The example in Figure 4 illustrates this:¶
Vendors are strongly encouraged to specify a new standard value once a vendor-specific one turns out to also be useful for other systems.¶
Every instance of a JSContact Card (Section 2) indicates which JSContact version its IANA-registered properties and values are based on. 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. All IANA-registered elements indicate the version at which they were introduced or obsoleted.¶
A JSContact version consists of a major and minor version.¶
Differing major version values indicate substantial differences in JSContact semantics and format. Implementations MUST be prepared for property definitions and other JSContact elements that differ in a backwards-incompatible manner.¶
Differing minor version values indicate additions that enrich JSContact data but do not introduce backwards-incompatible changes. Typically, these are new property enum values or properties with a narrow semantic scope. A new minor version MUST NOT require implementations to change their processing of JSContact data. Changing the major version number resets the minor version number to zero.¶
A version value starts with the numeric major version, followed by the FULL STOP character (U+002E), followed by the numeric minor version. Later versions are numerically higher than former versions, with the major version being more significant than the minor version. A version value is produced by the following ABNF:¶
This specification registers JSContact version value "1.0" (Table 1).¶
This section defines the JSContact object type Card. A Card stores contact information, typically that of a person, organization, or company.¶
Its media type is defined in Section 3.1.¶
Figure 6 shows a basic Card for the person "John Doe". As the object is the topmost object in the JSON data, it has the @type property set according to the rules defined in Section 1.3.4.¶
This section defines properties about this instance of a Card such as its unique identifier, its creation date, and how it relates to other Cards and other metadata information.¶
The kind of the entity the Card represents.¶
The enumerated (Section 1.7.5) values are:¶
The language tag, as defined in [RFC5646], that best describes the language used for text in the Card, optionally including additional information such as the script. Note that values MAY be localized in the localizations (Section 2.7.1) property.¶
The set of Cards that are members of this group Card. Each key in the set is the uid property value of the member, and each boolean value MUST be "true". If this property is set, then the value of the kind property MUST be "group".¶
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 the members property can be considered an abstract grouping or one whose members are known empirically (e.g., "IETF Participants").¶
The identifier for the product that created the Card. If set, the value MUST be at least one character long.¶
An identifier that associates the object as the same across different systems, address books, and views. The value SHOULD be a URN [RFC8141], but for compatibility with [RFC6350], it MAY also be a URI [RFC3986] or free-text value. The value of the URN SHOULD be in the "uuid" namespace [RFC9562]. [RFC9562] describes multiple versions of Universally Unique IDentifiers (UUIDs); UUID version 4 is RECOMMENDED.¶
This section defines properties that name the entity represented by the Card and its related organizations and roles. It also describes how to refer to the entity represented by the Card in spoken or written language.¶
A Name object has the following properties:¶
The components (Section 2.2.1.2) making up this name. The components property MUST be set if the full property is not set; otherwise, it SHOULD be set. The component list MUST have at least one entry having a different kind property value than "separator".¶
Name components SHOULD be ordered such that when their values are joined as a String, a valid full name of the entity is produced. If so, implementations MUST set the isOrdered property value to "true".¶
If the name components are ordered, then the defaultSeparator property and name components with the kind property value set to "separator" give guidance on what characters to insert between components, but implementations are free to choose any others. When lacking a separator, inserting a single space character in between the name component values is a good choice.¶
If, instead, the name components follow no particular order, then the isOrdered property value MUST be "false", the components property MUST NOT contain a NameComponent with the kind property value set to "separator", and the defaultSeparator property MUST NOT be set.¶
Figure 16 shows an example for the name "Vincent van Gogh". Note how a single name component value may consist of multiple words.¶
Figure 17 illustrates a name with a second surname such as a Spanish name. Additional examples are shown in Figures 19 and 39.¶
The full name representation of the Name. The full property MUST be set if the components property is not set.¶
The value to lexicographically sort the name in relation to other names when compared by a name component type. The keys in the map define the name component type. The values define the verbatim string to compare when sorting by the name component type. Absence of a key indicates that the name component type SHOULD NOT be considered during sort. Sorting by that missing name component type, or if the sortAs property is not set, is implementation-specific. The sortAs property MUST NOT be set if the components property is not set.¶
Each key in the map MUST be a valid name component type value as defined for the kind property of the NameComponent object (see below). For each key in the map, there MUST exist at least one NameComponent object that has the type in the components property of the name.¶
Figure 19 illustrates the use of the sortAs property. The property value indicates that the middle name followed by both surnames should be used when sorting the name by surname. The absence of "middle" indicates that the middle name on its own should be disregarded during sort. Even though the name only contains one name component for the given name, the sortAs property still explicitly defines how to sort by the given name; otherwise, sorting by it would be undefined.¶
The phonetic system used in the NameComponent phonetic property. See Section 1.5.4 for more information and Figure 20 for an example.¶
A NameComponent object has the following properties:¶
The kind of the name component. The enumerated (Section 1.7.5) values are:¶
A Nickname object has the following properties:¶
An Organization object has the following properties, of which at least one of the name and units properties MUST be set:¶
An OrgUnit object has the following properties:¶
A SpeakToAs object has the following properties, of which at least one of the grammaticalGender and pronouns properties MUST be set:¶
The grammatical gender to use in salutations and other grammatical constructs. For example, the German language distinguishes by grammatical gender in salutations such as "Sehr geehrte" (feminine) and "Sehr geehrter" (masculine). The enumerated (Section 1.7.5) values are:¶
Note that the grammatical gender does not allow inferring the gender identities or assigned sex of the contact.¶
The pronouns that the contact chooses to use for themselves.¶
A Pronouns object has the following properties:¶
A Title object has the following properties:¶
The organizational or situational kind of the title. Some organizations and individuals distinguish between titles as organizational positions and roles as more temporary assignments such as in project management.¶
The enumerated (Section 1.7.5) values are:¶
This section defines how properties contact the entity represented by the Card.¶
An EmailAddress object has the following properties:¶
An OnlineService object has the following properties, of which at least the uri or user property MUST be set:¶
Phone object has the following properties:¶
The set of contact features that the phone number may be used for. The set is represented as an object, with each key being a method type. The boolean value MUST be "true". The enumerated (Section 1.7.5) method type values are:¶
A LanguagePref object has the following properties:¶
This section defines properties for scheduling calendar events with the entity represented by the Card.¶
A Calendar object has all properties of the Resource (Section 1.4.4) data type, with the following additional definitions:¶
The kind property is mandatory. Its enumerated (Section 1.7.5) values are:¶
A SchedulingAddress object has the following properties:¶
This section defines properties for postal addresses and geographical locations associated with the entity represented by the Card.¶
An Address object has the following properties, of which at least one of components, coordinates, countryCode, full or timeZone MUST be set:¶
The components (Section 2.5.1.2) that make up the address. The component list MUST have at least one entry that has a kind property value other than "separator".¶
Address components SHOULD be ordered such that when their values are joined as a String, a valid full address is produced. If so, implementations MUST set the isOrdered property value to "true".¶
If the address components are ordered, then the defaultSeparator property and address components with the kind property value set to "separator" give guidance on what characters to insert between components, but implementations are free to choose any others. When lacking a separator, inserting a single space character in between address component values is a good choice.¶
If, instead, the address components follow no particular order, then the isOrdered property value MUST be "false", the components property MUST NOT contain an AddressComponent with the kind property value set to "separator", and the defaultSeparator property MUST NOT be set.¶
The contexts in which to use this address. The boolean value MUST be "true". In addition to the common contexts (Section 1.5.1), allowed key values are:¶
The following example illustrates the use of the address property for "54321 Oak St, Reston, CA 20190, USA". Additional examples are shown in Section 2.5.1.3.¶
An AddressComponent object has the following properties:¶
The kind of the address component. The enumerated (Section 1.7.5) values are:¶
The following example illustrates the use of the address property for "46, 1 Sukhumvit 51 Alley, Khlong Tan Nuea, Watthana, Bangkok 10110, Thailand".¶
The following example illustrates the use of the address property for "2-7-2 Marunouchi, Chiyoda-ku, Tokyo 100-8994" and its Japanese localization (Section 2.7.1).¶
This section defines properties for digital resources associated with the entity represented by the Card.¶
A CryptoKey object has all properties of the Resource (Section 1.4.4) data type, with the following additional definition:¶
The following example shows how to refer to an external cryptographic resource.¶
The following example shows how to embed key data in the CryptoKey. The key data is depicted in multiple lines only for demonstration purposes.¶
A Directory object has all properties of the Resource (Section 1.4.4) data type, with the following additional definitions:¶
The kind property is mandatory. Its enumerated (Section 1.7.5) values are:¶
In addition, the Directory object has the following property:¶
A Link object has all properties of the Resource (Section 1.4.4) data type, with the following additional definitions:¶
The kind property is optional. Its enumerated (Section 1.7.5) values are:¶
A Media object has all properties of the Resource (Section 1.4.4) data type, with the following additional definitions:¶
The kind property is mandatory. Its enumerated (Section 1.7.5) values are:¶
This section defines properties for localizing the content of the Card in human languages.¶
The property values localized to languages other than the main language (Section 2.1.5) of the Card. Localizations provide language-specific alternatives for existing property values and SHOULD NOT add new properties. The keys in the localizations property value are language tags [RFC5646]; the values are of type PatchObject 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 MUST NOT target the localizations property.¶
Conceptually, a Card is localized as follows:¶
A patch in the PatchObject may contain any value type. Its value MUST be a valid value according to the definition of the patched property.¶
Figure 39 localizes the name property by completely replacing its contents in Ukrainian language with Cyrillic script.¶
Figure 40 localizes the title name by patching inside the titles property. All properties, except the name property in the Title object, are left as is.¶
This section defines properties for which none of the previous sections are appropriate.¶
An Anniversary object has the following properties:¶
The kind of anniversary. The enumerated (Section 1.7.5) values are:¶
The date of the anniversary in the Gregorian calendar. This MUST be either a whole or partial calendar date or a complete UTC timestamp (see the definition of the Timestamp and PartialDate object types below).¶
A PartialDate object represents a complete or partial calendar date in the Gregorian calendar. It represents a complete date, a year, a month in a year, or a day in a month. It has the following properties:¶
A Timestamp object has the following properties:¶
Figure 41 illustrates anniversaries with partial dates and a timestamp. Note how the @type property is set for the Timestamp object value according to the rules defined in Section 1.3.4.¶
The set of free-text keywords, also known as tags. Each key in the set is a keyword, and each boolean value MUST be "true".¶
A Note object has the following properties:¶
An Author object has the following properties, of which at least one property other than @type MUST be set:¶
The URI value that identifies the author.¶
A PersonalInfo object has the following properties:¶
The kind of personal information. The enumerated (Section 1.7.5) values are:¶
The level of expertise or engagement in hobby or interest. The enumerated (Section 1.7.5) values are:¶
This document defines a media type for use with JSContact data formatted in JSON.¶
None¶
version¶
This parameter conveys the version of the JSContact data in the body part. It MUST NOT occur more than once. If this parameter is set, then the values of all JSContact version (Table 2) properties in the body part MUST match the parameter value.¶
IANA has created the "JSContact" registry group. The new registry definitions in the following sections all belong to that group.¶
Registry assignments that introduce backwards-incompatible (Section 1.9) changes require the JSContact major version to change; other changes only require a change to the minor version. The registry policy for assignments that require the JSContact major version to change is Standards Action ([RFC8126], Section 4.9). The registry policy for other assignments is Specification Required ([RFC8126], Section 4.6).¶
The designated expert (DE) decides if a major or minor version change is required and assigns the new version to the "JSContact Version" registry (Section 3.4). Version numbers increment by one, and a major version change resets the minor version to zero. An assignment may apply multiple changes and to more than one registry at once, in which case a single version change 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.¶
A registration MUST have an intended usage of "common", "reserved", or "obsolete".¶
The intended usage of registry items may change between versions, but the DE must carefully consider the impact on existing implementations and standards before doing so.¶
The registration procedure is not a formal standards process but rather an administrative procedure intended to allow community comments and to check whether it is coherent without excessive time delay. It is designed to encourage vendors to document and register new items they add for use cases not covered by the original specification, leading to increased interoperability.¶
Notice of a potential new registration MUST be sent to the Calext WG mailing list <calsify@ietf.org> for review. This mailing list is appropriate for soliciting community feedback on a proposed registry assignment.¶
The intent of the public posting to this list is to solicit comments and feedback on the choice of the item name or value, the unambiguity of its description, and a review of any interoperability or security considerations. The submitter may submit a revised registration proposal or abandon the registration completely at any time.¶
Registration requests can be sent to IANA <iana@iana.org>.¶
The primary concern of the DE is preventing name collisions and encouraging the submitter to document security and privacy considerations.¶
A new type name, property name, or enumerated value MUST NOT differ only in case from an already-registered name or value.¶
For a common-use registration, the DE is expected to confirm that suitable documentation is available to ensure interoperability. The DE should also verify that the new assignment does not conflict with work that is active or already published within the IETF.¶
The DE will either approve or deny the registration request and publish a notice of the decision to the Calext WG mailing list or its successor, as well as inform IANA. A denial notice must be justified by an explanation, and in the cases where it is possible, concrete suggestions on how the request can be modified to become acceptable should be provided.¶
Once a JSContact registry group item has been published by IANA, the Change Controller may request a change to its definition. The same procedure that would be appropriate for the original registration request is used to process a change request.¶
JSContact registrations do not get deleted; instead, items that are no longer believed appropriate for use are declared obsolete by a change to their "Intended Usage" field; such items will be clearly marked in the IANA registry.¶
Significant changes to a JSContact registry item's definition should be requested only when there are serious omissions or errors in the published specification, as such changes may cause interoperability issues. When review is required, a change request may be denied if it renders entities that were valid under the previous definition invalid under the new definition.¶
IANA has created the "JSContact Version" registry. The purpose of this new registry is to define the allowed value range of JSContact major and minor version numbers.¶
The registry entries sort numerically in ascending order by the "Major Version" column, and entries with equal "Major Version" sort numerically in ascending order by the "Minor Version" column.¶
The registry process is outlined in Section 3.3.¶
The following table lists the initial valid major and minor version number ranges.¶
Major Version | Highest Minor Version | Reference |
---|---|---|
1 | 0 | RFC 9553 |
IANA has created the "JSContact Properties" registry. The purpose of this new registry is to allow interoperability of extensions to JSContact objects.¶
The registry entries sort alphabetically in ascending order by the following columns: "Property Name" first, "Property Context" second, and "Since Version" third. Equal entries sort in any order.¶
The registry process for a new property is outlined in Section 3.3.¶
The following table lists the initial "common" usage entries of the "JSContact Properties" registry. For all properties, the Since Version is "1.0", the Until Version is not set, the Change Controller is "IETF", and RFC section references are for RFC 9553.¶
Property Name | Property Type | Property Context |
---|---|---|
@type | String | Address (Section 2.5.1.1), AddressComponent (Section 2.5.1.2), Anniversary (Section 2.8.1), Author (Section 2.8.3), Card (Section 2.1.1), Calendar (Section 2.4.1), CryptoKey (Section 2.6.1), Directory (Section 2.6.2), EmailAddress (Section 2.3.1), LanguagePref (Section 2.3.4), Link Section 2.6.3), Media (Section 2.6.4), Name (Section 2.2.1.1), NameComponent (Section 2.2.1.2), Nickname (Section 2.2.2), Note (Section 2.8.3), OnlineService (Section 2.3.2), Organization (Section 2.2.3), OrgUnit (Section 2.2.3), PartialDate (Section 2.8.1), PersonalInfo (Section 2.8.4), Phone (Section 2.3.3), Pronouns (Section 2.2.4), Relation (Section 2.1.8), SchedulingAddress (Section 2.4.2), SpeakToAs (Section 2.2.4), Timestamp (Section 2.8.1), Title (Section 2.2.5) |
address | String | EmailAddress (Section 2.3.1) |
addresses | Id[Address] | Card (Section 2.5.1.1) |
anniversaries | Id[Anniversary] | Card (Section 2.8.1) |
author | Author | Note (Section 2.8.3) |
calendars | Id[Calendar] | Card (Section 2.4.1) |
calendarScale | String | PartialDate (Section 2.8.1) |
components | AddressComponent[] | Address (Section 2.5.1.1) |
components | NameComponent[] | Name (Section 2.2.1.2) |
contexts | String[Boolean] | Address (Section 2.5.1.1), Calendar (Section 2.4.1), CryptoKey (Section 2.6.1), Directory (Section 2.6.2), EmailAddress (Section 2.3.1), LanguagePref (Section 2.3.4), Link (Section 2.6.3), Media (Section 2.6.4), Nickname (Section 2.2.2), OnlineService (Section 2.3.2), Organization (Section 2.2.3), Phone (Section 2.3.3), Pronouns (Section 2.2.4), SchedulingAddress (Section 2.4.2). Also see Sections 1.4.4 and 1.5.1. |
coordinates | String | Address (Section 2.5.1.1) |
countryCode | String | Address (Section 2.5.1.1) |
created | UTCDateTime | Card (Section 2.1.3), Note (Section 2.8.3) |
date | PartialDate|Timestamp | Anniversary (Section 2.8.1) |
day | UnsignedInt | PartialDate (Section 2.8.1) |
defaultSeparator | String | Address (Section 2.5.1.1), Name (Section 2.2.1.1) |
directories | Id[Directory] | Card (Section 2.6.2) |
emails | Id[EmailAddress] | Card (Section 2.3.1) |
features | String[Boolean] | Phone (Section 2.3.3) |
full | String | Address (Section 2.5.1.1), Name (Section 2.2.1.1) |
grammaticalGender | String | SpeakToAs (Section 2.2.4) |
isOrdered | Boolean | Address (Section 2.5.1.1), Name (Section 2.2.1.1) |
keywords | String[Boolean] | Card (Section 2.8.2) |
kind | String | AddressComponent (Section 2.5.1.2), Anniversary (Section 2.8.1), Calendar (Section 2.4.1), Card (Section 2.1.4), CryptoKey (Section 2.6.1), Directory (Section 2.6.2), Link (Section 2.6.3), Media (Section 2.6.4), NameComponent (Section 2.2.1.2), PersonalInfo (Section 2.8.4), Title (Section 2.2.5) |
label | String | Calendar (Section 2.4.1), CryptoKey (Section 2.6.1), Directory (Section 2.6.2), EmailAddress (Section 2.3.1), Link (Section 2.6.3), Media (Section 2.6.4), OnlineService (Section 2.3.2), PersonalInfo (Section 2.8.4), Phone (Section 2.3.3), SchedulingAddress (Section 2.4.2). Also see Sections 1.4.4 and 1.5.2. |
language | String | Card (Section 2.1.5), LanguagePref (Section 2.3.4) |
level | String | PersonalInfo (Section 2.8.4) |
links | Id[Link] | Card (Section 2.6.3) |
listAs | UnsignedInt | Directory (Section 2.6.2), PersonalInfo (Section 2.8.4) |
localizations | String[PatchObject] | Card (Section 2.7.1) |
media | Id[Media] | Card (Section 2.6.4) |
mediaType | String | Calendar (Section 2.4.1), CryptoKey (Section 2.6.1), Directory (Section 2.6.2), Link (Section 2.6.3), Media (Section 2.6.4). Also see Section 1.4.4. |
members | String[Boolean] | Card (Section 2.1.6) |
month | UnsignedInt | PartialDate (Section 2.8.1) |
name | Name | Card (Section 2.2.1.1) |
name | String | Author (Section 2.8.3), Nickname (Section 2.2.2), Organization (Section 2.2.3), OrgUnit (Section 2.2.3), Title (Section 2.2.5) |
nicknames | Id[Nickname] | Card (Section 2.2.2) |
note | String | Note (Section 2.8.3) |
notes | Id[Note] | Card (Section 2.8.3) |
number | String | Phone (Section 2.3.3) |
onlineServices | Id[OnlineService] | Card (Section 2.3.2) |
organizationId | String | Title (Section 2.2.5) |
organizations | Id[Organization] | Card (Section 2.2.3) |
personalInfo | Id[PersonalInfo] | Card (Section 2.8.4) |
phones | Id[Phone] | Card (Section 2.3.3) |
phonetic | String | AddressComponent (Section 2.5.1.2), NameComponent (Section 2.2.1.2) |
phoneticScript | String | Address (Section 2.5.1.1), Name (Section 2.2.1.1) |
phoneticSystem | String | Address (2.5.1.1), Name (Section 2.2.1.1) |
place | Address | Anniversary (Section 2.8.1) |
pref | UnsignedInt | Address (Section 2.5.1.1), Calendar (Section 2.4.1), CryptoKey (Section 2.6.1), Directory (Section 2.6.2), EmailAddress (Section 2.3.1), LanguagePref (Section 2.3.4), Link (Section 2.6.3), Media (Section 2.6.4), Nickname (Section 2.2.2), OnlineService (Section 2.3.2), Phone (Section 2.3.3), Pronouns (Section 2.2.4), SchedulingAddress (Section 2.4.2). Also see Sections 1.4.4 and 1.5.3. |
preferredLanguages | String[LanguagePref] | Card (Section 2.3.4) |
prodId | String | Card (Section 2.1.7) |
pronouns | Id[Pronouns] | SpeakToAs (Section 2.2.4) |
relatedTo | String[Relation] | Card (Section 2.1.8) |
relation | String[Boolean] | Relation (Section 2.1.8) |
schedulingAddresses | Id[SchedulingAddress] | Card (Section 2.4.2) |
service | String | OnlineService (Section 2.3.2) |
sortAs | String[String] | Name (Section 2.2.1.1) |
sortAs | String | Organization (Section 2.2.3), OrgUnit (Section 2.2.3) |
speakToAs | SpeakToAs | Card (Section 2.2.4) |
timeZone | String | Address (Section 2.5.1.1) |
titles | Id[Title] | Card (Section 2.2.5) |
uid | String | Card (Section 2.1.9) |
units | OrgUnit[] | Organization (Section 2.2.3) |
updated | UTCDateTime | Card (Section 2.1.10) |
uri | String | Author (Section 2.8.3), Calendar (Section 2.4.1), CryptoKey (Section 2.6.1), Directory (Section 2.6.2), Link (Section 2.6.3), Media (Section 2.6.4), OnlineService (Section 2.3.2), SchedulingAddress (Section 2.4.2). Also see Section 1.4.4. |
user | String | OnlineService (Section 2.3.2) |
utc | UTCDateTime | Timestamp (Section 2.8.1) |
value | String | AddressComponent (Section 2.5.1.2), NameComponent (Section 2.2.1.2), PersonalInfo (Section 2.8.4) |
version | String | Card (Section 2.1.2) |
year | UnsignedInt | PartialDate (Section 2.8.1) |
The following table lists the initial "reserved" usage entries of the "JSContact Properties" registry. For this property, the Change Controller is "IETF", and the RFC section reference is for RFC 9553.¶
Property Name | Property Type | Property Context | Intended Usage | Reference/Description |
---|---|---|---|---|
extra | not applicable | not applicable | reserved | Section 1.7.3.1 |
IANA has created the "JSContact Types" registry. The purpose of this new registry is to avoid name collisions for JSContact type names and provide a complete reference for all data types used for JSContact property values.¶
The registry entries sort alphabetically in ascending order by the "Type Name" column. Equal entries sort in any order.¶
The registry process for a new type is outlined in Section 3.3.¶
The following table lists the initial "common" usage entries in the "JSContact Types" registry. For all of these types, the Since Version is "1.0", the Until Version is not set, the Change Controller is "IETF", and RFC section references are for RFC 9553.¶
Type Name | Reference/Description |
---|---|
Address | Section 2.5.1.1 |
AddressComponent | Section 2.5.1.2 |
Anniversary | Section 2.8.1 |
Author | Section 2.8.3 |
Boolean | Section 1.3.2 |
Calendar | Section 2.4.1 |
Card | Section 2 |
CryptoKey | Section 2.6.1 |
Directory | Section 2.6.2 |
EmailAddress | Section 2.3.1 |
Id | Section 1.4.1 |
Int | Section 1.4.2 |
LanguagePref | Section 2.3.4 |
Link | Section 2.6.3 |
Media | Section 2.6.4 |
Name | Section 2.2.1.1 |
NameComponent | Section 2.2.1.2 |
Nickname | Section 2.2.2 |
Note | Section 2.8.3 |
Number | Section 1.3.2 |
OnlineService | Section 2.3.2 |
Organization | Section 2.2.3 |
OrgUnit | Section 2.2.3 |
PartialDate | Section 2.8.1 |
PatchObject | Section 1.4.3 |
PersonalInfo | Section 2.8.4 |
Phone | Section 2.3.3 |
Pronouns | Section 2.2.4 |
Relation | Section 2.1.8 |
SchedulingAddress | Section 2.4.2 |
SpeakToAs | Section 2.2.4 |
String | Section 1.3.2 |
Timestamp | Section 2.8.1 |
Title | Section 2.2.5 |
UnsignedInt | Section 1.4.2 |
UTCDateTime | Section 1.4.5 |
The following table lists the initial "reserved" usage entry of the "JSContact Types" registry. For this type, the version is "1.0", the Change Controller is "IETF", and the RFC section reference is for RFC 9553.¶
Type Name | Reference/Description |
---|---|
Resource | Section 1.4.4 |
IANA has created the "JSContact Enum Values" registry. The purpose of the new registry is to allow interoperable extension of semantics for JSContact properties with enumerable values. Each such property will have a subregistry of allowed values.¶
The registry entries sort alphabetically in ascending order by the following columns: "Property Name" first, "Property Context" second, and "Since Version" third. The enum values sort alphabetically in ascending order. Equal entries sort in any order.¶
The registry process for a new enum value or adding a new enumerable property is outlined in Section 3.3.¶
This template is for adding a subregistry for a new enumerable property to the "JSContact Enum Values" registry.¶
Note that the initial contents will be the initial list of defined values for the enum, using the template defined in Section 3.7.2. A subregistry will be created with these values for this property name/context tuple.¶
This template is for adding a new enum value to a subregistry in the "JSContact Enum Values" registry.¶
For all entries in each subregistry created in this section, the Since Version is "1.0", the Until Version is not set, the Change Controller is "IETF", and RFC section references are for RFC 9553.¶
Enum Value | Reference/Description |
---|---|
billing | Section 2.5.1.1 |
delivery | Section 2.5.1.1 |
private | Section 1.5.1 |
work | Section 1.5.1 |
Enum Value | Reference/Description |
---|---|
fax | Section 2.3.3 |
main-number | Section 2.3.3 |
mobile | Section 2.3.3 |
pager | Section 2.3.3 |
text | Section 2.3.3 |
textphone | Section 2.3.3 |
video | Section 2.3.3 |
voice | Section 2.3.3 |
Enum Value | Reference/Description |
---|---|
animate | Section 2.2.4 |
common | Section 2.2.4 |
feminine | Section 2.2.4 |
inanimate | Section 2.2.4 |
masculine | Section 2.2.4 |
neuter | Section 2.2.4 |
Enum Value | Reference/Description |
---|---|
apartment | Section 2.5.1.2 |
block | Section 2.5.1.2 |
building | Section 2.5.1.2 |
country | Section 2.5.1.2 |
direction | Section 2.5.1.2 |
district | Section 2.5.1.2 |
floor | Section 2.5.1.2 |
landmark | Section 2.5.1.2 |
locality | Section 2.5.1.2 |
name | Section 2.5.1.2 |
number | Section 2.5.1.2 |
postcode | Section 2.5.1.2 |
postOfficeBox | Section 2.5.1.2 |
region | Section 2.5.1.2 |
room | Section 2.5.1.2 |
separator | Section 2.5.1.2 |
subdistrict | Section 2.5.1.2 |
Enum Value | Reference/Description |
---|---|
birth | Section 2.8.1 |
death | Section 2.8.1 |
wedding | Section 2.8.1 |
Enum Value | Reference/Description |
---|---|
calendar | Section 2.4.1 |
freeBusy | Section 2.4.1 |
Enum Value | Reference/Description |
---|---|
application | Section 2.1.4 |
device | Section 2.1.4 |
group | Section 2.1.4 |
individual | Section 2.1.4 |
location | Section 2.1.4 |
org | Section 2.1.4 |
Enum Value | Reference/Description |
---|---|
directory | Section 2.6.2 |
entry | Section 2.6.2 |
Enum Value | Reference/Description |
---|---|
contact | Section 2.6.3 |
Enum Value | Reference/Description |
---|---|
logo | Section 2.6.4 |
photo | Section 2.6.4 |
sound | Section 2.6.4 |
Enum Value | Reference/Description |
---|---|
credential | Section 2.2.1.2 |
generation | Section 2.2.1.2 |
given | Section 2.2.1.2 |
given2 | Section 2.2.1.2 |
separator | Section 2.2.1.2 |
surname | Section 2.2.1.2 |
surname2 | Section 2.2.1.2 |
title | Section 2.2.1.2 |
Enum Value | Reference/Description |
---|---|
expertise | Section 2.8.4 |
hobby | Section 2.8.4 |
interest | Section 2.8.4 |
Enum Value | Reference/Description |
---|---|
role | Section 2.2.5 |
title | Section 2.2.5 |
Enum Value | Reference/Description |
---|---|
high | Section 2.8.4 |
low | Section 2.8.4 |
medium | Section 2.8.4 |
Enum Value | Reference/Description |
---|---|
ipa | Section 1.5.4 |
jyut | Section 1.5.4 |
piny | Section 1.5.4 |
Enum Value | Reference/Description |
---|---|
acquaintance | Section 2.1.8 |
agent | Section 2.1.8 |
child | Section 2.1.8 |
colleague | Section 2.1.8 |
contact | Section 2.1.8 |
co-resident | Section 2.1.8 |
co-worker | Section 2.1.8 |
crush | Section 2.1.8 |
date | Section 2.1.8 |
emergency | Section 2.1.8 |
friend | Section 2.1.8 |
kin | Section 2.1.8 |
me | Section 2.1.8 |
met | Section 2.1.8 |
muse | Section 2.1.8 |
neighbor | Section 2.1.8 |
parent | Section 2.1.8 |
sibling | Section 2.1.8 |
spouse | Section 2.1.8 |
sweetheart | Section 2.1.8 |
Contact information is very privacy sensitive. It can reveal the identity, location, credentials information, employment status, interests and hobbies, and social network of a user. Its transmission and storage must be done carefully to protect it from possible threats such as eavesdropping, replay, message insertion, deletion, modification, and on-path attacks.¶
The data being stored and transmitted may be used in systems with real-world consequences. For example, a malicious actor might provide JSContact data that uses the name of another person but insert their contact details to impersonate the unknown victim. Such systems must be careful to authenticate all data they receive to prevent them from being subverted and ensure the change comes from an authorized entity.¶
This document only defines the data format; such considerations are primarily the concern of the API or method of storage and transmission of such files.¶
The security considerations of [RFC8259] apply to the use of JSON as the data interchange format.¶
As for any serialization format, parsers need to thoroughly check the syntax of the supplied data. JSON uses opening and closing brackets for several types and structures, and it is possible that the end of the supplied data will be reached when scanning for a matching closing bracket; this is an error condition, and implementations need to stop scanning at the end of the supplied data.¶
JSON also uses a string encoding with some escape sequences to encode special characters within a string. Care is needed when processing these escape sequences to ensure that they are fully formed before the special processing is triggered, with special care taken when the escape sequences appear adjacent to other (non-escaped) special characters or adjacent to the end of data (as in the previous paragraph).¶
If parsing JSON into a non-textual structured data format, implementations may need to allocate storage to hold JSON string elements. Since JSON does not use explicit string lengths, the risk of denial of service due to resource exhaustion is small, but implementations may still wish to place limits on the size of allocations they are willing to make in any given context, to avoid untrusted data causing excessive memory allocation.¶
Several JSContact properties contain URIs as values, and processing these properties requires extra care. Section 7 of [RFC3986] discusses security risks related to URIs.¶
Fetching remote resources carries inherent risks. Connections must only be allowed on well-known ports, using allowed protocols (generally, just HTTP/HTTPS on their default ports). The URL must be resolved externally and not allowed to access internal resources. Connecting to an external source reveals IP (and therefore often location) information.¶
A maliciously constructed JSContact object may contain a very large number of URIs. In the case of published address books with a large number of subscribers, such objects could be widely distributed. Implementations should be careful to limit the automatic fetching of linked resources to reduce the risk of this being an amplification vector for a denial-of-service attack.¶