1EdTech Final Release

1EdTech Logo

1EdTech OneRoster®: Conformance and Certification

1EdTech Final Release
Version 1.1

Date Issued: 31st December 2020
Latest version: http://www.imsglobal.org/lis/

IPR and Distribution Notices

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.

1EdTech 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 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2020 1EdTech Consortium. All Rights Reserved.

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech 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 1EdTech 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/learning-information-services-oneroster-public-forum.

© 2020 1EdTech Consortium, Inc.
All Rights Reserved.

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

The 1EdTech Logo and OneRoster are trademarks of the 1EdTech Consortium, Inc. in the United States and/or other countries.
Document Name: 1EdTech OneRoster® 1.1 Conformance and Certification v1.1

Revision: 31st December, 2020

 

Table of Contents

1. Introduction

1.1 Scope and Context

1.2 Status of this Document

1.3 Structure of this Document

1.4 Related Documents

1.5 Nomenclature

2. The Conformance Process

2.1 Conformance Testing Process

2.1.1 Requirements for OneRoster v1.1 Conformance

2.1.2 OneRoster Conformance Mark

3. CSV Exchange Conformance

3.1 CSV File Compliance

3.2 Systems Compliance

3.2.1 Importing CSV Files

3.2.2 Exporting CSV Files

3.3 CSV File Processing Certification

3.3.1 CSV Importers Certification

3.3.2 CSV Exporters Certification

3.3.3 CSV Importers/Exporters Certification

4. REST-based Exchange Conformance

4.1 Service Providers Compliance

4.1.1 Rostering Endpoint Compliance

4.1.2 Gradebook Endpoint Compliance

4.1.3 Resources Endpoint Compliance

4.2 Service Consumers Compliance

4.2.1 Rostering Endpoint Compliance

4.2.2 Gradebook Endpoint Compliance

4.2.3 Resources Endpoint Compliance

4.3 OneRoster REST Service Certification

4.3.1 Service Provider Certification

4.3.2 Service Consumer Certification

4.3.3 A Comparison of the Certifications

5. OneRoster Certifications

About this Document

List of Contributors

Revision History

 

1. Introduction

1.1 Scope and Context

The OneRoster® standard is designed to be a subset of the full 1EdTech Learning Information Services (LIS) standard that focuses on the K-12/Schools needs to exchange roster information and grades. The standard includes a REST-based binding (also described by an OpenAPI [OpenAPI, 14] file) to make it quicker and easier to implement the exchange of information about people, membership, courses and gradebooks. In addition to the REST binding description, a format for CSV file based exchange has also been included (CSV files are typically exchanged between the school and the vendor to populate the roster information needed to gain access to learning tools, portals and learning environments).

The purpose of this document is provide the details of the conformance process and certifications available for the 1EdTech OneRoster 1.1 standard. Conformance certification is available for:

  • Systems that import and/or export OneRoster CSV files;
  • Systems that act as service providers and/or service consumers of the REST-based OneRoster services.

1.2 Status of this Document

This document is the Final Release, meaning the technical solution is now made available as a public document and as such several 1EdTech Members have aleady successfully completed conformance certification at the time of release of the document.

1EdTech strongly encourages its members and the community to provide feedback to continue the evolution and improvement of the OneRoster standard. To join the 1EdTech developer and conformance certification community focused on OneRoster please visit the 1EdTech OneRoster Alliance online here: http://www.imsglobal.org/lis/index.html

Public contributions, comments and questions can be posted here: Public OneRoster Forums.

1.3 Structure of this Document

The structure of the rest of this document is:

2. The Conformance Process The formal process to be undertaken by a vendor wishing to obtain OneRoster conformance certification;
3. CSV Exchange Conformance Conformance testing to be undertaken by systems seeking CSV exchange certification and/or verification that the CSV files are conformant;
4. REST-based Exchange Conformance Conformance testing and the available conformance certifications for vendors seeking conformance to the OneRoster REST-based exchange;
5. OneRoster Certifications A summary of the set of possible OneRoster certifications that a product could obtain and an explanation of how these could be combined to make a product solution.

1.4 Related Documents

[OneRoster, 17a] OneRoster Specification and REST Binding v1.1, P.Nicholls and C.Smythe, 1EdTech Consortium, Inc., April 2017, http://www.imsglobal.org/lis/imsonerosterv1p1/imsOneRoster-v1p1.html.
[OneRoster, 17b] OneRoster 1.1 CSV Tables, P.Nicholls and C.Smythe, 1EdTech Consortium, Inc., April 2017, https://www.imsglobal.org/lis/imsOneRosterv1p1/imsOneRosterCSV-v1p1.html.
[OAuth, 10] OAuth Version 1.0 (RFC 5849), IETF, April 2010, http://www.rfc-editor.org/info/rfc5849.
[OpenAPI, 14] OpenAPI Specification (fka Swagger RESTful API Documentation Specification), Open API Initiative (Linux Foundation), September 2014, https://openapis.org/specification.

1.5 Nomenclature

API Application Programming Interface
CSV Comma Separated Values
HTTP HyperText Transfer Protocol
IUT Implementation Under Test
LIS Learning Information Services
REST Representational State Transfer
SHA Secure Hash Algorithm

 

2. The Conformance Process

2.1 Conformance Testing Process

The process for conformance testing implementations of OneRoster includes the following:

  • Go to the 1EdTech Conformance Test Suite for OneRoster for either the REST or CSV version of OneRoster. Conformance Test Suite links are available in the 1EdTech LIS Alliance and the relevant link details are given in Sections 3 and 4 of this document;
  • Follow the onscreen instructions to run the tests;
  • Once the test has been successfully run, submit a print out of the test results along with the following information to conformance@imsglobal.org:
    1. Your Name
    2. Your Organization
    3. Your Product Name and Version
    4. Date the Product was tested
    5. Whether you are a Service/Data Provider or a Service/Data Consumer
    6. Whether you support the REST version, the CSV Version or both REST and CSV
    7. The optional features supported by your system (these must also have been subjected to conformance testing).

All Tests for either version must be passed successfully to be considered 1EdTech compliant.

2.1.1 Requirements for OneRoster v1.1 Conformance

All Tests for either the REST version or the CSV version must be passed successfully to be considered 1EdTech OneRoster compliant. There are three functional modes:

  • Rostering - the enrolment of people in classes;
  • Resources - the association of teaching/learning resources with courses/classes;
  • Gradebooks - the scores/grades for a learner who has completed some assessment of their learning activity on a class/course.

For CSV conformance ALL systems MUST support the 'Rostering' mode and for every operational processing mode that is supported by the product. For example, if both CSV import and export processing are supported then 'Rostering' for BOTH of these is required.

For the REST binding ALL systems MUST support at LEAST ONE of the 'Rostering', 'Resources' and 'Gradebooks' modes.

2.1.2 OneRoster Conformance Mark

After you have submitted your successful conformance information to conformance@imsglobal.org, and received confirmation and a registration number from 1EdTech you may then apply the appropriate conformance mark. The 1EdTech conformance chart will list your conformance details. If you have any questions, please feel free to contact us at any point.

Membership in the OneRoster/Learning Information Services Alliance is the only way to achieve official conformance to the OneRoster standard. Products without a 1EdTech conformance Registration Number are not considered to be compliant by 1EdTech.

Bug/Issues with Certification Suite

If you encounter any bugs in the certification suites, you can send your issue to bug-report@imsglobal.org or log it in github here:

https://github.com/IMSGlobal/certificationsuite-issues/issues

 

3. CSV Exchange Conformance

The 1EdTech Conformance program provides conformance testing for:

  • The set of CSV files that are to be exchanged;
  • The systems that either import and/or export CSV files.

It should be noted that all filenames, column headers and data values are case sensitive. Incorrect use of case will result in the corresponding conformance error being reported.

Details about OneRoster conformance are available at the webpage: https://www.imsglobal.org/oneroster-conformance-testing.

3.1 CSV File Compliance

The 1EdTech OneRoster CSV validator is available to test the validity of CSV files. This validator is available at:  https://onerostervalidator.imsglobal.org:8443/oneroster-server-cts-webapp/instructions. For OneRoster 1.0 this validator requires the CSV files to be submitted individually. For OneRoster v1.1 the set of CSV files are submitted as single zipped file. The validator will check that the ‘manifest.csv’ file is present and correctly structured. Next it will check the accompanying data CSV files for correctness. Finally it will provide a report on the correctness of the set of CSV files. Note that ONLY the ‘manifest.csv’ file is required in the zip file i.e. any combination of accompanying data model CSV files is permitted provided that these are semantically complete and self-consistent.

CSV files are defined as either 'BULK' or 'DELTA' processing. Bulk and Delta based CSV files have different content requirements and the validator will check for that consistency: all records in a single CSV file must be bulk or delta processing i.e. a mixture is NOT permitted and will be result in the file being declared invalid.

The OneRoster CSV validator is definitive when establishing whether or not a set of CSV files is conformant to the OneRoster specification.

3.2 Systems File Compliance

All systems, whether supporting import and/or export, must handle BULK processing content. Support for DELTA content is optional. Also, all systems must support the core set of rostering CSV files (this minimum set ensures semantic consistency for rostering information). Support for the non-rostering-oriented files is optional but the set of supported files must still create semantically consistent data exchange.

3.2.1 Importing CSV Files

Determining whether or not a system that imports OneRoster CSV files is conformant is based upon a report generated from the importing of the reference test set of OneRoster CSV files. This test set contains multiple zip files each of which must be imported by the Implementation Under Test (IUT). This set of zip files consists of two types of test files:

  • CSV files that are syntactically correct and semantically consistent;
  • CSV files which are syntactically incorrect and/or semantically inconsistent.

In the case of the files with known errors, a system must indicate that the files are incorrect. How those errors are reported and the subsequent file processing is implementation dependent and not subject to conformance. However, establishing whether or not a system is compliant requires the vendor to demonstrate that the CSV files have been appropriately processed and any errors detected.

A conformant system is NOT required to import every type of data model CSV file. A conformant system must import, completely, the ‘manifest.csv’ file, the mandatory set of CSV data files and any of the optional data model CSV files supported by the OneRoster system undergoing conformance (the set of supported CSV files must be identified during conformance). The correct CSV files must be processed appropriately i.e. updates according to any delta changes, etc. The mandatory set, or core, of CSV data files that MUST be supported for import is (note that it is NOT a requirement that every set of CSV files contain this core set):

  • ‘academicSessions.csv’ - bulk mode;
  • ‘classes.csv’ - bulk mode;
  • ‘courses.csv’ - bulk mode;
  • ‘enrollments.csv’ - bulk mode;
  • ‘orgs.csv’ - bulk mode;
  • ‘users.csv’ - bulk mode.

Therefore, the CSV data files that MAY be supported for import are:

  • ‘academicSessions.csv’ - delta mode;
  • ‘classes.csv’ - delta mode;
  • ‘courses.csv’ - delta mode;
  • ‘enrollments.csv’ - delta mode;
  • ‘orgs.csv’ - delta mode;
  • ‘users.csv’ - delta mode;
  • ‘categories.csv’ - bulk and/or delta mode;
  • ‘classResources.csv’ - bulk and/or delta mode;
  • ‘courseResources.csv’ - bulk and/or delta mode;
  • ‘demographics.csv’ - bulk and/or delta mode;
  • ‘lineItems.csv’ - bulk and/or delta mode;
  • ‘results.csv’ - bulk and/or delta mode;
  • ‘resources.csv’ - bulk and/or delta mode.

Any system claiming that it supports import of the above optional data files MUST demonstrate the correct importing of the reference test set as part of the conformance. Note that the requirement for semantic consistency means that not all combinations of the set of optionally supported file imports is permitted.

An importing system MUST support all of the required and optional data fields within the OneRoster specification. It is not a requirement that all of the data is stored internally but an importer must not flag as in error a CSV file that contains data that cannot be stored by the importing system.

The test set includes files sets that are semantically incomplete and these inconsistencies must be detected and the appropriate error messages logged. The test set also includes CSV files that have extensions. A system is not required to process these extensions but it must not result in the import files being rejected as invalid. A system that can process bulk files only must be capable of detecting delta files as invalid and logging the appropriate error information.

If a 'manifest.csv' file is NOT present in the zip file then an importing system MUST assume the set of files are as per the OR 1.0 CSV specification. The importing system must flag an error. Subsequent error handling is implementation dependent BUT if a system wishes to claim it can correctly process the OR 1.0 CSV files it MUST also be OR 1.0 compliant i.e. it MUST have been certified for both OR 1.0 and OR 1.1 specifications.

The set of OneRoster Reference Test CSV Files are available from 1EdTech through the OneRoster Conformance web pages (https://www.imsglobal.org/oneroster-conformance-testing).

Support for Importing Gradebooks and Resources

Systems that are certifed to support the importing of resources as well as rostering must support the following files (the files marked by '*' are the extra files to be supported):

  • ‘academicSessions.csv’ - bulk mode;
  • ‘classes.csv’ - bulk mode;
  • ‘courses.csv’ - bulk mode;
  • ‘enrollments.csv’ - bulk mode;
  • ‘orgs.csv’ - bulk mode;
  • ‘users.csv’ - bulk mode;
  • ‘classResources.csv’ - bulk mode*;
  • ‘courseResources.csv’ - bulk mode*;
  • ‘resources.csv’ - bulk mode*.

Systems that are certifed to support the importing of gradebooks as well rostering must support the following files (the files marked by '*' are the extra files to be supported):

  • ‘academicSessions.csv’ - bulk mode;
  • ‘classes.csv’ - bulk mode;
  • ‘courses.csv’ - bulk mode;
  • ‘enrollments.csv’ - bulk mode;
  • ‘orgs.csv’ - bulk mode;
  • ‘users.csv’ - bulk mode;
  • ‘lineItems.csv’ - bulk mode*;
  • ‘results.csv’ - bulk mode*;
  • ‘categories.csv’ - bulk mode*.

3.2.2 Exporting CSV Files

Determining whether or not a system that exports OneRoster CSV files is conformant is based upon the use of the OneRoster CSV validator to determine that the exported CSV files are valid. The IUT is required to export a set of CSV files that demonstrates the full range of the export capabilities of the IUT. These zip files must be validated by the 1EdTech OneRoster validator. The resulting set of reports, and the corresponding CSV files, must be submitted to 1EdTech as part of the conformance claim.

The submitted set of zipped CSV files must include examples of every one of the possible CSV files and must support contain ‘bulk’ and, if appropriate, ‘delta’ data sets. Support for the full range of the data models must also be demonstrated.

The demonstration set may contain extension fields but these must be the last set of columns. The header names for the extensions must not duplicate any of the other header names in CSV.

A system is NOT required to create all of the CSV files. A conformant system MUST be capable of creating the ‘manifest.csv’ file, the set of core data CSV files plus any of the other OneRoster CSV file as identified by the conformance claim and sustaining the semantic consistency. The range of data model CSV files created by the OneRoster system under test MUST be defined as part of the conformance. The mandatory, or core, set of CSV data files that MUST be supported for export is (note that it is NOT a requirement that every set of CSV files contain this core set):

  • ‘academicSessions.csv’ - bulk mode;
  • ‘classes.csv’ - bulk mode;
  • ‘courses.csv’ - bulk mode;
  • ‘enrollments.csv’ - bulk mode;
  • ‘orgs.csv’ - bulk mode;
  • ‘users.csv’ - bulk mode.

Therefore, the CSV data files that MAY be supported for export are:

  • ‘academicSessions.csv’ - delta mode;
  • ‘classes.csv’ - delta mode;
  • ‘courses.csv’ - delta mode;
  • ‘enrollments.csv’ - delta mode;
  • ‘orgs.csv’ - delta mode;
  • ‘users.csv’ - delta mode;
  • ‘categories.csv’ - bulk and/or delta mode;
  • ‘classResources.csv’ - bulk and/or delta mode;
  • ‘courseResources.csv’ - bulk and/or delta mode;
  • ‘demographics.csv’ - bulk and/or delta mode;
  • ‘lineItems.csv’ - bulk and/or delta mode;
  • ‘results.csv’ - bulk and/or delta mode;
  • ‘resources.csv’ - bulk and/or delta mode.

Any system claiming that it supports export of the above optional data files MUST demonstrate the correct exporting of the files using the OneRoster CSV Validator. The set of exported files MUST be semantically consistent otherwise the export capability will be declared invalid (the 1EdTech OneRoster CSV validator will check for this semantic consistency).

Exporting systems must supply all of the data that is defined as required and may supply any of the data fields defined as optional.

Support for Exporting Gradebooks and Resources

Systems that are certifed to support the exporting of resources as well rostering must support the following files (the files marked by '*' are the extra files to be supported):

  • ‘academicSessions.csv’ - bulk mode;
  • ‘classes.csv’ - bulk mode;
  • ‘courses.csv’ - bulk mode;
  • ‘enrollments.csv’ - bulk mode;
  • ‘orgs.csv’ - bulk mode;
  • ‘users.csv’ - bulk mode;
  • ‘classResources.csv’ - bulk mode*;
  • ‘courseResources.csv’ - bulk mode*;
  • ‘resources.csv’ - bulk mode*.

Systems that are certifed to support the exporting of gradebooks as well rostering must support the following files (the files marked by '*' are the extra files to be supported):

  • ‘academicSessions.csv’ - bulk mode;
  • ‘classes.csv’ - bulk mode;
  • ‘courses.csv’ - bulk mode;
  • ‘enrollments.csv’ - bulk mode;
  • ‘orgs.csv’ - bulk mode;
  • ‘users.csv’ - bulk mode;
  • ‘lineItems.csv’ - bulk mode*;
  • ‘results.csv’ - bulk mode*;
  • ‘categories.csv’ - bulk mode*.

3.3 CSV File Processing Certification

System that are certified as OneRoster CSV compliant will be categorised as:

  • CSV Importers - that support OneRoster CSV file importing only;
  • CSV Exporters - that support OneRoster CSV file exporting only;
  • CSV Importers/Exporters - that support OneRoster CSV file importing and exporting.

3.3.1 CSV Importers Certification

The functional capabilities of such systems are:

  • They shall support the importing of the manifest file;
  • They shall support the importing of the set of core rostering files in bulk processing mode;
  • They may support the importing of the 'demographics.csv' files in bulk processing mode;
  • They may support the importing of the full set of rostering files in delta processing mode (the eight files used for rostering);
  • They may support the importing of the set of non-rostering files in bulk and/or delta processing modes;
  • They must support all of the data fields;
  • They may support the processing of extension data fields.

3.3.2 CSV Exporters Certification

The functional capabilities of such systems are:

  • They shall support the exporting of the manifest file;
  • They shall support the exporting of the set of core rostering files in bulk processing mode;
  • They may support the exporting of the 'demographics.csv' files in bulk processing mode;
  • They may support the exporting of the set of full rostering files in delta processing mode (the eight files used for rostering);
  • They may support the exporting of the set of non-rostering files in bulk and/or delta processing modes;
  • They must supply all of the required data fields;
  • They may supply any of the optional data fields;
  • They may supply extension data fields.

3.3.3 CSV Importers/Exporters Certification

The functional capabilities of such systems are:

  • They shall support the importing and exporting of the manifest file;
  • They shall support the importing and exporting of the core set of rostering files in bulk processing mode;
  • They may support the importing and exporting of the 'demographics.csv' files in bulk processing mode;
  • They may support the importing and exporting of the full set of rostering files in delta processing mode;
  • They may support the importing and exporting of the set of non-rostering files in bulk and/or delta processing modes;
  • They must support the importing of all of the data fields;
  • When exporting, they must supply all of the required data fields;
  • When exporting they may supply any of the optional data fields;
  • They may support the import and/or export processing of extension data fields.

There is no requirement to maintain the integrity of the data set that is created by the import/export round-tripping.

 

4. REST-based Exchange Conformance

The 1EdTech Conformance program provides conformance testing for:

  • Systems that act as OneRoster Service Providers – these are, primarily, systems that store OneRoster data and MUST enable that data to be returned to requests from a consumer;
  • Systems that act as OneRoster Service Consumers – these are, primarily, systems that enable a OneRoster repository to be accessed and MUST enable requests to be made by the consumer.

For conformance the endpoint functionality is split into three classifications:

  • Rostering endpoints – the endpoints that handle rostering information, in particular, data about people, clases, courses, and enrollments;
  • Gradebooks endpoints – the endpoints that handle gradebooks information, in particular, data about results, lineItems and categories.
  • Resources endpoints – the endpoints that handle resources information.

For the REST binding ALL systems MUST support at LEAST one of the 'Rostering', 'Resources' and 'Gradebooks' set of endpoints.

In the tabular summaries of the endpoint requirements the following should be noted:

  • For a OneRoster 1.1 implementation the 'Endpoint' string should be appended to the string '/ims/oneroster/v1p1/';
  • The 'Mode' is used denote whether the system is responsible for issuing the request (Init) or responding to the request (Resp).

4.1 Service Providers Compliance

4.1.1 Rostering Endpoint Compliance

For service provider rostering conformance the endpoints listed in Table 4.1 must be supported.

Table 4.1 The endpoints that must be supported by a compliant OneRoster rostering service provider.
Service Call Endpoint HTTP Verb Mode
getAllAcademicSessions /academicSessions GET Resp
getAcademicSession /academicSessions/{id} GET Resp
getAllClasses /classes GET Resp
getClass /classes/{id} GET Resp
getAllCourses /courses GET Resp
getCourse /courses/{id} GET Resp
getAllEnrollments /enrollments GET Resp
getEnrollment /enrollments/{id} GET Resp
getAllGradingPeriods /gradingPeriods GET Resp
getGradingPeriod /gradingPeriods/{id} GET Resp
getAllOrgs /orgs GET Resp
getOrg /orgs/{id} GET Resp
getAllSchools /schools GET Resp
getSchool /schools/{id} GET Resp
getAllStudents /students GET Resp
getStudent /students/{id} GET Resp
getAllTeachers /teachers GET Resp
getTeacher /teachers/{id} GET Resp
getAllTerms /terms GET Resp
getTerm /terms/{id} GET Resp
getAllUsers /users GET Resp
getUser /users/{id} GET Resp

Support for ANY of the other endpoints and service modes is optional. For 'GET' requests a service provider must supply all of the required data fields for the action and may supply any of the optional data fields.

4.1.2 Gradebooks Endpoint Compliance

For service provider gradebook conformance the endpoints listed in either Tables 4.2 or/and 4.3 must be supported. Table 4.2 lists the 'pull' endpoints i.e. where the consumer reads the data from the provider. Table 4.3 list the 'push' endpoints where the provider writes the endpoints into the consumer.

Table 4.2 The endpoints that must be supported by a compliant OneRoster gradebooks service provider (data is pulled from the provider).
Service Call Endpoint HTTP Verb Mode
getAllCategories /categories GET Resp
getCategory /categories/{id} GET Resp
getAllLineItems /lineItems GET Resp
getLineItem /lineItems/{id} GET Resp
getAllResults /results GET Resp
getResult /results/{id} GET Resp

Support for ANY of the other endpoints and service modes is optional. For a 'GET' request a service provider must supply all of the required data fields for the action and may supply any of the optional data fields.

Table 4.3 The endpoints that must be supported by a compliant OneRoster gradebooks service provider (data is pushed by the provider).
Service Call Endpoint HTTP Verb Mode
putLineItem /lineItems/{id} PUT Init
putResult /results/{id} PUT Init

Support for ANY of the other endpoints and service modes is optional.

4.1.3 Resources Endpoint Compliance

For service provider resources conformance the endpoints listed in Tables 4.4 must be supported.

Table 4.4 The endpoints that must be supported by a compliant OneRoster resources service provider.
Service Call Endpoint HTTP Verb Mode
getAllResources /resources GET Resp
getResource /resources/{id} GET Resp

Support for ANY of the other endpoints and service modes is optional. For a 'GET' request a service provider must supply all of the required data fields for the action and may supply any of the optional data fields.

4.2 Service Consumers Compliance

4.2.1 Rostering Endpoint Compliance

For service consumer rostering conformance the endpoints listed in Table 4.5 must be supported.

Table 4.5 The endpoints that must be supported by a compliant OneRoster rostering service consumer.
Service Call Endpoint HTTP Verb Mode
getAllAcademicSessions /academicSessions GET Init
getAllClasses /classes GET Init
getAllCourses /courses GET Init
getAllEnrollments /enrollments GET Init
getAllGradingPeriods /gradingPeriods GET Init
getAllOrgs /orgs GET Init
getAllSchools /schools GET Init
getAllStudents /students GET Init
getAllTeachers /teachers GET Init
getAllTerms /terms GET Init
getAllUsers /users GET Init

Support for ANY of the other endpoints and service modes is optional. For a 'GET' request a service consumer must support all of the required and optional data fields in the corresponding received records.

4.2.2 Gradebooks Endpoint Compliance

For service consumer gradebooks conformance the endpoints listed in either Table 4.6 and/or Table 4.7 must be supported.

Table 4.6 The endpoints that must be supported by a compliant OneRoster gradebooks service consumer.
Service Call Endpoint HTTP Verb Mode
getAllCategories /categories GET Init
getAllLineItems /lineItems GET Init
getAllResults /results GET Init

Support for ANY of the other endpoints and service modes is optional. For a 'GET' request a service consumer must support all of the required and optional data fields in the corresponding received records.

Table 4.7 The endpoints that must be supported by a compliant OneRoster gradebooks service consumer (data is pushed by the provider).
Service Call Endpoint HTTP Verb Mode
putLineItem /lineItems/{id} PUT Resp
putResult /results/{id} PUT Resp

Support for ANY of the other endpoints and service modes is optional.

4.2.3 Resources Endpoint Compliance

For service consumer resources conformance the endpoints listed in Table 4.8 must be supported.

Table 4.8 The endpoints that must be supported by a compliant OneRoster resources service consumer.
Service Call Endpoint HTTP Verb Mode
getAllResources /resources GET Init

Support for ANY of the other endpoints and service modes is optional. For a 'GET' request a service consumer must support all of the required and optional data fields in the corresponding received records.

4.3 OneRoster REST Service Certification

4.3.1 Service Provider Certification

The functional capabilities of such systems are:

  • They MUST support at least one of the rostering, gradebooks and resources set of endpoints;
  • If rostering is supported, all of the required endpoints MUST be supported;
  • If rostering is supported, any of the optional endpoints MAY be supported;
  • If resources is supported, all of the required endpoints MUST be supported;
  • If resources is supported, any of the optional endpoints MAY be supported;
  • If gradebooks is supported, all of either the pull or the push modes required endpoints MUST be supported;
  • If gradebooks is supported, any of the optional endpoints MAY be supported (from both the pull and push modes);
  • They MUST supply all of the required data fields;
  • They MAY supply any of the optional data fields;
  • They MAY provide extension data fields;
  • They MUST support the endpoint payload pagination mechanism for all responses that provide a collection in the payload;
  • They MUST support the endpoint payload filtering mechanism for all responses that provide a collection in the payload. Filtering for all of the REQUIRED data fields MUST be supported and filtering for all of the OPTIONAL data fields avauilable from the Service Provider MUST be supported;
  • They MUST support the endpoint payload sorting mechanism for all responses that provide a collection in the payload;
  • They MUST support the endpoint payload field selection mechanism for all responses that provide a collection or a singleton in the payload;
  • They MUST support the OAuth 2.0 Bearer Token (Client Credentials) authentication mechanism. Use of the associated set of 'scopes' consistent with the set of available endpoints MUST be supported.

Systems that wish to undertake conformance testing as a Service Provider, ONLY available to 1EdTech Members, should use the conformance test system located at: http://validate.imsglobal.org/ORv1p1_CTS_ServiceProvider/

4.3.2 Service Consumer Certification

The functional capabilities of such systems are:

  • They MUST support at least one of the rostering, gradebooks and resources set of endpoints;
  • If rostering is supported, all of the required endpoints MUST be supported;
  • If rostering is supported, any of the optional endpoints MAY be supported;
  • If resources is supported, all of the required endpoints MUST be supported;
  • If resources is supported, any of the optional endpoints may be supported;
  • If gradebooks is supported, all of either the pull or the push modes required endpoints MUST be supported;
  • If gradebooks is supported, any of the optional endpoints MAY be supported (from both the pull and push modes);
  • They MUST support all of the required data fields;
  • They MUST support all of the optional data fields;
  • They MAY process extension data fields;
  • They MUST support the endpoint payload pagination mechanism for all requests that provide a collection in the response payload;
  • They MUST support the endpoint payload filtering mechanism for all requests that provide a collection in the response payload;
  • They MUST support the endpoint payload sorting mechanism for all requests that provide a collection in the response payload;
  • They MUST support the endpoint payload field selection mechanism for all requests that provide a collection or a singleton in the response payload;
  • They MUST support the OAuth 2.0 Bearer Token (Client Credentials) authentication mechanism. Use of the associated set of 'scopes' consistent with the set of available endpoints MUST be supported.

Systems that wish to undertake conformance testing as a Service Consumer, ONLY available to 1EdTech Members, should use the conformance test system located at:  https://onerostervalidator.imsglobal.org:8443/oneroster-client-cts-webapp/index

4.3.3 A Comparison of the Certifications

A comparison of the available certifications for the defined OneRoster endpoints is shown in Table 4.9. In this table the key is:

  • 'C' denotes a service consumer;
  • 'P' denotes a service provider;
  • 'Init' denotes that the end-system issues the request (a shaded box denotes that support for the endpoint is required for that mode);
  • 'Resp' denotes that the end-system responds to the request (a shaded box denotes that support for the endpoint is required for that mode)-
  • '-' denotes that the endpoint is not available to that operational mode.
Table 4.9 A comparison of the certifications available with respect to the defined OneRoster endpoints.
Service Call Endpoint HTTP Verb Rostering Gradebooks Resources
C P C P C P
getAllAcademicSessions /academicSessions GET Init Resp - - - -
getAcademicSession /academicSessions/{id} GET Init Resp - - - -
getAllClasses /classes GET Init Resp - - - -
getClass /classes/{id} GET Init Resp - - - -
getResourcesForClass /classes/{class_id}/resources GET - - - - Init Resp
getStudentsForClass /classes/{class_id}/students GET Init Resp - - - -
getTeachersForClass /classes/{class_id}/teachers GET Init Resp - - - -
getAllCourses /courses GET Init Resp - - - -
getCourse /courses/{id} GET Init Resp - - - -
getClassesForCourse /courses/{course_id}/classes GET Init Resp - - - -
getResourcesForCourse /courses/{course_id}/resources GET - - - - Init Resp
getAllDemographics /demographics GET Init Resp - - - -
getDemographics /demographics/{id} GET Init Resp - - - -
getAllEnrollments /enrollments GET Init Resp - - - -
getEnrollment /enrollments/{id} GET Init Resp - - - -
getAllGradingPeriods /gradingPeriods GET Init Resp - - - -
getGradingPeriod /gradingPeriods/{id} GET Init Resp - - - -
getAllOrgs /orgs GET Init Resp - - - -
getOrg /orgs/{id} GET Init Resp - - - -
getAllResources /resources GET - - - - Init Resp
getResource /resources/{id} GET - - - - Init Resp
getAllSchools /schools GET Init Resp - - - -
getSchool /schools/{id} GET Init Resp - - - -
getClassesForSchool /schools/{school_id}/classes GET Init Resp - - - -
getCoursesForSchool /schools/{id}/courses GET Init Resp - - - -
getEnrollmentsForSchool /schools/{school_id}/enrollments GET Init Resp - - - -
getEnrollmentsForClassInSchool /schools/{school_id}/classes/{class_id}/enrollments GET Init Resp - - - -
getStudentsForClassInSchool /schools/{school_id}/classes/{class_id}/students GET Init Resp - - - -
getStudentsForSchool /schools/{school_id}/students GET Init Resp - - - -
getTeachersForClassInSchool /schools/{school_id}/classes/{class_id}/teachers GET Init Resp - - - -
getTeachersForSchool /schools/{school_id}/teachers GET Init Resp - - - -
getTermsForSchool /schools/{school_id}/terms GET Init Resp - - - -
getAllStudents /students GET Init Resp - - - -
getStudent /students/{id} GET Init Resp - - - -
getClassesForStudent /students/{student_id}/classes GET Init Resp - - - -
getAllTeachers /teachers GET Init Resp - - - -
getTeacher /teachers/{id} GET Init Resp - - - -
getClassesForTeacher /teachers/{teacher_id}/classes GET Init Resp - - - -
getAllTerms /terms GET Init Resp - - - -
getTerm /terms/{id} GET Init Resp - - - -
getClassesForTerm /terms/{term_id}/classes GET Init Resp - - - -
getGradingPeriodsForTerm /terms/{term_id}/gradingPeriods GET Init Resp - - - -
getAllUsers /users GET Init Resp - - - -
getUser /users/{id} GET Init Resp - - - -
getClassesForUser /users/{user_id}/classes GET Init Resp - - - -
getAllCategories /categories GET - - Init
(Pull)		 Resp
(Pull)		 - -
getCategory /categories/{id} GET - - Init
(Pull)		 Resp
(Pull)		 - -
putCategory /categories/{id} PUT - - Resp
(Push)		 Init
(Push)		 - -
deleteCategory /categories/{id} DELETE - - Resp
(Push)		 Init
(Push)		 - -
getAllLineItems /lineItems GET - - Init
(Pull)		 Resp
(Pull)		 - -
getLineItem /lineItems/{id} GET - - Init
(Pull)		 Resp
(Pull)		 - -
putLineItem /lineItems/{id} PUT - - Resp
(Push)		 Init
(Push)		 - -
deleteLineItem /lineItems/{id} DELETE - - Resp
(Push)		 Init
(Push)		 - -
getLineItemsForClass /classes/{class_id}/lineItems GET - - Resp
(Pull)		 Init
(Pull)		 - -
getAllResults /results GET - - Init
(Pull)		 Resp
(Pull)		 - -
getResult /results/{id} GET - - Init
(Pull)		 Resp
(Pull)		 - -
putResult /results/{id} PUT - - Resp
(Push)		 Init
(Push)		 - -
deleteResult /results/{id} DELETE - - Resp
(Push)		 Init
(Push)		 - -
getResultsForClass /classes/{class_id}/results GET - - Resp
(Pull)		 Init
(Pull)		 - -
getResultsForLineItemForClass /classes/{class_id}/lineItems/{li_id}/results GET - - Resp
(Pull)		 Init
(Pull)		 - -
getResultsForStudentForClass /classes/{class_id}/students/{student_id}/results GET - - Resp
(Pull)		 Init
(Pull)		 - -

 

5. OneRoster Certifications

A system that successfully achieves OneRoster certification will have a certain set of functional capabilities. OneRoster certification does NOT guarantee interoperability between ALL other OneRoster compliant solutions: a system that has only CSV certification will not interoperate with a system that has only REST API certification, etc. The set of functional properties that a OneRoster certified product may have is shown in Table 5.1. The key for Table 5.1 is:

  • There are three functional modes i.e. Rostering (the enrollment of people on classes), Resources (the identification of resources allocated to courses/classes and Gradebook (the scores/grades achieved by learners on courses/classes). ALL systems must support at LEAST one of the functional modes of operation;
  • There are two operational modes i.e. CSV processing and REST-API support;
  • For CSV processing a system can support import and/or export file processing. In both cases there are the 'bulk' and 'delta' processing with support for 'bulk' processing being required;
  • For REST API support a system can be a service provider and/or a service consumer. In both cases there is a set of 'Core' endpoints that must be supported and a set of 'Other' endpoints that may be supported (these other endpoints are distinct for each of the 'Rostering', 'Resources' and 'Gradebook' support).

ALL systems must support at LEAST one of the 'Rostering', 'Resources' and 'Gradebooks'.

Table 5.1 A comparison of the certifications available for a OneRoster compliant product.
Functional Mode
(at least one must be supported)		 CSV Processing REST API
Import Export Provider Consumer
Bulk Delta Bulk Delta Core Other Core Other
Rostering Required Optional Required Optional Required Optional Required Optional
Resources Required
(Support for Rostering
CSV also required)		 Optional

Required
(Support for Rostering 
CSV also required)

 Optional Required Optional Required Optional
Gradebooks Required
(Support for Rostering
CSV also required)		 Optional

Required
(Support for Rostering 
CSV also required)

 Optional Required
(Pull or Push)		 Optional Required
(Pull or Push)		 Optional

 

About this Document

Title: 1EdTech OneRoster® v1.1 Conformance and Certification
Editors: Colin Smythe, 1EdTech (UK)
Phil Nicholls, Oracle (USA)
Version: 1.1 / Document 1.1
Version Date: 31st December, 2020
Status: 1EdTech Final Release
Summary: This document contains the conformance and certification information for OneRoster, a K-12/Schools focused specification for the exchange of information about students, enrolments and gradebooks. This conformance definition addresses the exchange of data using CSV files and the set of REST/JSON-based endpoints
 
Revision Information: The fifth release of the 1EdTech OneRoster Conformance and Certification document. This 1.1 revision remives all refernce to the use of OAuth 1.0a  message  signing as an available  authorization mechanism.
Purpose: This document is made available to the public for adoption of the OneRoster specification.
Document Location: 1EdTech Public Website (Standards Download): http://www.imsglobal.org/activity/onerosterlis/

 

List of Contributors

The following individuals contributed to the development of this document:

William Baker Pearson (USA)
Arthur Barstow McGraw-Hill (USA)
Sari Connard Performance Matters (USA)
Hank Davidson Pearson (USA)
Vijay Dhanaraj Classlink (USA)
David Gappa Safari Montage (USA)
Linda Feng Unicom (USA)
Tom Ingram Escambia County School District (USA)
Oxana Jurosevic Instructure (USA)
Mike Kaastra Desire2Learn (Canada)
Jong Kim Pearson (USA)
Andrew Kuritzky HMH (USA)
Lisa Mattson 1EdTech (USA)
David Mayes Gwinnett County Schools (USA)
Andy Miller Learning.com (USA)
Phil Nicholls Oracle (UK)
Padraig O'hiceadha HMH (UK)
Upendra Penegalapati Pearson (USA)
George Perreault Classlink (USA)
James Perreault FLVS (USA)
Patrick Porter Houston ISD (USA)
Wendy Riedy Sungard K12 (USA)
Kurt Rompot Pearson (USA)
Marc Sheftel Pearson (USA)
Colin Smythe 1EdTech (UK)
Konrad Stimeling K12 (USA)
Aditya Subramaniam Schoology (USA
Matt Vella Schoology (USA)
TJ Vering Microsoft (USA)
Mark Walls Gwinnett County Schools (USA)
Stanley Watts Classlink (USA)
Mike Zackerson Instructure (USA)

 

Revision History

Version No. Release Date Comments
Final Release v1.0 3rd June 2015 The first formal release of the Final Release version of this document.
Final Release v1.1 17th April, 2017 The second formal release of this document. The conformance requirements, for both CSV and REST, have been made considerably more demanding and specific.
Final Release v1.1 / Document 1.0.1 11th September, 2017 The changes made in this revision of the document are focused on removing some of the endpoints from the REST API certification for a Consumer:
  • Consumer support for Rostering mode - support for the single resource 'getAcademicSession()', 'getClass()', 'getCourse()', 'getEnrollment()', 'getGradingPeriod()', 'getOrg(), 'getUser()', 'getSchool()', 'getTeacher()' and 'getTerm()' endpoints has been made optional
  • Consumer support for Resources mode - support for the single resource 'getResource()' endpoint has been made optional
  • Consumer support for Gradebook mode - support for the single resource 'getCategory()', 'getLineItem()' and 'getResult()' endpoints has been made optional
Final Release v1.1 / Document 1.0.2 3rd April, 2019

The changes made in this revision address the changes in conformance requirements for the security aspects.  In particular:
Final Release v1.1 / Document 1.0.3 19th February, 2020

The changes made in this revision are:

  • Optional support for OAuth 1.0a (SHA256) based message signing. Either OAuth 1.0a (SHA256) or OAuth 2 MUST be supported;
  • Support for the certification of implementations using OAuth 1.0a (SHA1) has been removed;
  • The links to the various conformance test ssyetms have been corrected;
  • Support for the 'putCategory()' in both the consumer and provider implementations has been made optional.
Final Release v1.1 / Document 1.1 31st December, 2020

The changes made in this revision are:

  • Support for the certification of implementations using OAuth 1.0a  has been removed i.e. ALL systems MUST support Oauth 2 (Client Credentials) ONLY;
  • Clarification on the data fields for which use of the filtering query parameter MUST be available has been added.

 

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

1EdTech 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.

1EdTech would appreciate receiving your comments and suggestions.

Please contact 1EdTech through our website at http://www.imsglobal.org.

Please refer to Document Name: 1EdTech OneRoster® 1.1 Conformance and Certification Final Specification v1.1

Date: 31st December, 2020

 

This page contains trademarks of the 1EdTech Consortium including the 1EdTech Logos, Learning Tools Interoperability® (LTI®), Accessible Portable Item Protocol® (APIP®), Question and Test Interoperability® (QTI®), Common Cartridge® (CC®), AccessForAll™, OneRoster®, Caliper Analytics™ and SensorAPI™. For more information on the 1EdTech trademark usage policy see trademark policy page

© 2001-2020 1EdTech Consortium Inc. All Rights Reserved. Privacy Policy

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

This page contains trademarks of the 1EdTech Consortium, including the 1EdTech logos, TrustEd Apps™, Learning Tools Interoperability (LTI)®, LTI™,OneRoster®, Caliper Analytics®, Common Cartridge®, Competencies and Academic Standards Exchange® (CASE®), Question and Test Interoperability® (QTI®), Accessible Portable Item Protocol® (APIP®), AccessForAll®, BadgeConnect®, and SensorAPI™.

For information on the 1EdTech trademark usage policy, see our trademark policy page.

Connect on LinkedInFollow Us on TwitterView 1EdTech on YouTube

© 2001-2023 1EdTech Consortium Inc. All Rights Reserved. Privacy Policy