The VOOT Protocol
draft-gn3-jra3-t2-voot

Abstract

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&E federations.

Status of this Memo

This Internet-Draft is submitted to IETF in full conformance with the provisions of BCP 78 and 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 3, 2012.

Copyright Notice

Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved.

This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents in effect on the date of publication of this document (http://trustee.ietf.org/license-info). Please review these documents carefully, as they describe your rights and restrictions with respect to this document.

Table of Contents

1.  Introduction
    1.1.  Requirements Language
    1.2.  Motivation
2.  VOOT 2.0 API and Datamodels
    2.1.  VOOT Core API Server Specification
    2.2.  VOOT Social API Server Specification
        2.2.1.  Get a Person
        2.2.2.  Get a list of People
        2.2.3.  Get Activity Streams
        2.2.4.  Create an ActivityEntry
    2.3.  VOOT Social Data Specification
    2.4.  Extensions
        2.4.1.  VOOT Attributes
            2.4.1.1.  isMemberOf
            2.4.1.2.  getGroupMembers
3.  VOOT 2.0 Metadata and Discovery
4.  Security Considerations
5.  References
    5.1.  Normative References
    5.2.  Informative References
§  Authors' Addresses

1.  Introduction

1.1.  Requirements Language

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 RFC 2119 (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.) [RFC2119] .

1.2.  Motivation

VOOT 2.0 is a very simple protocol for cross-domain read-access to groups. The current version (2.0) is a profile of OpenSocial 2.0.1 (, “OpenSocial Templating Specification,” August 2011.) [OpenSocial‑Specification] .

TODO - motivational text on VOs and the need for standardized group membership access protocols.

2.  VOOT 2.0 API and Datamodels

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.

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.

2.1.  VOOT Core API Server Specification

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.

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).

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

A VOOT provider MUST implement the standard request parameters from section 6 of the OpenSocial 2.0 Core API Server Specification. This includes:

• updateSince
• format

and for calls that return collections the following request parameters MUST be supported.

• count
• filterBy
• filterOp
• filterValute
• sortOrder
• startIndex

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)

2.2.  VOOT Social API Server Specification

A VOOT provider SHOULD return only single-page responses. - leifj: is this reasonable?

The minimal VOOT mandatory to implement set of social services is:

• Get a Person [OpenSocial Social API Server 2.1.1.1]
• Get a list of People [OpenSocial Social Server API 2.1.1.2]
• Get Activity Streams [OpenSocial Social Server API 2.3.1]
• Create an ActivityEntry [OpenSocial Social Server API 2.3.2]

2.2.1.  Get a Person

A VOOT provider MUST implement the get person call over REST. This is an HTTP GET to /people/<userId> that MUST return a single Person object encoded as JSON.

In order to preserve the anonymity of VOOT users a VOOT provider MAY return a constant value for displayName.

2.2.2.  Get a list of People

A VOOT provider MUST support listing members of a group using HTTP GET to /people/@me/<groupId>. Each member of the returned OpenSocial Collection MUST be a Person object with at least the 'id' and 'displayName' attribute.

2.2.3.  Get Activity Streams

TODO

2.2.4.  Create an ActivityEntry

TODO

2.3.  VOOT Social Data Specification

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.

The following are minimal requirements on Group and Person objects.

• Person objects MUST contain at least the 'id' and 'displayName' attribute.
• Group objects MUST contain the 'id' and 'title' fields.

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.

2.4.  Extensions

TODO - describe where extensions can happen

THIS SECTION NEEDS MORE DISCUSSION, and will be updated

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

2.4.1.  VOOT Attributes

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.

All VOOT specific membership attributes is prefixed with 'voot_memership_'.

2.4.1.1.  isMemberOf

With 'isMemberOf', the membership attributes represents the current persons membership to each of the returned groups.

Example of group membership attributes to 'isMemberOf':

GET /groups/@me

[
    {
        id: 'geant_identityfederations',
        voot_membership_role: 'owner'
    },
    {
        id: 'refeds',
        voot_membership_role: 'member'
    }
]

2.4.1.2.  getGroupMembers

With 'getGroupMembers', the memership attributes represents the membership of the relevant group for each of the persons returned.

Example of group membership attributes to 'getGroupMembers':

GET /people/@me/geant_identityfederations

[
    {
        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'
    }
]

3.  VOOT 2.0 Metadata and Discovery

TODO

4.  Security Considerations

Yeah probably...

5.  References

5.1. Normative References

5.2. Informative References

Authors' Addresses