voot-2.0.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
     which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
     There has to be one entity for each item to be referenced. 
     An alternate method (rfc include) is described in the references. -->
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC2629 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2629.xml">
<!ENTITY RFC3552 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY I-D.narten-iana-considerations-rfc2434bis SYSTEM "http://xml.resource.org/public/rfc/bibxml3/reference.I-D.narten-iana-considerations-rfc2434bis.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs), 
     please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
     (Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space 
     (using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="exp" docName="draft-gn3-jra3-t2-voot" ipr="pre5378Trust200902">
  <front>
    <title abbrev="VOOT">The VOOT Protocol</title>

    <author fullname="Leif Johansson" initials="LJ" role="editor"
            surname="Johansson">
      <organization>NORDUNet A/S</organization>

      <address>
        <email>leifj@nordu.net</email>
      </address>
    </author>

    <author fullname="Andreas" initials="AS" role="editor"
            surname="&Aring;kre Solberg">
      <organization>UNINETT</organization>

      <address>
        <postal>
          <street></street>

          <city></city>

          <region></region>

          <code></code>

          <country></country>
        </postal>

        <phone></phone>

        <facsimile></facsimile>

        <email>andreas.solberg@uninett.no</email>

        <uri></uri>
      </address>
    </author>

    <date month="April" year="2012" />

    <abstract>
      <t>The VOOT (Virtual Organization Orthogonal Technology) protocol is a
      subset of OpenSocial used to manage group membership. The primary
      motivation for VOOT is as a simple tool for managing virtual
      organization in R&amp;E federations.</t>
    </abstract>
  </front>

  <middle>
    <section title="Introduction">
      <section title="Requirements Language">
        <t>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 <xref
        target="RFC2119">RFC 2119</xref> .</t>
      </section>

      <section title="Motivation">
        <t>VOOT 2.0 is a very simple protocol for cross-domain read-access to
        groups. The current version (2.0) is a profile of <xref
        target="OpenSocial-Specification">OpenSocial 2.0.1</xref> .</t>

        <t>TODO - motivational text on VOs and the need for standardized group
        membership access protocols.</t>
      </section>
    </section>

    <section title="VOOT 2.0 API and Datamodels">
      <t>VOOT 2.0 is a profile of OpenSocial 2.0.1. The following sections
      describe the mandatory to implement subset of OpenSocial 2.0.1 in
      relation to the corresponding document of the OpenSocial 2.0.1
      specification set. A VOOT provider is a subset of the functionality of
      an OpenSocial Core and Social APIs. In particular a VOOT provider does
      not have to implement any part of the container specification or the
      gadget APIs.</t>

      <t>Support for non-read-only operations (such as content upload, group
      creation etc) is OPTIONAL unless otherwize stated. In places where
      OpenSocial mandates support for write operations (eg creation of
      ActivityEntries) VOOT stipulates null operations to simulate
      write-operations.</t>

      <section title="VOOT Core API Server Specification">
        <t>A VOOT provider MUST implement the REST protocol with JSON format.
        A VOOT client SHOULD use REST with JSON format payloads. All other
        formats and protocols are OPTIONAL with one exception: a VOOT provider
        MUST implement the System service using the RPC protocol as this is
        part of the OpenSocial discovery mechanism which is fully supported by
        VOOT.</t>

        <t>NOTE: The OpenSocial specification stipulates than an OpenSocial
        container MUST support JSON and ATOM for all resources and JSON, ATOM
        and XML for the people resources. Anticipating future development in
        this area VOOT clients MUST only use JSON and REST where applicable
        and SHOULD NOT call the RPC System service (instead XRD discovery
        SHOULD be used).</t>

        <t>A VOOT provider MUST support authorization using OAuth 2.0 and
        OAuth 1.0a in accordance with the OpenSocial specification.</t>

        <t>A VOOT provider MUST implement the standard request parameters from
        section 6 of the OpenSocial 2.0 Core API Server Specification. This
        includes: <list style="symbols">
            <t>updateSince</t>

            <t>format</t>
          </list> and for calls that return collections the following request
        parameters MUST be supported. <list style="symbols">
            <t>count</t>

            <t>filterBy</t>

            <t>filterOp</t>

            <t>filterValue</t>

            <t>sortOrder</t>

            <t>startIndex</t>
          </list></t>

        <t>All VOOT providers MUST support XRD-based Discovery as described in
        section 7 of the OpenSocial 2.0 Core API Server Specification. An
        example System request and response given the mandatory to implement
        features in VOOT: (TODO)</t>
      </section>

      <section title="VOOT Social API Server Specification">
        <t>A VOOT provider SHOULD return only single-page responses. - leifj:
        is this reasonable?</t>

        <t>The minimal VOOT mandatory to implement set of social services is:
        <list style="symbols">
            <t>Get a Person [OpenSocial Social API Server 2.1.1.1]</t>

            <t>Get a list of People [OpenSocial Social Server API 2.1.1.2]</t>

            <t>Get Activity Streams [OpenSocial Social Server API 2.3.1]</t>

            <t>Create an ActivityEntry [OpenSocial Social Server API
            2.3.2]</t>
          </list></t>

        <section title="Get a Person">
          <t>A VOOT provider MUST implement the get person call over REST.
          This is an HTTP GET to /people/&lt;userId&gt; that MUST return a
          single Person object encoded as JSON.</t>

          <t>In order to preserve the anonymity of VOOT users a VOOT provider
          MAY return a constant value for displayName.</t>
        </section>

        <section title="Get a list of People">
          <t>A VOOT provider MUST support listing members of a group using
          HTTP GET to /people/@me/&lt;groupId&gt;. Each member of the returned
          OpenSocial Collection MUST be a Person object with at least the 'id'
          and 'displayName' attribute.</t>
        </section>

        <section title="Get Activity Streams">
          <t>TODO</t>
        </section>

        <section title="Create an ActivityEntry">
          <t>TODO</t>
        </section>
      </section>

      <section title="VOOT Social Data Specification">
        <t>A VOOT provider MUST support for Group and Person and SHOULD
        support the ActivityEntry (used in ActivityStreams) object. The
        OpenSocial specification mandates the use of the id and displayName
        fields.</t>

        <t>The following are minimal requirements on Group and Person
        objects.</t>

        <t><list style="symbols">
            <t>Person objects MUST contain at least the 'id' and 'displayName'
            attribute.</t>

            <t>Group objects MUST contain the 'id' and 'title' fields.</t>
          </list></t>

        <t>The 'id' field SHOULD be a 'Global-Id' type field on the form
        Domain-Name ":" Local-Id. The Domain-Name MUST uniquely and globally
        identitfy the VOOT provider instance and SHOULD be based on part of
        the VOOT provider instance hostname. The VOOT client MUST NOT assume
        that the Local-Id is part of a shared identifier namespace (eg an
        email address) and MUST NOT assue that Local-Id can be used to
        represent objects outside the scope of the given VOOT provider
        instance.</t>
      </section>

      <section title="Extensions">
        <t>TODO - describe where extensions can happen</t>

        <t>THIS SECTION NEEDS MORE DISCUSSION, and will be updated</t>

        <t>The namespace prefix 'voot_' is used for attributes defined in this
        specification, that are not part of OpenSocial.</t>

        <section title="VOOT Attributes">
          <t>There may be VOOT attributes for both Person and Group objects;
          but also for group membership. Attributes for group membership may
          be merged into both Person and Group objects depending on the
          protocol method used.</t>

          <t>All VOOT specific membership attributes is prefixed with
          'voot_memership_'.</t>
		
			<section title="isMemberOf">
			<t>With 'isMemberOf', the membership attributes represents the
          	current persons membership to each of the returned groups.</t>
          	
          	 <t>Example of group membership attributes to 'isMemberOf':</t>
          	<t><figure><artwork>
          	<![CDATA[   
GET /groups/@me

{
    "startIndex": 0,
    "totalResults": 2,
    "itemsPerPage": 2,
    "entry":
    [
        {
            id: 'geant_identityfederations',
            voot_membership_role: 'owner'
        },
        {
            id: 'refeds',
            voot_membership_role: 'member'
        }
    ]
}
         	]]>
          	</artwork></figure></t>
          	</section>
		
			<section title="getGroupMembers">
			<t>With 'getGroupMembers', the memership attributes represents the
          	membership of the relevant group for each of the persons
          	returned.</t>
          	
          	<t>Example of group membership attributes to 'getGroupMembers':</t>
          	
          	<t><figure><artwork>
          	<![CDATA[         	
GET /people/@me/geant_identityfederations

{
    "startIndex": 0,
    "totalResults": 2,
    "itemsPerPage": 2,
    "entry" : 
    [
        {
            displayName: 'Andreas Akre Solberg',
            emails: ['andreas@uninett.no','andreas.solberg@uninett.no'],
            voot_membership_role: 'admin'
        },
        {
            displayName: 'Leif Johansson',
            emails: ['leif@sunet.se'],
            voot_membership_role: 'manager'
        }
    ]
}
         	]]>
          	
          	</artwork></figure></t>
			
			</section>
              
        </section>
      </section>
    </section>

    <section title="VOOT 2.0 Metadata and Discovery">
      <t>TODO</t>
    </section>

    <section title="Security Considerations">
      <t>Yeah probably...</t>
    </section>
  </middle>

  <back>
    <references title="Normative References">
      <?rfc include="http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml"?>
    </references>

    <references title="Informative References">
      <reference anchor="OpenSocial-Specification"
                 target="http://opensocial-resources.googlecode.com/svn/spec/2.0.1/OpenSocial-Specification.xml">
        <front>
          <title>OpenSocial Templating Specification</title>

          <author fullname="OpenSocial and Gadgets Specification Group &lt;opensocial-and-gadgets-spec@googlegroups.com&gt;"></author>

          <date month="August" year="2011" />
        </front>
      </reference>
    </references>
  </back>
</rfc>