Profiles

An xAPI Profile is a collection of statement templates and patterns. Each xAPI statement must have a statement template to describe when it will be used and what data is required. Relationships between xAPI statements may be described with patterns.

Profile Creation

In order to create a profile, there must be a working group to administer the profile. Profile creation may be done from the working group's profile list page or from the profile list page. If profile creation is started from the profile list page, a working group must be selected or created before continuing.

There are three ways to create a profile on the server; by manually creating the profile using the server interfaces, through upload of a JSON-ld document using the server interfaces, or via the create/import API.

To manually create or upload a JSON-ld document, the following fields must be completed:

• IRI
• Profile Name
• Profile Description

An external IRI which will be hosted by the working group pointed to the profile server or use a server generated IRI.

A server generated IRI will contain less descriptive information in the IRI, an external IRI is recommended.

The profile IRI may only be changed before the first version of the profile is published, while the profile's version 1 is in draft state. In the case of a JSON-ld upload, the data entered in the fields must match the JSON-ld document.

It is recommended that a link be provided to documentation as the profile server holds the data requirements and definitions. It does not provide the implementation guidance required to make good and consistent decisions about how a profile should be used.

Tags are used for search and recommended to help people find relevant profiles.

Profile Publishing

Once the profile has been created it goes into draft state. This draft document is only available to members of the working group until it is published. While in 1st draft state, all profile data may be changed. After the first version is published, the profile IRI may no longer be changed. If a profile requires a different IRI after the first version is published, a new profile must be created.

Publishing the First Version

This is the FINAL chance to change the profile IRI and the acknowledgement checkbox must be selected in order to proceed publishing. Only after selecting the publish button on a profile, in the first version draft state, will this message be seen.

Profile Verification

In order to help people find the most authoritative profiles quickly, the server has a profile verification feature. A profile verification request may be sent to the server administrator for the current published version of a profile.

After the server administrator reviews the profile, an email confirms the profile verification or denies the verification with an explanation from the server administrator as to why the profile cannot be verified.

Statement Templates

Statement templates provide a set of instructions for what data is required in an xAPI statement which describes a particular event. There should be corresponding documentation describing instructional design considerations and implementation decisions for each statement template.

Add Existing Statement Template

When adding statement templates to a profile, statement templates from other profiles should be selected for reuse in the profile. After selecting the button to add a statement template, the next screen is a search screen to look for existing statement templates. If no existing statement templates meet the profile needs, the create new button may be used to write a new statement template.

Create New Statement Template

A new statement template requires an IRI. There are two options for the IRI field. An external IRI may be used or a system generated IRI may be selected. Using a generated IRI, the IRI field is pre-populated with the IRI selected for the profile as a root, to which a statement identifier may be appended. Statement name and description are required.

Add Statement Example

A valid xAPI statement example should be pasted into this field and saved. Invalid xAPI statements will not be stored.

Add determining properties

Determining properties are used to identify which statements will be validated, to which statement templates. This mapping is required because xAPI statements do not include statement template IDs. All selected determining properties must be included in an xAPI statement to be validated to the statement template.

Only one identifier may be selected for the following determining properties:

• verb
• objectActivityType

Multiple identifiers may be selected for the following determining properties:

• contextCategoryActivityType
• contextGroupingActivityType
• contextOtherActivityType
• contextParentActivityType
• attachmentUsageType

Add Rules

A rule describes the data requirements for a statement to be validated to the statement template. Rules have a huge amount of flexibility. In order to allow this flexibility to be used as the specification designed, rules must be written as JSON. To begin, the location for the rule is selected.

Once the location within the statement is selected, an editor is opened with instructions for how to use the different types of rules and examples of valid rules which use them. The location may be further edited at this point to describe an even more specific part of a statement.

The following instructions are included in the server:

There are two ways to set rules for a statement. One is through presence and the other through specifying values. Presence describes which locations in an xAPI statement are important to the statement. If the goal is to receive data in a specific location, but it is not important what data is to be in the location, "presence": "included" is the best way to do that.

Presence

Presence describes whether a specified location should be used to conform to this template.

• included, the location must be present with a value in every statement to conform to this template
• excluded, this location should not be in any statement to conform to this template
• recommended, this location should be present, but it will not fail validation to this template if it is excluded

Example of Presence:

"rules": [
  {
    "location": "context.contextActivities.grouping[*].id",
    "presence": "included"
  }
]

In this example, a statement must include an ID for every activity in the context activities grouping array in order to conform to this statement template.

RuleSpecifying Values

If just saying whether or not a location should be in the statement is not enough, the following may be used to identify which data will allow a statement to validate to this template.

• any, any of the values listed are allowed to be in the specified location in order for a statement to validate to a template. When any is used, a list of potential values must be included. A statement will validate to this template if at least one of the values listed is included in the specified location in the template.
• all, all of the values in the specified location must be listed in the all array in order for a statement to validate to a template. When all is used, a list of values must be included. A statement will validate if ALL of those values are present in the statement.
• none, none of the values listed are allowed to be in the specified location in order for a statement to validate to a template. When none is used, a list of potential values must be included. A statement will validate to this template if none of the values listed is included in the specified location in the template.

Example of using any:

"rules": [
  {
    "location": "context.contextActivities.grouping[*].definition.type",
    "any": ["http://adlnet.gov/expapi/activities/attempt"]
  }
]

In this example, a statement can use the activity type of "http://adlnet.gov/expapi/activities/attempt" as the definition of type for context activities grouping as at least one of the provided definition types and the statement will conform to this statement template.

Scope notes should be added to describe usage and implementation details to clarify the intent of the rule in practice.

Once a rule is written, it will be validated before it can be added to the statement template. The following validation errors may present themselves:

• Improper JSON
• Unknown identifier
• Conflict with determining properties
• Value not allowed

Once a rule is successfully validated, it may be added to the statement template.

Associated Concepts

As concepts are defined for use in determining properties and rules, they are added to the list of associated concepts. This section is intended to give an overview of the vocabulary used in the statement template.

Statement Template References

When similar statement templates exist, but they are not suitable for use as they are written, they may be referenced. This allows people implementing the statement template a way to understand the similarities. This also helps with linking like statement templates together.

Concepts

Concepts are building blocks for use and reuse in xAPI data and other Profiles. In the case of Verbs, Activity Types, Attachment Usage Types, and Activities, the Concept is "the thing", and when you use that Concept in xAPI you're using it directly. In the case of Document Resources and Extensions, the Concept is "the shape of the thing" that the identifier can be used to point at, and will be used with many different values of xAPI data.

Reusing Concepts from Other Profiles

Selecting concepts which have been defined by other profiles is the simplest way to use them in the current profile. Reusing concepts is better for interoperability than creating new niche concepts. When a concept has been defined by a profile, that profile is the owner of the concept and responsible for the concept's management.

Create a New Concept

Many concepts have different data requirements. When existing concepts aren't a match, in order to create a new concept, first select the type of concept to create.

If a concept is created in error, the concept can be edited before the profile is published. Concepts cannot be deleted, but they can be deprecated after publishing.

Create an Activity

A new activity requires an IRI, and there are two options for the IRI field. An external IRI may be used or a system generated IRI may be selected. Using a generated IRI, the IRI field is pre-populated with the IRI selected for the profile as a root, to which an activity identifier may be appended. The activity name, description, and activity type are required.

If the activity has an activity type which is unknown to the server, the activity type must be created before the activity may be created.

Activity Type, Attachment Usage Type, Verb

There are two options for the IRI field. An external IRI may be used or a system generated IRI may be selected. Using a generated IRI, the IRI field is pre-populated with the IRI selected for the profile as a root, to which an identifier may be appended. Name and description are also required.

Document

The IRI field is required, with two options for the IRI field. An external IRI may be used or a system generated IRI may be selected. Using a generated IRI, the field is pre-populated with the IRI selected for the profile as a root, to which an identifier may be appended. Name, description, document resource type, and media type are also required. Schema is required and may be an IRI to or a string describing the JSON Schema for the document.

Extension

The IRI field is required, with two options for the IRI field. An external IRI may be used or a system generated IRI may be selected. Using a generated IRI, the field is pre-populated with the IRI selected for the profile as a root, to which an identifier may be appended. Name, description, and extension type are also required. Schema is required and may be an IRI to or a string describing the JSON Schema for the document.

Patterns

Patterns describe groups of Statements matching particular Statement Templates, ordered in certain ways. For example, a Pattern in a video Profile might start with a Statement about playing a video and then be followed by Statements about pausing, skipping, playing again, and so forth.

When adding patterns, the first option is to reuse existing patterns from other profiles. One or more may be selected via search and added to the profile. If no existing patterns match the profile's needs, a new pattern may be created.

Create a New Pattern

The first step in creating a new pattern is selecting the type of pattern. When considering the pattern type, it is important to know if this will be a primary or secondary pattern. Designating the pattern primary or secondary will be done on the next screen. The only time a pattern may be selected as a component of another pattern is when it is a secondary pattern.

Primary

Primary patterns define which combinations of statements have meaning to a profile. A primary pattern cannot be pulled into other patterns. Each statement received with this profile ID will be checked for conformance to this pattern.

Secondary

Contains statement templates and secondary patterns. Statements received which contain this profile ID will not be checked for conformance to this pattern, unless it is pulled into the primary pattern for this profile.

The following pattern types exist:

• Sequence - A list of statement templates or secondary patterns in a particular order. This will match if the identified components match in the order specified. This type allows selection of multiple components and ordering of them in a three step process.
• Alternates - A list of statement templates or secondary patterns. This will match if any component from the list matches. This type allows selection of multiple components, but not ordering because alternates are interchangeable with one another.
• Optional - Identifies a single statement template or secondary pattern. This will match if the component is not present once or not at all. This type allows selection of a single component which is not required, but may be used once, for a pattern to be considered complete.
• One or More - Identifies a single statement template or secondary pattern. This will match if the component is present one or more times. This type allows selection of a single component which must be used once and may be used more for a pattern to be considered complete.
• Zero or More - Identifies a single statement template or secondary pattern. This will match if the component is not present or is present one or more times. This type allows selection of a single component which is not required, but may be used multiple times, for a pattern to be considered complete.

Sequence Patterns

The IRI field is required, with two options for the IRI field. An external IRI may be used or a system generated IRI may be selected. Using a generated IRI, the field is pre-populated with the IRI selected for the profile as a root, to which an identifier may be appended. Name, description, and primary or secondary type selection are required.

If the sequence is set as a primary pattern, the component search will return secondary patterns and statement templates to be included in the pattern. If the pattern is set as secondary, only statement templates and secondary patterns will be returned by the search as well.

Once components are selected, the order requirements for the sequence are set by dragging-and-dropping components into order. Once the ordering of components is finalized, the pattern may be added to the profile.

Alternate Patterns

An alternate pattern allows for selection of multiple components, but does not require ordering.

Optional Patterns, One or More Patterns, and Zero or More Patterns

All of these patterns allow for selection of a single component per pattern. Often these patterns are secondary patterns included in a primary sequence pattern to allow for a consistent sequence which has some variation in the details of the activities which count.

Import

Statement Import may be initiated via the second button in the secondary header or from the statement templates page.

A properly formatted JSON file with a valid array of JSON statements can be uploaded and parsed by the server. The server limits statement uploads to 20 at a time. It will not reject uploads with more than 20; it will not store any beyond the first 20. Two examples are provided in Appendix A. Please note that the import function can take either a single statement, which starts and ends with "{" or an array of statements, which starts and ends with "[".

Once an import has been completed, the sub-navigation will show a new navigation item labeled "Import Queue" to allow the user to move between sections as they work through the imported data.

When a set of statements are imported, the first 20 are stored and their concepts are parsed. The concepts are then matched to known concepts on the server.

A complete, valid JSON-LD file can be imported through the ALIAS profile API. The API provides optimum handling of JSON-LD details and validation which are required for xAPI Profile specification conformance.

Per the xAPI Profile specification, Scope Notes are only allowed as a property for statement template rules. If you are importing a profile through the API with scope notes in other sections, the profile is not valid to the specification and will not be accepted.

Profile Maintenance

Each piece of data available during creation of a profile, statement template, concept, or pattern is editable until the profile version is published for the first time. However, once a statement template, concept, or pattern has been published, the only edit allowed is to add a translation. Statement templates, concepts, and patterns are intended to be reused, so a significant edit could alter someone else's profile. Therefore, edits are limited.

After a profile version is published it remains in a published state until an edit is made or a verified status is granted. When an edit is made to a published version, it is assigned a new version number and placed in a draft state. The profile's draft state is only visible to working group members, all other users only see published versions.

If a section is being edited by another working group member, the server will not allow another group member to edit the section until all changes have been saved. When this happens, the message below will be shown.