Data Model

Description

  The Statement is the core of the xAPI. All learning events are stored as Statements. A Statement is akin to a sentence of the form "I did this".

Statement Properties

  The details of each property of a statement are described in the table below.

Property Type Description Required
actor Object Who the Statement is about, as an Agent or Group Object. Represents the "I" in "I Did This". Required
verb Object Action of the Learner or Team Object. Represents the "Did" in "I Did This". Required
object Object Activity, Agent, or another Statement that is the Object of the Statement. Represents the "This" in "I Did This". Note that Objects which are provided as a value for this field should include an "objectType" field. If not specified, the Object is assumed to be an Activity. Required
result Object Result Object, further details representing a measured outcome relevant to the specified Verb. Optional
context Object Context that gives the Statement more meaning. Examples: a team the Actor is working with, altitude at which a scenario was attempted in a flight simulator. Optional
timestamp Date/Time Timestamp (Formatted according to ISO 8601) of when the events described within this Statement occurred. If not provided, LRS should set this to the value of "stored" time. Optional
authority Object Agent who is asserting this Statement is true. Verified by the LRS based on authentication, and set by LRS if left blank. Optional
attachments Array of attachment Objects Headers for attachments to the Statement. Optional
version Version The Statement's associated xAPI version. Optional
Requirements
  • A Statement MUST use each property no more than one time.
  • A Statement MUST use 「actor」, 「verb」, and 「object」.
  • A Statement MAY use its properties in any order.
Example
{
    "id": "12345678-1234-5678-1234-567812345678",
    "actor":{
        "mbox":"mailto:xapi@adlnet.gov"
    },
    "verb":{
        "id":"http://adlnet.gov/expapi/verbs/created",
        "display":{
            "zh-TW":"created"
        }
    },
    "object":{
        "id":"http://example.adlnet.gov/xapi/example/activity"
    }
}


Actor

A mandatory Agent or Group Object.

Agent Object

An Agent (an individual) is a persona or system.

Details
Property Type Description Required
objectType string "Agent". This property is optional except when the Agent is used as a Statement's object. Optional
name String Full name of the Agent. Optional
see Inverse Functional Identifier Required
Requirements
  • An Agent Object must contain Inverse Functional Identifiers of mbox.
  • An Agent MUST be identified by one of the four types of Inverse Functional Identifiers.
  • An Agent MUST NOT include more than one Inverse Functional Identifier;
  • An Agent SHOULD NOT use Inverse Functional Identifiers that are also used as a Group identifier.

Group Object

A Group represents a collection of Agents and can be used in most of the same situations an Agent can be used. There are two types of Groups, anonymous and identified.

Anonymous Group

An Anonymous Group is used describe a cluster of people where there is no ready identifier for this cluster, e.g. an ad hoc team.

Details
Property Type Description Required
objectType String "Group". Required
name String Name of the group. Optional
member Array of Agent Objects Required
Requirements
  • An Anonymous Group MUST include a 'member' property listing constituent Agents.
  • An Anonymous Group MUST NOT contain Group Objects in the 'member' property.
  • An Anonymous Group MUST NOT include any Inverse Functional Identifiers.

Identified Group

An Identified Group is used to uniquely identify a cluster of Agents.

Details
Property Type Description Required
objectType String Group Required
name String Name of the group. Optional
member Array of Agent Objects Optional
see Inverse Functional Identifier. Required
Requirements
  • An Identified Group MUST include exactly one Inverse Functional Identifier.
  • An Identified Group MUST NOT contain Group Objects in the 'member' property.
  • An Identified Group SHOULD NOT use Inverse Functional Identifiers that are also used as Agent identifiers.
  • An Identified Group MAY include a 'member' property listing constituent Agents.

Inverse Functional Identifier

  An "Inverse Functional Identifier" is a value of an Agent or Identified Group that is guaranteed to only ever refer to that Agent or Identified Group.

Details
Property Type Description Required
mbox mailto IRI The required format is "mailto:email address". Only email addresses that have only ever been and will ever be assigned to this Agent, but no others, should be used for this property and mbox_sha1sum. Required
mbox_sha1sum String The SHA1 hash of a mailto IRI (i.e. the value of an mbox property). An LRS MAY include Agents with a matching hash when a request is based on an mbox. Optional
openid URI An openID that uniquely identifies the Agent. Optional
account Object A user account on an existing system e.g. an LMS or intranet. Optional

Account Object

A user account on an existing system, such as a private system (LMS or intranet) or a public system (social networking site).

Details
Property Type Description Required
homePage IRL The canonical home page for the system the account is on. This is based on FOAF's accountServiceHomePage. Required
name String The unique id or name used to log in to this account. This is based on FOAF's accountName. Required
Example
{
  "objectType": "Agent",
  "account": {
      "homePage": "http://www.example.com",
      "name": "1625378"
  }
}


Verb

  The Verb in an xAPI Statement describes the action performed during the learning experience. The xAPI does not specify any particular Verbs. (With one exception, namely the reserved Verb 'http://adlnet.gov/expapi/verbs/voided'). Instead, it defines how to create Verbs so that communities of practice can establish Verbs meaningful to their members and make them available for use by anyone. A predefined list of Verbs would be limited by definition and might not be able to effectively capture all possible future learning experiences.

Details
Property Type Description Required
id IRI Corresponds to a Verb definition. Each Verb definition corresponds to the meaning of a Verb, not the word. The IRI should be human-readable and contain the Verb meaning. Required
display Language Map The human readable representation of the Verb in one or more languages. This does not have any impact on the meaning of the Statement, but serves to give a human-readable display of the meaning already determined by the chosen Verb. Recommended
Requirements
  • The display property MUST be used to illustrate the meaning which is already determined by the Verb IRI.
  • A system reading a Statement MUST use the Verb IRI to infer meaning.
  • The display property MUST NOT be used to alter the meaning of a Verb.
  • A system reading a Statement MUST NOT use the display property to infer any meaning from the Statement.
  • A system reading a Statement MUST NOT use the display property for any purpose other than display to a human. Using the display property for aggregation or categorization of Statements is an example of violating this requirement.
Example
{
    "id":"http://www.adlnet.gov/XAPIprofile/ran(travelled_a_distance)",
    "display":{
        "en-US":"ran",
        "es" : "corrió"
    }
}


Object

  The Object of a Statement can be an Activity, Agent/Group, Sub-Statement, or Statement Reference. It is the "this" part of the Statement, i.e. "I did this".

Activity ObjectType

A Statement may represent an Activity as the Object of the Statement. The following table lists the Object properties in this case.

Details
Property Type Description Required
objectType String MUST be "Activity" when present. Required
id IRI An identifier for a single unique Activity. Required
definition Object Metadata. Optional

definition

Details
Property Type Description Required
name Language Map The human readable/visual name of the Activity. Recommended
description Language Map A description of the Activity. Recommended
type IRI The type of Activity. Recommended
moreInfo IRL Resolves to a document with human-readable information about the Actiivty, which could include a way to launch the activity. Optional
Interaction properties, See: Interaction Activities
extensions Object A map of other properties as needed. Optional
Requirements
  • An Activity id MUST be unique.
  • An Activity id MUST always reference the same Activity.

Interaction Activities

Details
Property Type Description Required
interactionType String As in "cmi.interactions.n.type" as defined in the SCORM 2004 4th Edition Run-Time Environment. Optional
correctResponsesPattern An array of strings Corresponds to "cmi.interactions.n.correct_responses.n.pattern" as defined in the SCORM 2004 4th Edition Run-Time Environment, where the final n is the index of the array. Optional
choices | scale | source | target | steps Array of interaction components Specific to the given interactionType. Optional
Requirements
  • Interaction Activities MUST have a valid interactionType.

Interaction Components

Details
Property Type Description Required
id String Required
description Language Map Optional

The following table shows the supported lists of CMI interaction components for an interaction Activity with the given interactionType.

interactionType component
choice, sequencing choices
likert scale
matching source, target
performance steps
true-false, fill-in, long-fill-in, numeric, other [No component lists defined]
Requirements
  • Within an array of interaction components, all id values MUST be distinct.
  • An interaction component's id value SHOULD NOT have whitespace.

ObjectType - Agent or Group

Statements that specify an Agent or Group as an Object MUST specify an 'objectType' property.

ObjectType - Statement

There are two possibilities for using a Statement as an Object. First, an Object can take on the form of a Statement that already exists by using a Statement Reference. A common use case for Statement References is grading or commenting on an experience that could be tracked as an independent event. The special case of voiding a Statement would also use a Statement Reference. Second, an Object can be a brand new Statement by using a Sub-Statement. A common use case for Sub-Statements would be any experience that would be misleading as its own Statement. Each type is defined below.

Statement References

A Statement Reference is a pointer to another pre-existing Statement.

Details
Property Type Description Required
objectType String StatementRef Required
id UUID Statement 的 UUID Required
Requirements
  • A Statement Reference MUST specify an "objectType" property with the value "StatementRef".
Example
{
    "actor" : {
        "objectType": "Agent",
        "mbox":"mailto:test@example.com"
    },
    "verb" : {
        "id":"http://example.com/commented",
        "display": {
            "en-US":"commented"
        }
    },
    "object" : {
        "objectType":"StatementRef",
        "id":"8f87ccde-bb56-4c2e-ab83-44982ef22df0"
    },
    "result" : {
        "response" : "Wow, nice work!"
    }
}


Sub-Statements

A Sub-Statement is a new Statement included as part of a parent Statement.

Requirements
  • A Sub-Statement MUST specify an "objectType" property with the value "SubStatement".
  • A Sub-Statement MUST be validated as a Statement in addition to other Sub-Statement requirements.
  • A Sub-Statement MUST NOT have the "id", "stored", "version" or "authority" properties.
  • A Sub-Statement MUST NOT contain a Sub-Statement of their own, i.e., cannot be nested.
Example
{
    "actor": {
        "objectType": "Agent",
        "mbox":"mailto:test@example.com"
    },
    "verb" : {
        "id":"http://example.com/planned",
        "display":{
            "en-US":"planned"
        }
    },
    "object": {
        "objectType": "SubStatement",
        "actor" : {
            "objectType": "Agent",
            "mbox":"mailto:test@example.com"
        },
        "verb" : {
            "id":"http://example.com/visited",
            "display":{
                "en-US":"will visit"
            }
        },
        "object": {
            "id":"http://example.com/website",
            "definition": {
                "name" : {
                    "en-US":"Some Awesome Website"
                }
            }
        }
    }
}


Result

An optional field that represents a measured outcome related to the Statement in which it is included.

Details
Property Type Description Required
score Object The score of the Agent in relation to the success or quality of the experience. Optional
success Boolean Indicates whether or not the attempt on the Activity was successful. Optional
completion Boolean Indicates whether or not the Activity was completed. Optional
response String A response appropriately formatted for the given Activity. Optional
duration Formatted according to ISO 8601 with a precision of 0.01 seconds Period of time over which the Statement occurred. Optional
extensions Object A map of other properties as needed. Optional

Score

An optional field that represents the outcome of a graded Activity achieved by an Agent.

Details
Property Type Description Required
scaled Decimal number between -1 and 1, inclusive Cf. 'cmi.score.scaled' 於 SCORM 2004 4th Edition Recommended
raw Decimal number between min and max (if present, otherwise unrestricted), inclusive Cf. 'cmi.score.raw' Optional
min Decimal number less than max (if present) Cf. 'cmi.score.min' Optional
max Decimal number greater than min (if present) Cf. 'cmi.score.max' Optional
Requirements
  • The Score Object SHOULD include 'scaled' if a logical percent based score is known.
  • The Score Object SHOULD NOT be used for scores relating to progress or completion. Consider using an extension from an extension profile instead.

Context

An optional field that provides a place to add contextual information to a Statement. All properties are optional.

Details
Property Type Description Required
registration UUID The registration that the Statement is associated with. Optional
instructor Agent Instructor that the Statement relates to, if not included as the Actor of the Statement. Optional
team Group Team that this Statement relates to, if not included as the Actor of the Statement. Optional
contextActivities contextActivities Object A map of the types of learning activity context that this Statement is related to. Valid context types are: "parent", "grouping", "category" and "other". Optional
revision String Revision of the learning activity associated with this Statement. Format is free. Optional
platform String Platform used in the experience of this learning activity. Optional
language String (RFC 5646) Code representing the language in which the experience being recorded in this Statement (mainly) occurred in, if applicable and known. Optional
statement Statement Reference Another Statement, which should be considered as context for this Statement. Optional
extensions Object A map of any other domain-specific context relevant to this Statement. For example, in a flight simulator altitude, airspeed, wind, attitude, GPS coordinates might all be relevant. Optional
Requirements
  • The revision property MUST only be used if the Statement's Object is an Activity.
  • The platform property MUST only be used if the Statement's Object is an Activity.
  • The language property MUST NOT be used if not applicable or unknown.
  • The revision property SHOULD be used to track fixes of minor issues (like a spelling error).
  • The revision property SHOULD NOT be used if there is a major change in learning objectives, pedagogy, or assets of an Activity. (Use a new Activity id instead).

Registration Property

An instance of a learner undertaking a particular learning activity.

ContextActivities Property

There are four valid context types. All, any or none of these MAY be used in a given Statement:

  1. Parent:an Activity with a direct relation to the Activity which is the Object of the Statement. In almost all cases there is only one sensible parent or none, not multiple. For example: a Statement about a quiz question would have the quiz as its parent Activity.
  2. Grouping:an Activity with an indirect relation to the Activity which is the Object of the Statement. For example: a course that is part of a qualification. The course has several classes. The course relates to a class as the parent, the qualification relates to the class as the grouping.
  3. Category:an Activity used to categorize the Statement. "Tags" would be a synonym. Category SHOULD be used to indicate a "profile" of xAPI behaviors, as well as other categorizations. For example: Anna attempts a biology exam, and the Statement is tracked using the CMI-5 profile. The Statement's Activity refers to the exam, and the category is the CMI-5 profile.
  4. Other:a context Activity that doesn't fit one of the other fields. For example: Anna studies a textbook for a biology exam. The Statement's Activity refers to the textbook, and the exam is a context Activity of type "other".

  5. Requirements
  6. Every key in the contextActivities Object MUST be one of parent, grouping, category, or other.

  7. Every value in the contextActivities Object MUST be either a single Activity Object or an array of Activity Objects.
Example
{
    "parent" : [
        {"id" : "http://example.adlnet.gov/xapi/example/test1"}
    ],
    "grouping" : [
        {"id" : "http://example.adlnet.gov/xapi/example/Algebra1"}
    ]
}


Timestamp

The time at which the experience occurred.

Requirements
  • A timestamp MUST be formatted according to ISO 8601.
  • A timestamp SHOULD include the time zone.
  • A timestamp SHOULD be the current or a past time when it is outside of a Sub-Statement.
  • A timestamp MAY represent any point of time during the experience happened over a period of time.
  • A timestamp MAY be truncated or rounded to a precision of at least 3 decimal digits for seconds (millisecond precision MUST be preserved).
  • A timestamp MAY be a moment in the future, to denote a deadline for planned learning, provided it is included inside a Sub-Statement.

Authority

The authority property provides information about whom or what has asserted that this Statement is true.

Example
"authority": {
    "objectType" : "Group",
    "member": [
        {
            "account": {
                "homePage":"http://example.com/xAPI/OAuth/Token",
                "name":"oauth_consumer_x75db"
            }
        },
        {
            "mbox":"mailto:bob@example.com"
        }
    ]
}


Attachments

A digital artifact providing evidence of a learning experience.

Details
Property Type Description Required
usageType IRI Identifies the usage of this attachment. For example: one expected use case for attachments is to include a "completion certificate" Required
display Language Map Display name (title) of this attachment. Required
description Language Map A description of the attachment. Optional
contentType Internet Media Type The content type of the attachment. Required
length Integer The length of the attachment data in octets. Required
sha2 String The SHA-2 (SHA-256, SHA-384, SHA-512) hash of the attachment data. SHA-224 SHOULD not be used: a minimum key size of 256 bits is recommended. Required
fileUrl IRL An IRL at which the attachment data may be retrieved, or from which it used to be retrievable. Optional
Example
{
    "actor": {
        "mbox": "mailto:sample.agent@example.com",
        "name": "Sample Agent",
        "objectType": "Agent"
    },
    "verb": {
        "id": "http://adlnet.gov/expapi/verbs/answered",
        "display": {
            "en-US": "answered"
        }
    },
    "object": {
        "id": "http://www.example.com/tincan/activities/multipart",
        "objectType": "Activity",
        "definition": {
            "name": {
                "en-US": "Multi Part Activity"
            },
            "description": {
                "en-US": "Multi Part Activity Description"
            }
        }
    },
    "attachments": [
        {
            "usageType": "http://example.com/attachment-usage/test",
            "display": {"en-US": "A test attachment"},
            "description": {"en-US": "A test attachment (description)" },
            "contentType": "text/plain; charset=ascii",
            "length": 27,
            "sha2": "495395e777cd98da653df9615d09c0fd6bb2f8d4788394cd53c56a3bfdcd848a"
        }
    ]
}


results matching ""

    No results matching ""