Activity Base Schema (Draft)
activity-schema-01

Abstract

This document presents a base set of Object types and Verbs for use with Activity Streams.

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 (, “RFC 2119,” .) [RFC2119].

Status of this Memo

This document is an Internet-Draft and is NOT offered in accordance with Section 10 of RFC 2026, and the author does not provide the IETF with any rights other than to publish as an Internet-Draft.

Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at http://datatracker.ietf.org/drafts/current/.

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

This Internet-Draft will expire on November 28, 2011.

Table of Contents

1.  Introduction
2.  Notational Conventions
3.  Verbs
4.  Object Types
    4.1.  Article
    4.2.  Audio
    4.3.  Badge
    4.4.  Bookmark
    4.5.  Collection
    4.6.  Comment
    4.7.  Event
    4.8.  File
    4.9.  Group
    4.10.  Image
    4.11.  Note
    4.12.  Person
    4.13.  Place
    4.14.  Product
    4.15.  Question
    4.16.  Review
    4.17.  Service
    4.18.  Video
5.  Base Extension Properties
    5.1.  Location
    5.2.  Mood
    5.3.  Rating
    5.4.  Source
    5.5.  Tags
6.  Normative References
Appendix A.  Acknowledgements
§  Authors' Addresses

1.  Introduction

This document presents a base set of object types and verbs for use with Activity Streams.

2.  Notational Conventions

This specification allows the use of IRIs [RFC3987]. Every URI [RFC3986] is also an IRI, so a URI MAY be used wherever an IRI is named. When an IRI that is not also a URI is given for dereferencing, it MUST be mapped to a URI using the steps in Section 3.1 of [RFC3987]. When an IRI is serving as an identifier, it MUST NOT be so mapped.

3.  Verbs

4.  Object Types

4.1.  Article

The "article" object type indicates that the object is an article, such as a news article, a knowledge base entry, or other similar construct. Such objects generally consist of paragraphs of text, in some cases incorporating embedded media such as photos and inline hyperlinks to other resources.

At a minimum, an article object has the following properties:

4.2.  Audio

The "audio" object type represents audio content.

At a minimum, an audio object has the following properties:

4.3.  Badge

The "badge" object type represents a Badge or Award granted to an object (typically a person).

At a minimum, an badge object has the following properties:

4.4.  Bookmark

The "bookmark" object type represents a pointer to some URL -- typically a web page. In most cases, a bookmark is specific to a given user and contains metadata chosen by that user. Bookmark Objects are similar in principle to the concept of bookmarks or favorites in a web browser. A bookmark represents a pointer to the URL, not the URL or the associated resource itself.

When dealing with bookmarks it is important to note the distinction between the title, description, and URL of the bookmark itself and the title, content, and URL of the resource that is the target of the bookmark. In some implementations these MAY be the same, but bookmark managers often allow a user to edit the title and description of his or her own bookmarks to differ from the metadata on the target itself.

Some implementations refer to this object type as a "link". This specification uses the term "bookmark" to avoid confusion with the general concept of hyperlinks which apply to all object types.

Since bookmarks are often specific to a particular user, even though multiple users might have bookmarks pointing at the same resource, it is appropriate to use the post verb to describe the publication of such a bookmark. The favorite verb SHOULD be used when a user flags another user's bookmark as being a favorite without creating his own bookmark, or when a user flags his own bookmark as being a favorite as a special classification within his own bookmark collection.

At a minimum, a bookmark object has the following properties:

4.5.  Collection

The "collection" object type represents a generic collection of objects of any type. This object type can be used, for instance, to represent a collection of files like a folder, a collection of photos like an album, and so forth.

At a minimum, the collection object has the following properties:

4.6.  Comment

The "comment" object type represents a textual response to another object. The comment object type MUST NOT be used for other kinds of responses, such as video replies or reviews.

At a minimum, the comment object has the following properties:

4.7.  Event

The "event" object type represents an event that occurs in a certain place during a particular interval of time.

At a minimum, the event object has the following properties:

4.8.  File

The "file" object type represents some document or other file with no additional machine-readable semantics.

It is intended that this type be used as a base type for other Objects that manifest as files, so that additional semantics can be added while providing a fallback ability for clients that do not support the more specific Object type.

At a minimum, the file object has the following properties:

4.9.  Group

The "group" object type represents a grouping of objects in which member objects can join or leave.

At a minimum, the group object has the following properties:

4.10.  Image

The "image" object type represents a graphical image.

Previous versions of this specification had defined a "photo" object type which SHOULD be treated as a deprecated alias of "image".

At a minimum, the image object has the following properties:

4.11.  Note

The "note" object type represents short-form text messages. This object type is intended for use in "micro-blogging" and in systems where users are invited to publish short, often plain-text messages whose useful lifespan is generally shorter than that of an article or weblog entry.

A note is similar in structure to an article, but it does not have a title and its body tends to be shorter. Applications will often display the entire content of a note in an activity stream UI, whereas they MAY display only the title or the title and summary for a weblog entry.

At a minimum, a note object has the following properties:

It is expected that the "note" object type can be used for a broad range of purposes, including the representation of a human-readable description of what the author is doing, feeling or experiencing. Older versions of this specification had defined a "status" object type for that purpose. There are deployed implementations that currently still use "status". The "status" object type SHOULD be treated as a deprecated alias of the "note" object type. The determination of whether or not a "note" object represents a person's current status is based on the context in which the "note" is used.

4.12.  Person

The "person" object type represents a user account. This is often represents a person, but might also be a company or fictitious character that is being represented by a user account.

At a minimum, the person object has the following properties:

4.13.  Place

The "place" object type represents a location on Earth. Locations can be represented using geographic coordinates, a physical address, a free-form location name, or any combination of these.

At a minimum, the place object has the following properties:

The properties for the address property are:

4.14.  Product

The "product" object type represents a commercial good or service.

At a minimum, the product object has the following properties:

4.15.  Question

The "question" object type represents a question or poll.

At a minimum, a question object has the following properties:

4.16.  Review

The "review" object type represents a primarily prose-based commentary on another object.

At a minimum, a review object has the following properties:

4.17.  Service

The "service" object type represents a website, personal website or blog, business, brand, or other entity that performs some kind of work for other entities, people, or services, or acts as kind of container for other objects.

At a minimum, the service object has the following properties:

4.18.  Video

The "video" object type represents video content, which usually consists of a motion picture track and an audio track.

At a minimum, the video object has the following properties:

5.  Base Extension Properties

This specification defines an initial set of extension properties that can be used with all activities or objects.

5.1.  Location

Location data can be added to any object type or activity. Location can be specified via geographic coordinates, a street address, a free-form location name or any combination of these.

Within a JSON-serialized Activity Stream, the Location is represented using a property named location whose value is a Place (Place) object. The objectType property of this object MAY be omitted.

When appearing within an activity, the location data indicates the location where the activity occurred. When appearing within an object, the location data indicates the location of that object at the time the activity occurred.

For example:

  {
    "objectType": "person",
    "displayName": "John Doe",
    "location": {
      "displayName": "Mount Everest",
      "position": "+27.5916+086.5640+8850/"
    }
  }

5.2.  Mood

Mood describes the mood of the user when the activity was performed. This is usually collected via an extra field in the user interface used to perform the activity. For the purpose of this schema, a mood is a freeform, short mood keyword or phrase along with an optional mood icon image.

In JSON, Moods are included within an object or activity using a property named mood whose value is a JSON object with the following properties:

For example:

  {
    "objectType": "note",
    "content": "Working on the activity streams spec",
    "mood": {
      "displayName": "Optimistic",
      "image": "http://example.org/moods/optimistic.png"
    }
  }

5.3.  Rating

A rating given as a number between 1.0 and 5.0 inclusive with one decimal place of precision. Represented in JSON as a property called rating whose value is a JSON number giving the rating.

Ratings are generally most useful only for particular types of objects, such as audio, video, photos and places.

For example:

  {
    "objectType": "review",
    "content": "This is a great product",
    "rating": 3.5
  }

5.4.  Source

The source property provides a reference to the original source of an object or activity. The value of the source property is an Object of any object type.

The source property is closely related to the generator and provider properties but serves the distinct purpose of identifying where the activity or object was originally published as opposed to identifying the applications that generated or published it.

For example:

  {
    "actor": {
      "objectType": "person",
      "displayName": "Joe"
    },
    "verb": "post",
    "object": {
      "objectType": "photo",
      "image": "http://example.org/photos/fluffycat.jpg"
    },
    "source": {
      "objectType": "collection",
      "displayName": "Joe's Photo's",
      "url": "http://example.org/joes/photos"
    }
  }

5.5.  Tags

A listing of the objects that have been associated with a particular object using the tag verb. Represented in JSON using a property named tags whose value is an Array of objects.

For example:

  {
    "objectType": "photo",
    "image": "http://example.org/photos/fluffycat.jpg",
    "tags": [
      {
        "objectType": "person",
        "displayName": "John"
      },
      {
        "objectType": "person",
        "displayName": "Jane"
      }
    ]
  }

6. Normative References

Appendix A.  Acknowledgements

...

Authors' Addresses