< draft-stepanek-jscontact-01.txt   draft-stepanek-jscontact-02.txt >
TBD R. Stepanek TBD R. Stepanek
Internet-Draft FastMail Internet-Draft FastMail
Intended status: Standards Track June 7, 2019 Intended status: Standards Track M. Loffredo
Expires: December 9, 2019 Expires: December 22, 2019 IIT-CNR
June 20, 2019
JSContact: A JSON representation of addressbook data JSContact: A JSON representation of addressbook data
draft-stepanek-jscontact-01 draft-stepanek-jscontact-02
Abstract Abstract
This specification defines a data model and JSON representation of This specification defines a data model and JSON representation of
contact information that can be used for data storage and exchange in contact information that can be used for data storage and exchange in
address book or directory applications. It aims to be an alternative address book or directory applications. It aims to be an alternative
to the vCard data format and to be unambiguous, extendable and simple 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 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 direct mapping from the vCard data model and expands semantics where
appropriate. appropriate.
skipping to change at page 1, line 36 skipping to change at page 1, line 37
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 9, 2019. This Internet-Draft will expire on December 22, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2019 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 13 skipping to change at page 2, line 14
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2
1.1. Relation to the xCard and jCard formats . . . . . . . . . 3 1.1. Relation to the xCard and jCard formats . . . . . . . . . 3
1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Terminology . . . . . . . . . . . . . . . . . . . . . . . 3
2. Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Contact Group . . . . . . . . . . . . . . . . . . . . . . . . 7 3. Contact Group . . . . . . . . . . . . . . . . . . . . . . . . 8
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 7 4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9
5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 8 6. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
6.1. Normative References . . . . . . . . . . . . . . . . . . 8 6.1. Normative References . . . . . . . . . . . . . . . . . . 9
6.2. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 9 6.2. Informative References . . . . . . . . . . . . . . . . . 10
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 6.3. URIs . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11
1. Introduction 1. Introduction
This document defines a data model for contact data normally used in This document defines a data model for contact data normally used in
address book or directory applications and services. It aims to be address book or directory applications and services. It aims to be
an alternative to the vCard data format [RFC6350] and to provide a an alternative to the vCard data format [RFC6350] and to provide a
JSON-based standard representation of contacts data. JSON-based standard representation of contacts data.
The key design considerations for this data model are as follows: The key design considerations for this data model are as follows:
o Most of the initial set of attributes should be taken from the o Most of the initial set of attributes should be taken from the
vCard data format [RFC6350], but the specification should add new vCard data format [RFC6350] and extensions ([RFC6473], [RFC6474],
attributes or value types, or not support existing ones, where [RFC6715], [RFC6869], [RFC8605]). The specification should add
new attributes or value types, or not support existing ones, where
appropriate. Conversion between the data formats need not fully appropriate. Conversion between the data formats need not fully
preserve semantic meaning. preserve semantic meaning.
o The attributes of the contacts data represented must be described o The attributes of the contacts data represented must be described
as a simple key-value pair, reducing complexity of its as a simple key-value pair, reducing complexity of its
representation. representation.
o The data model should avoid all ambiguities and make it difficult o The data model should avoid all ambiguities and make it difficult
to make mistakes during implementation. to make mistakes during implementation.
skipping to change at page 3, line 30 skipping to change at page 3, line 32
14 [RFC2119] [RFC8174] when, and only when, they appear in all 14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here. capitals, as shown here.
2. Contact 2. Contact
MIME type: "application/jscontact+json;type=jscontact" MIME type: "application/jscontact+json;type=jscontact"
A JSContact object stores contact information about a person, A JSContact object stores contact information about a person,
organization or company. It has the following properties: organization or company. It has the following properties:
o uid: String (mandatory). A globally unique identifier, used to o uid: String (mandatory). An identifier, used to associate the
associate the object as the same across different systems, object as the same across different systems, addressbooks and
addressbooks and views. The value of this property MUST be unique views. [RFC4122] describes a range of established algorithms to
across _all_ JSContact objects. [RFC4122] describes a range of generate universally unique identifiers (UUID), and the random or
established algorithms to generate universally unique identifiers pseudo-random version is recommended. For compatibility with
(UUID), and the random or pseudo-random version is recommended. [RFC6350] UIDs, implementations MUST accept both URI and free-form
For compatibility with [RFC6350] UIDs, implementations MUST accept text.
both URI and free-form text.
o prodId: String (optional). The identifier for the product that
created the JSContact object.
o updated: String (mandatory). The date and time when the data in
this JSContact object was last modified. The timestamp MUST be
formatted as specified in [RFC3339].
o kind: String (optional). The kind of the entity the Contact o kind: String (optional). The kind of the entity the Contact
represents. The value MUST be either one of the following values, represents. The value MUST be either one of the following values,
registered in a future RFC, or a vendor-specific value: registered in a future RFC, or a vendor-specific value:
* "individual": a single person * "individual": a single person
* "org": an organization * "org": an organization
* "location": a named location * "location": a named location
o fullName: String (mandatory) The full name(s) of a contact (e.g. * "device": a device, such as appliances, computers, or network
the personal name and surname of an individual, the name of an elements
organization).
o prefix: String[] (optional). The honorific title(s) of the * "application": a software application
contact (e.g. "Mr", "Ms", "Dr").
o personalName: String[] (optional). The personal name(s) of a o fullName: FullName[] (mandatory). The full name(s) of a contact.
contact (also known as "first name", "give name"). A FullName object has the following properties:
o surname: String[] (optional). The surname(s) of a contact (also * name: String (mandatory) The full name (e.g. the personal name
known as "last name", "family name"). and surname of an individual, the name of an organization).
o additionalName: String[] (optional). The additional name(s) of a * language: String (optional) The [RFC5646] language tag of this
contact (also known as "middle name"). name, if any.
o suffix: String[] (optional). The honorific suffix(es) of the * isPreferred: Boolean (optional, default: "false"). Whether
contact (e.g. "B.A.", "Esq."). this FullName is the preferred name for this contact.
o structuredName: StructuredName (optional). The name of this
contact, structured by its constituents. A StructuredName object
has the following properties:
* prefix: String[] (optional). The honorific title(s) of the
contact (e.g. "Mr", "Ms", "Dr").
* personalName: String[] (optional). The personal name(s) of a
contact (also known as "first name", "give name").
* surname: String[] (optional). The surname(s) of a contact
(also known as "last name", "family name").
* additionalName: String[] (optional). The additional name(s) of
a contact (also known as "middle name").
* suffix: String[] (optional). The honorific suffix(es) of the
contact (e.g. "B.A.", "Esq.").
o nickname: String[] (optional). The nickname(s) of the contact. o nickname: String[] (optional). The nickname(s) of the contact.
o birthday: String (optional). The contact's birth date in the form o birthday: String (optional). The contact's birth date in the form
"YYYY-MM-DD" (any part may be all 0s for unknown). "YYYY-MM-DD" (any part may be all 0s for unknown) or a [RFC3339]
timestamp.
o birthPlace: String (optional). The contact's birth place.
o deathDate: String (optional). The contact's death date in the
form "YYYY-MM-DD" (any part may be all 0s for unknown) or a
[RFC3339] timestamp.
o deathPlace: String (optional). The contact's death place.
o anniversary: String (optional). The contact's anniversary date in o anniversary: String (optional). The contact's anniversary date in
the form "YYYY-MM-DD" (any part may be all 0s for unknown). the form "YYYY-MM-DD" (any part may be all 0s for unknown).
o organization: String[] (optional). The company or organization o organization: String[] (optional). The company or organization
name and units associated with this contact. The first entry in name and units associated with this contact. The first entry in
the list names the organization, and any following entries name the list names the organization, and any following entries name
organizational units. organizational units.
o jobTitle: String (optional). The job title or functional position o jobTitle[]: String (optional). The job title(s) or functional
of the contact. position(s) of the contact.
o role: String (optional). The role, function or part played in a o role[]: String (optional). The role(s), function(s) or part(s)
particular situation by the contact. In contrast to a job title, played in a particular situation by the contact. In contrast to a
the role might differ for example in project contexts. job title, the roles might differ for example in project contexts.
o emails: ContactInformation[] (optional). An array of o emails: ContactMethod[] (optional). An array of ContactMethod
ContactInformation objects where the values are email addresses. objects where the values are email addresses. Types are:
Types are:
* "personal" The address is for emailing the contact in a * "personal" The address is for emailing the contact in a
personal context. personal context.
* "work" The address is for emailing the contact in a * "work" The address is for emailing the contact in a
professional context. professional context.
* "other" The address is for some other purpose. A label * "other" The address is for some other purpose. A label
property MAY be included to display next to the address to help property MAY be included to display next to the address to help
the user identify its purpose. the user identify its purpose.
o phones: ContactInformation[] (optional). An array of o phones: ContactMethod[] (optional). An array of ContactMethod
ContactInformation objects where the values are phone numbers. objects where the values are phone numbers. Types are:
Types are:
* "voice" The number is for calling the contact. * "voice" The number is for calling the contact.
* "fax" The number is for sending faxes to the contact. * "fax" The number is for sending faxes to the contact.
* "pager" The number is for a pager or beeper associated with the * "pager" The number is for a pager or beeper associated with the
contact. contact.
* "other" The number is for some other purpose. A label property * "other" The number is for some other purpose. A label property
MAY be included to display next to the number to help the user MAY be included to display next to the number to help the user
identify its purpose. identify its purpose.
The following labels are pre-defined for phone contact The following labels are pre-defined for phone contact methods:
information:
* "private" The phone number should be used in a private context. * "private" The phone number should be used in a private context.
* "work" The phone number should be used in a professional * "work" The phone number should be used in a professional
context context
o online: ContactInformation[] (optional). An array of o online: ContactMethod[] (optional). An array of ContactMethod
ContactInformation objects where the values are URIs or usernames objects where the values are URIs or usernames associated with the
associated with the contact for online services. Types are: contact for online services. Types are:
* "uri" The value is a URI, e.g. a website link. * "uri" The value is a URI, e.g. a website link.
* "username" The value is a username associated with the contact * "username" The value is a username associated with the contact
(e.g. for social media, or an IM client). A label property (e.g. for social media, or an IM client). A label property
SHOULD be included to identify what service this is for. For SHOULD be included to identify what service this is for. For
compatibility between clients, this label SHOULD be the compatibility between clients, this label SHOULD be the
canonical service name, including capitalisation. e.g. canonical service name, including capitalisation. e.g.
"Twitter", "Facebook", "Skype", "GitHub", "XMPP". "Twitter", "Facebook", "Skype", "GitHub", "XMPP".
* "other" The value is something else not covered by the above * "other" The value is something else not covered by the above
categories. A label property MAY be included to display next categories. A label property MAY be included to display next
to the number to help the user identify its purpose. to the number to help the user identify its purpose.
o preferredContactMethod: String (optional) Defines the preferred o preferredContactMethod: String (optional) Defines the preferred
contact method. The value MUST be the property name of one of the contact method. The value MUST be the property name of one of the
ContactInformation lists: "emails", "phones", "online", "other". ContactMethod lists: "emails", "phones", "online", "other".
o addresses: Address[] (optional). An array of Address objects, o addresses: Address[] (optional). An array of Address objects,
containing physical locations associated with the contact. containing physical locations associated with the contact.
o personalInfo: PersonalInformation[] (optional). A list of
personal information about this contact. 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 of this contact
+ "interest": an interest of this contact
+ "other": an information not covered by the above categories
* value: String (mandatory). The actual contact information.
This generally is free-text, but future specifications MAY
restrict allowed values depending on the type of this
PersonalInformation.
* level: String (optional) Indicates the level of expertise, or
engagement in hobby or interest. Allowed values are: "high",
"medium" and "low".
o notes: String (optional). Arbitrary notes about the contact. o notes: String (optional). Arbitrary notes about the contact.
A ContactInformation object has the following properties: o categories: String[] (optional). A list of free-text or URI
categories that relate to the contact.
A ContactMethod object has the following properties:
o type: String (mandatory). Specifies the context of the contact o type: String (mandatory). Specifies the context of the contact
information. This MUST be taken from the set of values allowed method. This MUST be taken from the set of values allowed
depending on whether this is part of the phones, emails or online depending on whether this is part of the phones, emails or online
property (see above). property (see above).
o label: String (optional). A label describing the value in more o label: String (optional). A label describing the value in more
detail, especially if the type property has value "other" (but MAY detail, especially if the type property has value "other" (but MAY
be included with any type). be included with any type).
o value: String (mandatory). The actual contact information, e.g. o value: String (mandatory). The actual contact method, e.g. the
the email address or phone number. email address or phone number.
o isPreferred: Boolean (optional, default: "false"). Whether this o isPreferred: Boolean (optional, default: "false"). Whether this
ContactInformation is the preferred for its type. This SHOULD ContactMethod is the preferred for its type. This SHOULD only be
only be one per type. one per type.
An Address object has the following properties: An Address object has the following properties:
o type: String (mandatory). Specifies the context of the address o type: String (mandatory). Specifies the context of the address
information. The value MUST be either one of the following information. The value MUST be either one of the following
values, registered in a future RFC, or a vendor-specific value: values, registered in a future RFC, or a vendor-specific value:
* "home" An address of a residence associated with the contact. * "home" An address of a residence associated with the contact.
* "work" An address of a workplace associated with the contact. * "work" An address of a workplace associated with the contact.
skipping to change at page 6, line 51 skipping to change at page 8, line 12
o label: String (optional). A label describing the value in more o label: String (optional). A label describing the value in more
detail. detail.
o fullAddress: String (optional). The complete address, excluding o fullAddress: String (optional). The complete address, excluding
type and label. This property is mainly useful to represent type and label. This property is mainly useful to represent
addresses of which the individual address components are unknown. addresses of which the individual address components are unknown.
o street: String (optional). The street address. This MAY be o street: String (optional). The street address. This MAY be
multiple lines; newlines MUST be preserved. multiple lines; newlines MUST be preserved.
o extension: String (optional) The extended address, such as an
apartment or suite number, or care-of address.
o postOfficeBox: String (optional) The post office box.
o locality: String (optional). The city, town, village, post town, o locality: String (optional). The city, town, village, post town,
or other locality within which the street address may be found. or other locality within which the street address may be found.
o region: String (optional). The province, such as a state, county, o region: String (optional). The province, such as a state, county,
or canton within which the locality may be found. or canton within which the locality may be found.
o postcode: String (optional). The postal code, post code, ZIP code o postcode: String (optional). The postal code, post code, ZIP code
or other short code associated with the address by the relevant or other short code associated with the address by the relevant
country's postal system. country's postal system.
skipping to change at page 9, line 5 skipping to change at page 10, line 18
[RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC
2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174,
May 2017, <https://www.rfc-editor.org/info/rfc8174>. May 2017, <https://www.rfc-editor.org/info/rfc8174>.
[RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data [RFC8259] Bray, T., Ed., "The JavaScript Object Notation (JSON) Data
Interchange Format", STD 90, RFC 8259, Interchange Format", STD 90, RFC 8259,
DOI 10.17487/RFC8259, December 2017, DOI 10.17487/RFC8259, December 2017,
<https://www.rfc-editor.org/info/rfc8259>. <https://www.rfc-editor.org/info/rfc8259>.
6.2. URIs 6.2. Informative References
[RFC3339] Klyne, G. and C. Newman, "Date and Time on the Internet:
Timestamps", RFC 3339, DOI 10.17487/RFC3339, July 2002,
<https://www.rfc-editor.org/info/rfc3339>.
[RFC5646] Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying
Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646,
September 2009, <https://www.rfc-editor.org/info/rfc5646>.
[RFC6473] Saint-Andre, P., "vCard KIND:application", RFC 6473,
DOI 10.17487/RFC6473, December 2011,
<https://www.rfc-editor.org/info/rfc6473>.
[RFC6474] Li, K. and B. Leiba, "vCard Format Extensions: Place of
Birth, Place and Date of Death", RFC 6474,
DOI 10.17487/RFC6474, December 2011,
<https://www.rfc-editor.org/info/rfc6474>.
[RFC6715] Cauchie, D., Leiba, B., and K. Li, "vCard Format
Extensions: Representing vCard Extensions Defined by the
Open Mobile Alliance (OMA) Converged Address Book (CAB)
Group", RFC 6715, DOI 10.17487/RFC6715, August 2012,
<https://www.rfc-editor.org/info/rfc6715>.
[RFC6869] Salgueiro, G., Clarke, J., and P. Saint-Andre, "vCard
KIND:device", RFC 6869, DOI 10.17487/RFC6869, February
2013, <https://www.rfc-editor.org/info/rfc6869>.
[RFC8605] Hollenbeck, S. and R. Carney, "vCard Format Extensions:
ICANN Extensions for the Registration Data Access Protocol
(RDAP)", RFC 8605, DOI 10.17487/RFC8605, May 2019,
<https://www.rfc-editor.org/info/rfc8605>.
6.3. URIs
[1] https://www.iana.org/time-zones [1] https://www.iana.org/time-zones
Author's Address Authors' Addresses
Robert Stepanek Robert Stepanek
FastMail FastMail
PO Box 234, Collins St West PO Box 234, Collins St West
Melbourne VIC 8007 Melbourne VIC 8007
Australia Australia
Email: rsto@fastmailteam.com Email: rsto@fastmailteam.com
Mario Loffredo
IIT-CNR
Via Moruzzi,1
Pisa 56124
Italy
Email: mario.loffredo@iit.cnr.it
 End of changes. 30 change blocks. 
61 lines changed or deleted 158 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/