OneRoster v1p2 Implementation and Best Practices Guide (Candidate Final Public)

OneRoster v1p2 Implementation and Best Practices Guide

IMS Candidate Final Public
Version 1.2
IMS Candidate Final Public
Date Issued: July 01, 2021
Status: This document is for review and adoption by the IMS membership.
This version: https://www.imsglobal.org/spec/oneroster/v1p2/impl/

IPR and Distribution Notice

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/speclicense.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources.

© 2021 IMS Global Learning Consortium, Inc. All Rights Reserved.

Trademark information: http://www.imsglobal.org/copyright.html

Abstract

The IMS OneRoster (OR) standard addresses the exchange of student data (primarily about people, courses, enrollments and grades) between different educational systems for the specific needs of K-12. The primary use-case is the exchange of data between a Student Information System (SIS) and Learning Management System (LMS). In OR 1.2, the service has been split into three core services:

1. Introduction

The IMS OneRoster®(OR) specification supports securely sharing class rosters and related data between a student information system (SIS) and any other system, typically a content application or learning information system (LMS). The OneRoster standard supports spreadsheet-style (CSV) export-import as well as direct system exchanges using REST APIs. With OneRoster, schools pave the way for digital resources for teaching and learning and eliminate problems before they happen.

Teachers, institutional technical administrators, and suppliers all benefit when OneRoster integrations are implemented. Anyone who takes part in the management of the many and diverse tools and technologies in schools and districts benefit from the consistency and standardization offered by the OneRoster standard.

1.1 Status of this document

This document is the Candidate Final Public release, meaning the technical specification is also in Candidate Final Public status. IMS members are currently working towards successful completion of conformance certification.

IMS strongly encourages its members and the community to provide feedback to continue the evolution and improvement of the OneRoster standard. To join the IMS developer and conformance certification community focused on OneRoster and the other related IMS standards please visit the IMS EduERP alliance online here: https://www.imsglobal.org/lis/alliance.html

1.2 Where Can I Get Help?

If you have questions or need help with implementing OneRoster or achieving conformance certification, here are some available resources:

  • Public Forum - for all parties interested in OneRoster.
  • OneRoster Support - for EduERP Alliance, Affiliate, and Contributing Members.
  • OneRoster Developer FAQs - series of articles published by the IMS staff answering frequently asked implementation questions.
  • IMS Contributing Members have access to private GitHub repositories and a Slack channel for OneRoster Project Group discussions and collaborations. Contact an IMS staff member to gain access.

1.3 Conformance Certification

IMS offers a process for testing the conformance of products using the IMS certification test suite. Certification designates passing a set of tests that verify the standard has been implemented correctly and guarantees a product’s interoperability across hundreds of other certified products. The OneRoster 1.2 Conformance Certification Guide [OR-CERT-12] provides details about the testing process, requirements, and how to get started.

Conformance certification is much better than claims of “compliance," since the only way IMS can guarantee interoperability is by obtaining certification for the latest version of the standard. Only products listed in the official IMS Certified Product Directory can claim conformance certification. IMS certification provides the assurance that a solution will integrate securely and seamlessly into an institution's digital learning ecosystem.

In order to become certified a paid IMS membership is necessary. Here's why: while conformance certification provides a "seal" for passing prescribed tests it is much more than that. It is a commitment by a supplier to the IMS community for continuous support for achieving "plug and play" integration. Certification implies ongoing community commitment to resolve problems, revise implementations and retest as need. For that reason, only IMS Contributing Members, Affiliate Members and Alliance members are eligible to apply for conformance certification. Details and benefits of membership are listed at https://www.imsglobal.org/imsmembership.html.

This document is an informative resource in the Document Set of the OneRoster v1p2 specification [OR-12]. As such, it does not include any normative requirements. Occurrences in this document of terms such as MAY, MUST, MUST NOT, SHOULD or RECOMMENDED have no impact on the conformance criteria for implementors of this specification.

1.4 Product Directory Listing

The IMS Certified Product Directory is the official listing of products that have passed IMS Global conformance certification testing. Products that are listed in this directory are guaranteed to meet the IMS standards for which they have passed testing. If you experience an integration issue with a product listed here, IMS will work with the supplier to resolve the problem. If a product is NOT listed here it has either not passed IMS testing or its certification has expired.

1.5 Acronyms

The following acronyms are used in this document

Acronym Description
AfA PNP Access for All Personal Needs and Preferences
BOM Byte Order Mark
CEDS Common Education Data Standards
CSV Comma Separated Values
GUID Globally Unique Identifier
IETF Internet Engineering Task Force
JSON JavaScript Object Notation
LDAP Lightweight Directory Access Protocol
LMS Learning Management System
LTI Learning Tools Interoperability
NCES National Center for Educational Statistics
OR OneRoster
ORCA OneRoster Consumer API
REST Representational State Transfer
RFC Request For Comment
SIS Student Information System
TLS Transaction Layer Security
UTF Unicode Transformation Format
UUID Universally Unique Identifier

2. Specification

The OneRoster (OR) v1p2 Standard documentation is split by it's services and transport protocols. For REST implementations this is split into an information model document and a REST binding document. For CSV implementations there is one document that describes the data and file structure for CSV file exchange. The information model documents describe the data dictionary and logical data model for the service. The REST binding documents describe the serialization and endpoint definitions for the service. There is also a formal profile for the Gradebook service that enables hierarchical assessments outside of a required class context.

2.1 REST Documents

2.2 CSV Documents

2.3 Supporting Documents

3. OneRoster Interoperability Architecture

Like all IMS specifications, the OneRoster specification describes data in motion i.e. the exchange of information achieved using agreed interoperability. For OneRoster the information being exchanged is contained in three groups:

  • Class Rosters - the set of people enrolled on a class at a site and for a set period;
  • Gradebooks - the data is broken into results, lineItems (a set of results) and categories (a set of lineItems).
  • Resources - to identify the set of resources that are required for a class and/or a course;

OneRoster 1.2 serves as a major upgrade to OneRoster 1.1. This version to the educational content, tool and platform rostering standard and consists of three distinct services available in previous revisions. A brief list of features supported in OneRoster 1.2 are:

  • Simplification of workflows by separation into 3 distinct services:

  • Multiple transfer options to support multiple system requirements. OneRoster supports transmission through spreadsheet-style CSV templates or through system to system data exchange (REST API)

  • Support of sort, filter, and field selection

3.1 OneRoster Process Flow

OneRoster defines two roles, a Provider and a Consumer. Technical administrators or other users of the CSV will export from the Provider system such as a student information system and import to a consumer system, such as an LMS or a digital text. REST API-based products adopt the same concepts but users are not handling files directly since the exchange is system-to-system. OneRoster Architecture

3.2 Additional Product Considerations

When selecting products it is very important to understand what OneRoster product type you are considering purchasing. Will the product be a OneRoster Provider or a OneRoster Consumer? Or is the product performing an Aggregator service, which is a Consumer of data from one system and Provider of that data to another system? An Aggregator service usually performs additional value-added services to help make the onboarding and enrollment of students in multiple platforms easier and more efficient. Because of their intermediary role, to be compliant, Aggregator product types must be certified as both Consumers and Providers.

4. What is this document?

The purpose of this document is to provide the collected and collated best practice recommendations and offer implementation guidance for the adoption of the IMS OneRoster 1.2 standard. This information was produced during the development of the standard and from the feedback of the IMS Members who have the adopted OneRoster.

This document is an informative part of the OneRoster 1.2 document set. As such, it may be revised without the specification version being incremented. Please refer to the revision history below for more information

As an informative resource it does not include any normative requirements. Occurrences in this document of terms such as MAY, MUST, MUST NOT, SHOULD or RECOMMENDED have no impact on the conformance criteria for implementors of this specification.

The primary goal of this document is to lead you to successful implementation of the OneRoster© v1.2 specification. More than that, this guide helps you along the way to achieving conformance certification.

5. What's new in OneRoster 1.2

OneRoster 1.2 introduces a variety of changes intended to improve the functionality and usability of the specification. Additionally, the specification has been updated with the feedback and needs of institutions and suppliers alike in mind. Below are the set of changes being brought to OneRoster 1.2.

5.1 Specification-wide Changes

5.1.1 Service API Separation

OneRoster 1.2 has been split into 3 separate services. This enables a simpler set of workflows when utilizing individual services, simplifying the teaching and learning ecosystem. It also allows suppliers to pick and choose which services to support. To support this in the REST service the base URL for the service endpoints have been changed as below:

  • /ims/oneroster/rostering/v1p2
  • /ims/oneroster/gradebook/v1p2
  • /ims/oneroster/resources/v1p2

5.1.2 Security improvements

OneRoster 1.2 is updated to exclusively use OAuth 2.0 Bearer Token (Client Credentials Grant). This change aligns OneRoster with well-supported industry best practices that reinforce an institutions' cohesive security framework. More information can be found in the IMS Security framework document.

5.1.3 Certification Improvements

OneRoster certification has been improved with additional support for certification of systems that have requirements for processing large volumes of data. Certification has also been modified for OneRoster consumers to only require at least one of the set of core defined endpoints.

5.1.4 REST API discovery mechanism

OneRoster 1.2 introduces the requirement that a Service Provider is required to make a localized OpenAPI file available to enable Service Discovery.

5.2 Rostering Service Changes

Changes have been made to the rostering service to support the following use cases.

5.2.1 Enhanced User Demographics Support

OneRoster 1.2 includes support for users who wish to be referenced by a first, middle or last name that is different then their legal name via the addition of 3 new properties; preferredFirstName, preferredMiddleName, and preferredLastName to the 'user' class. Additionally, OneRoster 1.2 adds support for learners with non-binary genders via additions to the associated vocabulary set.

5.2.2 Enhanced User Role Support

OneRoster 1.2 adds support for users who have multiple roles within a single or multiple organizations. In prior versions of OneRoster, a user could have only one role, resulting in duplication of users who might have multiple roles at one or many organizations. E.g., a teacher in one school may be a parent in another. OneRoster 1.2 has been enhanced to enable the assignment of any combination of role/org/account mappings for a user. This was accomplished with the following set of changes:

  • The 'roles' class has been added to enable the assignment of any combination of role/org/account mappings for a user including date stamping to enable partial academic sessions.
  • The roles attribute has been added to the 'user' class.
  • The role attribute has been removed from the 'user' class.
  • The orgs attribute has been removed from the 'user' class.
  • The primaryOrg attribute added to the 'user' class.

5.2.3 Enhanced User Credential Support

OneRoster 1.2 adds in support for Zero or Multiple Sets of Credentials for a Single user. Users may have multiple accounts or credential profiles in one API. Support was added to allow for zero-to-many credential profiles for an individual user

  • The 'userProfile' class have been added to the 'user' class allowing the assignment of one or many profile(s) to a user.
  • The 'credentials' class has been added allowing application specific credentials to be assigned to a 'userProfile'.
  • The credentials attribute has been included on the 'userProfiles' class to allow one or many set of credentials to be enabled.
  • The username attribute has been made optional.

5.2.4 All Rostering Changes:

The full set of rostering changes in OneRoster 1.2 are:

  • The Rostering parts of the OneRoster specification have been separated out into their own Service Model and REST/JSON Binding documents; The endpoints have been annotated as '/ims/oneroster/rostering/v1p2' to replace the '/ims/oneroster/v1p1';
  • The attribute preferredName has been added to the 'User' class;
  • The enumeration vocabulary for the attribute sex in the 'Demographics' class has been extended with the tokens 'other' and 'unspecified';
  • The userMasterId attribute has been added to the 'User' class enable the assignment of a definitive globally unique identifier (not the interoperability sourcedId for the user);
  • The roles attribute has been added to the 'User' class and the 'Roles' class has been added to enable the assignment of any combination of role/org/account mappings for a user;
  • The resources attribute has been added to the 'User' class to allow identification of the set of resources available to the user;
  • The role and orgs attributes have been removed from the 'User' class;
  • The primaryOrg attribute has been added to the 'User' class;
  • The masterProfiles attribute has been added to the 'User' class and the 'UserProfiles' and 'Credential' classes have been added to enable the assignment of profiles to a user. A profile enables the management of credentials for access to a system;
  • The 'ClassTypeEnum', 'GenderEnum', 'OrgTypeEnum', 'RoleEnum' and 'SessionTypeEnum' vocabularies have been made extensible to enable easier profiling and internationalization;
  • All references to the CEDS/SCEDS vocabularies have been removed so that such vocabularies can be replaced by those that are more relevant to a geographic region;
  • Use of OAuth 1.0a message signing has been removed. The use of OAuth 2.0 Bearer Tokens (Client Credentials Grant) is required instead. The security architecture has been aligned to the IMS Security Framework [Security, 21];
  • A Service Provider is REQUIRED to make a localized OpenAPI file available to enable Service Discovery

5.3 Gradebook Service Changes

5.3.1 Standards Based Grading Support

Incorporating the ability to align grade passback with learning objectives via Competencies and Academic Standards Exchange (CASE) Service 1.0 Specification into OneRoster 1.2 Gradebook Service means data on learners’ progress towards mastery can now be transported between systems for monitoring and reporting. Supporting alignment of the scores and results that are generated by learners in the systems where learning occurs provides valuable data to drive insights for stakeholders as they continue to strive to support learners. Without this progress data, stakeholders are flying blind when attempting to assist learners.

5.3.2 Score Scale Support

Faculty using connected systems benefit because OneRoster 1.2 allows for more detailed information about grade book attributes for how scores should be weighted. The result is the weighting scheme the organization or teacher has designed in the OneRoster provider system is available to the OneRoster consumer system, thereby increasing consistency between the two systems while saving time and reducing error.

5.3.3 Non-numeric Scores Support

OneRoster 1.2 adds a new attribute to the result payload called textScore. This is a string value for storing non-numeric scores (i.e. rubric values). The score attribute still exists as a float for purposes of backwards compatibility

5.3.4 Class-specific Category Support

The 'getCategoriesForClass' endpoint has been added to support systems that have a unique set of gradebook categories for each class.

5.3.5 All Gradebook Changes:

The full set of gradebook changes in OneRoster 1.2 are:

  • The Gradebook parts of the OneRoster specification have been separated out into their own Service Model and REST/JSON Binding documents;
  • The endpoints have been annotated as '/ims/oneroster/gradebook/v1p2' to replace the '/ims/oneroster/v1p1';
  • The usage of the terms from CEDS/SCED for vocabularies have been removed so that the appropriate localised vocabularies MAY be used;
  • Support for the exchange of 'Score Scales' has been added. The following set of endpoints have been added to the 'ScoreScales Management' interface:-
    • getAllScoreScales()
    • getScoreScale()
    • deleteScoreScale()
    • putScoreScale()
  • Support for the exchange of 'Assessment LineItems' has been added. The following set of endpoints have been added to the 'AssessmentLineItems Management' interface:-
    • getAllAssessmentLineItems()
    • getAssessmentLineItem()
    • deleteAssessmentLineItem()
    • putAssessmentLineItem()
  • Support for the exchange of 'Assessment Results' has been added. The following set of endpoints have been added to the 'AssessmentResults Management' interface:-
    • getAllAssessmentResults()
    • getAssessmentResult()
    • deleteAssessmentResult()
    • putAssessmentResult()
  • The following endpoint has been added to the 'LineItems Management' interface:-
    • postResultsForLineItem()
  • The following endpoints have been added to the 'Classes Management' interface:-
    • getScoreScalesForClass()
    • getAcademicStandardIdsForClass()
    • postResultsForAcademicSessionForClass()
    • postLineItemsForClass
  • The following endpoints have been added to the 'Schools Management' interface:-
    • getScoreScalesForSchool()
    • getAcademicStandardIdsForSchool()
    • postLineItemForSchool()
  • The 'ScoreScale' and accompanying classes have been added to the data model;
  • The 'AssessmentLineItem' and accompanying classes have been added to the data model;
  • The 'AssessmentResult' and accompanying classes have been added to the data model;
  • The weight attribute has been added to the 'Category' class;
  • The scoreScale, gradingPeriod, learningObjectiveSet and school attributes have been added to the 'LineItem' class;
  • The resultValueMin and resultValueMax attributes in the 'LineItem' class have been made optional (instead of required);
  • The scoreScale, textScore, class and learningObjectiveSet attributes have been added to the 'Result' class;
  • The 'LearningObjectiveSet', 'LearningObjectiveIdSet', 'LearningObjectiveScoreSet' and 'LearningObjectiveResults' classes has been defined for use with the learningObjectiveSet attributes;
  • The permitted tokens in the scoreStatus attribute in the 'Result' class has been expanded with new values of { late, incomplete, missing, withdrawal, in progress };
  • Use of OAuth 1.0a message signing has been removed. The use of OAuth 2.0 Bearer Tokens (Client Credentials Grant) is required instead.

5.4 Resource Service Changes

5.4.1 Bulk Resource Exchange

Users can be assigned content in bulk outside the context of a class, enabling users who are not enrolled in a class (such as school administrators) to quickly and easily gain access to learning resources. The resources attribute added to the user class to allow identification of the set of resources available to the user.

5.4.2 All Resource Changes

The full set of resource changes in OneRoster 1.2 are:

  • The Resource Management parts of the OneRoster specification have been separated out into their own Service Model and REST/JSON Binding documents;
  • The endpoint 'getResourcesForUser()' has been added;
  • The endpoints have been annotated as '/ims/oneroster/resources/v1p2' to replace the '/ims/oneroster/v1p1';
  • The 'RoleEnum' vocabulary has been made extensible to enable easier profiling for internationalization;
  • Use of OAuth 1.0a message signing has been removed. The use of OAuth 2.0 Bearer Tokens (Client Credentials Grant) is required instead. The security architecture has been aligned to the IMS Security Framework [Security, 20].

6. Common REST/CSV Adoption Best Practices

6.1 Identifiers and Their Use

6.1.1 Sourced Identifiers

The sourcedId attribute is used to provide the unique identification of the associated object between the communicating end-systems. Ideally, these should be globally unique identifiers (the internal format/structure is an implementation dependent issue and NOT constrained to a form of Universal Unique Identifier, UUID). The identifiers MUST not be used as the internal data store keys i.e. a mapping between the identifier and the key should be maintained by an implementation.

Every data object is allocated a unique identifier i.e. its sourcedId. This identifier must be unique in the context of the two systems that access the object i.e. the identifiers do not have to be globally unique. The end-systems are responsible for maintaining the contextual integrity of these identifiers. The sourcedId is not required to have end-system significance except for enabling the associated record to be identified for the processing of the CSV file or ingestion of the REST payload.

It is the inability to find a record for a given sourcedId that is used to define a ‘deleted’ record. Therefore, an end-system should have its own unique key for identifying the associated record. This ensures that the record does not have to be deleted from the end-system to provide consistent interoperability deletion. If an object has been deleted then the associated sourcedId' MUST NOT be reassigned to another object. Therefore, once a sourcedId has been assigned it is permanently allocated to the associated object and so can be used to recover 'deleted' data.

The sourcedId is used as the unique interoperability key. If data is being received from multiple sources e.g. the import and aggregation of many sets of CSV files, then it is possible that the same sourcedId may be used for different objects (each source will have some sourcedId generation/allocation mechanism and so the probability of a clash will depend on the sophistication of those approaches). It is recommended that systems make use of access control mechanisms to minimize accidental data overwriting. For example, in the REST API a HTTP PUT request on an existing object will result in that object being replaced by the new data set. Therefore, a write request should be moderated by a suitable access control mechanism with requests that fail the access control rules returning the HTTP code 403 (forbidden).

6.1.2 Resources VendorID

This should be an value that uniquely identifies the vendor. The actual vendorId has two components the prefix "vnd" connected to a string assigned by IMS as part of the OneRoster Conformance program and connected via a period. (ex. "vnd.12345")

6.1.3 User IDs

The user class has a number of identifier fields. In keeping with IMS specifications, the preferred practice is for the sourcedId field to be used wherever possible, across all systems. That is to say, the SIS should provide a sourcedId for a user to the LMS. The LMS should provide that same sourcedId for that user to any tools that it launches via LTI, rather than supplying some other identifier. This should be true across all orgs and roles.

However, it is known that at present this isn’t current practice, so other identifiers have been added to the user class to enable migration to best practice.

The userIds collection is intended as a bridging piece in which any other machine readable 'id' can be stored for a given user. This might be an LTI identifier, or it might be an active directory or LDAP identifier. If LMSs cannot use the 'sourcedIds' for the user when making external calls, then this field can be used instead. From version 1.1 on, there is support for the assignment of multiple userIds in which each identity has an assigned type (there is no predefined vocabulary for this type field and so it is left to local deployments to establish an appropriate vocabulary e.g. LDAP, LTI, etc.). Below are some examples of common userIds and their uses.

6.1.4 Universal Identifier

The userMasterIdentifier attribute was added in OneRoster 1.2 as a way to communicate the canonical universal identifier for a student both in and out of context of interoperability. To help better understand this identifier you can consider this in a similar light to a Government Issued ID*. This field is not to be confused with the sourcedID which is meant to provide the unique identification of the associated object between the communicating end-systems not to help prove or maintain the identity of a user. A common use for this would be to communicate the federated user ID which often serves as a system independent canonical identifier. Consult with the vendor documentation and the customer on how this field should be used if at all.

*Non-US Jurisdictions should agree on a suitable identifier for their region.

6.2 User Status and User Record Status

The enabledUser field originates from the status field in OR 1.0. In discussing the status field values in OR 1.0 as they are used in 'users.csv', a problem was identified in that the delta mode submissions carried more information than could be expressed in bulk mode. In delta mode, using the status field, one could distinguish a user as needing to be deleted, as being current and active, and as being current but not active. In bulk mode, there are two states, "the row is present in the csv", which most closely corresponds to the delta status of active and "the row was in a previous submission but is now missing from the CSV", which most closely corresponds to the delta status of tobedeleted. So there is an entire value, inactive, which cannot be modeled in a bulk transmission in OR 1.0.

Further discussion revealed that the distinction between active and tobedeleted was a concern of the data exchange protocol, whereas the distinction between active and inactive was useful entity data. Further investigation found that the distinction was only ever intended for users.

Given those observations, it was decided to eliminate inactive as a status for all files, and for the Users class, add a new field, enabledUser. EnabledUser is used to expresses the distinction between the OR 1.0 active and inactive statuses. OR 1.1 fixed this flaw that bulk files cannot express all three states. Now they can, with "row present" and "row missing" being an indication of active vs tobedeleted, and, for 'users.csv', the enabledUser field indicating the distinction between OR 1.0's active and inactive. This support continues in v1.2.

Since the status field was mandatory in OR 1.0 delta submissions, the enabledUser field was made mandatory in later versions of OR. The ability to accept and understand the inactive status was mandatory in OR 1.0 as well, so it does not add further constraint to later versions of OR to require that a processor accept the enabledUser field.

6.3 Consideration of Learning Objective Support

OneRoster 1.2 added support for Learning Ojbectives via the ability to attach a set of learning objectives and their scores to line items. This is accomplished by attaching the guid for the appropriate learning objective to via the use of the new 'learningObjectiveIds' class.

Additionally, a result object has both a score and a textScore attribute. The result field is used to store numeric scores; the textScore is used to store non-numeric scores.

The resultValueMin and resultValueMax attributes are provided to give context for the score attribute and must not be used to interpret the textScore attribute.

The service provider should return an error code of 422, unprocessable entity, if they do not support standards-based grades. The service provider must be able to retain the right to require numeric values for their specific implementation.

6.4 Access to Specific Information

In some cases it may be desirable for an API provider to allow for the restricting of data to individual consumers without relying on the consumer’s proper use of query filters. This concept is different than what you normally see with OAuth scopes because while OAuth scopes define access to individual endpoints, data scoping may allow for limited access to data within each endpoint. Common examples of data scoping include:

6.4.1 Guardian information Use Case

Very few vendors need to consume guardian information. Most products only need student, staff and rostering information. If access to guardian information is not limited, when the question is asked: “Which vendors have access to guardian data?” we have to include all of our OneRoster connected vendors even though most vendors do not pull or even attempt to access the information.

Most districts have very strict parameters on when guardian information can be released beyond internal use, and it is important for districts to have that control within their OneRoster integrations. This gives confidence to families, school and district staff (including local board members), that guardian information is protected within OneRoster as it is in other integration types. Without limiting access to guardian information, districts are put in a potentially tough position of explaining why a vendor accessed guardian information when the contract does not specify that level of data would be released.

6.4.2 Information for Learners with Special Needs Use Case

While these use cases are very important and valuable, they should be considered implementation details on the API provider side and are not included a feature in the base OneRoster specification.

6.5 Resource License Allocation & Tracking

OneRoster 1.2 enhances systems ability to exchange resource allocation information. It may additionally be necessary for content providers to communicate not only the allocation of resources to a user or class but also the associated licensing information for customers / partners in order to facilitate resource binding and accurate licensing.

To accomplish this, a system can extend OneRoster (either REST or CSV) with an extension of the 'OrgResources' data set provided by the content provider extended to includes the following additional metadata fields:

  • License_StartDate
  • License_EndDate
  • metadata_LicenseType
  • metadata_LicenseValue

In this model, metadata_LicencyeType is defined as an enumerated list consisting of the following suggested values: Concurrent Users, Seat Count, Class Count, Concurrent User Type

The content consumer would then use the data in these metadata fields to populate their ‘CourseResources’ or ‘ClassResources’ data according to the aggregate metadata_ LicenseValue limits for a given resource that are active as of the metadata_StartDate and metadata_EndDate values

It should be understood that there may be multiple instances of a license for a resource as it may have been provisioned at different times. It would be useful for the content consumer to provide a warning when over enrollment happens or when licenses are nearing exhaustion.

6.6 Filtering fields in an array

The existing specification query syntax can be used to filter on fields in an array (e.g. a collection of userIDs on a User object). To achieve this, one should use the 'Contains' operator to inspect the contents of the array and find an object with multiple matched attributes. For example, to find a user with a sisId of 500, the syntax would be:

user.userIds~(type='sisId'ANDidentifier='500')

6.7 Supporting need for multiple phone numbers

It can sometimes be necessary to provide multiple phone numbers for some users. This makes contact possible when one of the phone numbers is unavailable or untenable for any reason. While OneRoster 1.2 supplies only one phone number field in the user class. There are 2 recommended paths to follow if you need multiple phone numbers.

  • Put the second number in the sms field of the user record. If you do this, you need to agree that this number can be used for voice calls.
  • Add a field via extension mechanisms. The suggested field name is metadata.secondaryPhone

7. CSV File Handling Best Practices

7.1 File Encoding and File Ordering

The file format for each of the data files is a comma separated values format (CSV) as specified in RFC 4180 with the extra restriction that carriage-returns are not permitted within a field. Fields containing commas and double-quotes must be enclosed in double-quotes. If double-quotes are used to enclose a field, then a double-quote appearing inside the field must be escaped by preceding it with another double-quote.

The CSV files must be UTF-8 encoded RFC3629. Importing processors must tolerate BOM (Byte Order Mark) prefixes and ignore them. In a UTF-8 encoded file with a BOM, the BOM will appear as the 3-byte sequence ‘EF BB BF’ at the beginning of the file. If present, the CSV header will begin at the 4th byte of the file; if not present, the CSV header will begin at the 1st byte of the file.

When the data is exchanged as CSV files, there will be 1-14 CSV files. An exchange MUST include the ‘manifest.csv’ file. The case of when only the ‘manifest.csv’ is supplied is used to denote that no updates occurred. At most, 14 CSV files exchanged i.e. there MUST NOT be more than one of each of the data CSV files. When the set of files are for bulk processing then they must be semantically consistent i.e. every object referenced in a file must also be defined in either the same, or one of the other files in the zip package.

The CSV files will be exchanged as a zip file. The encompassed files must be at the root level i.e. they MUST NOT be contained within an enclosing directory. There is NO constraint on the name of the zip file but it must have a file extension of ‘zip’. The compression must conform to RFC1951. Within the zip file there is NO preferred ordering of the CSV files.

7.2 Exchanging the CSV Files

The CSV files should be exchanged as a zipped file. These files must NOT be encrypted otherwise they will not pass validation: the transport mechanism is responsible for encrypting the data and so protecting the integrity of the CSV files.

The transport mechanism is out the scope of the CSV Binding.

7.3 Round-tripping Between OneRoster Versions

It is good best practice to support round-tripping between OneRoster versions without losing data. For example, consider when an organization submits a OR 1.2 CSV file to a OneRoster gateway that needs to support downstream consumers who support 1.2 as well as systems that only support 1.1. In this scenario sends it in v1.1 form, but rather than throwing away fields which are not part of the v1.1 specification, these are encoded as metadata fields of the same name.

For example if the v1.2 'users.csv' includes data in the 'primaryOrg' field convert that to a 'metadata.orv1p2.primaryOrg' field in the equivalent ORv1.1 CSV. While the 1.1 conformant system may not understand the semantics of 'primaryOrg', it may support the display of the metadata fields, including primary org to end users who need this information, and it may also have use where a system allows search filters include meta-data fields make use of the 'primaryOrg' information by filtering on 'metadata.orv1p1.primaryOrg'.

When converting between versions ALL the columns with 'metadata.**' should be placed as the final set of columns (the order is NOT significant).

7.4 Ensuring Semantic Consistency

For bulk exchange the set of CSV files MUST be semantically complete i.e. if a sourcedId reference for an object is used in one of the CSV files then that object MUST be defined somewhere in the set of CSV files (it may be the CSV file in which the reference occurs). The data models for the CSV files means that the following groups of files may be exchanged with the accompanying constraints of:

  • 'academicSessions.csv' - this file may contain references to other academicSessions and so ALL such definitions must be contained within the same file. This CSV file may be exchanged independently of other files;
  • 'categories.csv' - this file contains no references to other files and so it may be exchanged independently of other files;
  • 'classes.csv' - this file MUST contain references to the relevant academisSession, course and organization objects. Therefore it must be accompanied with the 'academicSessions.csv', 'courses.csv' and 'orgs.csv' files;
  • 'classResources.csv' - this file MUST contain references to the relevant academisSession, class, organization and resource objects. Therefore it must be accompanied with the 'academicSessions.csv', 'classes.csv', 'orgs.csv' and 'resources.csv' files;
  • 'courseResources.csv' - this file MUST contain references to the relevant academisSession, course, organization and resource objects. Therefore it must be accompanied with the 'academicSessions.csv', 'courses.csv', 'orgs.csv' and 'resources.csv' files;
  • 'demographics.csv' - this file MUST contain references to the relevant organization and user objects. Therefore it must be accompanied with the 'orgs.csv' and 'users.csv' files;
  • 'enrollments.csv' - this file MUST contain references to academicSession, class, course, organization and user objects. Therefore it must be accompanied with the 'academicSessions.csv', 'classes.csv', 'courses.csv', 'orgs.csv' and 'users.csv' files;
  • 'lineItems.csv' - this file MUST contain references to academicSession, categories, class, course, organization and user objects. Therefore it must be accompanied with the 'academicSessions.csv', 'categories.csv', 'classes.csv', 'courses.csv', 'orgs.csv' and 'users.csv' files;
  • 'courses.csv' - this file MUST contain references to the associated organization and may contain references to academicSession objects. Therefore it must be exchanged with an 'orgs.csv' file and may require an 'academicSessions.csv' file;
  • 'orgs.csv' - this file may contain references to other organizations and so ALL such definitions must be contained within the same file. This CSV file may be exchanged independently of other files;
  • 'resources.csv' - this file contains no references to other files and so it may be exchanged independently of other files;
  • 'results.csv' - this file MUST contain references to academicSession, categories, class, course, lineItem, organization and user objects. Therefore it must be accompanied with the 'academicSessions.csv', 'categories.csv', 'classes.csv', 'courses.csv', 'lineItem.csv', 'orgs.csv' and 'users.csv' files;
  • 'users.csv' - this file MUST contain references to the associated organization and may contain references to other user objects (whose definition must be contained within the same file). Therefore it must be exchanged with an 'orgs.csv' file.

The full details of this grouping of files is available in the OneRoster CSV definition OneRoster 1.2 CSV Binding. However, it should be noted that an implementation may require/supply more than the minimum set of semantically consistent files. For example is not uncommon to encounter implementations to require/provide the following sets of files:

  • For Rostering exchange - 'academicSessions.csv', 'classes.csv', 'courses.csv', 'enrollments.csv', 'orgs.csv' and 'users.csv' files;
  • For Resource exchange - 'academicSessions.csv', 'classes.csv', 'classResources.csv', 'courseResources.csv', 'courses.csv', 'enrollments.csv', 'orgs.csv' and 'resources.csv', 'users.csv' files;
  • For Gradebook exchange - 'academicSessions.csv', 'categories.csv', 'classes.csv', 'courses.csv', 'enrollments.csv', 'lineItems.csv', 'orgs.csv', 'results.csv' and 'users.csv' files;

7.5 Extending the Data Model for the CSV Files

Open vocabularies MAY be extended. These extensions should take the form of a URI so that the creator of the term is also supplied.

For CSV exchange, the data model can only be extended by adding new columns to the end of the defined set of columns. A suitable naming convention should be used for the new header names. An example is: metadata.[orglabel].[namepart] Where:

  • 'metadata' is the initial set of characters for all extensions;
  • [orglabel] is the label used to identify the organization that has created the extension. In the case of an extension from IMS Global this field will be empty and one of the delimiters removed;
  • [namepart] the unique header name part allocated by the organization for the data model.

Examples are: 'metadata.hmh.homeemail', 'metadata.pearson.namesuffix', etc.

7.6 Suggested Extension Fields

Below are a set of suggested metadata fields that can be added to some of the OneRoster 1.2 CSV files as well as the rationale behind using them.

7.6.1 'courses.csv' Data Model

Field Header Required Format Description
metadata.duration No String Description of how long the course runs for (e.g. two weeks, one semester).

Used to identify courses that may or may not be aligned with the length of the academic session.

7.6.2 'orgs.csv' Data Model

Field Header Required Format Description
metadata.classification No String Suggested option set: "charter"; "private"; "public".

This data represents useful information for school or district administrators to be used in funding based reporting
metadata.boarding No Boolean “true” if school is boarding school.
metadata.address1 No Boolean First line of the organization's free format address e.g. "80 Iron Point Circle".
metadata.address2 No Boolean Second line of the organization's free format address e.g. "Dept. 2100".
metadata.city No Boolean The city in which the organization operates e.g. Bismarck.
metadata.state No Boolean Postal abbreviation for the state/province in which the organization operates, e.g. 'ND' to represent 'North Dakota'.

The vocabulary for U.S. addresses.
The vocabulary for Canadian addresses.
metadata.postCode No Boolean The zip/postal code of the organization address, e.g. (for U.S. addresses) "91311" or "91311-5349", (for Canadian addresses) "K1A 0B1".
metadata.country No Boolean The country in which the organization operates. Use the CEDS Vocabulary.

7.6.3 'users.csv' Data Model

Field Header Required Format Description
metadata.pnpfileurl No String This is the URL for the user's Access for All Personal Needs and Preferences file. This file defines the configuration settings for the accessibility features for any computer systems to be used by the user. The contents of the file identified by this URL are as defined in the associated IMS AfA PNP 3.0 specification [AFA-30].
metadata.instructionalNeedsType No Array Suggestions option set: "IEP"; "504"; "ELL"; "G&T"

8. REST-based Exchanges Best Practices

8.1 Compatibility of the REST API between Versions

A system that is certified as OneRoster 1.0 or 1.1 must be separately certified for OneRoster 1.2 compliance. Updating an OR 1.0 or 1.1 system for OR 1.2 conformance testing requires the following changes:

  • The base URL must be changed from '/ims/oneroster/v1p1' to /ims/oneroster/{rostering|gradebook|resources}/v1p2.
  • The redefinition of the required endpoints (classified in the three groups of rostering, resources and gradebook) should be inspected (in OR 1.0 there was no subgrouping and support for only a subset of the endpoints is required). A set of new endpoints have been added.
  • The detailed data models must be investigated. A number of optional additional attributes have been made to the data models, some attributes in the data models have been renamed and some have had their types refined. These have created significant differences in some of the JSON payloads.

8.2 Authentication

OneRoster 1.2 requires OAuth 2.0 Bearer Tokens (Client Credentials Grant) as the authentication mechanism. Use of OAuth 1.0a message signing has been removed. For more information please review the IMS Security framework document.

8.3 Read, Write, Delete Choreography Implications

In OR 1.2, Read, Write and Delete choreography is only an issue for the Gradebook services endpoints. The set of Read endpoints provide the data 'pull' capability whereas the Write/Delete provide the 'push' capability. The specification does not prescribe any specific choreography. A choreography is defined to realize a specific workflow but the OR specification is designed to enable a wide range of workflow. Typically, a workflow will require a mix of the 'pull' and 'push' endpoints. Some issues to be considered when realizing a workflow are:

  • The Write and Delete endpoints can only operate on a single object at a time. Therefore, the REST API should not be used for large-scale deletions and data creation;
  • When an object has been 'deleted' the 'sourcedId' MUST not be reallocated and a Read request on that 'sourcedId' MUST result in a read failure (with a HTTP 404 code);
  • Care should be taken to avoid overlapping Read/Write requests at a Provider i.e. a Provider should not issue a Write request to a Consumer that has an incomplete Read request being processed by the Provider;
  • Care should be taken to avoid overlapping Read/Write requests at a Consumer i.e. a Consumer should ensure that a received Write/Delete request does not conflict with a concurrent and incomplete Read request. The manner in which the conflict is avoided is implementation dependent.

8.4 Gradebook Exchanges

8.4.1 Assignment Grade Transfer

Assignment-level grade transfer is important for K-12 districts and schools that use SIS technology for state reporting requirements. Typically, the LMS serves as a system of record for assignment data and facilitates the assignment grade transfer on an on-demand or scheduled basis. The SIS provider acts as a grade data consumer and exposes endpoints to accept the assignment grade data from the LMS. OneRoster v1.2 gradebook services provide a set of specific RESTful endpoints to facilitate assignment grade data transfer.

OneRoster v1.2 gradebook services recommend a set of specific RESTful endpoints to facilitate assignment grade data transfer. In a typical assignment grade data transfer implementation, the LMS serves as a system of origin for 'lineItem' and 'result' objects. The majority of SIS gradebooks require an end user to segregate 'lineItem' objects by 'lineItem' grading categories such as “homework”, “quizzes” or “essays”. Best practice is for the SIS provider to expose 'lineItem' categories available for the end user in the SIS gradebook via the 'categories' endpoint. The LMS provider will request categories on an on-demand or scheduled basis to allow an end user to maintain SIS LineItem category nomenclature and sourcedIds in the LMS.

Commonly, the LMS should provide the end user with a utility to request the transfer of assignment grades to an SIS gradebook on an on-demand or scheduled basis. When a grade transfer is requested, the LMS assembles the LineItem and/or LineItem Result dataset and pushes it to the SIS gradebook. The LMS uses 'putLineItem' and 'putResult' RESTful endpoints to insert assignment and assignment grade objects into the SIS gradebook. The following use cases are commonly accepted in the industry:

Step 1: LMS imports LineItem Categories from SIS via GET Categories service call:

  • SIS generally supplies:
    • sourcedId (use UUID or GUID to avoid any data collision)
    • category title
    • category status
    • Metadata Optional: link to course, class, teacher user or gradebook via corresponding sourcedId (allows the LMS provider to set proper permissions around access to grading categories in LMS course gradebook)
  • The LMS generally imports LineItem Categories on an on-demand or scheduled basis:
    • request LineItem Categories from the SIS via the getCategories endpoint
    • create SIS LineItem Categories in the LMS
    • allow the end user to associate line items with grading categories imported from the SIS Step 2: LMS generally creates LineItem object in the SIS via PUT LineItem service call:-
  • Dataset commonly required by the SIS:
    • LineItem sourcedId (use UUID or GUID to avoid any data collision)
    • Title
    • dueDate
    • Class
    • Category
    • Result Value

Step 3: LMS generally creates Result object in SIS via PUT Result service call by providing GUID or UUID for each result record;

Step 4: LMS generally replaces LineItem object in SIS via PUT LineItem service call:

  • SIS to allow LMS:
    • Replace all data elements in the existing lineitem records with new values;
    • Override lineItem data element values multiple times;
    • Restore a lineItem record after it has been soft deleted from the SIS e.g. when the end user accidentally deletes a lineItem in the SIS but the lineItem is still active in the LMS.

Step 5: LMS generally replaces Result object in SIS via PUT Result service call:

  • SIS to allow LMS:-
    • Override Line Item Result data element values multiple times;
    • Restore a Result object with PUT Result service call after it has been soft deleted from the SIS e.g when the end user accidentally deletes a line item result in the SIS but the line item is still an active result in the LMS

Step 6: LMS generally deletes LineItem object in SIS via DELETE LineItem service call:

  • SIS to update Line Item status to “tobedeleted” (for soft delete);
  • SIS to remove Line Item from the SIS gradebook (for hard delete);

Step 7: LMS generally deletes Result object in SIS via DELETE Result service call:

  • SIS to update Result status for result record that matches provided result sourcedId to “tobedeleted” status (for soft delete);
  • SIS to permanently remove Result record that matches provided result sourcedId from SIS gradebook (for hard delete). It should be noted that OneRster does NOT allow the sourcedId of the result record that was previously deleted to be reused.

8.5 Matching End-to-End Service Capabilities

The available certifications for a OR 1.2 REST implementation is summarized in Table 5.1.

REST API
Functional Mode
(at least one must be supported)
Provider Consumer
Core Other Core Other
Rostering Required Optional Required Optional
Resources Required Optional Required Optional
Gradebook Required (Pull or Push) Optional Required (Pull or Push) Optional

Therefore, when matching whether or not two certified OR 1.2 REST systems can exchange data the following rules should be applied:

  • A Provider/Consumer pair WILL have core endpoint interoperability if they support the same mode(s) pairings of operation i.e. rostering/rostering, resources/resources, gradebook(pull)/gradebook(pull) and gradebook(push)/gradebook(push) pairings;
  • For a common pairing there will also be interoperability for ANY of the optional endpoints that are supported by both the provider/consumer;
  • Only the mandatory data attributes are guaranteed to be exchanged. Different systems will support different combinations of the optional data attributes and so a mapping between the capabilities of the provider/consumer must be undertaken (this information is not available from the IMS certification report or the IMS product database);
  • ALL REST implementations MUST support the OAuth 2.0 Bearer Tokens (Client Credentials Grant).

8.6 Escaping Characters in Filter Criteria

Section 6.1 describes the file encoding requirements for OneRoster CSV. Additionally It is necessary in some scenarios to escape a character that exists within the text of a field in the filter criteria of a REST call. The way to add filter criteria is to surround the text with single quotes. However if you require a single quote character as a value in the filter string then use a double single quote to escape that character.

For example, to do a filter for users with the last name O'Connor you would send a GET to.

.../oneroster/ims/oneroster/v1p2/users?filter=lastName='o''connor'

8.7 Enhance filter syntax to support filtering fields in an array

The existing specification query syntax may be used to filter on fields in an existing array (e.g. a collection of userIDs on a User object). To achieve this, one should use the ‘Contains’ operator to inspect the contents of the array and find an object with multiple matched attributes. For example, to find a user with a sisId of 500, the syntax would be:

user.userIds~(type='sisId'ANDidentifier='500')

8.8 Extending the REST API

By definition the creation and use of extensions creates features that are not interoperable. Extensions must NOT be used to replace the supported functionality. Extensions should be created as a last resort. There are two ways in which the REST API can be extended:

  • Adding endpoints - new endpoints can be defined and added to the API. Such endpoints should follow the pattern of the established endpoints and the associated JSON payloads should be well defined and, if required, use the same data model extension method as used for the other endpoints;
  • Adding to the data model - the data model includes a 'metadata' class that MUST be used when new attributes are to be added to a JSON payload (the use of this class is explained in the OneRoster 1.2 specification [OneRoster, 17a]. The addition of attributes into a JSON payload using any other technique is PROHIBITED;
  • Adding Scopes - new scopes can be defined and agreed to between partners. Such scopes should be defined and agreed to between partners. The considerations are detailed below.

It is recommended that organizations that wish to create extensions contact IMS Global (Lisa Mattson, IMS COO).

8.9 Extending the Scopes

The OneRoster 1.2 REST Binding documents for each service define the set of specified scopes. However it can be valuable at some times to create specific and refined access to specific information as needed to support a given integration. The url naming pattern for the scope should be "http://purl.imsglobal.org/spec/or/v1p2/scope/[scopename].operation" and should be recognizable for the access that it provides.

The scope should provide access to a specific set of the OneRoster 1.2 operation endpoints as defined by the specification that are not already covered by the OneRoster 1.2 service bindings.

When defining the definition of the scope between the integration partners the operation, HTTP Verb and Endpoint's included should be defined.

For Example if you have an integration with an application looking to provide notifications to users with the guardian role, you may wish to limit their access to only the get users and get individual user endpoints. That scope might be defined as:

Operation HTTP Verb Endpoint
getAllUsers GET /users
getUser GET /users/{sourcedId}

9. Realizing the Use Cases

Some of the use-cases that can be supported using OR 1.2 are:

  • Making roster information available;
  • Establishing and maintaining a district repository for K-12 Information;
  • Identification of Resource Allocation;
  • SIS/LMS exchange of gradebook information;
  • Real-time bulk exchange of OneRoster information;
  • Batch bulk exchange of OneRoster information.
  • Standards Based Gradebook Exchange

9.1 Making Roster Information Available

Rostering data can be made available through the REST API or as a set of exported CSV files. Exported CSV files should be used when real-time availability is not required and/or when the size of the data-set is excessive i.e. gigabytes. Once the zip file containing the CSV files has been created the method of exchanging the file is implementation dependent. The REST API makes collections of data sets available depending on the endpoint i.e. all of the 'user' objects are available from one endpoint, a separate endpoint is used for obtaining all of the 'course' objects, etc. Therefore, obtaining a mixed set of objects requires the use of more than one endpoint (the corresponding choreography is implementation dependent). The REST API permits reading of the roster data ONLY i.e. the consumer MUST issue a read request to the provider.

9.2 Establishing and Maintaining a District Repository for K-12 Information

Large-scale data aggregation should be realized using CSV Import. The manner in which the zip file data is made available for import is implementation dependent i.e. it is NOT defined as part of the OR specification. The supplier of the CSV files is responsible for assigning/identifying each record with a 'sourcedId'. Therefore, there may be 'sourcedId' clashes when zip files are supplied from more than one supplier/source. Import of a set of CSV files using the bulk mode is used to establish/redefine the data set whereas the delta mode is used to update the data set. The aggregation of data from multiple sources should be carefully managed to ensure that data separation/integrity is managed appropriately.

9.3 Identification of Resource Allocation

OR 1.2 continues to support the ability to identify the set of resources that are required for a class and/or course. This identification uses a GUID for the resource i.e. it does not include the actual resource (one way of obtaining the resource is to use an IMS Common Cartridge/Thin Common Cartridge which provides the access to the resource via an identifier). The resource identification can be supplied using either CSV-based or REST API-based exchange.

9.4 SIS/LMS Exchange of Gradebook Information

OR 1.2 expands on the support for the exchange of gradebook information added in v1.1. Both CSV-based and REST API-based approaches are available. In the case of the REST API both 'push' and 'pull' endpoints are available. In many implementations there is a choreography using both push and pull approaches (see Section [7.4.1](#Assignment Grade Transfer)for a detailed explanation of how this can be achieved).

9.5 Standards Based Gradebook Exchange

OR 1.2 adds the ability to align learning objectives to gradebook lineitems and their results via the use of their framework guids. This is done using the 'learningObjectiveSet' class that has been added as part of OR 1.2.

9.5.1 Resource License Allocation & Tracking

OneRoster 1.2 facilitates the exchange of resource allocation information. It may additionally be necessary for content providers to communicate not only the allocation of resources to a user or class but also the associated licensing information for customers / partners in order to facilitate resource binding and accurate licensing.

To accomplish this, a system can extend OneRoster (either REST or CSV) with an extension of the ‘OrgResources’ data set provided by the content provider extended to includes the following additional metadata fields:

  • License_StartDate
  • License_EndDate
  • metadata_LicenseType
  • metadata_LicenseValue

In this model, metadata_LIcencyeType is defined as an enumerated list consisting of the following suggested values:

  • Concurrent Users
  • Seat Count
  • Class Count
  • Concurrent UserType

The content consumer would then use the data in these metadata fields to populate populate their ‘CourseResources’ or ‘ClassResources’ data according to the ‘aggregate metadata_ LicenseValue’ limits for a given resource that are active as of the ‘metadata_StartDate’ and ‘metadata_EndDate’ values

It should be understood that there may be multiple instances of a license for a resource as it may have been provisioned at different times.

It would be useful for the content consumer to provide a warning when over enrollment happens or when licenses are nearing exhaustion.

9.6 Real-time Bulk Exchange of OneRoster Information

This is achieved using the REST API with the consumer system reading the data sets from the provider. The consumer must issue a set of read requests on each of the collections that are required for the batch exchange. The REST API defines a pagination mechanism to ensure that the consumer can control the amount of data that it will receive in each response payload. The consumer will issue a sequence of requests until all of the collection has been received. The next collection can then be requested. The order of the reading of the collections is determined by the consumer.

9.7 Batch Bulk Exchange of OneRoster Information

This is achieved using CSV export/import. The source system creates the set of CSV files using OR 1.2 CSV export to create the new zip file. This file is now transported to the receiving system (the method of transport is implementation dependent e.g. using secure FTP, etc.). The receiving system must now import the CSV file set using OR 1.2 CSV import capability. If errors are detected during the import then a manual recovery mechanism must be used.

9.8 Handling Users with Start and/or End Dates

Sometimes it may be necessary to indicate that a user has left an organization mid-year. Common examples are dropouts or a student changing schools.. It may be desired to maintain the now defunct org association until the end of the year. This is handled by the use of the beginDate and endDate fields on the 'Role' object in the 'User' Model. Below are examples payloads detailing how this might be accomplished for the 2 scenarios mentioned.

9.8.1 Scenario 1: Student Drops Out Mid Year

9.8.2 Scenario 2: Student Changes Schools Mid Year

10. Working with Other IMS Specifications

10.1 CASE - Competencies and Academic Standards Exchange

The IMS Global CASE standard is designed to align learning content, activities, assessments, and assertions of mastery with academic standards. Work has been done in OneRoster 1.2 to allow for the alignment of learning objectives with results. Using the new learningObjectiveSet attribute on the 'lineItem' or 'assessmentLineItem' class, systems can now exchange information about which learning standards are aligned with the gradebook entries as well as exchange the related results information by including the corresponding CASE guid.

10.2 User roles and how they compare to other specifications

10.2.1 Institutional Roles

Role Name New? Role Description IRI or recommendation
aide   Someone who provides appropriate aid to the learner but NOT also one of the other roles. http://purl.imsglobal.org/vocab/lis/v2/institution/person#Staff
counselor Someone who has care/pastoral supervision responsibility for one or more people. http://purl.imsglobal.org/vocab/lis/v2/institution/person#Mentor
districtAdministrator The district administrator will have responsibility for systems within the district sites and/or for systems that are accessed by the schools in the district. http://purl.imsglobal.org/vocab/lis/v2/institution/person#Administrator
guardian   Guardian of the user and NOT the Mother or Father. May also be a Relative.  
parent   Mother or father of the user.  
principal The schools' Principal or other very senior academic administrator in the School. The principal will have access to confidential/private data about teachers, etc.  This is also meant to account for senior leadership in non-US locales such as a Headmaster. http://purl.imsglobal.org/vocab/lis/v2/institution/person#Administrator
proctor   Exam proctor. May be used for enrollment. http://purl.imsglobal.org/vocab/lis/v2/institution/person#Observer
relative   A relative of the user and NOT the Mother or Father. May also be the Guardian.  
siteAdministrator Site administrator in the organization e.g. School. The site administrator will have responsibility for all of the systems at the site. http://purl.imsglobal.org/vocab/lis/v2/institution/person#Administrator
student   A student at an organization e.g. School. May be used for enrollment. http://purl.imsglobal.org/vocab/lis/v2/institution/person#Student
systemAdministrator System administrator in the organization e.g. School. The system administrator will have responsibility for one of more systems at the site. http://purl.imsglobal.org/vocab/lis/v2/system/person#SysAdmin
teacher   A Teacher at organization e.g. School. May be used for enrollment. http://purl.imsglobal.org/vocab/lis/v2/institution/person#Faculty

11. Revision History

Release Date Comments
02 December 2020 Candidate Final Release
01 July 2021 Candidate Final Public Release

A. References

A.1 Normative references

[AFA-30]
AccessForAll v3.0. IMS Global Learning Consortium. September 2012. IMS Public Draft. URL: https://www.imsglobal.org/activity/accessibility/
[CASE-SM]
Competencies and Academic Standards Exchange (CASE) Service 1.0 Specification. Bruce, Grogan; Greg, Nadeau; Jill, Hobson; Colin, Smythe. IMS Global Learning Consortium, Inc. July 2017. URL: https://www.imsglobal.org/sites/default/files/CASE/casev1p0/information_model/caseservicev1p0_infomodelv1p0.html
[OR-ARP-12]
IMS Assessment Results Profile for Gradebook Service. Colin, Smythe; Matthew, Richards; Joshua, McGhee. IMS Global Learning Consortium, Inc. July, 2021. URL: https://www.imsglobal.org/spec/oneroster-arp/v1p2/
[OR-CERT-12]
OneRoster 1.2 Conformance and Certification Guide. Colin, Smythe; Matthew, Richards; Joshua, McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/spec/oneroster/v1p2/cert/
[OR-CSV-12]
OneRoster 1.2 CSV Binding. Colin Smythe; Matthew Richards; Joshua McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/ims-oneroster-v1p2-final-csvbindv1p0.html
[OR-GBK-RJ-12]
OneRoster 1.2 Gradebook Service REST Binding. Colin, Smythe; Matthew, Richards; Joshua, McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/ims-oneroster-gradebook-v1p2-final-restbindv1p0.html
[OR-GBK-SM-12]
OneRoster 1.2 Gradebook Service Information Model. Colin Smythe; Matthew Richards; Joshua McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/ims-oneroster-gradebook-v1p2-final-infomodelv1p0.html
[OR-IMPL-12]
OneRoster 1.2 Implementation Guide. Colin, Smythe; Matthew, Richards; Joshua, McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/spec/oneroster/v1p2/impl/
[OR-RES-RJ-12]
OneRoster 1.2 Resource Service REST Binding. Colin, Smythe; Matthew, Richards; Joshua, McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/ims-oneroster-resource-v1p2-final-restbindv1p0.html
[OR-RES-SM-12]
OneRoster 1.2 Resource Service Information Model. Colin, Smythe; Matthew, Richards; Joshua, McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/ims-oneroster-resource-v1p2-final-infomodelv1p0.html
[OR-ROS-RJ-12]
OneRoster 1.2 Rostering Service REST Binding. Colin, Smythe; Matthew, Richards; Joshua, McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/ims-oneroster-rostering-v1p2-final-restbindv1p0.html
[OR-ROS-SM-12]
OneRoster 1.2 Rostering Service Information Model. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/ims-oneroster-rostering-v1p2-final-infomodelv1p0.html
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

B. List of Contributors

The following individuals contributed to the development of this document:

Name Organization Role
Eric AdamsKimono
Joshua McGheeIMS GlobalEditor
Colin SmytheIMS GlobalEditor
Lisa MattsonIMS Global
Arthur BarstowMcGhraw-Hill Education
Barry BrahierInfinite Campus
Vijay DhanarajClasslink
Linda FengUnicon
Viktor HaagDesire2Learn
Richard HeimLearningMate
David MayesGwinnett County Schools
Padraig O'hiceadhaHMH
George PerreaultClasslink
Matt RichardsInfinite CampusCo-Chair
Kurt RompotPearson
Hank DavidsonPearson
Jong KimPearson
Upendra PenegalapatiPearson
Konrad StimelingK12 Inc
Matt VellaSchoology
TJ VeringMicrosoft
Stanley WattsClasslink
Mike ZackersonInstructure
David GappaSafari Montage
Tom IngramEscambia County School District
Mike KaastraDesire2Learn
James PerreaultFLVS
Patrick PorterHouston ISD
Mark WallsGwinnett County Schools
Sari ConnardPerformance Matters
Andrew KuritzkyHMH
Wendy RiedySungard K12
Aditya SubramaniamSchoology
Gabrielle SandersonRennaissance Learning
Tom ClarkPearson

IMS Global Learning Consortium, Inc. ("IMS Global") is publishing the information contained in this document ("Specification") for purposes of scientific, experimental, and scholarly collaboration only.

IMS Global makes no warranty or representation regarding the accuracy or completeness of the Specification.

This material is provided on an "As Is" and "As Available" basis.

The Specification is at all times subject to change and revision without notice.

It is your sole responsibility to evaluate the usefulness, accuracy, and completeness of the Specification as it relates to you.

IMS Global would appreciate receiving your comments and suggestions.

Please contact IMS Global through our website at http://www.imsglobal.org.

Please refer to Document Name: OneRoster v1p2 Implementation and Best Practices Guide 1.2

Date: July 01, 2021