Portable Contacts 1.0 Draft C - Schema Only

Abstract

The Portable Contacts specification is designed to make it easier for developers to give their users a secure way to access the address books and friends lists they have built up all over the web. Specifically, it seeks to create a common access pattern and contact schema that any site can provide, well-specified authentication and access rules, standard libraries that can work with any site, and absolutely minimal complexity, with the lightest possible toolchain requirements for developers.

By far the easiest way to start understanding this spec is to jump to the example in the Appendix. The format and meaning of the response should be readily apparent, and the majority of this document is merely an attempt to formalize the details of what should be relatively clear from this example.

NOTE: This document specifies only the schema for an individual Contact as represented in Portable Contacts. It is indended for use with other projects that need to reference a standard Contact schema, but do not intend to provide the full discovery, authentication, and access protocol that the full Portable Contacts spec provides. This document is intended to remain a strict subset of the full Portable Contacts spec, and should never deviate in the details of the Contact schema. For convenience, this spec also defines a namespace and mime-type for use with Portable Contacts schema data.

Table of Contents

1.  Notation and Conventions
2.  Definitions
3.  XML Namespace
4.  MIME Media Types
5.  Contact Schema
    5.1.  Structure
    5.2.  entry Element
        5.2.1.  Singular Fields
        5.2.2.  Plural Fields
    5.3.  name Element
    5.4.  address Element
    5.5.  organization Element
    5.6.  account Element
Appendix A.  Example
Appendix B.  Compatibility with OpenSocial
6.  References
§  Author's Address

1.  Notation and Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119] (Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” .). Domain name examples use [RFC2606] (Eastlake, D. and A. Panitz, “Reserved Top Level DNS Names,” .).

2.  Definitions

Portable Contacts:

The complete [PortableContacts] (Smarr, J., “Portable Contacts 1.0,” .) specification.

Contact:

A record describing information about a particular person or entity, consisting of contact information (e.g. name, e-mail addresses, phone numbers) and other descriptive information, as is typically found in address book and social networking applications.

Singular Field:

A contact field that can appear at most once per contact, e.g. displayName or gender.

Plural Field:

A contact field that can appear multiple times per contact, e.g. emails or tags.

Simple Field

A Singular Field or Plural Field whose value is a single string attribute (see Section 5.1 (Structure)).

Complex Field

A Singular Field or Plural Field whose value is an object containing multiple sub-field attributes (see Section 5.1 (Structure)).

Canonical Value:

Specified string values for string-valued contact fields that represent common values in a canonical form, e.g. "male" and "female" for gender. Service Providers SHOULD conform to Canonical Values if appropriate, but MAY deviate if they need to represent additional values.

Primary Sub-Value:

The sub-field in a Complex Field that should be used when sorting or filtering by that field. Unless otherwise specified, the value sub-field is always the Primary Sub-Field.

3.  XML Namespace

If a contact is being represented in XML using the Portable Contacts schema, and a developer wishes to embed this contact within a larger XML document, the following XML Namespace URI SHOULD be used: http://portablecontacts.net/ns/1.0.

4.  MIME Media Types

If a server is providing contact data as a document available at a URL, one of the following MIME types SHOULD be returned as the value of the Content-type HTTP response header: application/poco+json if the contact is encoded as JSON, or application/poco+xml if the contact is encoded as XML.

5.  Contact Schema

The Contact schema defines the containers and attributes used to deliver an individual Contact or a list of Contacts as requested by the Consumer. The traditional contact info fields were taken directly from the vCard spec where possible [RFC2425] (Howes, T., “A MIME Content-Type for Directory Information,” .), though instances of vCard's archaic spellings were modernized (e.g. addresses instead of adr). Even with the spelling updates, the field mappings remain equivalent, which means it should be easy to convert Portable Contacts data to and from vCard. By convention, Singular Fields have singular spelling (e.g. displayName) and plural fields have plural spelling (e.g. phoneNumbers) to make it easy to distinguish them.

Each contact returned MUST include the id and displayName fields with non-empty values, but all other fields are optional, and it is recognized that not all Service Providers will be able to provide data for all the supported fields. The field list below is broad so that, for Service Providers that do support any of these fields, there is a standard field name available.

5.1.  Structure

Each field is defined as either a Singular Field, in which case there MUST NOT be more than one instance of that field per contact, or as a Plural Field, in which case any number of instances of that field MAY be present per contact.

Contact information is formatted using labeled attributes with either structured or unstructured string data. Each attribute value consists of one of the following types:

Simple:

A single string attribute which MAY specify a REQUIRED data format or allow any string. A simple field MAY contain Canonical Values specified, in which case Service Providers SHOULD try to conform to those values if appropriate, but MAY provide alternate string values to represent additional values.

Boolean:

A special case of a Simple Field with two legal values: true and false. Values are case-sensitive.

Complex:

A multi-value attribute containing any combination of other attributes. Complex attributes are defined by listing the child attributes and their types. For most Complex Fields, the value sub-field contains the Major Value of that field (i.e. the primary piece of contact information described by that field), and the other fields provide additional meta-data.

5.2.  entry Element

Unless otherwise specified, all fields are optional and of type xs:string. Also, unless specified, all field values MUST NOT contain any newline characters (\r or \n).

5.2.1.  Singular Fields

id:

Unique identifier for the Contact. Each Contact returned MUST include a non-empty id value. This identifier MUST be unique across this user's entire set of Contacts, but MAY not be unique across multiple users' data. It MUST be a stable ID that does not change when the same contact is returned in subsequent requests. For instance, an e-mail address is not a good id, because the same person may use a different e-mail address in the future. Usually, in internal database ID will be the right choice here, e.g. "12345".

displayName:

The name of this Contact, suitable for display to end-users. Each Contact returned MUST include a non-empty displayName value. The name SHOULD be the full name of the Contact being described if known (e.g. Joseph Smarr or Mr. Joseph Robert Smarr, Esq.), but MAY be a username or handle, if that is all that is available (e.g. jsmarr). The value provided SHOULD be the primary textual label by which this Contact is normally displayed by the Service Provider when presenting it to end-users.

name:

The broken-out components and fully formatted version of the contact's real name, as described in Section 5.3 (name Element).

nickname:

The casual way to address this Contact in real life, e.g. "Bob" or "Bobby" instead of "Robert". This field SHOULD NOT be used to represent a user's username (e.g. jsmarr or daveman692); the latter should be represented by the preferredUsername field.

published:

The date this Contact was first added to the user's address book or friends list (i.e. the creation date of this entry). The value MUST be a valid xs:dateTime (e.g. 2008-01-23T04:56:22Z).

updated:

The most recent date the details of this Contact were updated (i.e. the modified date of this entry). The value MUST be a valid xd:dateTime (e.g. 2008-01-23T04:56:22Z). If this Contact has never been modified since its initial creation, the value MUST be the same as the value of published.

birthday:

The birthday of this contact. The value MUST be a valid xs:date (e.g. 1975-02-14. The year value MAY be set to 0000 when the age of the Contact is private or the year is not available.

anniversary:

The wedding anniversary of this contact. The value MUST be a valid xs:date (e.g. 1975-02-14. The year value MAY be set to 0000 when the year is not available.

gender:

The gender of this contact. Service Providers SHOULD return one of the following Canonical Values, if appropriate: male, female, or undisclosed, and MAY return a different value if it is not covered by one of these Canonical Values.

note:

Notes about this contact, with an unspecified meaning or usage (normally contact notes by the user about this contact). This field MAY contain newlines.

preferredUsername:

The preferred username of this contact on sites that ask for a username (e.g. jsmarr or daveman692). This field may be more useful for describing the owner (i.e. the value when /@me/@self is requested) than the user's contacts, e.g. Consumers MAY wish to use this value to pre-populate a username for this user when signing up for a new service.

utcOffset:

The offset from UTC of this Contact's current time zone, as of the time this response was returned. The value MUST conform to the offset portion of xs:dateTime, e.g. -08:00. Note that this value MAY change over time due to daylight saving time, and is thus meant to signify only the current value of the user's timezone offset.

connected:

Boolean value indicating whether the user and this Contact have established a bi-directionally asserted connection of some kind on the Service Provider's service. The value MUST be either true or false. The value MUST be true if and only if there is at least one value for the relationship field, described below, and is thus intended as a summary value indicating that some type of bi-directional relationship exists, for Consumers that aren't interested in the specific nature of that relationship. For traditional address books, in which a user stores information about other contacts without their explicit acknowledgment, or for services in which users choose to "follow" other users without requiring mutual consent, this value will always be false.

The following additional Singular Fields are defined, based on their specification in OpenSocial [OpenSocial] (Panzer, J., “OpenSocial 0.8.1 RESTful Protocol Specification,” .): aboutMe, bodyType, currentLocation, drinker, ethnicity, fashion, happiestWhen, humor, livingArrangement, lookingFor, profileSong, profileVideo, relationshipStatus, religion, romance, scaredOf, sexualOrientation, smoker, and status.

5.2.2.  Plural Fields

Unless specified otherwise, all Plural Fields have the same three standard sub-fields:

value:

The primary value of this field, e.g. the actual e-mail address, phone number, or URL. When specifying a sortBy field in the Query Parameters for a Plural Field, the default meaning is to sort based on this value sub-field. Each non-empty Plural Field value MUST contain at least the value sub-field, but all other sub-fields are optional.

type:

The type of field for this instance, usually used to label the preferred function of the given contact information. Unless otherwise specified, this string value specifies Canonical Values of work, home, and other.

primary:

A Boolean value indicating whether this instance of the Plural Field is the primary or preferred value of for this field, e.g. the preferred mailing address or primary e-mail address. Service Providers MUST NOT mark more than one instance of the same Plural Field as primary="true", and MAY choose not to mark any fields as primary, if this information is not available. For efficiency, Service Providers SHOULD NOT mark all non-primary fields with primary="false", but should instead omit this sub-field for all non-primary instances.

When returning Plural Fields, Service Providers SHOULD canonicalize the value returned, if appropriate (e.g. for e-mail addresses and URLs). Providers MAY return the same value more than once with different types (e.g. the same e-mail address may used for work and home), but SHOULD NOT return the same (type, value) combination more than once per Plural Field, as this complicates processing by the Consumer.

emails:

E-mail address for this Contact. The value SHOULD be canonicalized by the Service Provider, e.g. joseph@plaxo.com instead of joseph@PLAXO.COM.

urls:

URL of a web page relating to this Contact. The value SHOULD be canonicalized by the Service Provider, e.g. http://josephsmarr.com/about/ instead of JOSEPHSMARR.COM/about/. In addition to the standard Canonical Values for type, this field also defines the additional Canonical Values blog and profile.

phoneNumbers:

Phone number for this Contact. No canonical value is assumed here. In addition to the standard Canonical Values for type, this field also defines the additional Canonical Values mobile, fax, and pager.

ims:

Instant messaging address for this Contact. No official canonicalization rules exist for all instant messaging addresses, but Service Providers SHOULD remove all whitespace and convert the address to lowercase, if this is appropriate for the service this IM address is used for. Instead of the standard Canonical Values for type, this field defines the following Canonical Values to represent currently popular IM services: aim, gtalk, icq, xmpp, msn, skype, qq, and yahoo.

photos:

URL of a photo of this contact. The value SHOULD be a canonicalized URL, and MUST point to an actual image file (e.g. a GIF, JPEG, or PNG image file) rather than to a web page containing an image. Service Providers MAY return the same image at different sizes, though it is recognized that no standard for describing images of various sizes currently exists. Note that this field SHOULD NOT be used to send down arbitrary photos taken by this user, but specifically profile photos of the contact suitable for display when describing the contact.

tags:

A user-defined category or label for this contact, e.g. "favorite" or "web20". These values SHOULD be case-insensitive, and there SHOULD NOT be multiple tags provided for a given contact that differ only in case. Note that this field is a Simple Field, meaning each instance consists only of a string value.

relationships:

A bi-directionally asserted relationship type that was established between the user and this contact by the Service Provider. The value SHOULD conform to one of the XFN relationship values (e.g. kin, friend, contact, etc.) if appropriate, but MAY be an alternative value if needed. Note this field is a parallel set of category labels to the tags field, but relationships MUST have been bi-directionally confirmed, whereas tags are asserted by the user without acknowledgment by this Contact. Note that this field is a Simple Field, meaning each instance consists only of a string value.

addresses:

A physical mailing address for this Contact, as described in Section 5.4 (address Element).

organizations:

A current or past organizational affiliation of this Contact, as described in Section 5.5 (organization Element).

accounts:

An online account held by this Contact, as described in Section 5.6 (account Element).

The following additional Plural Fields are defined, based on their specification in OpenSocial: activities, books, cars, children, food, heroes, interests, jobInterests, languages, languagesSpoken, movies, music, pets, politicalViews, quotes, sports, turnOffs, turnOns, and tvShows.

5.3.  name Element

The components of the contact's real name. Providers MAY return just the full name as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same name, with the formatted name indicating how the component fields should be combined.

formatted:

The full name, including all middle names, titles, and suffixes as appropriate, formatted for display (e.g. Mr. Joseph Robert Smarr, Esq.). This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

familyName:

The family name of this Contact, or "Last Name" in most Western languages (e.g. Smarr given the full name Mr. Joseph Robert Smarr, Esq.).

givenName:

The given name of this Contact, or "First Name" in most Western languages (e.g. Joseph given the full name Mr. Joseph Robert Smarr, Esq.).

middleName:

The middle name(s) of this Contact (e.g. Robert given the full name Mr. Joseph Robert Smarr, Esq.).

honorificPrefix:

The honorific prefix(es) of this Contact, or "Title" in most Western languages (e.g. Mr. given the full name Mr. Joseph Robert Smarr, Esq.).

honorificSuffix:

The honorifix suffix(es) of this Contact, or "Suffix" in most Western languages (e.g. Esq. given the full name Mr. Joseph Robert Smarr, Esq.).

5.4.  address Element

The components of a physical mailing address. Service Providers MAY return just the full address as a single string in the formatted sub-field, or they MAY return just the individual component fields using the other sub-fields, or they MAY return both. If both variants are returned, they SHOULD be describing the same address, with the formatted address indicating how the component fields should be combined.

formatted:

The full mailing address, formatted for display or use with a mailing label. This field MAY contain newlines. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

streetAddress:

The full street address component, which may include house number, street name, PO BOX, and multi-line extended street address information. This field MAY contain newlines.

locality:

The city or locality component.

region:

The state or region component.

postalCode:

The zipcode or postal code component.

country:

The country name component.

5.5.  organization Element

Describes a current or past organizational affiliation of this contact. Service Providers that support only a single Company Name and Job Title field should represent them with a single organization element with name and title properties, respectively.

name:

The name of the organization (e.g. company, school, or other organization). This field MUST have a non-empty value for each organization returned. This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

department:

The department within this organization.

title:

The job title or role within this organization.

type:

The type of organization, with Canonical Values job and school.

startDate:

The date this Contact joined this organization. This value SHOULD be a valid xs:date if possible, but MAY be an unformatted string, since it is recognized that this field is often presented as free-text.

endDate:

The date this Contact left this organization or the role specified by title within this organization. This value SHOULD be a valid xs:date if possible, but MAY be an unformatted string, since it is recognized that this field is often presented as free-text.

location:

The physical location of this organization. This may be a complete address, or an abbreviated location like "San Francisco".

description:

A textual description of the role this Contact played in this organization. This field MAY contain newlines.

5.6.  account Element

Describes an account held by this Contact, which MAY be on the Service Provider's service, or MAY be on a different service. Consumers SHOULD NOT assume that this account has been verified by the Service Provider to actually belong to this Contact. For each account, the domain is the top-most authoritative domain for this account, e.g. yahoo.com or reader.google.com, and MUST be non-empty. Each account must also contain a non-empty value for either username or userid, and MAY contain both, in which case the two values MUST be for the same account. These accounts can be used to determine if a user on one service is also known to be the same person on a different service, to facilitate connecting to people the user already knows on different services. If Consumers want to turn these accounts into profile URLs, they can use an open-source library like [google‑sgnodemapper] (Fitzpatrick, B., “Social Graph Node Mapper,” .).

domain:

The top-most authoritative domain for this account, e.g. "twitter.com". This is the Primary Sub-Field for this field, for the purposes of sorting and filtering.

username:

An alphanumeric user name, usually chosen by the user, e.g. "jsmarr".

userid:

A user ID number, usually chosen automatically, and usually numeric but sometimes alphanumeric, e.g. "12345" or "1Z425A".

Appendix A.  Example

Here is a sample contact that illustrates much of of the Portable Contacts schema.

Sample contact (JSON):

"entry": {
  "id": "703887",
  "displayName": "Mork Hashimoto",
  "name": {
    "familyName": "Hashimoto",
    "givenName": "Mork"
  },
  "birthday": "0000-01-16",
  "gender": "male",
  "drinker": "heavily",
  "tags": [
    "plaxo guy",
    "favorite"
  ],
  "emails": [
    {
      "value": "mhashimoto-04@plaxo.com",
      "type": "work",
      "primary": "true"
    },
    {
      "value": "mhashimoto-04@plaxo.com",
      "type": "home"
    },
    {
      "value": "mhashimoto@plaxo.com",
      "type": "home"
    }
  ],
  "urls": [
    {
      "value": "http://www.seeyellow.com",
      "type": "work"
    },
    {
      "value": "http://www.angryalien.com",
      "type": "home"
    }
  ],
  "phoneNumbers": [
    {
      "value": "KLONDIKE5",
      "type": "work"
    },
    {
      "value": "650-123-4567",
      "type": "mobile"
    }
  ],
  "photos": [
    {
      "value": "http://sample.site.org/photos/12345.jpg",
      "type": "thumbnail"
    }
  ],
  "ims": [
    {
      "value": "plaxodev8",
      "type": "aim"
    }
  ],
  "addresses": [
    {
      "type": "home",
      "streetAddress": "742 Evergreen Terrace\nSuite 123",
      "locality": "Springfield",
      "region": "VT",
      "postalCode": "12345",
      "country": "USA",
      "formatted": "742 Evergreen Terrace\nSuite 123\nSpringfield, VT 12345 USA"
    }
  ],
  "organizations": [
    {
      "name": "Burns Worldwide",
      "title": "Head Bee Guy"
    }
  ],
  "accounts": [
    {
      "domain": "plaxo.com",
      "userid": "2706"
    }
  ]
}

Sample contact (XML):

<entry>

 <id>703887</id>
 <displayName>Mork Hashimoto</displayName>
 <name>

  <familyName>Hashimoto</familyName>

  <givenName>Mork</givenName>
 </name>
 <birthday>0000-01-16</birthday>

 <gender>male</gender>

 <drinker>heavily</drinker>
 <tags>plaxo guy</tags>
 <tags>favorite</tags>

 <emails>

  <value>mhashimoto-04@plaxo.com</value>
  <type>work</type>
  <primary>true</primary>

 </emails>

 <emails>
  <value>mhashimoto-04@plaxo.com</value>
  <type>home</type>

 </emails>
 <emails>

  <value>mhashimoto@plaxo.com</value>
  <type>home</type>

 </emails>
 <urls>
  <value>http://www.seeyellow.com</value>

  <type>work</type>

 </urls>
 <urls>
  <value>http://www.angryalien.com</value>
  <type>home</type>

 </urls>
 <phoneNumbers>
  <value>KLONDIKE5</value>
  <type>work</type>
 </phoneNumbers>

 <phoneNumbers>
  <value>650-123-4567</value>
  <type>mobile</type>
 </phoneNumbers>

 <photos>

  <value>http://sample.site.org/photos/12345.jpg</value>
  <type>thumbnail</type>
 </photos>

 <ims>
  <value>plaxodev8</value>

  <type>aim</type>
 </ims>

 <addresses>
  <type>home</type>
  <streetAddress><![CDATA[742 Evergreen Terrace
Suite 123]]></streetAddress>

  <locality>Springfield</locality>

  <region>VT</region>
  <postalCode>12345</postalCode>
  <country>USA</country>

  <formatted><![CDATA[742 Evergreen Terrace
Suite 123
Springfield, VT 12345 USA]]></formatted>

 </addresses>
 <organizations>
  <name>Burns Worldwide</name>
  <title>Head Bee Guy</title>

 </organizations>
 <accounts>
  <domain>plaxo.com</domain>
  <userid>2706</userid>
 </accounts>

</entry>

Appendix B.  Compatibility with OpenSocial

This version of the Portable Contacts specification is currently wire-compatible with the overlapping portion of the OpenSocial RESTful Protocol version 0.8.1 [OpenSocial] (Panzer, J., “OpenSocial 0.8.1 RESTful Protocol Specification,” .). Specifically, any compliant OpenSocial RESTful Protocol 0.8.1 Provider is also a compliant Portable Contacts Provider, because they are specified to use the same Authorization methods (OAuth), Additional Path Information, Query Parameters, and Contact Schema. The OpenSocial and Portable Contacts communities chose to wire-align our respective specs in order to maximize widespread adoption of a single API for accessing people data.

It is our intention to maintain this compatibility going forward, so long as it is feasible, and so long as the changes required are compatible with the Goals and Approach of this spec. Although Portable Contacts is an independent spec, with a more limited scope than OpenSocial, any proposed changes to either this Portable Contacts spec or the OpenSocial RESTful Protocol should be considered in the context of both communities, and we should strive not to break compatibility unless it is truly necessary, e.g. if the goals of the two communities diverge significantly in the future.

6. References

Author's Address