Official verb extension method for DoD use of activity streams

[Nikolaus Hruska]

Hi:

We are using activity streams in the new DoD eLearning spec for Next
Generation SCORM. see my posts:
http://www.adlnet.gov/from-adl-team-member-nikolaus-hruska-using-activity-streams-in-next-generation-scorm

http://www.adlnet.gov/which-verbs-would-you-use-to-describe-learning

The use and extension of verbs is a hot topic. i've been searching
your project for a verb extension mechanism. is there a document you
can point me to so that i can bring informed decisions to the Tin Can
API Adopters Group:
https://groups.google.com/a/adlnet.gov/group/TinCanAPI-adopters/topics

Thanks for your help!

[James M Snell]

Verb extension is definitely an important topic that's been on my mind
quite a bit lately. The main challenge is bootstrapping the the use
and comprehension of new verbs. One mechanism that I have been
considering is allowing URI-based verbs to be dereferenced in order to
discover information about the verb.

For instance, taking an example from one of the links you mention...

"Nikolaus Completed CPR Training"

There currently is no "completed" verb in the base schema... There are
two options for representing the "completed" verb within the JSON
Activity Stream:

1. "verb":"completed"
2. "verb":"http://example.org/scorm/verbs/completed"

That is, either a simple label or as a fully-qualified IRI.

Using option 1, there's no real way to bootstrap the us of the verb.
An implementation either knows what it means or it doesn't. There's
really nothing else that can be done. Using option 2, however, we can
make it so that if an implementation does a GET request on the URL, it
can fetch a document that describes the verb...

GET /scorm/verbs/completed HTTP/1.1
Host: example.org

Returns...

HTTP/1.1 200 OK
Content-Type: application/json

{
"objectType": "verb",
"id":"http://example.org/scorm/verbs/completed",
"displayName": "Completed",
"summary": "Indicates that the actor completed the task identified
by the object",
"verbs": ["http://example.org/scorm/verbs/read", "play"]
}

This adds a degree of complexity to the overall model, yes, but it
allows verbs to be introduced in a decentralized way and allows
implementations to evolve, learning new verbs as they are used.

You also show the example:

1. Nikolaus Read Hamlet
2. Nikolaus Completed Hamlet

And ask how a system can know that these are potentially aliases of
one another. Note the "verbs" field in the example verb object I give
above. Here, we can list other verbs for which the defined verb can be
considered an alias. These can be extension verbs or registered verbs.
If they are extension verbs, the same GET discovery model can be
applied unless the verb is already known to the system.

It more detail is required, then we can provide more explicit detail:

{
"objectType": "verb",
"id":"http://example.org/scorm/verbs/completed",
"displayName": "Completed",
"summary": "Indicates that the actor completed the task identified
by the object",
"alias-of": ["http://example.org/scorm/verbs/read"],
"specialization-of": ["play"]
}

e.g. alias-of defines that "completed" is an alias of "read" but a
more specific form of "play"... This is just a strawman example but
hopefully the idea is clear.

Note that that I'm using the basic Activity stream object syntax to
represent the verb information. If an organization wish to, it can
publish and syndicate collections of extension verbs using the same
basic collection syntax used for Activity streams...

{
"totalItems": 2,
"items": [
{"objectType":"verb", ...},
{"objectType":"verb", ...}
]
}

It would even be possible to create an activity stream ABOUT verbs...

{
"totalItems": 2,
"items": [
{"verb":"created",
"actor":{"displayName":"tin can"},
"object":{"objectType":"verb",...}},
...
]
}

In this way, libraries of extension verbs can be defined and pushed in
to supporting implementations at once, providing a natural
extensibility model.

- James

> --
> You received this message because you are subscribed to the Google Groups "Activity Streams" group.
> To post to this group, send email to activity...@googlegroups.com.
> To unsubscribe from this group, send email to activity-strea...@googlegroups.com.
> For more options, visit this group at http://groups.google.com/group/activity-streams?hl=en.
>

[Martin Atkins]

A while back we discussed/prototyped a system somewhat like the activity
templates system that the Facebook API was using to allow a publisher to
include along with an activity feed information on how to render the
activity as a sentence.

I'm not sure I have my prototype code around anymore but basically what
it did was match on the verb and the object type of the object as the
key to a sentence template for a particular language, with the object
type optional to allow generic verb handling as a fallback. For example:

post, <null>: {actor} posted {object}
post, event: {actor} created an event: {object}

I'd imagined that an activity stream would link to its "templates file"
so that consumers can optionally retrieve it, cache it and use it to
provide an activity sentence for a verb that's otherwise unknown to the
consumer.

So I think this is basically a more presentation-oriented version of
what you've proposed here, not attempting to carry any machine-readable
semantics but rather just describing how to communicate a new verb to a
human.

At the time we'd dismissed this as too complicated for a first version
that was focused on social web activities, but now that there's interest
in using activity streams in other domains it might be a good time to
revisit something along these lines.

[James M Snell]

We've had similar requirements for a templating mechanism in our
implementation... in our approach, the implementation maintains a
templates file that provides a link from verb to template using a
generally identical syntax (i.e. {actor} posted {object} ) ... If the
activity had a title property, the system would use the title property
always; if there was no title property, then the matching template
from the local file would be used. This works reasonably well for an
initial implementation but obviously does not work for extension
verbs.

Expanding on the idea of having self-describing extension verbs...
imagine if when I do a GET on the verb IRI, I get back the verb
document like I describe with template data included directly
within... e.g.


{ ..., "verb": "http://example.org/verbs/complete", ...}


GET /verbs/complete HTTP/1.1
Host: example.org

HTTP/1.1 200 OK
Content-Type: application/json

{
"objectType": "verb",

"displayName": "Completed",
"id": http://example.org/verbs/complete",
...,
"templates": {
"title": {
"en-*": "{actor.displayName} completed {object.displayName}",
"fr-*": "{actor.displayName} terminé {object.displayName}"
}
}
}

In this, the "title-templates" value is an object whose keys are
RFC4647 lang tag ranges so we can provide proper localization of the
templates.

Thoughts?

-James

[@garemoko]

Hi James,

@garemoko form the Tin Can API group here.

Thanks so much for that - especially the mention of the alias of and specialization properties - really helpful.

Are those properties a fixed part of the activity stream spec or could you use any properties? Have you defined a way of defining the type of specialization or other relationships? e.g. 

unenrolled is the negation of enrolled

Was passed is the passive voice of passed

Excluded is the causative negation of enrolled

@garemoko

[@garemoko]

I'm not sure if my earlier message is still in the queue, but if not,
thanks so much for the really helpful replies.

I have a couple of questions:
Could you also add properties to explain in what way the verb is
specialised?
Do objects tend to support adding any property or have they got to be
predefined in the spec?

@garemoko

> >> <nikolaus.hruska....@adlnet.gov>  wrote:

>
> >>> Hi:
>
> >>> We are using activity streams in the new DoD eLearning spec for Next
> >>> Generation SCORM. see my posts:
>

> >>>http://www.adlnet.gov/from-adl-team-member-nikolaus-hruska-using-acti...

[James M Snell]

I had not scoped it out to that level of detail; and to be honest, not
everyone is going to require going to that extent. What would likely
be best is to define a bare minimal core "Verb" object and add in the
additional detail necessary via extension following a simple pattern
established by the core. I can write up that basic core. Beyond that,
I would look forward to seeing whatever extensions emerge.

> --
> You received this message because you are subscribed to the Google Groups
> "Activity Streams" group.

> To view this discussion on the web visit
> https://groups.google.com/d/msg/activity-streams/-/hVTVw55a9qcJ.