Contact Us Support Forum Get Email Updates
 
 

Thanks! Someone will be in touch with you shortly.

Rather just email us? Email us here.
Rather speak with someone in person?
Call any time with Experience API questions:

866.497.2676

Deep Dive: Verbs

Posted by

Categories: Best Practices, Deep Dive, Statement Anatomy, Statements, xAPI

Posted 20 June 2013

 

Experience API Deep Dive: Verbs

In continuing with our “Anatomy of a xAPI Statement” series, here’s the next installment — verbs. In this post, I’ll tell you a lot about how verbs work with the Experience API. If you have any questions at all, please leave them in the comments below, or contact us here.

Inclusion in Statements

Verbs are a required part of statements and including them is simple enough. Set a Verb object into the “verb” property of a statement to indicate the action being taken for a given experience. A Verb object can consist only of an “id” property pointing to a URI (well, IRI). Here is an example:

{
    id: "http://adlnet.gov/expapi/verbs/experienced"
}


While that’s sufficient it seems people prefer something a little more akin to their own language, therefore Verbs should include a “display” property as well. The ‘display’ property’s value is a language map (a list of language codes with corresponding string values). Language maps are central to giving the xAPIAPI  internationalized data interoperability. Here is the same verb, but with a human readable display value:

{
    id: "http://adlnet.gov/expapi/verbs/experienced",
    display: {
        "en-US": "experienced"
    }
}

Additional language values can be easily added to the language map using the RFC 5646 language tags, “en-US” above is an example of American English.

History

Early in the specification process there was a pre-defined set of verbs. In the development of the 0.95 version of the specification that list moved to the object form with full URI for “id” and was moved out of the specification proper in favor of letting new verbs be created at will. ADL still maintains a list of verbs that are specifically designed for the learning community, though there is no reason those verbs can’t be used for other purposes as well. Verbs such as “attempted”, “experienced”, “passed”, “failed”, “answered”, and “completed” (in their URI form of course) match up well with previous standards and have become some of the most common used in xAPI so far. It is expected that communities of practice will evolve to create their own set of specific verbs known and used within a particular community. And the exception to the rule, since they all have one, there is one predefined verb included in the specification which serves the special purpose of voiding a statement. To void a statement send a new statement with this special verb having id “http://adlnet.gov/expapi/verbs/voided” along with a statement ref (more about these in a future post) to any LRS that may have received the statement.

Past Tense

Verbs should be past tense. xAPI is designed to track experiences which by their nature are time based, consequently verbs are past tense because a statement has to be recorded (note past tense) for the experience. No matter how soon after a recorded experience is reported on, that portion of the experience must already be in the past. (This is also one of the reasons why a statement no longer indicates something as “in progress”.) The concept of time passing as relates to streams of activities, potentially within the same experience, provides a significant amount of the complexity required to derive meaning from just a pile of statements, but at the same time provides the flexibility that allows content creators’ imaginations to flourish.

Resolvability

Verb IDs as URIs mean that many verbs can be resolved to a location (URL), and when they do they can provide additional meta information. The meta information should contain an object with a “name” and “description” properties, at least when requested as JSON, per the specification. These properties are used to provide information specifically about the verb rather than the representation of the verb itself (what the “display” property is for). This is a good start and as verbs and xAPI evolve we’ll have a way to extend the information surrounding verbs (and other items using URIs). The Internet purist in me says that because a Verb uses a URI and because I can pick a URI that can be a URL that I should, and that all verbs should resolve, but the specification (rightly so, cause I’m not always a purist) leaves it open that Verbs don’t have to resolve.

To Coin, or Not to Coin

It really isn’t a question! You should avoid coining new verbs except as a last resort. Okay, last resort may be a bit strong as early as xAPI adoption is, but eventually the set of verbs should move towards a fixed state. Consider the three required parts of a statement–actor, verb, object–only one of these, the verb, can be consistently matched across experiences for different people, or indicate different actions within an experience for the same actor. Those two dimensions are fundamental to reporting and don’t work if every new experience comes with a whole new set of verbs. This is where the community of practice comes in, verbs will gain traction through adoption. As verbs gain traction their common use allows system implementers to rely on their semantic meaning which is the foundation of the interoperability that a specification like xAPI seeks to provide. Statement creators should look for and leverage existing verbs whenever possible.

Registry

We’ve taken to calling a list of verbs (and other URI based components) a “registry,” and have implemented one, specifically The Registry where you can go to find Verbs that are being used in the wild. Right now it consists of the list of ADL verbs, but we are working on functionality (when not writing blog posts) to allow users to create new verbs through a curated process precisely to prevent the explosion of verb creation that could lead to less interoperability. Certainly we can’t prevent people from coining and using new verbs, and new verbs will be necessary over time, but we also want to help those verbs to be ever lasting (as they need to be since statements are) and that those ever lasting verbs will continue to resolve, so we’ve opened up the “id.tincanapi.com” domain namespace to be used for URI based ids. Verbs (and other items) created in The Registry will have resolvable URLs that will serve the meta data associated with them as defined by the specification.

Meanings, Not Words

Verbs are tough, and English (other languages do too I’m sure) does its best to make them tougher. So far we’ve said to reuse verbs when possible to allow interoperability, but we’ve also said there will be communities of practice that will adopt their own set of verbs. There is a conflict in these two best practices that arises because a single verb may have different meanings depending on context, a synonym if you will. To say it another way to stress the impact of this, Verb objects have an identifier that maps directly to a singular meaning, not to a specific word. It is the meaning therefore that must match when determining when a Verb object with a given ID can be reused in different cases.

“Fired” is a commonly cited one, probably because it is the one used by the specification. The word “fired” has very different meanings depending on the situation in which it is used. The specification calls out this fact and suggests that verb IDs be used to separate these meanings, the problem with that is how to demarcate the line. For instance are “fired a gun” and “fired a cannon” different verbs? One could argue that both are for the rapid expulsion of a projectile, so the same, similarly arguments can be made that the act of firing the two different instruments require significantly different skill sets, equipment, etc. which might make them different verbs. We are left with a gray (or is that grey?) area that will have to be filled in by systems consuming the statements and ultimately up to us fallible humans to step in and create meaning from difficult semantic relationships. Really only time and adoption can point us in the right direction when it comes to coining verbs and their synonyms.

To conclude, I mean to finish, I mean to sum up, I mean to wrap up… ah, the heck with it!

Go now, make statements!

 
  • Pingback: Deep Dive: 'object' - Experience API()

  • Pingback: Deep Dive: Activity - Experience API()

  • David

    I just checked the list and there are already 119 verbs; I’m hesitant to use this registry unless there is going to be some rigorous and disciplined curation into the top or preferred verbs. Shoudn’t there be fewer verbs, and if we want more details, have these as properties or traits of the objects?

  • Thanks for your comment. You raise a good point, about keeping the list of verbs as small as possible, but in the scheme of all trackable data points this list is still very small. The verbs in the current list fall into three categories,

    1) Vast majority are from the Activity Streams specification, a body of work that is already in existence and can be made to operate with xAPI relatively easily. Including the full set allows us to satisfy AS users while preventing even more verbs from cropping up specific to the xAPI space where an AS verb already captures the same meaning. We think there will be a lot of overlap so included them as early as possible.

    2) The ADL verbs, these were natural to include and number approximately 25.

    3) The rest (6-7) are a couple of verbs we thought made sense related to video handling that weren’t already included in the AS set, and some external submissions of verbs from at least one community member who is already using them. I personally have a list of about 30 more that I feel capture the existing space well, but I’ve not had a chance to cross check against the AS list yet.

    Without the AS verbs we’d be looking at closer to 40, but even still when you consider the number of verbs in just the English language (which is nearly impossible to accurately estimate) we have only a tiny slice defined.

    Having said all of that, we are working on tools that will allow slicing and dicing the lists in more manageable ways and allow communities to build lists of what they expect to use. Stay tuned for those developments landing very soon, thanks for reading!

  • Brian Miller

    Thanks for your comment. You raise a good point, about keeping the list of verbs as small as possible, but in the scheme of all trackable data points this list is still very small. The verbs in the current list fall into three categories,

    1) Vast majority are from the Activity Streamsspecification, a body of work that is already in existence and can be made to operate with xAPI relatively easily. Including the full set allows us to satisfy AS users while preventing even more verbs from cropping up specific to the xAPI space where an AS verb already captures the same meaning. We think there will be a lot of overlap so included them as early as possible.

    2) The ADL verbs, these were natural to include and number approximately 25.

    3) The rest (6-7) are a couple of verbs we thought made sense related to video handling that weren’t already included in the AS set, and some external submissions of verbs from at least one community member who is already using them. I personally have a list of about 30 more that I feel capture the existing space well, but I’ve not had a chance to cross check against the AS list yet.

    Without the AS verbs we’d be looking at closer to 40, but even still when you consider the number of verbs in just the English language (which is nearly impossible to accurately estimate) we have only a tiny slice defined.

    Having said all of that, we are working on tools that will allow slicing and dicing the lists in more manageable ways and allow communities to build lists of what they expect to use. Stay tuned for those developments landing very soon, thanks for reading!

  • Mario

    Hi, I’m confused with URI’s.

    The URI’s in verbs and Activity Types of Registry not resolve. For example, the URI for “experiencied” is “http://activitystrea.ms/schema/1.0/experience” and not resolve. However the URI “https://registry.tincanapi.com/#uri/verb/108” does solve. Is this correct? Should not resolve the first?

    On the other hand is there any diference or advice to use “http://adlnet.gov/expapi/verbs/experienced” and (“http://activitystrea.ms/schema/1.0/experience” or “https://registry.tincanapi.com/#uri/verb/108”)?

  • Brian Miller

    URis at “registry.tincanapi.com” should *NOT* be used in statements (ever) that is a URL to the location in registry where they can be accessed, not the URI of the id that will be resolvable. The Registry contains both URIs for verbs, etc. that are coined by another owner, specifically the owner of whatever domain they are at, for instance “activitystrea.ms” which is specific to the Activity Streams specification group. There isn’t an indication from the AS group that they will make their ids resolve. Identifiers specifically coined at The Registry as an open domain will always start with “id.tincanapi.com” and they will resolve, so for example:

    http://id.tincanapi.com/verb/called

    Has been added via The Registry interface and resolves to the meta data for that verb. ADL’s verbs also resolve:

    http://adlnet.gov/expapi/verbs/scored

    Which verb(s) used is up to the Activity Provider (the source of the statements), for APs targeting the Activity Streams specification they will want to use those items. For content targeting a different domain they’ll likely want to use others. Within the e-learning space most APs will probably want to default to the ADL supplied items and augment with others that are found in The Registry (or other places).

    Various communities of practice will likely come up with a standardized (or at least conventional) set of accepted terms within their domain, we call these profiles. For more about profiles check out: https://experienceapi.com/2013/01/15/its-time-for-profiles/. We’ll be releasing features on The Registry for building out these types of profiles very soon.

    Hope this helps, and let us know if you have any more questions, thanks,

    Brian

  • David

    Hi,
    i’m very new to xAPI, so please ignore my comment if its completely non sense.
    There are some verbs, which contain nouns/objects in it,
    i would interpret this a possible misconception. I think it indicates the lack of some further context information?
    For example the verbs: replied-to-tweet, cancelled_planned_learning

  • bsc_scorm

    Hi David,

    We prefer to avoid verbs like that as well, but we’ve included them in the registry since they’re part of the Activity Streams specification.

    Activity Streams and xAPI have many similarities, so we expect there to be demand for conversion between the two formats, or at least tools which use both. To make that sort of thing easier, and to avoid questions of “what’s the closest verb in the xAPI community to this AS concept”, we’ve included the AS verbs in the registry.

    That may not be relevant to everyone and to address that let me quote Brian’s earlier comment: “We are working on tools that will allow slicing and dicing the lists in more manageable ways and allow communities to build lists of what they expect to use. Stay tuned for those developments landing very soon, thanks for reading!”

  • Sreekanth

    Hi

    Can you please clarify couple of doubts?

    1. Who creates these statements, more specifically the verbs? For example, if I developing content from using an Adobe content authoring tool, and hosting it on say SumTotal LMS that supports LRS/ TinCan API, who should I check with for the support of the statement/verb I require?

    2. Can statement creation be a continuous activity? For example, if I decide to track “video pause points” at a later stage, after say 6 months of implementing TinCan API for my courses, is that possible without much hassles?

  • Brian Miller

    Thanks for the questions Sreekanth,

    1. Anyone can create (or “coin”) a new verb, though as a community it is best to leverage existing verbs where possible. Tools are and will be developed that extract meaning from statements, those statements will have to have more or less specificity depending on the tool. Statements that draw from a common vocabulary enable the widest possible use of a given tool, and is the reason we developed The Registry for registering all the various grammar elements.

    Statements on the other hand are created by Activity Providers and will fit for the format necessary for capturing the details of an experience which will vary widely. In your case the content would be the Activity Provider, the authoring tool has a pre-defined map of how interactions with your content will translate into Statement structure. For determining support you would need to check both with the authoring tool to see what types of statements it will produce (or just run the content against a sandbox LRS, for instance in SCORM Cloud) and with any reporting tools on what kinds of statements they expect to be generated.

    2. Yes and no. As systems evolve the range of statements generated for an experience is very likely to grow and/or change. It will be up to the tools used to draw the meaning from the pile of statements to anticipate and/or adapt to the changing model, as well as to understand and possibly support gaps in the knowledge. Statements are simply a representation of a single data point.

    In your example, a tool used to interpret the data stream coming from a video player would need to be outfitted such that it can understand (if only to ignore) the data before and after the pause points were added. It is also possible to retroactively record data points because of the ‘timestamp’ property of the statement, assuming you have the data in some non-Statement form. The amount of hassle then is highly dependent on the complexity of the data model used for capturing the experience, and the extent of adoption and control one has over adopters. For instance, for smart phone apps it may be relatively easy to re-outfit an app with a new generated statement through automated updates, but flight simulators at military installations would be more difficult though likely more controllable and narrower in population.

    A key to handling the re-outfitting is to allow for already existing legacy data as it will still exist. With the LRS to LRS transfers that xAPI enables and expects, trying to reach (to change) all existing data will likely be a non-starter.

    Hope this helps, let us know if you still have questions, thanks,

    Brian

  • Pingback: Deep Dive: Attachments - Experience API()

  • Phil

    If the Activity Streams specification already included a “completed” verb then why add an ADL one at all? I can understand the point about there being many verbs needed, but the overlap seems problematic.

  • Brian Miller

    I think this is historical from a time before the AS specification and the xAPI specification weren’t so closely aligned. Back in the days of 0.9 the verbs were a pre-defined set of words (rather than URIs). In the transition from 0.9 to 0.95 they switched from being words to URIs and the accepted set was opened up to any URI. To allow for easy development as relates specifically to e-learning the original pre-defined set of verbs moved to a set under ADL’s namespace such that other verbs that would normally fall outside of AS’s normal space didn’t have to go through their approval process. Essentially there is a full profile of verbs for capturing e-learning under ADL’s namespace.

  • Pingback: Crafting Statements: Choosing the Right Verb (Get to the Point) - Experience API()

  • CrisDeBlonde

    Hello,

    I’ve been struggling with the following issue for the past couple of days:
    Since “A Verb object can consist only of an “id” property pointing to a URI”, in a statement where the verb’s ‘display’ field is missing, whose responsibility is it to find a “suitable” display string? Is it the LRS that should have a type of “mapping” between verb ids and displays? (If so, then it should also keep populating it as the list in https://registry.tincanapi.com/ expands, or not?)
    Is this something outside the TC specs range?

    Thank you in advance

  • Brian Miller

    Technically, no one’s, a verb does not *have* to have a “display” property at all. It is just there to make it easier to implement human readable verbs. Having said that, an LRS may implement functionality that will provide it with a “fuller” canonical representation of a verb, such as making a call out to a 3rd party service such as a registry. It is also suggested that coiners of Verbs (and the various other terms) make the URIs resolvable to the metadata associated with that kind of term and LRSs could then resolve the URI to pull down additional information. (All of the terms created on our Registry do so automatically.) There is a specific “format” query parameter for the /statements resource that takes a “canonical” value to get this representation of statements, but how the LRS decides on the “canonical” representation is left out of the specification. There is also nothing stopping this from being handled by the Activity Provider (which may also be doing the querying) itself and ignoring what the LRS thinks.

    Hope this covers it,

    Brian

  • Ripulryu

    The verb list in the spec (https://registry.tincanapi.com/#home/verbs) is large enough to define any activity, however only a handful of these are recorded successfully in Scorm cloud, others are simply rejected, why ?

  • Brian Miller

    Can you provide an example that is failing? SCORM Cloud shouldn’t be rejecting a statement based on verb containing a valid URI, any in the Registry should work. Unless you are sending statements without an ‘X-Experience-API-Version’ header in which case it would be interpreted as a 0.9 spec statement.

  • CFK

    So I just found this:

    https://registry.tincanapi.com/#uri/verb/157

    Am I on drugs, or is this self-contradictory? I was under the impression that ‘object’ is just an alias for ‘target’. It seems like what the creator of this verb should have used ‘context’ instead of ‘target’. Is this totally insane of me?

    For that matter, is this registry still even a good idea to be using? I just submitted a verb I’m going to need for a project I’m working on, but I’m not sure whether it’s still being maintained.

  • Brian Miller

    Not sure about the drugs part, maybe :-). On the other questions, the verb in that case is an Activity Streams verb and would be used as such, so to understand how that verb would be applied it is important to look at the full Activity Streams specification which has distinctive handling for object/target. xAPI isn’t a direct mapping of AS and they have diverged in their aims, AS specifically targets social network streams of data, where xAPI targets e-learning. At the time of the development of the Registry it made sense to include the full AS vocabulary, and some terms are being used by specific profiles and Recipes so it makes sense to keep those terms as available for users of xAPI, but it should be recognized that they may not apply in all use cases.

    The Registry is still maintained and we are continuing to curate new submissions. It appears Andrew Downes replied to your submission, let us know if you have any more questions.

  • CFK

    Ayup, Andrew was very helpful 🙂 Thanks for your reply, this makes sense.

  • chromahoen

    Where should I submit new verbs for consideration for being added to the registry?

  • chromahoen

    Well, it appears that I have found it… https://registry.tincanapi.com/#submit