Resources

Guidance for authoring, publishing, and updating xAPI Profiles

About

Welcome to the resource page for guidance on Profiles. Locate the quick links section below for commonly accessed resources that are often useful for xAPI Profiles. Read the other sections for an overview of the xAPI Profile authoring process.

Quick Links

Some of the most commonly accessed resources:
  1. xAPI Profile Specification
  2. xAPI Authored Profiles Github Repository
  3. xAPI Use Cases & Statements Template
  4. xAPI Profile Starter Template

Getting Started

Before diving right into authoring a Profile there are some general questions that should be answered first as these could influence your overall xAPI strategy. You need a clear understanding of why you might (or might not) need to create a Profile in the first place. Below are a list of questions to get you started:

Can I reuse existing Profiles?

First, check and see if there are vocabulary concepts from a Profile or complete Profiles you can reuse before attempting to author a new one. Existing vocabulary concepts might not describe or accurately define the concept you need. In that case, you might need to coin a new concept and create a profile. You also might not want to use all the concepts of an existing Profile. Let's say you only want to use some of the verbs from the SCORM profile. That's perfectly fine. You can reuse any concepts from multiple existing Profiles and you can also require the inclusion of statement templates from existing Profiles. If you mix multiple profiles and don't really add any new concepts (verbs, activity types, extensions, attachment usage types) on top of them then you don't need to create a profile. You are just simply going to reuse existing ones.

Do I need to author a Profile?

You should create a Profile if you need to mint new vocabulary concepts such as verbs, activity types, or extensions. If you mix multiple profiles and add new concepts on top of them then you do need to create a profile. Profiles may often contain vocabulary concepts and aren't required to include statement templates. However, the answer is also "Yes" if you have specific structural requirements for your statements and need to provide statement templates to enforce the rules.

Where do I begin if I need to author a Profile?

These high-level steps will help you get started:
  1. Define Use Cases
  2. The very first step is to identify the specific requirements you’re trying to satisfy with xAPI such as improving learning, human performance, or even business processes. What types of learning activities and interactions do you need to track? This will help inform what you put into your Profile. And your Profile will help you to realize your options for reports and analytics. Click "Define Use Cases" to open the Use Case Template and get started with this step.

  3. Author & Reuse
  4. Browse and search xapi.vocab.pub and then document the specific vocabulary concepts, Profiles, and statement templates you will author from scratch or reuse. Reuse whole Profiles are only parts of them that are needed for your project. Let's say you were developing a SCORM course or updating an existing one. The course has video embedded in it. You could use a combination of both the SCORM and the Video Profile rather than creating a new Profile. If you need to author a new Profile you can start with an empty starter template. Click "Author & Reuse" to open the repo of existing Profiles and the starter template.

  5. Prototype & Refine
  6. Create functional examples and send statements to an LRS. Query the LRS and visualize the data to help inform any changes or refinements to your Profile. Click "Prototype & Refine" to test your xAPI prototype with the ADL Learning Record Store (LRS). You can also search the web for existing commercial LRS vendors as most offer free trial accounts for testing as well.

  7. Publish & Share
  8. Once you've finished authoring and refining your Profile you will publish it to the Profile repository on github. For more detailed steps on publishing see the "Publishing Profiles" section below. Click "Publish & Share" to see complete examples of existing Profiles. After your Profile has been submitted to the repository, your Profile and vocabulary concepts are curated by the xAPI community. Then they are imported to xapi.vocab.pub for reuse.


Authoring Profiles

The process of authoring Profiles for xAPI can be made easier if some specific rules are followed. This section of the document will explain these rules and provide the recommended practices for Profile authoring.

IRI Design Practices

This section provides a set of general design principles aimed at helping Profile authors mint consistent and reliable IRIs. The IRIs for concepts are expected to be dereferenced (aka resolve to a URL) by a browser or any other client making an HTTP GET request. Therefore, Profile authors must follow good IRI design practices in order to ensure that xapi.vocab.pub will be able to consistently dereference Profile metadata. The following IRI pattern should be adopted by anyone creating new concepts for a profile:

https://w3id.org/xapi/ [profile name] / [concept type] / [concept]

The parts of the IRI in brackets are the only parts that will be customized. For example the Video Profile Verb, https://w3id.org/xapi/video/verbs/seeked, follows this pattern. A best practice for IRIs is to use a persistent resolution service. The xAPI community is using the W3C's w3id.org service for this purpose. This is why all IRIs should begin with the w3id.org domain (except older IRIs that were generated before the community established this process).

Quality Metadata

Profiles should include information about the profile such as the the name of the profile, a description, the organization or person that authored it, and the date/time it was published. Profiles can also include concepts (e.g., verbs, activity types, extensions) and statement templates. These are all described in a JSON-LD document based on the W3C's Resource Description Framework (RDF). However, you don't need to understand RDF or JSON-LD in order to author a Profile. You can simply look at existing examples and look at the starter template to begin the process. What's most important is that we keep the process simple so Profile authors can focus on providing quality metadata.

Quality Assurance & Help

Once the metadata has been written for your Profile you can prepare to publish it. When you publish to it the Profiles repository, the xAPI community will curate the Profile for quality and validate it. We will also assist you if need help with authoring your Profile or have questions. Submit inquires or ask questions by opening an issue. If you would like to make sure it produces valide JSON before publishing it you can use any of the tools below:
  1. JSON Lint
  2. JSON-LD Playground


Publishing Profiles

This section describes the process for publishing Profiles. The workflow utilizes Github for version control and as the official repository location for importing Profile metadata into xapi.vocab.pub. If you don't have experience with Github and would like to learn, there's tons of help and training resources available. If you don't want to learn Github or don't have time then contact us and we'll help publish your Profile for you.

Workflow

—Fork the Profiles Repository from Github.
—Add your Profile (yourprofilename.jsonld) to your copy of the repository using the same structure as existing Profiles (e.g., /folder/filename.jsonld) where the folder and file names are the same as your profile name.
—Submit a pull request to the origin/master Profiles Repository.
—Wait for confirmation that your Profile has been approved and merged into the repository.
—Once approved, the Profile metadata will be imported into xapi.vocba.pub and listed.

Updating Profiles

This section describes the process for updating existing Profiles that have already been published to the Github repository.

Workflow

—Fork the Profiles Repository from Github.
—Update your Profile metadata such as the version information and the date/time it was updated. For more information on versioning, read the versioning section of the Profile Spec.
—Add your updated Profile (yourprofilename.jsonld) to your copy of the repository using the new version folder structure (e.g., /folder/v1.x.x/filename.jsonld) where the folder and file names are the same as your profile name. Simply make sure to create a subfolder named v1.x and put the updated file there. Do not over-write the older version of your Profile. Use Semantic Versioning except the formula is: Given a version number MODEL.REVISION.ADDITION, increment the: MODEL (when you make a breaking change which WILL prevent interaction with historical Profile concepts or statement templates), REVISION (when you make a change which MAY prevent interaction with historical Profile concepts or statement templates), ADDITION (when you make a Profile change this compatible with all historical Proile data).
—Submit a pull request to the origin/master and specify the following message in the pull request subject and body: "VERSION 1.x.x - PROFILENAME"Profiles Repository.
—Wait for confirmation that your Profile has been approved and merged into the repository.
—Check xapi.vocab.pub to ensure your Profile updates are showing up.

External Resources

Other external resources relevant to xAPI Profiles and the underlying standards and technologies used.
  1. JSON-LD
  2. RESTful Web APIs (book)
  3. RDF-Primer
  4. SPARQL Tutorial