Activity Base Schema (Draft)

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

Table of Contents

1.  Introduction
    1.1.  Notational Conventions
2.  Verbs
3.  Object Types
    3.1.  Audio and Video Objects
    3.2.  Binary Objects
    3.3.  Event
    3.4.  Issue
    3.5.  Place
    3.6.  Task
4.  Base Extension Properties
    4.1.  Context
    4.2.  Location
    4.3.  Mood
    4.4.  Rating
    4.5.  Result
    4.6.  Source
    4.7.  Starting and Ending Timestamps
    4.8.  Tags
5.  Multi-page Collections
6.  External Vocabularies
    6.1.  "dc"
    6.2.  "geojson"
    6.3.  "ld"
    6.4.  "links"
        6.4.1.  Link Objects
    6.5.  "odata"
    6.6.  "opengraph"
    6.7.  "schema_org"
7.  Normative References
§  Authors' Addresses

1.  Introduction

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

1.1.  Notational Conventions

This specification allows the use of IRIs (Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005.) [RFC3987]. Every URI (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [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] (Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005.). When an IRI is serving as an identifier, it MUST NOT be so mapped.

Unless otherwise specified, all properties specifying date and time values MUST conform to the "date-time" production in [RFC3339] (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.). In addition, an uppercase "T" character MUST be used to separate date and time, and an uppercase "Z" character MUST be present in the absence of a numeric time zone offset.

2.  Verbs

This specification defines the following core verbs in addition to the default post verb that is defined in Section 6 of [activitystreams] (Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson, M., and R. Dolin, “JSON Activity Streams 1.0,” May 2011.):

3.  Object Types

The table contains the core set of common objectTypes in addition to the activity objectType defined in Section 7 of [activitystreams] (Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson, M., and R. Dolin, “JSON Activity Streams 1.0,” May 2011.).

All Activity Stream Objects inherit the same fundamental set of basic properties as defined in section 3.4 of [activitystreams] (Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson, M., and R. Dolin, “JSON Activity Streams 1.0,” May 2011.). In addition to these, objects of any specific type are permitted to introduce additional optional or required properties that are meaningful to objects of that type.

3.1.  Audio and Video Objects

In addition to the core properties shared by all Activity Streams Objects, "audio" and "video" objects MAY contain the following properties:

3.2.  Binary Objects

The "binary" object type is used to carry arbitrary Base64-encoded binary data within an Activity Stream object. It is primarily intended to attach binary data to other object types through the use of the "attachments" property.

In addition to the core properties shared by all Activity Streams Objects, "binary" objects MAY contain the following properties:

Note that the binary and file objectTypes are conceptually related. The key difference between the two lies in the fact that the file objectType is more representative of the abstract description of a file or document while the binary objectType represents the actual, concrete stream of octets that make up the content.

Because of their close relationship, it is possible for the file objectType to share the same basic properties as the binary objectType. That is, a file MAY also have properties such as length, mimeType, and md5.

3.3.  Event

In addition to the core properties shared by all Activity Streams Objects, "event" objects MAY contain the following properties:

3.4.  Issue

In addition to the core properties shared by all Activity Streams Objects, "issue" objects MAY contain the following properties:

3.5.  Place

In addition to the core properties shared by all Activity Streams Objects, "place" objects MAY contain the following properties:

The properties for the position property are:

Note that in older versions of this specification, the value of the position property was represented as an ISO 6709 compliant String. For instance "position":"+27.5916+086.5640+8850/". This format has been deprecated and SHOULD NOT be used. However, there might be existing deployed applications still utilizing the ISO 6709. Consuming implementations can choose to continue supporting the ISO 6709 format but SHOULD NOT produce Activity Streams that use the deprecated format.

The properties for the address property are:

3.6.  Task

In addition to the core properties shared by all Activity Streams Objects, "task" objects MAY contain the following properties:

4.  Base Extension Properties

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

4.1.  Context

The basic model for an Activity provides properties that allow the expression of who (actor) performed the action, what (object) was acted upon, the action (verb) that was taken, and to what the action was directed (target). The additional context property allows the Activity to further include information about why a particular action occurred by providing details about the context within which a particular Activity was performed. The value of the context property is an Object of any objectType. The meaning of the context property is only defined when used within an Activity object.

For example, the following Activity uses the context property to reference the specific reasons a particular article object has been flagged as being inappropriate:

  {
    "actor": {
      "objectType": "person",
      "displayName": "Joe"
    },
    "verb": "flag-as-inappropriate",
    "object": {
      "objectType": "article",
      "displayName": "An article about stuff"
    },
    "context": {
      "objectType": "issue",
      "displayName": "Terms of Use Violation",
      "url": "http://.../terms-of-use",
      "types": [
        "http://example.org/codes/inappropriateMaterial",
        "http://example.org/codes/copyrightViolation"
      ]
    }
  }

4.2.  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": {
        "altitude": 8848.00,
        "latitude": 27.9881,
        "longitude": 86.9253
      }
    }
  }

4.3.  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"
    }
  }

4.4.  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
  }

4.5.  Result

The result provides a description of the result of any particular activity. The value of the result property is an Object of any objectType. The meaning of the result property is only defined when used within an Activity object.

For instance:

  {
    "actor": {
      "objectType": "person",
      "displayName": "Joe"
    },
    "verb": "complete",
    "object": {
      "objectType": "http://example.org/Exam",
      "displayName": "The Big Exam"
    },
    "result": {
      "score": 123,
      "duration": "P1H",
    }
  }

Use of the result property is only applicable with certain combinations of verbs and objectTypes. In many cases, the result will be implicit in the combination of actor, verb and object used -- for example, in an activity where a person, Joe, creates an article, the result of the activity is clear without the need to specify a separate result property.

4.6.  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 objectType.

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"
    }
  }

4.7.  Starting and Ending Timestamps

When an long running Activity occurs over a distinct period of time, or when an Object represents a long-running process or event, the startTime and endTime properties can be used to specify the date and time at which the activity or object begins or concludes. The values for each are represented as JSON Strings conforming to the "date-time" production in [RFC3339] (Klyne, G., Ed. and C. Newman, “Date and Time on the Internet: Timestamps,” July 2002.).

For example:

  {
    "actor": {
      "objectType": "person",
      "displayName": "John Doe"},
    "verb": "at",
    "object": {
      "objectType":"place",
      "displayName":"Home"},
    "published": "2012-08-28T03:34:23Z",
    "startTime": "2012-08-12T12:13:14Z",
    "endTime": "2012-08-13T01:34:12Z"
  }

The startTime and endTime verbs can be used independently or together. If both are specified, the endTime property MUST specify a moment in time that is more recent that that specified by the startTime property.

4.8.  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"
      }
    ]
  }

5.  Multi-page Collections

A multi-page collection is a set of linked collection objects that together contain the complete set of objects that can be considered to be members of the collection.

When using multi-paged collections, the following additional properties can be used in addition to the core collection properties defined in section 3.5 of [activitystreams] (Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson, M., and R. Dolin, “JSON Activity Streams 1.0,” May 2011.).

The value of the links property is an object as defined in Section 6.4 ("links"). The properties of the object are Registered or Extension Link Relations as defined by [RFC5988] (Nottingham, M., “Web Linking,” October 2010.). The following Registered Link Relations are identified as having specific purpose for use with Multi-page Collections:

For example, one page of a multi-page collection:

  {
    "totalItems": 12,
    "itemsPerPage" : 10,
    "startIndex": 10,
    "links": {
      "self": {"href":"http://example.org/items?page=1"},
      "next": {"href":"http://example.org/items?page=2"},
      "prev": {"href":"http://example.org/items?page=3"},
      "current": {"href":"http://example.org/items"}
    },
    "items" : [
      {
        "objectType": "person",
        "displayName":"Joe"
      },
      {
        "objectType": "person",
        "displayName":"Sally"
      }
    ]
  }

Note that, as the example illustrates, the totalItems property specifies the total number of items that can be considered to be a part of the collection as a whole, while the itemsPerPage indicates the maximum number of objects that will be included in this particular subset. The actual number of objects included in the value of the items properly can be equal to or less than either of these values.

6.  External Vocabularies

Any object within an Activity Streams object can be extended with additional properties not defined by the core Activity Streams (Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson, M., and R. Dolin, “JSON Activity Streams 1.0,” May 2011.) [activitystreams] specification or this document. Such extension properties can be specific to individual applications or be drawn from other defined vocabularies such as that defined by the Schema.org organization and others.

When utilizing such vocabularies, it is possible that conflicts in the naming of properties and format of expected values might arise. To mitigate the risk of such conflicts, the following guidelines SHOULD be followed:

1. When selecting the objectType for an object, if there is a close equivalent objectType already defined by this specification, then that objectType SHOULD be used.
2. When properties specific to an external vocabulary are to be included within an object, those SHOULD be grouped together under a single "namespace" property whose name is uniquely reflective of the vocabulary.
3. When including properties from the external vocabulary, avoid properties that are a close semantic match to existing properties defined by this or the core Activity Streams (Snell, J., Atkins, M., Norris, W., Messina, C., Wilkinson, M., and R. Dolin, “JSON Activity Streams 1.0,” May 2011.) [activitystreams] specification. For example, within the Schema.org vocabulary, the properties name, description, url and image are semantically equivalent to core Activity Streams object properties and therefore SHOULD NOT be used.
4. Further, avoid utilizing properties from multiple external vocabularies that are similar or semantically equivalent to each other.

This specification defines the following initial set of "namespace" properties that correspond to specific external vocabularies currently considered to be reasonable candidates for use within Activity Streams objects. Future versions of this specification might add additional "namespace" properties to this list. Implementors are free to define additional "namespace" properties representing other external vocabularies as necessary; however, there is a risk of potential conflicts if multiple independent implementors select the same "namespace" property to represent different external vocabularies. To help prevent such conflicts, it is RECOMMENDED that implementors publicly document their use of external vocabularies.

6.1.  "dc"

The dc "namespace" property is defined to encapsulate the set of extension properties that represent information specific to the Dublin Core Metadata Initiative. If, for instance, Dublin Core properties can be applied to an Activity Streams object, those properties SHOULD be grouped together under the dc property.

For example:

  {
    "objectType": "file",
    "displayName": "A Document",
    "fileUrl": "http://example.org/foo.html"
    "dc": {
      "format": "text/html; charset="UTF-8"
    }
  }

6.2.  "geojson"

The geojson "namespace" property is defined defined to encapsulate the set of extension properties that represent information specific to an GeoJSON data type. If, for instance, GeoJSON properties can be applied to an Activity Streams object, those properties SHOULD be grouped together under the geojson property.

For example:

  {
    "objectType": "place",
    "displayName": "A GeoJSON Described Place",
    "geojson": {
      "type": "FeatureCollection",
      "features": [
        {"type": "Feature",
         "geometry": {
           "type": "Point",
           "coordinates": [102.0, 0.5]
         },
         "properties": {
           "prop0": "value0"}
         },
         {"type": "Feature",
          "geometry": {
            "type": "LineString",
            "coordinates": [
              [102.0, 0.0],
              [103.0, 1.0],
              [104.0, 0.0],
              [105.0, 1.0]
            ]
          },
          "properties": {
            "prop0": "value0",
            "prop1": 0.0
          }
        },
        {"type": "Feature",
         "geometry": {
           "type": "Polygon",
           "coordinates": [
             [[100.0, 0.0],
              [101.0, 0.0],
              [101.0, 1.0],
              [100.0, 1.0],
              [100.0, 0.0]]]
           },
           "properties": {
             "prop0": "value0",
             "prop1": {"this": "that"}
           }
         }
      ]
    }
  }

6.3.  "ld"

The ld "namespace" property is defined to encapsulate the set of extension properties that represent information specific to the JSON Linked Data vocabulary. If, for instance, Linked Data properties can be applied to an Activity Streams object, those properties SHOULD be grouped together under the ld property.

For example:

 {
   "objectType": "person",
   "displayName": "John Doe",
   "ld": {
     "@context": "http://json-ld.org/contexts/person.ld",
     "@id": "http://example.org/john.doe",
     "born": "1929-12-12"
   }
 }

6.4.  "links"

The links "namespace" property is defined to encapsulate the set of extension properties that represent links to external resources. Property names are defined as being either Registered or Extension Link Relation Types as defined by [RFC5988] (Nottingham, M., “Web Linking,” October 2010.). The list of currently known Registered Link Relations can be found within the IANA Registry of Link Relations.

For example:

  {
    "objectType": "note",
    "displayName": "This is a simple note",
    "links": {
      "canonical": {
        "href":"http://www.example.org/notes/123"
      },
      "edit": {
        "href":"http://www.example.org/api/notes/123"
      }
    }
  }

The value of each property within the links object is either a single Link Object as defined in Section 6.4.1 (Link Objects) or an array of Link Objects in the case where multiple links with the same Link Relation must be specified.

When the value is specified as an array of Link Objects, the ordering of values within the array is considered insignificant. Each contained value is to be treated as a separate link. An array SHOULD NOT contain multiple Link Objects specifying the same href value.

When using extension link relation types, the property name can be specified as an IRI (Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005.) [RFC3987] but MUST be converted to URIs (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” January 2005.) [RFC3986] when compared and dereferenced as required by Section 4.2 of [RFC5988] (Nottingham, M., “Web Linking,” October 2010.).

As defined in Section 3 of [RFC5988] (Nottingham, M., “Web Linking,” October 2010.), such properties can be viewed as statements of the form "The containing object has a {relation type} resource at {target IRI}" where the {relation type} is identified by the property name, and the {target IRI} is provided by the property value.

6.4.1.  Link Objects

All links are expressed as JSON objects that MUST contain an href property whose value is an absolute IRI (Duerst, M. and M. Suignard, “Internationalized Resource Identifiers (IRIs),” January 2005.) [RFC3987] providing the target of the link. The object MAY contain the following additional properties:

Link Objects MAY contain an objectType property with the value link.

Additional properties MAY be specified but are undefined by this specification.

6.5.  "odata"

The odata "namespace" property is defined to encapsulate the set of extension properties that represent information specific to the OData specification. If, for instance, OData properties can be applied to an Activity Streams object, those properties SHOULD be grouped together under the odata property.

For example:

 {
   "objectType": "person",
   "displayName": "John Doe",
   "odata": {
     "__metadata": { ... },
     "com.example.user.kind" : "PAID",
     "CustomerID": "JDOE",
     "UserName": "jdoe",
   }
 }

6.6.  "opengraph"

The opengraph "namespace" property is defined to encapsulate the set of extension properties that represent information specific to an OpenGraph data type. If, for instance, OpenGraph properties can be applied to an Activity Streams object, those properties SHOULD be grouped together under the opengraph property.

For example:

  {
    "objectType": "person",
    "displayName": "John Smith",
    "opengraph": {
      "username": "john_smith",
      "verified": false,
      "relationship_status": "Single"
    }
  }

6.7.  "schema_org"

The schema_org "namespace" property is defined to encapsulate the set of extension properties that represent information specific to a Schema.org data type. If, for instance, Schema.org properties can be applied to an Activity Streams object, those properties SHOULD be grouped together under the schema_org property.

For example:

  {
    "objectType": "person",
    "displayName": "John Smith",
    "schema_org": {
      "additionalType": ["http://schema.org/Person"]
      "birthDate": ["1976-12-23"],
      "gender": ["Male"]
    }
  }

7. Normative References

Authors' Addresses