Network Working Group J. Smarr Internet-Draft Plaxo Intended status: Informational December 2, 2008 Expires: June 5, 2009 Portable Contacts: A Common Format and Protocol for Accessing Contacts draft-smarr-vcarddav-portable-contacts-00 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on June 5, 2009. Abstract This document specifies Portable Contacts, XML and JSON address book document formats and an interface for accessing address book and friends-list information over HTTP. Smarr Expires June 5, 2009 [Page 1] Internet-Draft Portable Contacts 1.0 December 2008 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Goals . . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.2. Approach . . . . . . . . . . . . . . . . . . . . . . . . . 4 1.3. Feedback . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Notational Conventions . . . . . . . . . . . . . . . . . . . . 5 3. Definitions . . . . . . . . . . . . . . . . . . . . . . . . . 5 4. Workflow Overview . . . . . . . . . . . . . . . . . . . . . . 6 5. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 6 6. Invocation . . . . . . . . . . . . . . . . . . . . . . . . . . 7 6.1. Authentication and Authorization . . . . . . . . . . . . . 7 6.1.1. Delegated Authorization . . . . . . . . . . . . . . . 8 6.1.2. Direct Authorization . . . . . . . . . . . . . . . . . 8 6.1.3. Available Authorization Methods . . . . . . . . . . . 8 6.2. Additional Path Information . . . . . . . . . . . . . . . 9 6.3. Query Parameters . . . . . . . . . . . . . . . . . . . . . 9 6.3.1. Filtering . . . . . . . . . . . . . . . . . . . . . . 10 6.3.2. Sorting . . . . . . . . . . . . . . . . . . . . . . . 12 6.3.3. Pagination . . . . . . . . . . . . . . . . . . . . . . 12 6.3.4. Presentation . . . . . . . . . . . . . . . . . . . . . 13 6.3.5. Declining to honor query parameters . . . . . . . . . 14 6.4. Response Format . . . . . . . . . . . . . . . . . . . . . 14 6.5. Error Codes . . . . . . . . . . . . . . . . . . . . . . . 15 7. Contact Schema . . . . . . . . . . . . . . . . . . . . . . . . 16 7.1. Structure . . . . . . . . . . . . . . . . . . . . . . . . 17 7.2. entry Element . . . . . . . . . . . . . . . . . . . . . . 17 7.2.1. Singular Fields . . . . . . . . . . . . . . . . . . . 17 7.2.2. Plural Fields . . . . . . . . . . . . . . . . . . . . 19 7.3. name Element . . . . . . . . . . . . . . . . . . . . . . . 22 7.4. address Element . . . . . . . . . . . . . . . . . . . . . 22 7.5. organization Element . . . . . . . . . . . . . . . . . . . 23 7.6. account Element . . . . . . . . . . . . . . . . . . . . . 24 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 24 9. Security Considerations . . . . . . . . . . . . . . . . . . . 24 Appendix A. Example . . . . . . . . . . . . . . . . . . . . . . . 24 Appendix B. Compatibility with OpenSocial . . . . . . . . . . . . 29 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 10.1. Normative References . . . . . . . . . . . . . . . . . . . 29 10.2. Informative References . . . . . . . . . . . . . . . . . . 29 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 30 Intellectual Property and Copyright Statements . . . . . . . . . . 31 Smarr Expires June 5, 2009 [Page 2] Internet-Draft Portable Contacts 1.0 December 2008 1. Introduction 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. This API defines a language- and platform- neutral protocol for Consumers to request address book, profile, and friends-list information from Service Providers. As a protocol, it is intended to be easy to understand and implement, either as a Service Provider or Consumer, using any language or platform of choice. It is also intended to be implemented by both individuals and small services as well as large providers, in any case where a service contains data about who a user knows and wishes to make that information portable, under the user's control. While there are currently standards for describing contact info (such as vCard), these standards do not specify how to discover, access, and manipulate this information, and they do not capture the full range of information typically found in modern address book and social networking applications. Several large companies have also released their own non-standard APIs for accessing and interacting with contact information, increasing the burden on developers and Consumers who wish to support most or all Service Providers. Nor do these APIs inform other providers as to how they should construct similar APIs. Thus Portable Contacts is an attempt to specify a complete, modern, and straight-forward recipe for Service Providers and Consumers of all sizes to make available and consume contact data in a standardized way. 1.1. Goals The goal of Portable Contacts is 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, we seek to create: Smarr Expires June 5, 2009 [Page 3] Internet-Draft Portable Contacts 1.0 December 2008 o A common access pattern and contact schema that any Service Provider can implement o Well-specified authorization and access rules o Free and open source libraries in many languages for most popular platforms o Community-sourced support, documentation, and collaborative tools o and absolutely minimal complexity, with the lightest possible toolchain requirements for developers. A measure of our success will be the elimination of the "password anti-pattern," by making it far easier to implement Portable Contacts than to engage in scraping, as well as a dramatic increase in the number of sites that both provide and consume who-you-know data. 1.2. Approach Our design is focused around ease of adoption, which means a few things: 1. First, our emphasis is on simplicity of design and targeted use cases, keeping our scope intentionally narrow at the outset. For example, version 1 is simply about access, and defers for now on the more complex issues around update and sync. 2. Second, we're taking a modern approach to who-you-know data by unifying traditional contact information and social network data, in order to properly represent the current diversity of the social web ecosystem. 3. Third, we're reusing existing standards wherever possible, including vCard, OpenSocial, XRDS-Simple, OAuth, etc. 4. And lastly, we're designing something that should be easy for current service providers to adopt. We started with a review of all the major existing contacts APIs and targeted common capabilities that they all share and provide. We believe this pragmatic balance is the best and quickest way to achieve our intended goal of widespread adoption. 1.3. Feedback The Portable Contact specification is currently being developed on the http://groups.google.com/group/portablecontacts mailing list, with additional feedback coming from the OpenSocial community. Smarr Expires June 5, 2009 [Page 4] Internet-Draft Portable Contacts 1.0 December 2008 Feedback can be posted to the Portable Contacts list or directly to the author. If you encounter any problems with joining the list, please contact the author. 2. Notational 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]. 3. Definitions 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. Service Provider: A web application that provides Contact information via the Portable Contacts protocol. Consumer: A website or application that uses the Portable Contacts protocol to request contacts managed by the Service Provider. Base URL: The root endpoint URL specified by the Service Provider during Discovery and used to make requests. Consumers MAY append additional path information and query string parameters to this URL as part of the request. 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 7.1). Complex Field A Singular Field or Plural Field whose value is an object containing multiple sub-field attributes (see Section 7.1). 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. Smarr Expires June 5, 2009 [Page 5] Internet-Draft Portable Contacts 1.0 December 2008 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. 4. Workflow Overview A Consumer wishing to access a user's data via Portable Contacts must start with an Initial Identifier for the Service Provider containing the user's data, usually provided by the user. In many cases, this may be the domain name of the Service Provider's web site, such as sample.site.org, but may be a more specific URL, such as the OpenID identifier of the user, if available. Consumers then perform Discovery on the Initial Identifier to determine where the Portable Contacts endpoint for this Service Provider resides. If successful, the Consumer may then attempt to request information from that endpoint. If the endpoint contains private data, the Service Provider will return an authorization challenge, and the Consumer must then guide the user through an appropriate authorization flow to obtain the credentials necessary to access this private data. Upon successful authorization, the Consumer may request data from the Portable Contacts endpoint using these authorization credentials. Whether accessing public or private data, Consumers may request a specific subset of the user's data using standard Query Parameters. Upon a successful request, the data is returned in the response, and the Consumer may then parse the response data and use it as desired. The following sections detail each of these steps. 5. Discovery Portable Contacts API endpoint is discoverable from the domain root using [XRDS-Simple] (previously known as YADIS). The API is identified by the Service Type http://portablecontacts.net/spec/1.0 and the corresponding URI is the Base URL for the API. The Base URL MUST NOT contain any query string, as additional path information and query string variables MAY be appended by Consumers as part of forming the request (as described in detail below). An example XRDS-Simple document describing the availability and location of a Portable Contacts endpoint might look like this: Smarr Expires June 5, 2009 [Page 6] Internet-Draft Portable Contacts 1.0 December 2008 xri://$xrds*simple http://portablecontacts.net/spec/1.0 http://sample.site.org/path/to/api/ In addition to discovering the endpoint itself, Service Providers using OAuth to protect responses MUST also support OAuth Discovery, as described in Section 6.1. 6. Invocation All requests to the Service Provider are made as HTTP GET operations on a URL deriving from the Base URL specified in Section 5. Consumers MAY append additional path information and/or query string parameters to the Base URL as part of the request, as specified in Section 6.3. Additionally, authentication information MAY be sent via POST data or additional HTTP headers in the request, as specified in Section 6.1. Responses are returned in the body of the HTTP response, formatted as JSON or XML, depending on what is requested. Response and error codes SHOULD be transmitted via the HTTP status code of the response (if possible), and SHOULD also be specified in the body of the response, as described in Section 6.4 and Section 6.5. Since the API endpoint is dynamic (and not serving static content), Consumers MUST NOT interpret any cache headers in the response as having meaning concerning when the same URL request might return a different response upon subsequent invocation. 6.1. Authentication and Authorization The data returned by a Portable Contacts endpoint MAY contain public data, or it MAY contain private data. If the data returned is public, no authentication or authorization is required. In most cases however, the data returned is not public, and Service Providers SHOULD ensure that the user has given prior consent, either explicitly or implicitly, for their information to be released by this API. Typically this is done by Consumers obtaining either Direct Authorization (with raw credentials, for example the user's username and password) or Delegated Authorization (with an access token obtained out-of-band by the user, and given to the Consumer to present as part of the request). Portable Contacts specifies standard mechanisms for both types of authorization, so that Smarr Expires June 5, 2009 [Page 7] Internet-Draft Portable Contacts 1.0 December 2008 Consumers may be able to obtain private data on a user's behalf from Service Providers in an automated and consistent fashion. Regardless of the Authorization method used, the context of the request (i.e. the user for whom data is being requested) MUST be inferred by Service Providers from the Base URL and the authorization credentials provided. If public data is being accessed (and no authorization is provided), the Base URL MUST contain enough information for Service Providers to know which data to return, but if private data is being accessed (and authorization is provided), the same Base URL MAY return information for different users depending on the authorization credentials provided. 6.1.1. Delegated Authorization Service Providers wishing to provide Delegated Authorization MUST support [OAuth Core 1.0] as an OAuth Service Provider, and MAY also support additional Delegated Authorization mechanisms, if they choose. Service Providers supporting OAuth MUST also support [OAuth Discovery] to facilitate automatic discovery of authorization endpoints for Consumers. Service Providers SHOULD provide a mechanism for Consumers to automatically obtain a Consumer Key and Consumer Secret, but MAY require this to be done out-of-band. 6.1.2. Direct Authorization Service Providers wishing to provide Direct Authorization MUST support HTTP Basic Access Authentication [RFC2617], and MAY also support additional Direct Authorization mechanisms, if they choose. In addition to being a well-established mechanism for Direct Authorization, HTTP Basic has the added benefit of being understood by most Web Browsers, and can prompt users to enter their credentials as part of accessing a resource protected in this manner. There are also convenient ways of providing and parsing HTTP Basic credentials in popular tools and libraries like curl and PHP. 6.1.3. Available Authorization Methods Service Providers that provide access to private data MAY choose not to support either Direct Authorization or Delegated Authorization, depending on their security requirements, but they MUST support either OAuth or HTTP Basic auth if they require any Authorization. When accessing a Portable Contacts endpoint, if sufficient authorization credentials are not provided, the Service Provider SHOULD return a 401 Unauthorized response, and SHOULD provide the available Authorization mechanisms available by including WWW- Authenticate headers in the response for each type of Authorization method supported (as defined in [RFC2616], section 14.47. Consumers will then be able to recognize that the API is a protected resource Smarr Expires June 5, 2009 [Page 8] Internet-Draft Portable Contacts 1.0 December 2008 and initiate the proper Authorization process needed to obtain the appropriate credentials. An example set of WWW-Authenticate headers returned by a Service Provider that supports both OAuth and HTTP Basic might look like this. Note that the realm value is intended to be an opaque string that merely defines a shared label for resources that share the same authorization requirements. WWW-Authenticate: OAuth realm="sample.site.org" WWW-Authenticate: Basic realm="sample.site.org" If Service Providers wish to make some response data publicly available and also provide additional info given the proper authorization credentials, they SHOULD provide a 200 OK response to requests without authorization with a WWW-Authenticate header in the response indicating that additional info is available via the specified authorization mechanisms. 6.2. Additional Path Information A request using the Base URL alone MUST yield a result, assuming that adequate authorization credentials are provided. In addition, Consumers MAY append additional path information to the Base URL to request more specific information. Service Providers MUST recognize the following additional path information when appended to the Base URL, and MUST return the corresponding data: o "/@me/@all" -- Return all contact info (equivalent to providing no additional path info) o "/@me/@all/{id}" -- Only return contact info for the contact whose "id" value is equal to the provided "{id}", if such a contact exists. In this case, the response format is the same as when requesting all contacts, but any contacts not matching the requested ID MUST be filtered out of the result list by the Service Provider o "/@me/@self" -- Return contact info for the owner of this information, i.e. the user on whose behalf this request is being made. In this case, the response format is the same as when requesting all contacts, but any contacts not matching the requested ID MUST be filtered out of the result list by the Service Provider. 6.3. Query Parameters Portable Contacts defines a standard set of operations that can be used to filter, sort, and paginate response results. The operations are specified by adding query parameter to the Base URL, either in Smarr Expires June 5, 2009 [Page 9] Internet-Draft Portable Contacts 1.0 December 2008 the query string or as HTTP POST data. Providers MAY support additional query parameters not specified here, and Providers SHOULD ignore any query parameters they don't recognize. 6.3.1. Filtering Filtering is used to limit the request results to Contacts that match given criteria. Content filtering is accomplished by combining three request parameters: filterBy: Specifies the field name to filter by. If the specified field is a Plural Field, the Contact SHALL match if any of the instances of the given field match the specified criterion (e.g. if a contact has multiple "emails" values, only one has to match for the entire Contact to match). If a Simple Field is specified, its value must match the specified "filterValue" according to the specified "filterOp". If a Complex Field is specified, its Primary Sub-Field must match. If the specified field is not a direct child of the "entry" element, the full path MUST be specified using the '.' character as separator. For example, to filter by gender the parameter value is "gender" and to filter by first name, the parameter value is "name.givenName". filterOp: Specifies the comparison method used to evaluate the field value with the value of the filter criterion. Providers SHOULD support the following values: * "equals": the two values must be identical strings. * "contains": the entire "filterValue" must be a substring of the Contact field value. * "startswith": the entire "filterValue" must be a substring of the Contact field value, starting at the beginning of the field value. This criterion is satisfied if the two strings are equal. * "present": a Contact matches the criterion if the field specified by "filterBy" has a non-empty value, or if it contains a non-empty node for complex fields. Providers MAY support additional filter operations if they choose. Providers MUST decline to filter results if the specified filter operation is not recognized (as per Section 6.3.5). Smarr Expires June 5, 2009 [Page 10] Internet-Draft Portable Contacts 1.0 December 2008 filterValue: Specifies the value to filter by, using the comparison method defined by "filterOp". In addition, requests can filter content based on their "update" timestamp: updatedSince: Returns only contacts that have been modified on or after the given time, specified as an xs:dateTime. The filter is based on the value of the "updated" field, and can be used independently of other filters or combined. It enables a basic syndication pattern when accessing the same data over time. The first API call returns all data, which can be stored locally. Subsequent API calls can specify "updatedSince" with the time of the last API call, so that only contacts that have been added or modified since the last API call will be returned. Here are a few illustrative examples of filtering matches with "filterBy", "filterOp", and "filterValue". In each case, assume the following two contacts would be returned if no filtering parameters were provided: { "id": "1", "displayName": "Chris Messina", "urls": [ { "value": "http://factoryjoe.com/blog", "type": "blog" } ] }, { "id": "2", "displayName": "Joseph Smarr", "emails": [ { "value": "joseph@plaxo.com", "type": "work", "primary": "true" }, { "value": "jsmarr@gmail.com", "type": "home" } ], } Given the parameters "filterBy=displayName&filterOp=startswith&filterValue=Chr", only the first contact (with id=1) would match and be returned. However, with parameters "filterBy=displayName&filterOp=present", both contacts would be returned. Given the parameters "filterBy=email&filterOp=contains&filterValue=plaxo.com", only the second contact (with id=2) would match, as would it be the only contact to match given the parameters "filterBy=email&filterOp=present". If a request specifies a "filterValue" but no "filterBy" or Smarr Expires June 5, 2009 [Page 11] Internet-Draft Portable Contacts 1.0 December 2008 "filterOp", it is up to the Provider how to interpret this filter request. Providers MAY choose to default to filtering by a given field (e.g. "displayName"); they MAY choose to implement a custom, Provider-specific query syntax for "filterValue" in this case; or they MAY choose to reject requests of this type. In general, if Consumers want to request specific behavior from Providers, they should do so by being explicit in their use of query parameters. 6.3.2. Sorting Sorting allows requests to specify the order in which contacts are returned. sortBy Specifies the field name whose value SHALL be used to order the returned Contacts. The sort order is determine by the "sortOrder" parameter. If "sortBy" is a Singular Field, contacts are sorted according to that field's value; if it's a Plural Field, contacts are sorted by the Value (or Major Value, if it's a Complex Field, see Section 7) of the field marked with "primary": "true", if any, or else the first value in the list, if any, or else they are sorted last if the given contact has no data for the given field. sortOrder The order in which the "sortBy" parameter is applied. Allowed values are "ascending" and "descending". If a value for "sortBy" is provided and no "sortOrder" is specifies, the "sortOrder" SHALL default to "ascending". Sort order is expected to be case-insensitive Unicode alphabetic sort order, with no specific locale implied. 6.3.3. Pagination The pagination parameters can be used together to "page through" a large number of results in manageable chunks: startIndex: Specifies the offset of the first result to be returned with respect to the list of contacts that would be returned if no "startIndex" were provided. For instance, if in a given request 10 contacts would normally be provided, if "startIndex" is 7 and no "count" is specified, then only the last 3 contacts in that list would be returned (contacts are zero-indexed). If "startIndex" is greater than or equal to the total number of results that would be returned, no contacts are returned. Value MUST be a non-negative integer and defaults to 0 if no value is specified. Smarr Expires June 5, 2009 [Page 12] Internet-Draft Portable Contacts 1.0 December 2008 count: If non-zero, specifies the maximum number of contacts the Consumer would like the Provider to return at a time. Value MUST be a non-negative integer and defaults to 0 if no value is specified. A "count" of 0 means that is up to the Provider to determine how many contacts to return by default (some Providers may return all contacts by default; others may return a fixed default number like 10). Providers SHOULD honor a very large "count" value, and SHOULD support returning all contacts at once when presented with a "count" request that is larger than the number of contacts the user has, but Providers MAY choose to never return more than a Provider-determined maximum number of contacts per request, if returning all contacts is too burdensome. In all cases, at most "count" contacts SHALL be returned, starting at "startIndex" and counting up from there. In each of these cases, Providers MUST indicate the total number of contacts they chose to return in the response using the "itemsPerPage" response element (see Section 6.4). For instance, on an initial query, specifying "startIndex=0&count=10" will return only the first 10 results. The total number of possible results is indicated by the "totalResults" field of results, so the client knows how many "pages" of results exist. A subsequent query of "startIndex=10&count=10" will return the next 10 results, and so on. 6.3.4. Presentation Presentation controls the format, makeup, and delivery mechanism for returning the requested result set: fields: If non-empty, each contact returned SHALL contain only the fields explicitly requested. Service Provider MAY return a subset of the requested fields if they are not supported. This field is used for efficiency when the client only wishes to access a subset of the fields normally returned in results. Value is a comma separated list of top level field names (e.g. "id,name,emails,photos") and defaults to an empty list which means it's up to the Provider which fields to return. Consumers may request all available fields to be returned by using the special value "@all". format: Specifies the format in which the response data is returned. Service Providers MUST support the values "json" for JSON (http://json.org) and "xml" for XML (http://www.w3.org/XML/) and MAY support additional formats if desired. The format defaults to "json" if no format is specified. The data structure returned is equivalent in both formats; the only difference is in the encoding of the data. Singular Fields are encoded as string key/value Smarr Expires June 5, 2009 [Page 13] Internet-Draft Portable Contacts 1.0 December 2008 pairs in JSON and tags with text content in XML, e.g. ""field": "value"" and "value" respectively. Plural Fields and Plural Bundles are encoded as arrays in JSON and repeated tags in XML, e.g. ""fields": [ "value1", "value2" ]" and "value1value2" respectively. Nodes with multiple sub-nodes are represented as objects in JSON and tags with sub-tags in XML, e.g. ""field": { "subfield1": "value1", "subfield2": "value2" }" and "value1value2" respectively. 6.3.5. Declining to honor query parameters Providers SHOULD honor all filtering, sorting, and pagination requests specified via Query Parameters. However, in some instances it may be too burdensome to comply with a particular request, e.g. because the Provider does not have an efficient database index set up for a given field that is requested for filtering or sorting, and is unable to efficiently fetch all data and post-process the results to honor the request before returning the response. In such cases, Providers MAY decline to honor the request (or specific pieces of the request). If any part of the request is declined, Providers MUST specify which part(s) of the request were declined in the response, using ""sorted": false", ""filtered": false", and/or ""updatedSince": false" as appropriate. For efficiency, Providers SHOULD omit these response fields if that part of the request was successfully performed, or if no such Query Parameter was specified in the request. Note that since all of the filtering, sorting, and pagination operations are designed to reduce the amount of data returned, it is possible for Consumers to emulate these operations client-side when a Provider declines to perform them server-side. For instance, filtering can be accomplished by iterating through each entry returned and deleting those that do not match the filtering criteria. Thus Consumers can request these operations to be performed server- side, and Providers will honor them if possible, and otherwise indicate to Consumers that they need to be performed client-side, effectively "splitting the workload" while maintaining consistent semantics. 6.4. Response Format The structure of the response object returned from a successful request is as follows. The root element is "response", which is shown explicitly as the root element in XML format, and is the anonymous root object returned when the format is JSON (i.e. in JSON, the response returned is the object value of the "response" node). The "response" node MUST contain the following child nodes, and MAY Smarr Expires June 5, 2009 [Page 14] Internet-Draft Portable Contacts 1.0 December 2008 contain additional nodes that the Service Provider wishes to add to expose additional data. Note that "startIndex", "itemsPerPage", and "totalResults" are based on [OpenSearch]. See the Appendix for a full example. o "startIndex": the index of the first result returned in this response, relative to the starting index of all results that would be returned if no "startIndex" had been requested. In general, this will be equal to the value requested by the "startIndex", or 0 if no specific "startIndex" was requested. o "itemsPerPage": the number of results returned per page in this response. In general, this will be equal to the "count" Query Parameter, but MAY be less if the Service Provider is unwilling to return as many results per page as requested, or if there are less than the requested number of results left to return when starting at the current "startIndex". This field MUST be present if and only if a value for "count" is specified in the request. o "totalResults": the total number of contacts that would be returned if there were no "startIndex" or "count" specified. This value tells the Consumer how many total results to expect, regardless of the current pagination being used, but taking into account the current filtering options in the request. o "entry": an array of Contact objects, one for each contact matching the request, as defined in Section 7.2. For consistency of parsing, if the request could possibly return multiple contacts (as is normally the case), this value MUST always be an array of results, even if there happens to be 0 or 1 matching results. If the request is specifically for a single contact (e.g. because the request contains Additional Path Information like "/@me/@all/{id}" or "/@me/@self"), then "entry" MUST be an object containing the single contact returned (i.e. ""entry": [ { /* first contact */ } ]" and ""entry": { /* only contact */ }" respectively). 6.5. Error Codes The Service Provider MUST return a response code with every response. Response codes are numeric and conform to existing HTTP response codes where possible, as defined below. In addition to the response code, Service Providers SHOULD also provide a human-readable reason that explains the reason for the response code. This message SHOULD be intelligible to developers, but MAY be unsuitable for display to end-users. Clients SHOULD provide their own appropriate error message to users when encountering an error response. Service Providers SHOULD conform to the following response codes to Smarr Expires June 5, 2009 [Page 15] Internet-Draft Portable Contacts 1.0 December 2008 indicate the following situations. Service Providers MAY return additional codes to indicate additional information, but are discouraged from doing so and should instead augment the reason text with existing codes, if possible. 200: OK (response returned successfully) 400: Bad Request (request was malformed or illegal and cannot be completed) 401: Unauthorized (authentication headers / parameters were invalid or missing) 404: Not Found (the request points to an object that does not exist, e.g. to an unknown contact id; note that Service Providers MUST return a 200 with an empty array of contacts if the request has filtering parameters that are valid but have no matches) 500: Internal Server Error (un unexpected error occurred during processing) 503: Service Unavailable (service is temporarily unavailable; this may be because the Consumer has exceeded their rate-limit of requests) 7. 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], 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. Smarr Expires June 5, 2009 [Page 16] Internet-Draft Portable Contacts 1.0 December 2008 7.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. 7.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). 7.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"". Smarr Expires June 5, 2009 [Page 17] Internet-Draft Portable Contacts 1.0 December 2008 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 7.3. 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". Note the "updatedSince" Query Parameter described in Section 6.3 can be used to select only contacts whose "updated" value is equal to or more recent than a given xs:dateTime. This enables Consumers to repeatedly access a user's data and only request newly added or updated contacts since the last access time. 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. Smarr Expires June 5, 2009 [Page 18] Internet-Draft Portable Contacts 1.0 December 2008 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]: "aboutMe", "bodyType", "currentLocation", "drinker", "ethnicity", "fashion", "happiestWhen", "humor", "livingArrangement", "lookingFor", "profileSong", "profileVideo", "relationshipStatus", "religion", "romance", "scaredOf", "sexualOrientation", "smoker", and "status". 7.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 Smarr Expires June 5, 2009 [Page 19] Internet-Draft Portable Contacts 1.0 December 2008 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 Smarr Expires June 5, 2009 [Page 20] Internet-Draft Portable Contacts 1.0 December 2008 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 7.4. organizations: A current or past organizational affiliation of this Contact, as described in Section 7.5. accounts: An online account held by this Contact, as described in Section 7.6. 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". Smarr Expires June 5, 2009 [Page 21] Internet-Draft Portable Contacts 1.0 December 2008 7.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."). 7.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. Smarr Expires June 5, 2009 [Page 22] Internet-Draft Portable Contacts 1.0 December 2008 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. 7.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". Smarr Expires June 5, 2009 [Page 23] Internet-Draft Portable Contacts 1.0 December 2008 description: A textual description of the role this Contact played in this organization. This field MAY contain newlines. 7.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]. 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". 8. IANA Considerations This memo includes no request to IANA at this time. [[Future drafts are likely to request registration for the XML and JSON content types.]] 9. Security Considerations This memo abides by the security considerations of HTTP Basic Auth [RFC2617] and the OAuth protocol [OAuth Core 1.0]. Appendix A. Example Here is a sample request and response that illustrates much of Portable Contacts. For simplicity, authorization information is not Smarr Expires June 5, 2009 [Page 24] Internet-Draft Portable Contacts 1.0 December 2008 shown in the request. Sample request (via HTTP GET): http://sample.site.org/path/to/api/@me/@all?startIndex=10 &count=10&sortBy=displayName Sample response (JSON): { "startIndex": 10, "itemsPerPage": 10, "totalResults": 12, "entry": [ { "id": "123", "displayName": "Minimal Contact" }, { "id": "703887", "displayName": "Mork Hashimoto", "name": { "familyName": "Hashimoto", "givenName": "Mork" }, "birthday": "0000-01-16", "gender": "male", "drinker": "heavily", "tags": [ "plaxo guy" ], "emails": [ { "value": "mhashimoto-04@plaxo.com", "type": "work", "primary": "true" }, { "value": "mhashimoto-04@plaxo.com", "type": "home" }, { "value": "mhashimoto@plaxo.com", "type": "home" } ], Smarr Expires June 5, 2009 [Page 25] Internet-Draft Portable Contacts 1.0 December 2008 "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" Smarr Expires June 5, 2009 [Page 26] Internet-Draft Portable Contacts 1.0 December 2008 } ], "accounts": [ { "domain": "plaxo.com", "userid": "2706" } ] } ] } Sample response (XML): 10 10 12 123 Minimal Contact 703887 Mork Hashimoto Hashimoto Mork 0000-01-16 male heavily plaxo guy mhashimoto-04@plaxo.com work true mhashimoto-04@plaxo.com home mhashimoto@plaxo.com home Smarr Expires June 5, 2009 [Page 27] Internet-Draft Portable Contacts 1.0 December 2008 http://www.seeyellow.com work http://www.angryalien.com home KLONDIKE5 work 650-123-4567 mobile http://sample.site.org/photos/12345.jpg thumbnail plaxodev8 aim home Springfield VT 12345 USA Burns Worldwide Head Bee Guy plaxo.com 2706 Smarr Expires June 5, 2009 [Page 28] Internet-Draft Portable Contacts 1.0 December 2008 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]. 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. 10. References 10.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2425] Howes, T., Smith, M., and F. Dawson, "A MIME Content-Type for Directory Information", RFC 2425, September 1998. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. [RFC2617] Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, June 1999. 10.2. Informative References [OAuth Core 1.0] OAuth, OCW., "OAuth Core 1.0". Smarr Expires June 5, 2009 [Page 29] Internet-Draft Portable Contacts 1.0 December 2008 [OAuth Discovery] Eran Hammer-Lahav, E., "OAuth Discovery 1.0". [OpenSearch] Clinton, D., "OpenSearch 1.1". [OpenSocial] Panzer, J., "OpenSocial 0.8.1 RESTful Protocol Specification". [XRDS-Simple] Hammer-Lahav, E., "XRDS-Simple 1.0". [google-sgnodemapper] Fitzpatrick, B., "Social Graph Node Mapper". Author's Address Joseph Smarr Plaxo Email: joseph@plaxo.com URI: http://josephsmarr.com/ Smarr Expires June 5, 2009 [Page 30] Internet-Draft Portable Contacts 1.0 December 2008 Full Copyright Statement Copyright (C) The IETF Trust (2008). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Smarr Expires June 5, 2009 [Page 31]