"My thanks to everyone who contributed to the Experience API project. Many of you have called into the weekly meetings and helped to shape the specification into something that is useful for the entire distributed learning community. Many of you assisted in releasing code samples, products, and documentation to aid those who are creating and adopting the specification. I'd also like to thank all of those who were involved in supplying useful, honest information about your organization's use of SCORM and other learning best practices. Through the use-cases, shared experiences, and knowledge you have shared, ADL and the community clearly identified the first step in creating the Training and Learning Architecture--the Experience API. You are truly the community leaders on which we depend to make our training and education the very best."
Kristy S. Murray, Ed.D.
Director, ADL Initiative
| Name | Organization |
|---|---|
| Aaron Silvers | ADL |
| Al Bejcek | NetDimensions |
| Ali Shahrazad | SaLTBOX |
| Andrew Downes | Watershed |
| Andriy Drozdyuk | |
| Andy Johnson | ADL |
| Andy Whitaker | Watershed |
| Ángel Serrano | eUCM |
| Anthony Altieri | American Red Cross |
| Anto Valan | Omnivera Learning Solutions |
| Avron Barr | Aldo Ventures, Inc. |
| Ben Clark | Rustici Software |
| Bill McDonald | Boeing |
| Brian J. Miller | Rustici Software |
| Chad Udell | Float Mobile Learning |
| Chaim-Leib Halbert | Rustici Software |
| Chris Handorf | Pearson |
| Chris Sawwa | Meridian Knowledge Solutions |
| Dan Allen | Litmos |
| Dan Kuemmel | Sentry Insurance |
| Danny Pham | |
| Dave Mozealous | Articulate |
| David Ells | Rustici Software |
| David N. Johnson | Clear Learning Systems |
| David Pate | Riptide Software |
| Dennis Hall | Learning Templates |
| Doug Hagy | Twin Lakes Consulting Corporation |
| Eric Johnson | Planning and Learning Technologies, Inc. |
| Fiona Leteney | Feenix e-learning |
| Greg Tatka | Menco Social Learning |
| Ingo Dahn | University Koblenz-Landau |
| Jason Haag | ADL |
| Jason Lewis | Yet Analytics |
| Jeff Place | Questionmark |
| Jennifer Cameron | Sencia Corporate Web Solutions |
| Jeremy Brockman | |
| Jhorlin De Armas | Riptide Software |
| Joe Gorup | CourseAvenue |
| Joerg Boeselt | Brightcookie |
| John Kleeman | Questionmark |
| Jonathan Archibald | Brightwave |
| Jonathan Poltrack | ADL |
| Kris Miller | edcetra Training |
| Kris Rockwell | Hybrid Learning Systems |
| Lang Holloman | |
| Lewis Cowper | |
| Loic Jeannin | CrossKnowledge |
| Lou Wolford | ADL |
| Luke Hickey | dominKnow |
| Marcus Birtwhistle | ADL |
| Mark Davis | Exambuilder |
| Matteo Scaramuccia | |
| Megan Bowe | Rustici Software |
| Melanie VanHorn | ADL |
| Michael Flores | Here Everything's Better |
| Michael Roberts | vTrainingRoom |
| Michael Wheeler | |
| Mike Palmer | OnPoint Digital |
| Mike Rustici | Watershed |
| Nick Washburn | Riptide Software |
| Nikolaus Hruska | ADL |
| Pankaj Agrawal | Next Software Solutions |
| Patrick Kedziora | Kedzoh |
| Paul Esch | Nine Set |
| Paul Roberts | Questionmark |
| Rich Chetwynd | Litmos |
| Richard Fouchaux | Ontario Human Rights Commission |
| Richard Lenz | Organizational Strategies, Inc. |
| Rick Raymer | |
| RJ Zaworski | |
| Rob Chadwick | ADL |
| Robert Lowe | NetDimensions |
| Roger Swetnam | |
| Russell Duhon | SaLTBOX |
| Ryan Smith | HT2 |
| Stephen Trevorrow | Problem Solutions, LLC. |
| Steve Baumgartner | |
| Steve Flowers | XPConcept |
| Thomas Ho | |
| Tim Martin | Rustici Software |
| Tom Creighton | ADL |
| Tyler Mulligan | ADL |
| Walt Grata | ADL |
| Yannick Warnier | Chamilo |
| Zach Lowry | Watershed |
In collection of requirements for the Experience API, many people and organizations provided invaluable feedback to the SCORM, distributed learning efforts, and learning technology efforts in general. While not an exhaustive listing, the white papers gathered in 2008 by the Learning Education and Training Standards Interoperability (LETSI) group, the Rustici Software UserVoice website, one-on-one interviews and various blogs were important sources from which requirements were gathered for the Experience API specification.
The Advanced Distributed Learning (ADL) Initiative has taken on the roles of steward and facilitator in the development of the Experience API. The Experience API is seen as one piece of the ADL Total Learning Architecture (previously the Training and Learning Architecture), which facilitates learning anytime and anywhere. ADL views the Experience API as an evolved version of Sharable Content Object Reference Model (SCORM) that can support similar use cases, but can also support many of the use cases gathered by ADL and submitted by those involved in distributed learning that SCORM could not enable.
This document outlines various ways of contributing to the specification:
- Reviewing open Pull Requests
- Suggesting solutions to issues
- Making a Pull Request to address an issue
The most helpful and easiest way to contribute to the specification is to review an existing PR. You can find a list of open PRs here. To review a PR you should:
- Read any issues linked to from the PR description and make sure you understand the issue the PR is designed to address.
- Read any comments on both the issues and the PR to understand if the goals of the original issue have changed and if any solutions have been agreed.
- Read the relevant sections in the development version of the specification.
- Check the 'Files changed' tab of the PR and look at what has changed. Use the 'rich diff' option if that helps you to see the changes better. Check to see if what's been changed matches the solution you expected from reading the issue and comments.
- Look for problems such as typos, unintended changes to behaviour and any text that's unclear.
- Check that anything that's been removed has either been replaced or the removal was intentional (based on reading the issue and comments).
- Check that the Style Guide has been followed.
- If you spot any issues with the PR, add a comment describing these problems as best you can and suggesting how they can be resolved.
- If the PR looks good to you, add a comment saying "+1".
- If you are unsure about the PR or have questions, ask questions in the PR comments.
- If you feel that the PR should never be merged, even with changes, add a comment starting with "-1" and explaining your reasons. If your comments run contrary to what's already been agreed in the issues, there might be some resistance, but that's ok if you have a strong argument!
When reviewing a PR please don't:
- Review and leave no comment; always let us know you've had a look!
- Suggest additional changes outside of what the PR was intended to achieve. Raise a separate issue for additional changes.
- Make vague criticisms without suggesting the changes to the PR that would meet those criticisms.
The second most helpful and second easiest way to contribute to the specification is to suggest a solution to an issue that has been raised. Ideally the person who raises the issue will propose a solution, but this does not always happen and you may be able to improve a suggestion.
To suggest a solution to an issue you should:
- Read the issue and ensure you understand the problem being described. Ask questions if you need to.
- Read the relevant sections in the development version of the specification.
- Add a comment stating:
- Which sections of the specification you propose to change.
- A description of the proposed change.
- Any reasons for and against the change you're proposing.
Once your suggestion has been discussed and agreed, add another comment summarising your understanding of the outcome of the discussion and including proposed wording for the changes you've suggested.
Good and detailed suggested solutions for issues make it much easier to write PRa and helps to ensure those PRs are merged faster.
The hardest way of directly contributing to the specification is to make Pull Requests and the xAPI Working Group recommends only getting involved in this way if you are already used to Github and markdown and/or have previously contributed to reviewing PRs and suggesting solutions to issues.
Before making a PR you should:
- Read the issue you are planning to address carefully including any comments.
- Read the relevant sections in the development version of the specification.
- Read any suggested solutions to the issue and the discussion around those issues.
If you would like to raise a PR that directly addresses your own concern, there is no need to raise a separate issue.
To make a PR you will need to edit the appropriate .md file either using the github.com interface, or use git on your local computer. The github.com interface is simpler for new users and is ideal for smaller changes like typos. These two methods are described below.
When making a PR, you should include a description that explains:
- What issue numbers of any issues you are addressing (normally just one issue)?
- How does your PR relate to any proposed solutions to the issue?
- If you have moved sections, have you made any changes to content within those moved sections?
- What decisions did you make in writing the change? Why did you make those decisions?
To edit the specification on github.com, first open the development version of the specification, then follow the instructions here.
If you are not currently working with GitHub and git, follow these set up steps first. GitHub provides excellent help at https://help.github.com/articles/set-up-git
Go to the Experience API repository. Fork the repository to your own account using the "Fork" button on the top right of Experience API repository page. This makes a copy of the Experience API repository. This fork gives you the ability to edit your version of the document without impacting the master copy.
You need to install Git to work with a GitHub repository. If you are on a Windows machine, you can download the GitHub client app. If you use a Mac you can download the GitHub client app but will also have to download git to add a remote to the master repository. Otherwise install git from the git site.
Git This provides a command line client app for working with a git repository (like GitHub) Download and run git install
GitHub Client GitHub Client provides a GUI interface to simplify working with a repository on GitHub. This does not currently support synchronizing with a master repository so some commands will still need to be completed using the command line.
Mac: http://mac.github.com/ Windows: http://windows.github.com/
To make edits and work on the files in the repository, clone your repository to
your local machine using Git. The url is provided on the home page of your
repository (ex. https://github.com/<your username>/xAPI-Spec/)
Git
git clone https://github.com/<your username>/xAPI-Spec/>
GitHub Client On the home screen of the client app, select your account under 'github' and choose the repository you want to clone. Selecting the repository from the list gives you an option to clone it.
Add a remote repository to git to reference the master repository. This will make synchronizing with the master repository a bit easier.
Git
git remote add upstream https://github.com/adlnet/xAPI-Spec
GitHub Client
Currently the GitHub clients don't have a way to synchronize with the master
repository. In order to do this, open your repository on the GitHub client
app home screen. On the repository screen select 'tools' and 'open a shell
here'. Alternatively use the 'Git Shell' shortcut if it was created during
installation. NOTE: If you're using a Mac there is no shell shortcut so
navigate to /your/repo/path/xAPI-Spec then follow the shell instructions.
In the shell, enter..
git remote add upstream https://github.com/adlnet/xAPI-Spec
Pull down changes from the development repository. This automatically does a fetch of the repository and a merge into your local repository. Currently the development version of the spec is 1.0.3.
Git and GitHub Client
git pull upstream 1.0.3
Edit the local copy of the file, save and commit. Rule of thumb: Use commits like save points. Commit to indicate logical groups of edits, and places where the edits could be safely rolled back.
Git
git commit -a -m "<commit message>"
GitHub Client The GitHub client will detect saved changes to the documents in your local repository and present a button to commit your edits at the top right of the repository screen.
Pushing your changes to your remote GitHub repository stages the files so that you can then make requests to the master repository to merge in your changes.
Git
git push origin
GitHub Client The GitHub client has a 'sync' button at the top of the repository screen. This will synchronize your local and remote (origin) repository.
When you forked from the Experience API repository, a link back to the master repository is remembered. To send your changes back the the master repository, click the "Pull Request" button at the top of your repository page. This will direct you to a page that gives you the ability to submit a request to the master repository to merge in the changes you committed.
If a specific data format and value are to be used, the code style should be used to denote this.
For example:
A list of item ids is delimited by `[,]`
And
The value returned must be `false`.
When referring to a property, parameter or object, but not specifically calling it out as property, parameter, or object the name should be capitalized. No formatting or quotes should be used.
For example:
Context Activities within the Context of the Statement are awesome.
When a specific type is called out, Double quotes should be used (e.g. properties, parameters, and objects). When used within quotes, the capitalization should match that actually used in the object being described.
For example:
You can use "category" Context Activities to denote the recipe being followed in crafting the statement.
And
The "member" property is an unordered list!
When a value is expected or described within plain text, but isn't specifically code, single quotes should be used. In situations where it is important to group text to be specific to the concept, single quotes should also be used. Single quotes are also allowable if the text would be unclear due to certain property names. Basically, single quotes are the catch-all for any case where not having any clarifying punctuation or style would cause confusion.
For example:
The reserved Verb 'http://adlnet.gov/expapi/verbs/voided' is an exception.
And
These additional properties are called ‘interaction component lists’
And
The Score Object SHOULD include 'scaled'
And
The 'binary' value should be used.
Hashes (#) should be used for all headings following the following format: