OInvite Core 1.0 - Draft 3

Abstract

The OInvite protocol standardizes the manner in which communications relationships (e.g., friend-requests) are initiated between two users in a decentralized communications network.

This document specifies OInvite Core, a binding-independent request/response format and verification protocol to initiate and respond to communications relationship requests originating across social-network and/or domain boundaries (e.g., a Google Buzz user desiring to follow a Twitter user's protected feed on Twitter).

Table of Contents

1.  Definitions
    1.1.  Requirements Notation
    1.2.  Definitions
2.  Protocol Overview
    2.1.  Out of Scope
3.  OInvite Discovery
4.  OInvite Verification Procedure
    4.1.  OInvite Verification Extensions (OVE)
5.  OInvite Document Structure
    5.1.  Common Document Data Types
        5.1.1.  String Values
        5.1.2.  URI Values
        5.1.3.  Date/Time Values
    5.2.  OInvite Request Document Structure
        5.2.1.  XML Schema Elements
        5.2.2.  XML Schema
    5.3.  OInvite Response Document Structure
        5.3.1.  XML Schema Elements
        5.3.2.  OInvite Response Schema
6.  Security Considerations
Appendix A.  Non-Normative Examples
Appendix A.1.  Example: OInvite Request
Appendix A.2.  Example: OInvite Response
7.  References
    7.1.  Normative References
    7.2.  Informative References
§  Author's Address

1.  Definitions

1.1.  Requirements Notation

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT","SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" inthis document are to be interpreted as described in [RFC2119] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) .

1.2.  Definitions

Communications Relationship (CR)

An agreement between two parties to engage in some form of communication.

OInvite

An XML document representing an invitation to join a CR.

Invitor

The sender of an OInvite.

Invitee

The recipient of an OInvite.

OInvite Response

An XML document representing the Invitee's response to an OInvite.

Participant

An Invitor who has sent an OInvite, or an Invitee who has accepted an OInvite.

OInvite Verification Mechanism

A pluggable mechanism acceptable to Invitor and Invitee that is used to verify various aspects of an OInvite (e.g., authenticity, spaminess, etc).

2.  Protocol Overview

1. OInvite specifies two types of messages: OInvite Invitations (OInvites) and OInvite Responses (OResponses). These messages are defined in section Section 5.2 (OInvite Request Document Structure) .
2. When a particular Invitor wishes to establish a Communications Relationship with an Invitee, the Invitor creates a new OInvite and transmits it to the specified Invitee via an appropriate transport.
3. Upon receiving the OInvite, the Invitee's server verifies that the OInvite is authentic and valid per the rules specified in Section 4 (OInvite Verification Procedure) . Once a response has been readied, an OInvite Response is returned back to the Invitor.

2.1.  Out of Scope

The following are out of scope for OInvite Core and may be defined by OInvite extensions or other specifications:

OInvite Client-Server Interaction

This document does not define an API or other protocol to allow an end-user to interact with an OInvite server to perform various operations on the user's established or pending OInvites (e.g., approving, rejecting, querying, editing or deleting OInvites).

Transport

OInvite messages are not restricted to any particular transport binding.

OInvite Termination

This document does not specify how to terminate a Communications Relationship (often, this can be done silently).

3.  OInvite Discovery

This document does not formalize any particular discovery mechanism for OInvite Identifiers, which are URI's. Instead, each implementation or an OInvite extension MAY determine appropriate discovery mechansims in order to find out more information about a particular Identifier, as well as which transport to use to send and receive OInvites, and where to send them.

4.  OInvite Verification Procedure

Before accepting a particular OInvite and otherwise prompting or alerting an Invitee, implementations MUST verify the contents of an OInvite per the following procedure:

1. Verify that the OInvite includes all necessary elements, such as an 'id' and 'requestType'.
   
   
2. Verify the value of the 'InviteeId' element to ensure that it represents a valid user on the system.
   
   
3. Verify the valud of the 'InvitorId' element to ensure that it represents a sender that is not flagged by some other spam-related or system resource, such as an automatic-deny-list.
   
   
4. Follow the rules of any OInvite Verification Extension that is advertised on behalf of the invitee, found via OInvite discovery.

4.1.  OInvite Verification Extensions (OVE)

OInvite Core leaves room for verification extensions that can be used to aid a recipient in trying to determine if a particular OInvite is valid and authentic, and whether or not the invitation should be forwarded to an actual user or processed automatically.

As an example, see [oinvite‑ev‑pow] (Fuelling, D., “OInvite POW Verification,” 2010.) for an example of one such OEV that details a system to help prevent invitation spam.

5.  OInvite Document Structure

OInvite specifies a message format using XML Schema. The following sub-sections detail the elements, attributes, and schema of all OInvite Core message types.

5.1.  Common Document Data Types

5.1.1.  String Values

All OInvite string values have the type xs:string, which is built in to the W3C [xml‑schema‑datatypes] (Biron, P. and A. Malhotra, “XML Schema Datatypes,” 2004.) specification. Unless otherwise noted in this specification or extensions, all strings in OInvite documents MUST consist of at least one non-whitespace character (whitespace is defined in section 2.3 of [xml‑1.0] (Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, “Extensible Markup Language (XML) 1.0,” 2008.) ).

5.1.2.  URI Values

All OInvite URI reference values have the type xs:anyURI, which is built in to the W3C [xml‑schema‑datatypes] (Biron, P. and A. Malhotra, “XML Schema Datatypes,” 2004.) specification. Unless otherwise noted in this specification or extensions, all URIs in an OInvite document MUST consist of at least one non-whitespace character (whitespace is defined in section 2.3 of [xml‑1.0] (Bray, T., Paoli, J., Sperberg-McQueen, C., Maler, E., and F. Yergeau, “Extensible Markup Language (XML) 1.0,” 2008.) ). Additionally, Comparison of this value MUST be performed using the scheme-specific normalization rules for the URI, as specified in Section 6.2.3 of [RFC3986] (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.)

5.1.3.  Date/Time Values

All OInvite date and time values have the type xs:dateTime, which is built in to the W3C [XML Schema Datatypes] specification. Time values MUST be represented with the UTC designator 'Z'. OInvite providers MUST NOT generate time instants that specify leap seconds.

5.2.  OInvite Request Document Structure

5.2.1.  XML Schema Elements

5.2.1.1.  xml:id

This attribute, of type xs:ID, is defined by [xml‑id] (Marsh, J., Veillard, D., and N. Walsh, “xml:id,” 2005.) and provides a unique identifier for an OInvite.

5.2.1.2.  CreationDate

The date/time that this OInvite was created.

5.2.1.3.  InvitorId

A URI that identifies the sender of an OInvite. This value MUST be an absolute URI. .

Note that it will be desirable if this identifier is resolvable in order to provide the Invitee with more information about the Invitor.

5.2.1.4.  InvitorName

An optional full name for the Invitor, limited to 30 UTF-8 characters.

5.2.1.5.  InviteeId

A URI that identifies the recipient of an OInvite. This value MUST be an absolute URI.

5.2.1.6.  RequestType

One of either 'READ', 'WRITE', or 'BOTH'.

'READ' is used to indicate that the Invitor would like to receive information from the Invitee, but does not desire to send information (i.e., this is a 1-way communications relationship). A potential example of this type of CR is one where the Invitor desires to read information that the Invitee is posting to a private news feed or activity stream.

'WRITE' is used to indicate that the Invitor would like to send information to the Invitee, but does not desire to receive information back (i.e., this is a 1-way communications relationship). A potential example of this type of CR is one where the Invitor desires to send information to a resource controlled by the Invitee, such as a comment feed.

'BOTH' is used to indicate that the Invitor would like to both send and receive information to and from the Invitee (a bi-direcitonal communications relationship).

5.2.1.7.  VerificationExtensionType

A URI specifying the type of verification extension that should be used to verify this OInvite, as defined in an OInvite Verification Extension document.

5.2.1.8.  Subjects

A list of URIs, with each URI representing the indicated resources that this OInvite pertains to.

5.2.2.  XML Schema

  <?xml version="1.0"?>
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.oinvite.net/core/1.0"
    xmlns="http://www.oinvite.net/core/1.0" elementFormDefault="qualified">

    <xs:element name="oirequest">
      <xs:attribute name="xml:id" type="xs:ID"/>
      <xs:complexType>
        <xs:sequence>
          <xs:element name="creationDate" type="xs:dateTime"/>
          <xs:element name="invitorId" type="xs:anyURI"/>
          <xs:element name="invitorName" type="xs:string"/>
          <xs:element name="inviteeId" type="xs:anyURI"/>
          <xs:element name="requestType">
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="READ"/>
                <xs:enumeration value="WRITE"/>
                <xs:enumeration value="BOTH"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="subjects" minOccurs="0" maxOccurs="1">
            <xs:sequence>
              <xs:element name="subject" minOccurs="0" maxOccurs="unbounded"/>
            </xs:sequence>
          </xs:element>
          <xs:element name="verificationExtensionType" type="xs:anyURI"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>

  </xs:schema>

5.3.  OInvite Response Document Structure

5.3.1.  XML Schema Elements

5.3.1.1.  xml:id

This attribute, of type xs:ID, is defined by [xml‑id] (Marsh, J., Veillard, D., and N. Walsh, “xml:id,” 2005.) and provides a unique identifier for an OInvite.

5.3.1.2.  CreationDate

The date/time that this OInvite Response was created.

5.3.1.3.  RequestId

The xml:id of the OInvite Request that this document is in response to.

5.3.1.4.  Response

One of either 'ACCEPT', 'DENY', or 'INVALID'.

'ACCEPT' is used to indicate that the Invitee has accepted the OInvite and agrees to enter into a communications relationship specified by the OInvite Request.

'DENY' is used to indicate that the Invitee has declined the OInvite, and does not wish to enter into a communications relationship as specified by the OInvite Request.

'INVALID' is used to indicate that the OInvite was invalid or otherwise unacceptable to the Invitee's OInvite server.

5.3.1.5.  Reason

An optional textual string that can be used to augment the 'response', such as and error message explaining why an OInvite failed or was invalid.

5.3.2.  OInvite Response Schema

  <?xml version="1.0"?>
  <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://www.oinvite.net/core/1.0"
    xmlns="http://www.oinvite.netcore/1.0" elementFormDefault="qualified">

    <xs:element name="oiresponse">
      <xs:attribute name="xml:id" type="xs:ID"/>
      <xs:complexType>
        <xs:sequence>
          <xs:element name="creationDate" type="xs:dateTime"/>
            <xs:element name="requestId" type="xs:anyURI"/>
            <xs:element name="response">
            <xs:simpleType>
              <xs:restriction base="xs:string">
                <xs:enumeration value="ACCEPT"/>
                <xs:enumeration value="DENY"/>
                <xs:enumeration value="INVALID"/>
              </xs:restriction>
            </xs:simpleType>
          </xs:element>
          <xs:element name="reason" type="xs:string"/>
        </xs:sequence>
      </xs:complexType>
    </xs:element>

  </xs:schema>

6.  Security Considerations

Identity Verification

This specification does not address the question of Invitor nor Invitee identifier verification. Implementations should take care to employ best practices and/or OInvite Extension Verification callbacks for spam-prevention and increased security.

OInvite Content Inspection

OInvite does not place any restrictions on the contents of certain OInvite document fields, such as the InvitorName. Likewise, extensions may define document content that is free-form in nature. For this reason, implementations should take care to ensure that the content of any OInvite element is suitable for display to, and use by, end-users.

Appendix A.  Non-Normative Examples

Appendix A.1.  Example: OInvite Request

The following is a non-normative example of a simple OInvite Request:

Example:

  <oirequest xmlns="http://www.oinvite.net/core/1.0"
  	xml:id="tag:foo.com,2005:8.3093">

    <creationDate>2009-06-01T18:30:02.25Z</creationDate>
    <invitorId>bob@example.com</invitorId>
    <fullName>Bob Smith</fullName>
    <inviteeId>alice@example.net</inviteeId>
    <requestType>BOTH</requestType>
    <subjects>
    	<subject>http://example.com/userposts</subject>
    </subjects>
    <verificationExtension/>

  </oirequest>

Appendix A.2.  Example: OInvite Response

The following is non-normative example of a OInvite Response where an Invitee has accepted an OInvite:

  <oiresponse xmlns="http://www.oinvite.net/core/1.0"
  	xml:id="tag:foo.com,2005:8.3093">

    <requestId>tag:foo.com,2005:8.3094</requestId>
    <response>ACCEPT</response>
    <creationDate>2009-06-01T18:30:02.25Z</creationDate>

  </oiresponse>

7.  References

7.1. Normative References

7.2. Informative References

Author's Address