View on GitHub

xapi-profiles

A set of documents addressing the structure of and supporting services for xAPI Profiles.

xAPI Profiles

License

“Copyright 2017 Advanced Distributed Learning (ADL) Initiative, U.S. Department of Defense

Licensed under the Apache License, Version 2.0 (the “License”). You may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.”

This document was authored by the Data Interoperability Standards Consortium (DISC) under contract with ADL, reviewed and vetted by members of the xAPI Profiles Working Group in support of the Office of the Deputy Assistant Secretary of Defense (Readiness) Advanced Distributed Learning (ADL) Initiative. Please send all feedback and inquiries to helpdesk@adlnet.gov

Table of Contents

Part One: About xAPI Profiles

1.0 Introduction

The Experience API (xAPI) Profiles Specification is a technical document that aims to improve practices for creating Profiles as defined in the xAPI Specification. The xAPI Profiles Specification lays out a structure that describes profiles uniformly, describes how profiles can be discovered and reused, and how profiles can be published and managed.

Since the release of xAPI Version 1.0, institutions across industries employed xAPI to track learning experiences of individuals beyond formal, structured computer-based training. Now, as adoption of the xAPI specification expands, concerns about how adopters work with profiles to support semantic interoperability are apparent. How semantic interoperability has been addressed (and sometimes not) in practice, to-date, illustrates the set of challenges this documents aims to address. The challenges are assumed as follows:

  1. Data meant to reflect the same activity often doesn’t match. As xAPI champions data alignment from multiple sources, in practice many products create activity statements that are intended to reflect the same human activity, but are formatted different enough as to prove difficult to analyze correctly. This is because these varying learning activity providers don’t communicate effectively about how they express human activities with xAPI.

  2. Communities of Practice lack shared practices in their definitions of human activity, performance and outcomes. Communities of Practice at the scale of industry verticals (e.g. military, medical, compliance, trade groups, etc.) have historically approached measurement, even observation, of human activity in subjective, human-based terms. Our xAPI CoPs are often defining and storing their profiles in different ways and at different levels of granularity. Without consistency in how they are written and stored, it is challenging to make use of the profile data.

Therefore, the goals of the xAPI Profiles Specification are to

xAPI Profiles rely on linked data technologies to achieve these goals. If you are unfamiliar with linked data, the following article is recommended for all audiences (technical and not-as-technical):

Linked Data Explained: You’re No Dummy (2015)

“Linked data has been a hot topic lately for both web developers and librarians. But unless you are highly technical, many of the online definitions for linked data might make your eyes glaze over and wonder just what exactly is this thing everyone is talking about. Don’t worry - you are not a dummy. But computers definitely are, which is exactly why we need linked data on the web…”

2.0 How to Use This Document

This is a definitive document which describes how the xAPI Profiles are to be implemented. It is a technical document authored specifically for individuals and organizations implementing this technology with the intent of such individuals developing interoperable tools, systems and services that are independent of each other and interoperable with each other.

Whenever possible, the language and formatting used in this document is intended to be considerate of non-technical readers because various tools, systems and services are based on the specification set described below. For this reason, sections that provide a high-level overview of a given facet of the Experience API are labeled description or rationale. Items in this document labeled as requirements, details or examples are more technical.

This specification is split into three parts. Part one is this introduction. It offers some background, high-level summaries and direction on how to read the rest of the specification.

Part two of this specification defines a structure for the data objects used in this specification. This part helps to ensure that services implementing this specification follow a consistent data structure.

Part three of this specification sets out the communication methods that can be used when seeking information about xAPI Profiles among services that adhere to the specification.

2.1 MUST / SHOULD / MAY

There are three levels of obligation with regards to conformance to the xAPI specification identified by the terms MUST, SHOULD and MAY. A service or system that fails to implement a MUST (or a MUST NOT) requirement is non-conformant. Failing to meet a SHOULD requirement is not a violation of conformity, but goes against the recommendations of the specification. MAY indicates an option, to be decided by the developer with no consequences for conformity. Usage of these terms outside of requirement language does not designate a requirement and is avoided whenever possible. Complete definitions of MUST, SHOULD, MAY, MUST NOT and SHOULD NOT are found in RFC 2119.

The use of an asterisk* following SHOULD indicates a very strong recommendation. It is planned that these recommendations will become MUST requirements in a future version. Not following these recommendations could risk interoperability and and/or lead to various other issues depending on the specifics of the recommendation. These recommendations cannot be MUST requirements within this version as these would be breaking changes. The xAPI Working Group strongly encourages adopters to implement these requirements as though they were MUST requirements, while continuing to support other adopters that might not do so.

2.2 Guidelines for Interpreting Descriptive Text and Tables

As a rule of thumb, if the guideline appears technical or seems to be a requirement, interpret it as such. This is especially true of longer, more, detailed explanations and of tables, each of which would be unintuitive and/or lengthy to dissect into a list of requirements.

Tables are used throughout this specification to define requirements for lists of properties, parameters, etc. The tables define which properties are required, recommended and optional. Generally, the notion of “optional” relates to the service creating the object, while services receiving and interpreting the object need to be able to interpret all properties of that object. Often, properties are optional because the data may not be relevant in every context; if the data is relevant in a particular context, then it is expected the property will be populated.

If an optional property or parameter contains an object with properties that are recommended or required, then these properties are only recommended/required if the property or parameter containing them is used.

Examples are provided throughout the specification and in appendices to illustrate implementation. The content of these examples is fictional in order to illustrate the requirements of the specification and may not always illustrate the best practice approach to tracking the particular learning experience used in the example. Examples can be used to inform interpretation of requirements, but are not intended to take precedence over requirements.

Where the specification does not include requirements relating to a particular facet of implementation, that detail can be considered to be outside of the scope of this specification. It is up to the implementer to determine a sensible approach. This specification tries to avoid vagueness and will usually give a rationale even if there no requirement in a given area.

3.0 Definitions

Absolute IRI: an IRI. Used in the JSON-LD specification to contrast with compact IRIs and relative IRIs.

Activity: an Experience API Activity. This specification helps Profile Authors mint canonical Activities.

Activity Definition: an Experience API Activity Definition.

Activity Type: an Experience API Activity Type. This specification helps Profile Authors provide additional metadata for Activity Types they control.

Attachment Usage Type: an Experience API Attachment Usage Type. This specification helps Profile Authors provide additional metadata for Attachment Usage Types they control.

Compact IRI: A shortened IRI in the form prefix:name that becomes expanded on processing to an absolute IRI. Described in the JSON-LD specification.

Concept: In SKOS, any unit of thought. In this specification, any of a particular list of possible things a Profile might describe.

Context: In xAPI this refers to a part of a Statement, but in this specification it usually means a JSON-LD @context, which is a way of mapping JSON onto semantic terms and RDF.

Document Resource: An Experience API Document Resource. This specification helps Profile Authors describe what Document Resources in particular locations need to look like.

Experience API (xAPI): The Experience API Specification. For this specification, any 1.0.x version is relevant. Describes data structures for describing experiences and APIs for communicating them.

Extension: An Experience API Extension. This specification helps Profile Authors describe what Extensions with specific identifiers need to look like.

IRI: An Internationalized Resource Identifier. Like a URL, but more general. A distributed, structured, persistent identifier.

JSON: JavaScript Object Notation. A simple way to represent data structures for computers that humans don’t have too hard a time writing or reading. The way Profiles are represented in this specification.

JSON Schema: JSON Schema are a way to describe and constrain the form of JSON documents. This specification adheres to Draft-07 version of the JSON Schema specification.

JSON-LD: JSON-LD turns JSON into Linked Data, making it easy to use with Linked Data tools and integrate with other datasets.

JSONPath: JSONPath provides a way to address parts of JSON documents using a JSONPath expression.

Language Map: A Language Map expresses multiple language-specific values at once. While used in the xAPI specification essentially identically, the controlling specification is JSON-LD Language Maps.

Learning Record Provider: As in the Experience API specification, anything creating Learning Records (xAPI Statements and Document Resources).

Media Type: A media type is a simple, structured way to refer to particular types of content. Also known as MIME Type or Content Type.

Pattern: One way a series of Statements following a Profile could look. Defined by this specification.

Profile: A profile is the human and/or machine-readable documentation of application-specific concepts, statement patterns, extensions, and statement templates used when implementing xAPI in a particular context. A profile is a way to talk about Concepts, Statement Templates, and Patterns for Experience API data in a particular context, and in particular to describe them so machines can do some processing automatically.

Profile Author: Some person or group writing a Profile.

Profile Server: A place to find, browse, and query Profiles, vocabulary concepts, and other profile metadata.

Profile Validator: Any person or machine attempting to verify if the rules in a Profile are followed for a particular set of data.

Profile version: A Profile at a particular point in time.

PROV: PROV models the provenance of things. In this specification, PROV is used to provide rich versioning support.

RDF: The Resource Description Framework standardizes the exchange of semantic data by describing an information model of subject, predicate, and object.

Registration: An Experience API Registration. This specification uses registration to connect Statements that are following the same Pattern or Patterns.

SKOS: The Simple Knowledge Organization System provides the building blocks to describe and relate Concepts.

SPARQL: SPARQL is a query language for RDF data.

Statement: An Experience API Statement. The core unit of recorded data in the Experience API.

Statement Template: A set of rules for how Statements using certain Concepts should look. Defined by this specification.

StatementRef: An Experience API Statement Reference. Used for pointing at a second Statement from a first.

Subregistration: When multiple Patterns are being followed within a registration, subregistration is an extension specific to this specification to distinguish between them.

Verb: An Experience API Verb. This specification helps Profile Authors provide additional metadata about verbs they control.

xAPI Profile Processor Library: A programming library implementing the algorithms described in this specification.