--- 1/draft-ietf-jmap-jscontact-05.txt 2021-05-28 04:13:52.709406960 -0700 +++ 2/draft-ietf-jmap-jscontact-06.txt 2021-05-28 04:13:52.753408059 -0700 @@ -1,19 +1,19 @@ JMAP R. Stepanek Internet-Draft FastMail Intended status: Standards Track M. Loffredo -Expires: 16 October 2021 IIT-CNR - 14 April 2021 +Expires: 29 November 2021 IIT-CNR + 28 May 2021 JSContact: A JSON representation of contact data - draft-ietf-jmap-jscontact-05 + draft-ietf-jmap-jscontact-06 Abstract This specification defines a data model and 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. @@ -26,21 +26,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on 16 October 2021. + This Internet-Draft will expire on 29 November 2021. Copyright Notice Copyright (c) 2021 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 @@ -72,42 +72,46 @@ 2.1.6. relatedTo . . . . . . . . . . . . . . . . . . . . . . 8 2.2. Name and Organization properties . . . . . . . . . . . . 9 2.2.1. name . . . . . . . . . . . . . . . . . . . . . . . . 9 2.2.2. fullName . . . . . . . . . . . . . . . . . . . . . . 9 2.2.3. nickNames . . . . . . . . . . . . . . . . . . . . . . 10 2.2.4. organizations . . . . . . . . . . . . . . . . . . . . 10 2.2.5. titles . . . . . . . . . . . . . . . . . . . . . . . 10 2.3. Contact and Resource properties . . . . . . . . . . . . . 10 2.3.1. emails . . . . . . . . . . . . . . . . . . . . . . . 10 2.3.2. phones . . . . . . . . . . . . . . . . . . . . . . . 11 - 2.3.3. online . . . . . . . . . . . . . . . . . . . . . . . 11 - 2.3.4. photos . . . . . . . . . . . . . . . . . . . . . . . 12 + 2.3.3. online . . . . . . . . . . . . . . . . . . . . . . . 12 + 2.3.4. photos . . . . . . . . . . . . . . . . . . . . . . . 13 2.3.5. preferredContactMethod . . . . . . . . . . . . . . . 13 - 2.3.6. preferredContactLanguages . . . . . . . . . . . . . . 13 + 2.3.6. preferredContactLanguages . . . . . . . . . . . . . . 14 2.4. Address and Location properties . . . . . . . . . . . . . 14 2.4.1. addresses . . . . . . . . . . . . . . . . . . . . . . 14 - 2.5. Additional properties . . . . . . . . . . . . . . . . . . 15 - 2.5.1. anniversaries . . . . . . . . . . . . . . . . . . . . 15 - 2.5.2. personalInfo . . . . . . . . . . . . . . . . . . . . 15 - 2.5.3. notes . . . . . . . . . . . . . . . . . . . . . . . . 16 - 2.5.4. categories . . . . . . . . . . . . . . . . . . . . . 16 - 3. GroupCard . . . . . . . . . . . . . . . . . . . . . . . . . . 16 - 3.1. Group properties . . . . . . . . . . . . . . . . . . . . 17 - 3.1.1. members . . . . . . . . . . . . . . . . . . . . . . . 17 - 4. Implementation Status . . . . . . . . . . . . . . . . . . . . 17 - 4.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 17 - 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 18 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 18 - 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 18 - 7.1. Normative References . . . . . . . . . . . . . . . . . . 18 - 7.2. Informative References . . . . . . . . . . . . . . . . . 19 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 20 + 2.5. Additional properties . . . . . . . . . . . . . . . . . . 16 + 2.5.1. anniversaries . . . . . . . . . . . . . . . . . . . . 16 + 2.5.2. personalInfo . . . . . . . . . . . . . . . . . . . . 17 + 2.5.3. notes . . . . . . . . . . . . . . . . . . . . . . . . 17 + 2.5.4. categories . . . . . . . . . . . . . . . . . . . . . 17 + 2.5.5. timeZones . . . . . . . . . . . . . . . . . . . . . . 17 + 3. CardGroup . . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 3.1. Group properties . . . . . . . . . . . . . . . . . . . . 18 + 3.1.1. uid . . . . . . . . . . . . . . . . . . . . . . . . . 18 + 3.1.2. members . . . . . . . . . . . . . . . . . . . . . . . 18 + 3.1.3. name . . . . . . . . . . . . . . . . . . . . . . . . 18 + 3.1.4. card . . . . . . . . . . . . . . . . . . . . . . . . 18 + 4. Implementation Status . . . . . . . . . . . . . . . . . . . . 18 + 4.1. IIT-CNR/Registro.it . . . . . . . . . . . . . . . . . . . 19 + 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 19 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 19 + 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 7.1. Normative References . . . . . . . . . . . . . . . . . . 19 + 7.2. Informative References . . . . . . . . . . . . . . . . . 21 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 22 1. Introduction 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] and to provide a JSON-based standard representation of contact card data. The key design considerations for this data model are as follows: @@ -367,21 +371,22 @@ future. 2.2. Name and Organization properties 2.2.1. name Type: "NameComponent[]" (optional). The name components of the name of the entity represented by this Card. Name components SHOULD be ordered such that their values - joined by whitespace produce a valid full name of this entity. + joined by whitespace produce a valid full name of this entity. Doing + so, implementations MAY ignore any "separator" components. A NameComponent has the following properties: * value: "String" (mandatory). The value of this name component. * type: "String" (mandatory). The type of this name component. The value MUST be either one of the following values, registered in a future RFC, or a vendor-specific value: - "prefix". The value is a honorific title(s), e.g. "Mr", "Ms", @@ -392,20 +397,24 @@ - "surname". The value is a surname, also known as "last name", "family name". - "additional". The value is an additional name, also known as "middle name". - "suffix". The value is a honorific suffix, e.g. "B.A.", "Esq.". + - "separator". A separator for two name components. The "value" + property of the component includes the verbatim separator, for + example a newline character. + 2.2.2. fullName Type: "LocalizedString" (optional). The full name (e.g. the personal name and surname of an individual, the name of an organization) of the entity represented by this card. The purpose of this property is to define a name, even if the individual name components are not known. In addition, it is meant to provide alternative versions of the name for internationalisation. Implementations SHOULD prefer using the _name_ property over this one @@ -453,59 +462,69 @@ The email addresses to contact the entity represented by this card. An EmailAddress object has the following properties: * email: "String" (mandatory). The email address. This MUST be an _addr-spec_ value as defined in Section 3.4.1 of [RFC5322]. * contexts: "Context[Boolean]" (optional) The contexts in which to use this email address. The value for each key in the object MUST be "true". - * pref: Preference (optional) The preference of this email address + * pref: "Preference" (optional) The preference of this email address in relation to other email addresses. 2.3.2. phones Type: "Id[Phone]" (optional). The phone numbers to contact the entity represented by this card. A phone object has the following properties: * phone: "String" (mandatory). The phone value, as either a URI or a free-text phone number. Typical URI schemes are the [RFC3966] "tel" or [RFC3261] "sip" schemes, but any URI scheme is allowed. * features: "String[Boolean]" (optional). The set of contact features that this phone number may be used for. The set is represented as an object, with each key being a method type. The - value for each key in the object MUST be "true". The allowed - methods are: + value for each key in the object MUST be "true". The method type + MUST be either one of the following values, registered in a future + RFC, or a vendor-specific value: - "voice" The number is for calling by voice. - "fax" The number is for sending faxes. - "pager" The number is for a pager or beeper. + - "text" The number supports text messages (SMS). + + - "cell" The number is for a cell phone. + + - "textphone" The number is for a device for people with hearing + or speech difficulties. + + - "video" The number supports video conferencing. + - "other" The number is for some other purpose. The label property MAY be included to display next to the number to help the user identify its purpose. * contexts: "Context[Boolean]" (optional) The contexts in which to use this number. The value for each key in the object MUST be "true". * label: "String" (optional). A label describing the value in more detail, especially if the type property has value "other" (but MAY be included with any type). - * pref: Preference (optional) The preference of this number in + * pref: "Preference" (optional) The preference of this number in relation to other numbers. 2.3.3. online Type: "Id[Resource]" (optional). The online resources and services that are associated with the entity represented by this card. A Resource object has the following properties: @@ -539,21 +558,21 @@ the URI. * contexts: "Context[Boolean]" (optional) The contexts in which to use this resource. The value for each key in the object MUST be "true". * label: "String" (optional). A label describing the value in more detail, especially if the type property has value "other" (but MAY be included with any type). - * pref: Preference (optional) The preference of this resource in + * pref: "Preference" (optional) The preference of this resource in relation to other resources. 2.3.4. photos Type: "Id[File]" (optional). A map of photo ids to File objects that contain photographs or images associated with this card. A typical use case is to include an avatar for display along the contact name. @@ -562,21 +581,21 @@ * href: "String" (mandatory). A URI where to fetch the data of this file. * mediaType: "String" (optional). The content-type of the file, if known. * size: "UnsignedInt" (optional). The size, in octets, of the file when fully decoded (i.e., the number of octets in the file the user would download), if known. - * pref: Preference (optional) The preference of this photo in + * pref: "Preference" (optional) The preference of this photo in relation to other photos. 2.3.5. preferredContactMethod Type : "String" (optional) Defines the preferred method to contact the holder of this card. The value MUST be the property names: "emails", "phones", "online". 2.3.6. preferredContactLanguages @@ -607,74 +626,107 @@ Type: "Id[Address]" (optional). A map of address ids to Address objects, containing physical locations. An Address object has the following properties: * fullAddress: "LocalizedString" (optional). The complete address, excluding type and label. This property is mainly useful to represent addresses of which the individual address components are unknown, or to provide localized representations. - * street: "String" (optional). The street address. This MAY be - multiple lines; newlines MUST be preserved. - - * extension: "String" (optional) The extended address, such as an - apartment or suite number, or care-of address. + * street: "StreetComponent[]" (optional). The street address. The + concatenation of the component values, separated by whitespace, + SHOULD result in a valid street address for the address locale. + Doing so, implementations MAY ignore any "separator" components. + The StreetComponent object type is defined in the paragraph below. * locality: "String" (optional). The city, town, village, post town, or other locality within which the street address may be found. * region: "String" (optional). The province, such as a state, county, or canton within which the locality may be found. * country: "String" (optional). The country name. - * postOfficeBox: "String" (optional) The post office box. - * postcode: "String" (optional). The postal code, post code, ZIP code or other short code associated with the address by the relevant country's postal system. * countryCode: "String" (optional). The ISO-3166-1 country code. * coordinates: "String" (optional) A [RFC5870] "geo:" URI for the address. * timeZone: "String" (optional) Identifies the time zone this - address is located in. This SHOULD be a time zone name registered - in the IANA Time Zone Database (https://www.iana.org/time-zones). - Unknown time zone identifiers MAY be ignored by implementations. + address is located in. This either MUST be a time zone name + registered in the IANA Time Zone Database (https://www.iana.org/ + time-zones), or it MUST be a valid TimeZoneId as defined in FIXME + . For the latter, a corresponding time zone MUST be defined in the + "timeZones" property. * contexts: "Context[Boolean]" (optional). The contexts of the address information. In addition to the common contexts, allowed values are: - "billing" An address to be used for billing. - "postal" An address to be used for delivering physical items. The value for each key in the object MUST be "true". * label: "String" (optional). A label describing the value in more detail. - * pref: Preference (optional) The preference of this address in + * pref: "Preference" (optional) The preference of this address in relation to other addresses. + A StreetComponent object has the following properties: + + * type: "String" (mandatory). The type of this street component. + The value MUST be either one of the following values, registered + in a future RFC, or a vendor-specific value: + + - "name". The street name. + + - "number". The street number. + + - "apartment". The apartment number or identifier. + + - "room". The room number or identifier. + + - "extension". The extension designation or box number. + + - "direction". The cardinal direction, e.g. "North". + + - "building". The building or building part this address is + located in. + + - "floor". The floor this address is located on. + + - "postOfficeBox". The post office box number or identifier. + + - "separator". A separator for two street components. The + "value" property of the component includes the verbatim + separator, for example a newline character. + + - "unknown". A name component value for which no type is known. + + * value: "String" (mandatory). The value of this street component. + 2.5. Additional properties 2.5.1. anniversaries - Type : Anniversary[] (optional). + Type : Id[Anniversary] (optional). - Memorable dates and events for the entity represented by this card. - An Anniversary object has the following properties: + These are memorable dates and events for the entity represented by + this card. An Anniversary object has the following properties: * type: "String" (mandatory). Specifies the type of the anniversary. This RFC predefines the following types, but implementations MAY use additional values: - "birth": a birth day anniversary - "death": a death day anniversary - "other": an anniversary not covered by any of the known types. @@ -685,23 +737,23 @@ * date: "String" (mandatory). The date of this anniversary, in the form "YYYY-MM-DD" (any part may be all 0s for unknown) or a [RFC3339] timestamp. * place: Address (optional). An address associated with this anniversary, e.g. the place of birth or death. 2.5.2. personalInfo - Type: PersonalInformation[] (optional). + Type: "Id[PersonalInformation]" (optional). - A list of personal information about the entity represented by this + Defines personal information about the entity represented by this card. A PersonalInformation object has the following properties: * type: "String" (mandatory). Specifies the type for this personal information. Allowed values are: - "expertise": a field of expertise or credential - "hobby": a hobby - "interest": an interest @@ -722,41 +774,59 @@ Arbitrary notes about the entity represented by this card. 2.5.4. categories Type: "String[Boolean]" (optional). The set of free-text or URI categories that relate to the card. The set is represented as an object, with each key being a category. The value for each key in the object MUST be "true". -3. GroupCard +2.5.5. timeZones - MIME type: "application/jscontact+json;type=groupcard" + Type: "String[TimeZone]" (optional). Maps identifiers of custom time + zones to their time zone definitions. For a description of this + property see the "timeZones" property definition in FIXME . - A GroupCard object represents a group of cards. Its members may be - Cards or GroupCards. +3. CardGroup - Both GroupCard and Card share the same namespace for the "uid" - property. All properties for a Card are also defined for GroupCard, - with the exception that the "kind" property MUST be set to "group". + MIME type: "application/jscontact+json;type=cardgroup" + + A CardGroup object represents a group of cards. Its members may be + Cards or CardGroups. 3.1. Group properties -3.1.1. members +3.1.1. uid + + Type: "String" (mandatory). The uid of this group. Both CardGroup + and Card share the same namespace for the "uid" property. + +3.1.2. members Type: "String[Boolean]" (mandatory). The members of this group. The set is represented as an object, with each key being the uid of - another Card or GroupCard. The value for each key in the object MUST + another Card or CardGroup. The value for each key in the object MUST be "true". +3.1.3. name + + Type: "String" (optional). The user-visible name for the group, e.g. + "Friends". This may be any UTF-8 string of at least 1 character in + length and maximum 255 octets in size. The same name may be used by + two different groups. + +3.1.4. card + + Type: "Card" (optional). The card that represents this group. + 4. Implementation Status NOTE: Please remove this section and the reference to [RFC7942] prior to publication as an RFC. This section records the status of known implementations of the protocol defined by this specification at the time of posting of this Internet-Draft, and is based on a proposal described in [RFC7942]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the