IMS Final Release

IMS Global Logo

IMS OneRoster Resources Service REST/JSON Binding Version 1.2

IMS Final Release
Version 1.0

Date Issued: 19th September, 2022
Latest version: http://www.imsglobal.org/activity/onerosterlis/

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.

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.

Org Name Date Election Made Necessary Claims Type
Anthology Inc. 10th August 2022 No RF RAND (Required & Optional Elements)
D2L Corporation 21st July 2022 No RF RAND (Required & Optional Elements)
Gwinnett County Public Schools 22nd July 2022 No RF RAND (Required & Optional Elements)
Infinite Campus Inc 25th July 2022 No RF RAND (Required & Optional Elements)
Microsoft Corporation 8th August 2022 No RF RAND (Required & Optional Elements)
SameGoal Inc 21st July 2022 No RF RAND (Required & Optional Elements)

Copyright © 2022 IMS Global Learning Consortium. All Rights Reserved.

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: www.imsglobal.org/forums/ims-glc-public-forums-and-resources.

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

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

Document Name: IMS OneRoster Resources Service REST/JSON Binding v1.2

Revision: 19th September, 2022

toc | top

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:

This OR 1.2 Resources Service provides the ability to manage the allocation of resources to classes, courses and users. It does NOT enable access to the resources themselves. The resource data provides the information that describes the resource and its relationships to classes and/or courses and/or users. The service description includes the definition of the data formats that are exchanged using a set of service operations. In this document the binding implementation as a REST/JSON service is described.

toc | top

Table of Contents

Abstract

1. Introduction

1.1 Scope and Context

1.2 Conventions

1.3 Changes in the Resources Service 1.2

1.4 Structure of this Document

1.5 Nomenclature

2. REST Endpoints

2.1 Mapping of the Service Operations to the REST Endpoints

2.2 API Root URL and Versioning

2.3 Predefined Endpoint Query Parameters

2.3.1 "getAllResources" Endpoint Query Parameters

2.3.2 "getResource" Endpoint Query Parameters

2.3.3 "getResourcesForClass" Endpoint Query Parameters

2.3.4 "getResourcesForCourse" Endpoint Query Parameters

2.3.5 "getResourcesForUser" Endpoint Query Parameters

2.4 HTTP Code Handling

2.5 Service Discovery

3. Using the Endpoint Parameters

3.1 Pagination

3.2 Sorting

3.3 Filtering

3.4 Field Selection

4. Security Framework

4.1 Transport Security

4.2 Authorization

4.3 Scopes

4.3.1 "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" Scope

4.3.2 "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" Scope

5. UML to JSON Mappings

5.1 Service Parameter Payload Properties UML/JSON Mapping

5.2 Service Parameter Payload Class UML/JSON Mapping

5.2.1 ResourceSet Service Parameter Payload Class Mapping

5.2.2 SingleResource Service Parameter Payload Class Mapping

5.3 Payload Classes UML/JSON Mapping

5.3.1 Base Payload Class Mapping

5.3.2 Metadata Payload Class Mapping

5.3.3 Resource Payload Class Mapping

5.3.4 imsx_CodeMinor Payload Class Mapping

5.3.5 imsx_CodeMinorField Payload Class Mapping

5.3.6 imsx_StatusInfo Payload Class Mapping

5.4 Enumerated Class UML/JSON Mapping

5.5 Enumerated List Class UML/JSON Mapping

5.6 Primitive Type UML/JSON Mapping

6. JSON Payloads

6.1 "getAllResources" Request Payload

6.2 "getAllResources" Response Payload

6.2.1 Response Payloads for the HTTP Codes (200)

6.2.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

6.3 "getResource" Request Payload

6.4 "getResource" Response Payload

6.4.1 Response Payloads for the HTTP Codes (200)

6.4.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

6.5 "getResourcesForClass" Request Payload

6.6 "getResourcesForClass" Response Payload

6.6.1 Response Payloads for the HTTP Codes (200)

6.6.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

6.7 "getResourcesForCourse" Request Payload

6.8 "getResourcesForCourse" Response Payload

6.8.1 Response Payloads for the HTTP Codes (200)

6.8.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

6.9 "getResourcesForUser" Request Payload

6.10 "getResourcesForUser" Response Payload

6.10.1 Response Payloads for the HTTP Codes (200)

6.10.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

7. OpenAPI Description

7.1 General Information

7.2 Tags Information

7.3 Security Information

7.4 Paths Information

7.4.1 "/classes/{classSourcedId}/resources" Path

7.4.2 "/courses/{courseSourcedId}/resources" Path

7.4.3 "/resources" Path

7.4.4 "/resources/{sourcedId}" Path

7.4.5 "/users/{userSourcedId}/resources" Path

7.5 Definitions Information

7.5.1 "MetadataDType" Definition

7.5.2 "ResourceDType" Definition

7.5.3 "ResourceSetDType" Definition

7.5.4 "SingleResourceDType" Definition

7.5.5 "imsx_CodeMinorDType" Definition

7.5.6 "imsx_CodeMinorFieldDType" Definition

7.5.7 "imsx_StatusInfoDType" Definition

8. Extending and Profiling the Binding

8.1 Extending the Binding

8.1.1 Proprietary Operations

8.1.2 Proprietary Scopes

8.1.3 Proprietary Data Elements

8.1.4 Proprietary Vocabulary Terms

8.2 Profiling the Binding

References

Appendix A Model Binding Terms and Concepts

A1 REST Endpoint Description Explanations

A1.1 REST Endpoint Mapping Table Explanation

A1.2 Query Parameter Table Explanation

A1.3 Error Codes and Handling for each Endpoint Table Explanation

A2 UML to JSON Mapping Description Explanations

A2.1 Service Parameter Payload Properties UML/JSON Mapping Table Definition

A2.2 UML/JSON Payload Class Mapping Table Definition

A2.3 UML/JSON Enumerated and Enumerated List Class Mapping Table Definition

A2.4 UML/JSON Primitive Types Mapping Table Definition

A3 OpenAPI (v2 and v3) Descriptions Explanations

A3.1a OpenAPI(2) General Information Table Explanation

A3.1b OpenAPI(3) General Information Table Explanation

A3.2 OpenAPI Tags Table Explanation

A3.3 OpenAPI Security Table Explanation

A3.4 OpenAPI Paths Table Explanation

A3.5 OpenAPI Definitions Table Explanation

Appendix B OpenAPI Listings

B1 Listing of the OpenAPI (JSON) File

B1.1 OpenAPI 2.0 JSON Listing

B1.2 OpenAPI 3.0 JSON Listing

B2 Listing of the OpenAPI (YAML) File

B2.1 OpenAPI 2.0 YAML Listing

B2.2 OpenAPI 3.0 YAML Listing

Appendix C JSON Schema Listings

C1 JSON Schemas for Payload Validation

C1.1a JSON Schema for the "getAllResources" Operation Request Payload Validation.

C1.1b JSON Schema for the "getAllResources" Operation Response Payload Validation for HTTP Codes (200)

C1.1c JSON Schema for the "getAllResources" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

C1.2a JSON Schema for the "getResource" Operation Request Payload Validation.

C1.2b JSON Schema for the "getResource" Operation Response Payload Validation for HTTP Codes (200)

C1.2c JSON Schema for the "getResource" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

C1.3a JSON Schema for the "getResourcesForClass" Operation Request Payload Validation.

C1.3b JSON Schema for the "getResourcesForClass" Operation Response Payload Validation for HTTP Codes (200)

C1.3c JSON Schema for the "getResourcesForClass" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

C1.4a JSON Schema for the "getResourcesForCourse" Operation Request Payload Validation.

C1.4b JSON Schema for the "getResourcesForCourse" Operation Response Payload Validation for HTTP Codes (200)

C1.4c JSON Schema for the "getResourcesForCourse" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

C1.5a JSON Schema for the "getResourcesForUser" Operation Request Payload Validation.

C1.5b JSON Schema for the "getResourcesForUser" Operation Response Payload Validation for HTTP Codes (200)

C1.5c JSON Schema for the "getResourcesForUser" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

About this Document

List of Contributors

Revision History

toc | top

List of Figures

Table 7.5.1 - OpenAPI JSON Schema description for the "BaseDType" Complex Type.

Table 7.5.2 - OpenAPI JSON Schema description for the "MetadataDType" Complex Type.

Table 7.5.3 - OpenAPI JSON Schema description for the "ResourceDType" Complex Type.

Table 7.5.4 - OpenAPI JSON Schema description for the "ResourceSetDType" Complex Type.

Table 7.5.5 - OpenAPI JSON Schema description for the "SingleResourceDType" Complex Type.

Table 7.5.6 - OpenAPI JSON Schema description for the "imsx_CodeMinorDType" Complex Type.

Table 7.5.7 - OpenAPI JSON Schema description for the "imsx_CodeMinorFieldDType" Complex Type.

Table 7.5.8 - OpenAPI JSON Schema description for the "imsx_StatusInfoDType" Complex Type.

toc | top

List of Tables

Table 2.1 - The Set of REST Endpoint URL-leaf Values.

Table 2.4 - The List of HTTP Codes and Handling for each Endpoint.

Table 4.3.1 "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" Scope

Table 4.3.2 "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" Scope

Table 7.1a - The Set of General Information Defined in the OpenAPI(2) Description.

Table 7.1b - The Set of General Information Defined in the OpenAPI(3) Description.

Table 7.2 - The Set of Tags Defined in the OpenAPI Description.

Table 7.3.1 - The Set of OAuth 2.0 Client Credentials Security Information Defined in the OpenAPI Description.

Table 7.4.1 - The Set of HTTP Verbs Permitted on the "/classes/{classSourcedId}/resources" Path.

Table 7.4.2 - The Set of HTTP Verbs Permitted on the "/courses/{courseSourcedId}/resources" Path.

Table 7.4.3 - The Set of HTTP Verbs Permitted on the "/resources" Path.

Table 7.4.4 - The Set of HTTP Verbs Permitted on the "/resources/{sourcedId}" Path.

Table 7.4.5 - The Set of HTTP Verbs Permitted on the "/users/{userSourcedId}/resources" Path.

Table 7.5.1 - OpenAPI JSON Schema description for the "BaseDType" Complex Type.

Table 7.5.2 - OpenAPI JSON Schema description for the "MetadataDType" Complex Type.

Table 7.5.3 - OpenAPI JSON Schema description for the "ResourceDType" Complex Type.

Table 7.5.4 - OpenAPI JSON Schema description for the "ResourceSetDType" Complex Type.

Table 7.5.5 - OpenAPI JSON Schema description for the "SingleResourceDType" Complex Type.

Table 7.5.6 - OpenAPI JSON Schema description for the "imsx_CodeMinorDType" Complex Type.

Table 7.5.7 - OpenAPI JSON Schema description for the "imsx_CodeMinorFieldDType" Complex Type.

Table 7.5.8 - OpenAPI JSON Schema description for the "imsx_StatusInfoDType" Complex Type.

Table A1.1 The key to the descriptions of the mapping between a service calls and its REST endpoint URL-leaf

Table A1.2 The key to the descriptions of the data attribute/characteristic tables

Table A1.3 The key to the descriptions of the list of error codes and handling for each endpoint

Table A3.1a The key to the tabular description of the OpenAPI(2) general information

Table A3.1b The key to the tabular description of the OpenAPI(3) general information

Table A3.2 The key to the tabular description of the OpenAPI tags information

Table A3.3 The key to the tabular description of the OpenAPI security information.

Table A3.4 The key to the tabular description of the OpenAPI paths information for an HTTP Verb

Table A3.5 The key to the tabular description of the OpenAPI definitions information

toc | top

List of Code Blocks

Code 6.2.1 - JSON payload example for "200" response messages for a "getAllResources" operation.

Code 6.2.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getAllResources" operation.

Code 6.4.1 - JSON payload example for "200" response messages for a "getResource" operation.

Code 6.4.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResource" operation.

Code 6.6.1 - JSON payload example for "200" response messages for a "getResourcesForClass" operation.

Code 6.6.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForClass" operation.

Code 6.8.1 - JSON payload example for "200" response messages for a "getResourcesForCourse" operation.

Code 6.8.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForCourse" operation.

Code 6.10.1 - JSON payload example for "200" response messages for a "getResourcesForUser" operation.

Code 6.10.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForUser" operation.

toc | top

1. Introduction

This Section is NOT NORMATIVE.

1.1. Scope and Context

This document is the OneRoster 1.2 Resources Service REST/JSON Bindinging and as such it is used as the basis for the implementing the OR Resources Service Model. The key related documents are:

This service model and this REST/JSON binding is described using the Unified Modeling Language (UML) based upon the 1EdTech Model Driven Specification approach and the associated modelling toolkit [I-BAT, 06]. This means that this specification is based upon the concepts of:

Key artefacts produced as part of the REST/JSON binding description are the associated OpenAPI files based upon the OpenAPI Specifications version 2 [OAS, 14] and version 3 [OAS, 17].

1.2. Conventions

All sections marked as non-normative, all authoring guidelines, diagrams (with the exception of the UML diagrams), examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119]. This means that from the perspective of conformance:

The Conformance and Certification Guide for this specification may introduce greater normative constraints than those defined here for specific service or implementation categories.

The SHOULD/SHOULD NOT/RECOMMENDED statements MUST NOT be used in any document, or section of a document, that is responsible for defining the information model and/or the associated bindings and/or conformance and certification.

1.3. Changes in the Resources Service 1.2

The only changes made in this new version are:

1.4. Structure of this Document

The structure of the rest of this document is:

2. REST Endpoints An explanation of the relationship between the logical service operations (as defined in the OneRoster Resources Service Model) and how these are realised as the corresponding set of REST endpoints (including the set of query parameters that are permitted);
3. Using the Endpoint Parameters A detailed explanation of how the permitted set of query parameters should be used to control the volume and type of information that will be supplied by the service provider;
4. Security Framework The underlying security framework within which this REST/JSON binding is designed to operate. This includes the details about authentication and how the payload integrity may be protected;
5. UML to JSON Mappings The description of how the JSON payloads are derived from the equivalent UML data model definitions [OR-RES-SM-12]. Each UML class and attribute is mapped to the equivalent JSON object and property.
6. JSON Payloads Examples of the set of JSON payloads that are sent by the consumer (the request) and returned by the service provider (response). These examples are focused on the expected structure of a request/response and do not include actual payloads;
7. OpenAPI Description A detailed explanation of the structure of the OpenAPI files that are produced as part of the specification documentation. The associated JSON and YAML files are supplied in Appendix B;
8. Extending and Profiling the Binding An explanation of how the service can be extended, using the permitted points of extension and/or profiled. Profiling is the process by which the specification is tailored to a specific set of market/domain requirements;
References The set of cited documents, normative and informative, that are used to support the technical details in this document;
Appendix A Model Binding Terms and Concepts An overview of the model driven approach, the concepts and the terms used by IMS to create the service model REST/JSON binding definitions (based upon a profile of UML) and the accompanying documentation (including this binding);
Appendix B OpenAPI Listings The listings of the OpenAPI(JSON) and OpenAPI(YAML) files that have been created to define the REST/JSON binding in a machine-readable format i.e. conforming to the OpenAPI 2.0 specification;
Appendix C JSON Schema Listings The listings of the set of JSON Schema files (based upon IETF JSON Schema Draft 7) that have been created for the validation of the set of JSON payloads that are exchanged as part of this service.

1.5. Nomenclature

API Application Programming Interface
GUID Globally Unique Identifier
HTTP Hypertext Transfer Protocol
I-BAT IMS Binding Autogeneration Toolkit
IETF Internet Engineering Task Force
JSON Java Script Object Notation
LIS Learning Information Services
NCES National Centre for Education Statistics
OAS OpenAPI Specification
PII Personally Identifiable Information
REST Representational State Transfer
RFC Request for Comments
TLS Transport Layer Security
UML Unified Modeling Language
URI Uniform Resource Identifier
URL Uniform Resource Locator
UTC Coordinated Universal Time
YAML Yet Another Markup Language

toc | top

2. REST Endpoints

This Section is NORMATIVE.

2.1 Mapping of the Service Operations to the REST Endpoints

The mapping between the service operations and the REST Endpoint URL-leaf values are listed in Table 2.1. The syntax and semantics for this mapping are described in Appendix A1.1.

Table 2.1 - The Set of REST Endpoint URL-leaf Values.
Service Call REST Endpoint HTTP Verb
getAllResources /resources GET
getResource /resources/{sourcedId} GET
getResourcesForClass /classes/{classSourcedId}/resources GET
getResourcesForCourse /courses/{courseSourcedId}/resources GET
getResourcesForUser /users/{userSourcedId}/resources GET

2.2 API Root URL and Versioning

All of the paths MUST also contain, as the base of the path, excluding the host name, the string: "/ims/oneroster/resources/v1p2".

2.3 Predefined Endpoint Query Parameters

The definition of the permitted set of query parameters are defined in the following Tables. The syntax and semantics for this Tables are described in Appendix A1.2.

2.3.1 "getAllResources" Endpoint Query Parameters

2.3.1.1 "limit" Query Parameter

The description of the "limit" query parameter is presented in Table 2.3.1.1

Table 2.3.1.1 - The definition of the "limit" query parameter for the "getAllResources" operation.
Descriptor Definition
Parameter Name limit
Data Type PositiveInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "100".
Multiplicity [0..1]
Description To define the download segmentation value i.e. the maximum number of records to be contained in the response.

2.3.1.2 "offset" Query Parameter

The description of the "offset" query parameter is presented in Table 2.3.1.2

Table 2.3.1.2 - The definition of the "offset" query parameter for the "getAllResources" operation.
Descriptor Definition
Parameter Name offset
Data Type NonNegativeInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "0".
Multiplicity [0..1]
Description The number of the first record to be supplied in the segmented response message.

2.3.1.3 "sort" Query Parameter

The description of the "sort" query parameter is presented in Table 2.3.1.3

Table 2.3.1.3 - The definition of the "sort" query parameter for the "getAllResources" operation.
Descriptor Definition
Parameter Name sort
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.

2.3.1.4 "orderBy" Query Parameter

The description of the "orderBy" query parameter is presented in Table 2.3.1.4

Table 2.3.1.4 - The definition of the "orderBy" query parameter for the "getAllResources" operation.
Descriptor Definition
Parameter Name orderBy
Data Type Enumeration
Value Space Enumerated value set of: { asc | desc }
Multiplicity [0..1]
Description The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.

2.3.1.5 "filter" Query Parameter

The description of the "filter" query parameter is presented in Table 2.3.1.5

Table 2.3.1.5 - The definition of the "filter" query parameter for the "getAllResources" operation.
Descriptor Definition
Parameter Name filter
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description The filtering rules to be applied when identifying the records to be supplied in the response message.

2.3.1.6 "fields" Query Parameter

The description of the "fields" query parameter is presented in Table 2.3.1.6

Table 2.3.1.6 - The definition of the "fields" query parameter for the "getAllResources" operation.
Descriptor Definition
Parameter Name fields
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..*]
Description To identify the range of fields that should be supplied in the response message.

2.3.2 "getResource" Endpoint Query Parameters

2.3.2.1 "fields" Query Parameter

The description of the "fields" query parameter is presented in Table 2.3.2.1

Table 2.3.2.1 - The definition of the "fields" query parameter for the "getResource" operation.
Descriptor Definition
Parameter Name fields
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..*]
Description To identify the range of fields that should be supplied in the response message.

2.3.3 "getResourcesForClass" Endpoint Query Parameters

2.3.3.1 "limit" Query Parameter

The description of the "limit" query parameter is presented in Table 2.3.3.1

Table 2.3.3.1 - The definition of the "limit" query parameter for the "getResourcesForClass" operation.
Descriptor Definition
Parameter Name limit
Data Type PositiveInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "100".
Multiplicity [0..1]
Description To define the download segmentation value i.e. the maximum number of records to be contained in the response.

2.3.3.2 "offset" Query Parameter

The description of the "offset" query parameter is presented in Table 2.3.3.2

Table 2.3.3.2 - The definition of the "offset" query parameter for the "getResourcesForClass" operation.
Descriptor Definition
Parameter Name offset
Data Type NonNegativeInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "0".
Multiplicity [0..1]
Description The number of the first record to be supplied in the segmented response message.

2.3.3.3 "sort" Query Parameter

The description of the "sort" query parameter is presented in Table 2.3.3.3

Table 2.3.3.3 - The definition of the "sort" query parameter for the "getResourcesForClass" operation.
Descriptor Definition
Parameter Name sort
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.

2.3.3.4 "orderBy" Query Parameter

The description of the "orderBy" query parameter is presented in Table 2.3.3.4

Table 2.3.3.4 - The definition of the "orderBy" query parameter for the "getResourcesForClass" operation.
Descriptor Definition
Parameter Name orderBy
Data Type Enumeration
Value Space Enumerated value set of: { asc | desc }
Multiplicity [0..1]
Description The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.

2.3.3.5 "filter" Query Parameter

The description of the "filter" query parameter is presented in Table 2.3.3.5

Table 2.3.3.5 - The definition of the "filter" query parameter for the "getResourcesForClass" operation.
Descriptor Definition
Parameter Name filter
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description The filtering rules to be applied when identifying the records to be supplied in the response message.

2.3.3.6 "fields" Query Parameter

The description of the "fields" query parameter is presented in Table 2.3.3.6

Table 2.3.3.6 - The definition of the "fields" query parameter for the "getResourcesForClass" operation.
Descriptor Definition
Parameter Name fields
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..*]
Description To identify the range of fields that should be supplied in the response message.

2.3.4 "getResourcesForCourse" Endpoint Query Parameters

2.3.4.1 "limit" Query Parameter

The description of the "limit" query parameter is presented in Table 2.3.4.1

Table 2.3.4.1 - The definition of the "limit" query parameter for the "getResourcesForCourse" operation.
Descriptor Definition
Parameter Name limit
Data Type PositiveInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "100".
Multiplicity [0..1]
Description To define the download segmentation value i.e. the maximum number of records to be contained in the response.

2.3.4.2 "offset" Query Parameter

The description of the "offset" query parameter is presented in Table 2.3.4.2

Table 2.3.4.2 - The definition of the "offset" query parameter for the "getResourcesForCourse" operation.
Descriptor Definition
Parameter Name offset
Data Type NonNegativeInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "0".
Multiplicity [0..1]
Description The number of the first record to be supplied in the segmented response message.

2.3.4.3 "sort" Query Parameter

The description of the "sort" query parameter is presented in Table 2.3.4.3

Table 2.3.4.3 - The definition of the "sort" query parameter for the "getResourcesForCourse" operation.
Descriptor Definition
Parameter Name sort
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.

2.3.4.4 "orderBy" Query Parameter

The description of the "orderBy" query parameter is presented in Table 2.3.4.4

Table 2.3.4.4 - The definition of the "orderBy" query parameter for the "getResourcesForCourse" operation.
Descriptor Definition
Parameter Name orderBy
Data Type Enumeration
Value Space Enumerated value set of: { asc | desc }
Multiplicity [0..1]
Description The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.

2.3.4.5 "filter" Query Parameter

The description of the "filter" query parameter is presented in Table 2.3.4.5

Table 2.3.4.5 - The definition of the "filter" query parameter for the "getResourcesForCourse" operation.
Descriptor Definition
Parameter Name filter
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description The filtering rules to be applied when identifying the records to be supplied in the response message.

2.3.4.6 "fields" Query Parameter

The description of the "fields" query parameter is presented in Table 2.3.4.6

Table 2.3.4.6 - The definition of the "fields" query parameter for the "getResourcesForCourse" operation.
Descriptor Definition
Parameter Name fields
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..*]
Description To identify the range of fields that should be supplied in the response message.

2.3.5 "getResourcesForUser" Endpoint Query Parameters

2.3.5.1 "limit" Query Parameter

The description of the "limit" query parameter is presented in Table 2.3.5.1

Table 2.3.5.1 - The definition of the "limit" query parameter for the "getResourcesForUser" operation.
Descriptor Definition
Parameter Name limit
Data Type PositiveInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "100".
Multiplicity [0..1]
Description To define the download segmentation value i.e. the maximum number of records to be contained in the response.

2.3.5.2 "offset" Query Parameter

The description of the "offset" query parameter is presented in Table 2.3.5.2

Table 2.3.5.2 - The definition of the "offset" query parameter for the "getResourcesForUser" operation.
Descriptor Definition
Parameter Name offset
Data Type NonNegativeInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "0".
Multiplicity [0..1]
Description The number of the first record to be supplied in the segmented response message.

2.3.5.3 "sort" Query Parameter

The description of the "sort" query parameter is presented in Table 2.3.5.3

Table 2.3.5.3 - The definition of the "sort" query parameter for the "getResourcesForUser" operation.
Descriptor Definition
Parameter Name sort
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.

2.3.5.4 "orderBy" Query Parameter

The description of the "orderBy" query parameter is presented in Table 2.3.5.4

Table 2.3.5.4 - The definition of the "orderBy" query parameter for the "getResourcesForUser" operation.
Descriptor Definition
Parameter Name orderBy
Data Type Enumeration
Value Space Enumerated value set of: { asc | desc }
Multiplicity [0..1]
Description The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.

2.3.5.5 "filter" Query Parameter

The description of the "filter" query parameter is presented in Table 2.3.5.5

Table 2.3.5.5 - The definition of the "filter" query parameter for the "getResourcesForUser" operation.
Descriptor Definition
Parameter Name filter
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description The filtering rules to be applied when identifying the records to be supplied in the response message.

2.3.5.6 "fields" Query Parameter

The description of the "fields" query parameter is presented in Table 2.3.5.6

Table 2.3.5.6 - The definition of the "fields" query parameter for the "getResourcesForUser" operation.
Descriptor Definition
Parameter Name fields
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..*]
Description To identify the range of fields that should be supplied in the response message.

2.4 HTTP Code Handling

A service provider will either return a data payload or a payload that indicates the cause of the failure. The list of HTTP Codes and handling for each endpoint is shown in Table 2.4. The syntax and semantics for this tabular description are described in Appendix A1.3.

Table 2.4 - The List of HTTP Codes and Handling for each Endpoint.
REST Endpoint HTTP Verb HTTP Codes and Handling
/classes/{classSourcedId}/resources GET
  • 200 - the requested read has been fully serviced and all of the required data returned. The payload is defined by the structure ResourceSetDType.
  • 400 - either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. The payload is defined by the structure imsx_StatusInfoDType.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
/courses/{courseSourcedId}/resources GET
  • 200 - the requested read has been fully serviced and all of the required data returned. The payload is defined by the structure ResourceSetDType.
  • 400 - either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. The payload is defined by the structure imsx_StatusInfoDType.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
/resources GET
  • 200 - the requested read has been fully serviced and all of the required data returned. The payload is defined by the structure ResourceSetDType.
  • 400 - either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. The payload is defined by the structure imsx_StatusInfoDType.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
/resources/{sourcedId} GET
  • 200 - the requested read has been fully serviced and all of the required data returned. The payload is defined by the structure SingleResourceDType.
  • 400 - either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. The payload is defined by the structure imsx_StatusInfoDType.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
/users/{userSourcedId}/resources GET
  • 200 - the requested read has been fully serviced and all of the required data returned. The payload is defined by the structure ResourceSetDType.
  • 400 - either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. The payload is defined by the structure imsx_StatusInfoDType.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfoDType.

2.5 Service Discovery

A Service Provider MUST provide a localized version of the OpenAPI file (version 3 JSON file format) to enable service discovery [Security, 21].

This file MUST be located at: "...hostname.../ims/oneroster/resources/v1p2/discovery/".

The OpenAPI file MUST have the name: "onerosterv1p2resourcesservice_openapi3_v1p0.json".

Therefore the full URL for this service discovery file is: ...hostname.../ims/oneroster/resources/v1p2/discovery/onerosterv1p2resourcesservice_openapi3_v1p0.json

toc | top

3. Using the Endpoint Parameters

This SECTION is NOT NORMATIVE.

3.1. Pagination

For requests of collections e.g. the response for the 'getAllResources()' call, there is a danger of data overload. To avoid this, implementations should adopt a pagination mechanism. Pagination is controlled via two parameters that are appended to the request:

An example of a request to return the first 10 resources in a collection:

    GET https://imsglobal.org/ims/oneroster/resources/v1p2/resources?limit=10

An example of a request to return the second 10 resources in a collection:

    GET https://imsglobal.org/ims/oneroster/resources/v1p2/resources?limit=10&offset=10

It is RECOMMENDED that implementations pass the total resource count in collection back to the requester. This MUST be provided in the custom HTTP header: X-Total-Count.

It is RECOMMENDED that implementers pass back next, previous, first and last links in the HTTP Link Header.

Consider the requests for the example where 503 resources exist in the collection. The pagination is in units of 10.

    Link:

    <https://imsglobal.org/ims/oneroster/resources/v1p2/resources?limit=10&offset=20>; rel="next",
    <https://imsglobal.org/ims/oneroster/resources/v1p2/resources?limit=3&offset=500>; rel="last",
    <https://imsglobal.org/ims/oneroster/resources/v1p2/resources?limit=10&offset=0>; rel="first",
    <https://imsglobal.org/ims/oneroster/resources/v1p2/resources?limit=10&offset=0>; rel="prev"

3.2. Sorting

It should be possible for collections, e.g. the response for the 'getAllResources()' call etc. to be returned in a sorted order. It should be possible to sort the collection based on any single data element in the core description of the resource. Sort requests MUST make use of the reserved word "sort" (?sort= data_field), and optionally the reserved word orderBy for which:

An example of a request to ask for a list of resources sorted into ascending title order:

    GET https://imsglobal.org/ims/oneroster/resources/v1p2/resources?sort=title&orderBy=asc

Sorting should conform to the use of the Unicode Collation Algorithm [UNICODE, 16] when using the relevant comparisons.

If the consumer requests that the data is to be sorted by a non-existent field, data MAY be returned in the service provider's default sort order or an error response MAY be returned.

When sorting/ordering is requested on a property that is an array, the first value in the array is used as the basis of the sorting/ordering.

To sort/order on the properties of nested objects, (for example, with metadata properties), a dot-notation approach MUST be used. The format for this is:

    ?sort=<Nested_Object>.<Property>

3.3. Filtering

For the calls that request collections e.g. 'getAllResources()' call, it should be possible to filter collections for elements matching a certain criteria. It should be possible to filter collections based on any data element in the core description of the resource.Filter requests MUST take the form:

    ?filter=<data_field><predicate><value>

or

    ?filter=<data_field><predicate><value><logical><data_field><predicate><value>

The data fields that can be used are those present in the class definition being filtered. So for example in 'resources', it MUST be possible to filter on: 'sourcedId', 'title', 'vendorResourceId', 'dateLastModified', etc.

Predicates MUST be chosen from those listed below:

Values MUST be enclosed within single quotes and they MUST be handled as case insensitive. When the response is returned it is the receiving system that should consider whether or not case-sensitivity is important.

The <logical> parameters allow more complex queries to be created. For version 1.0, it is RECOMMENDED that logical operations are limited to " AND " and " OR " (note the surrounding white space at each side) and that there is only one such operator used in any filter i.e. a single 'AND' or a single 'OR' in the filter. A single white space must occur before and after the parameter.

To query on the properties of nested objects, (for example, with metadata properties), a dot-notation approach MUST be used. The format for this is:

    ?filter=<Nested_Object>.<Property>

Note then when querying on metadata, the property is loosely typed. An example or a request to find resources with a 'status' of 'active' is:

    GET https://imsglobal.org/ims/oneroster/resources/v1p2/resources?filter=status='active'

URL encoded as:

    GET https://imsglobal.org/ims/oneroster/resources/v1p2/resources?filter=status%3D%27active%27

Filter queries MUST be URL encoded.

An example of a complex query for all resources with a status='active' AND dateLastModified>'2016-12-12T00:00:00Z' is:

    GET https://imsglobal.org/ims/oneroster/resources/v1p2/resources?filter=status%3D%27active%27%20AND%20dateLastModified%3E%272016%3D12%3D12T00%3A00%3A00Z%27

When filtering on objects that are arrays the application of the filter depends on the nature of the comparison. So in the case of filtering on, for example, a 'role' field when the value of the field is 'role1,role2,role3' the following filters would return:

This means filtering using the '=' has 'AND' semantics and the '~' has 'OR' semantics. Filtering rules should conform to the use of the Unicode Collation Algorithm [UNICODE, 16] when using the relevant comparisons.

If the consumer requests that data be filtered by a non-existent field, NO data is returned and the server must provide the associated transaction status code information of:

3.4. Field Selection

For the read collection calls, such as 'getAllResources()', it should be possible for requesters to select the range of fields to be returned. By default, all mandatory fields from the core description of the resource MUST be returned. If any fields are specified in the request then the implementation should return those fields AND ONLY those fields i.e. the multiplicity constraint rules for an element are overridden. Any field or fields from the Data Model MAY be requested.

Field selection request MUST make use of the reserved word 'fields'. The value of fields is a comma delimited list of the fields to return. An example of a request message to ask for a list of Resources returning only the 'sourcedId' and 'title':

    GET https://imsglobal.org/ims/oneroster/resources/v1p2/resources?fields=sourcedId,title

If the consumer requests that data be selected using non-existent field, ALL data for the record is returned. If the consumer requests that data be selected using a blank field the request will be treated as an invalid request. The server must provide the associated transaction status code information of:

toc | top

4. Security Framework

This Section is NORMATIVE.

The information in this section is taken from the IMS Security Framework [Security, 21]: that document describes the security approaches to be adopted in all IMS specifications.

4.1. Transport Security

As the service will be exposing personal data related to students and their grades, it is important that only authorized users have access to that data. Further, data exchanges should be encrypted to ensure that packet sniffing cannot be used to read the data in transit.

All Requests and Responses MUST be sent using Transport Layer Security (TLS). Exchange of the signed certificates for endpoints between clients and servers is beyond the scope of this specification. Implementers of clients and servers are advised to look at the various 3rd party certificate signing services in order to obtain signed certificates.

Support for TLS 1.2 and/or TLS 1.3 is REQUIRED and SSL MUST NOT be used.

4.2. Authorization

The use of OAuth 2.0 Client Credentials with the Bearer Token obtained using the mechanism described in [RFC 6749] (Section 4.4) is REQUIRED. Details of this are given in the IMS Security Framework [Security, 21].

Authorization will use the OAuth 2.0 Client Credentials Grant mechanism. In this mechanism the client can request an access token using only its client credentials (using the consumer key and secret information) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server. In this approach the client issues a client authentication request and receives in response an access token. Issuing of an access token is defined in Section 5 of [RFC 6749].

The request for an access token, including three scopes (scopename1, scopename2 and scopenamex) takes the form of (this uses TLS):

        POST /token HTTP/1.1
        Host: server.example.com
        Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
        Content-Type: application/x-www-form-urlencoded

        grant_type=client_credentials&scope=scopename1%20scopename2%20scopenamex

The inclusion of scopes is REQUIRED and the set of scopes available for this service are defined in the following subsection. The authorization encoding is produced using the consumer key and secret. Note that the request for an access token MAY use a HTTP GET request.

The authorization encoding is produced using the consumer key and secret. Success results in the granting of the access token with a response of:

        HTTP/1.1 200 OK
        Content-Type: application/json;charset=UTF-8
        Cache-Control: no-store
        Pragma: no-cache

        {
            "access_token" : "2YotnFZFEjr1zCsicMWpAA",
            "token_type" : "bearer",
            "expires_in" : 3600,
            "scope" : "scopename1 scopename2 scopenamex"
        }

The recommended default value for the "expires_in" is 3600s. The authorization server MUST provide the scopes which are made available (either all or a subset of the scopes supplied in the request).

The client utilizes the access token to authenticate with the resource using the HTTP "Authorization" request header field [RFC 2617] with an authentication scheme defined by the specification of the access token type used, such as [RFC 6750]. An example of the use of the bearer token is:

        GET /resource/1 HTTP/1.1
        Host: provider.example.com
        Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

NOTE: This exchange assumes that TLS is used to secure the link.

4.3. Scopes

The set of scopes available in this service are listed in the following Tables.

4.3.1 "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" Scope

The core set of scopes to enable information about all resources or a single resource to be obtained. The set of service operations covered by this scope are listed in Table 4.3.1.

Table 4.3.1 Service Operations for the "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" Scope.
Operation HTTP Verb Endpoint
getAllResources GET /resources
getResource GET /resources/{sourcedId}

4.3.2 "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" Scope

To enable access to ALL of the endpoints for the resources service. The set of service operations covered by this scope are listed in Table 4.3.2.

Table 4.3.2 Service Operations for the "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" Scope.
Operation HTTP Verb Endpoint
getAllResources GET /resources
getResource GET /resources/{sourcedId}
getResourcesForClass GET /classes/{classSourcedId}/resources
getResourcesForCourse GET /courses/{courseSourcedId}/resources
getResourcesForUser GET /users/{userSourcedId}/resources

toc | top

5. UML to JSON Mappings

This Section is NOT NORMATIVE.

5.1 Service Parameter Payload Properties UML/JSON Mapping

The UML/JSON Mapping for the Service Parameters (excluding those service parameters passed as query parameters on the endpoint URL) to the JSON Payload Properties is given in Table 5.1. The syntax and semantics for this representation is described in Appendix A2.1.

Table 5.1 UML/JSON Mapping for the Service Parameters.
Operation Name Parameter Name UML Class JSON Name JSON Type JSON Schema Data Type
getAllResources resources ResourceSet resources Array of Objects ResourceSetDType
getResource resource SingleResource resource Object SingleResourceDType
getResourcesForClass resources ResourceSet resources Array of Objects ResourceSetDType
getResourcesForCourse resources ResourceSet resources Array of Objects ResourceSetDType
getResourcesForUser resources ResourceSet resources Array of Objects ResourceSetDType

5.2 Service Parameter Payload Class UML/JSON Mapping

The syntax and semantics for the Root Class UML/JSON mapping representations is described in Appendix A2.2.

5.2.1 ResourceSet Service Parameter Payload Class Mapping

The UML/JSON Mapping for the "ResourceSet" Service Parameter Payload Class is given in Table 5.2.1.

Table 5.2.1 UML/JSON Mapping for the "ResourceSet" Service Parameter Payload Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
ResourceSet Payload Parameter Container [ Sequence ] - N/A - ResourceSetDType Object
  • resources
 Attribute Resource [0.. *] resources Array of Properties

5.2.2 SingleResource Service Parameter Payload Class Mapping

The UML/JSON Mapping for the "SingleResource" Service Parameter Payload Class is given in Table 5.2.2.

Table 5.2.2 UML/JSON Mapping for the "SingleResource" Service Parameter Payload Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
SingleResource Payload Parameter Container [ Sequence ] - N/A - SingleResourceDType Object
  • resource
 Attribute Resource [1] resource Property

5.3 Payload Classes UML/JSON Mapping

The syntax and semantics for the Data Class UML/JSON mapping representations is described in Appendix A2.2.

5.3.1 Base Payload Class Mapping

The Payload UML/JSON Mapping for the "Base" Class is given in Table 5.3.1.

Table 5.3.1 Payload UML/JSON Mapping for the "Base" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
Base Core Container [ Sequence ] - N/A - BaseDType Object
  • sourcedId
 Attribute DT: GUID (PT: String) [1] sourcedId Property
  • status
 Attribute [ Enumeration (BaseStatusEnum) ] [1] status Property
  • dateLastModified
 Attribute PT: DateTime [1] dateLastModified Property
  • metadata
 Attribute Metadata [0..1] metadata Property

5.3.2 Metadata Payload Class Mapping

The Payload UML/JSON Mapping for the "Metadata" Class is given in Table 5.3.2.

Table 5.3.2 Payload UML/JSON Mapping for the "Metadata" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
Metadata Core Container [ Sequence ] - N/A - MetadataDType Object
  • extensions
 Attribute PT: Namespace [0.. *] Set of Proprietary Properties Set of Proprietary Properties

5.3.3 Resource Payload Class Mapping

The Payload UML/JSON Mapping for the "Resource" Class is given in Table 5.3.3.

Table 5.3.3 Payload UML/JSON Mapping for the "Resource" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
Resource Core Container [ Sequence ] AND Inherits [ Base ] - N/A - ResourceDType
 Object
  • sourcedId
    [ INHERITED ]
 Attribute DT: GUID (PT: String) [1] sourcedId Property
  • status
    [ INHERITED ]
 Attribute [ Enumeration (BaseStatusEnum) ] [1] status Property
  • dateLastModified
    [ INHERITED ]
 Attribute PT: DateTime [1] dateLastModified Property
  • metadata
    [ INHERITED ]
 Attribute Metadata [0..1] metadata Property
  • title
 Attribute PT: NormalizedString [0..1] title Property
  • roles
 Attribute [ Union (RoleEnumExt) ] [0.. *] roles Array of Properties
  • importance
 Attribute [ Enumeration (ImportanceEnum) ] [0..1] importance Property
  • vendorResourceId
 Attribute DT: Identifier (PT: String) [1] vendorResourceId Property
  • vendorId
 Attribute DT: Identifier (PT: String) [0..1] vendorId Property
  • applicationId
 Attribute DT: Identifier (PT: String) [0..1] applicationId Property

5.3.4 imsx_CodeMinor Payload Class Mapping

The Payload UML/JSON Mapping for the "imsx_CodeMinor" Class is given in Table 5.3.4.

Table 5.3.4 Payload UML/JSON Mapping for the "imsx_CodeMinor" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
imsx_CodeMinor Core Container [ Sequence ] - N/A - imsx_CodeMinorDType Object
  • imsx_codeMinorField
 Attribute imsx_CodeMinorField [1.. *] imsx_codeMinorField Array of Properties

5.3.5 imsx_CodeMinorField Payload Class Mapping

The Payload UML/JSON Mapping for the "imsx_CodeMinorField" Class is given in Table 5.3.5.

Table 5.3.5 Payload UML/JSON Mapping for the "imsx_CodeMinorField" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
imsx_CodeMinorField Core Container [ Sequence ] - N/A - imsx_CodeMinorFieldDType Object
  • imsx_codeMinorFieldName
 Attribute PT: NormalizedString [1] imsx_codeMinorFieldName Property
  • imsx_codeMinorFieldValue
 Attribute [ Enumeration (imsx_CodeMinorValueEnum) ] [1] imsx_codeMinorFieldValue Property

5.3.6 imsx_StatusInfo Payload Class Mapping

The Payload UML/JSON Mapping for the "imsx_StatusInfo" Class is given in Table 5.3.6.

Table 5.3.6 Payload UML/JSON Mapping for the "imsx_StatusInfo" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
imsx_StatusInfo Core Container [ Sequence ] - N/A - imsx_StatusInfoDType Object
  • imsx_codeMajor
 Attribute [ Enumeration (imsx_CodeMajorEnum) ] [1] imsx_codeMajor Property
  • imsx_severity
 Attribute [ Enumeration (imsx_SeverityEnum) ] [1] imsx_severity Property
  • imsx_description
 Attribute PT: String [0..1] imsx_description Property
  • imsx_CodeMinor
 Attribute imsx_CodeMinor [0..1] imsx_CodeMinor Property

5.4 Enumerated Class UML/JSON Mapping

The definition of the set of enumerated data-types used in this specification is given in Table 5.4. The syntax and semantics for the Enumerated Class UML/JSON mapping representations is described in Appendix A2.3.

Table 5.4 The UML/JSON Map Enumerated Class Definitions.
Enumeration Class Name Description
BaseStatusEnum Enumerated value set of: { active | tobedeleted }.
ImportanceEnum Enumerated value set of: { primary | secondary }.
RoleEnum Enumerated value set of: { administrator | aide | guardian | parent | proctor | relative | student | teacher }.
imsx_CodeMajorEnum Enumerated value set of: { success | processing | failure | unsupported }.
imsx_CodeMinorValueEnum Enumerated value set of: { fullsuccess | invalid_filter_field | invalid_selection_field | forbidden | unauthorisedrequest | internal_server_error | server_busy | unknownobject | invaliddata | invalid_sort_field | unsupported }.
imsx_SeverityEnum Enumerated value set of: { status | warning | error }.

5.5 Enumerated List Class UML/JSON Mapping

There are no enumerated list class definitions.

5.6 Union Class UML/JSON Mapping

The definition of the set of union data-types used in this specification is given in Table 5.6. The syntax and semantics for the Union Class UML/JSON mapping representations is described in Appendix A2.4.

Table 5.6 The UML/JSON Map Union Class Definitions.
Union Class Name Description
RoleEnumExt This is a value from one of the set of data-types: RoleEnum, RoleExtString

5.7 Primitive Type UML/JSON Mapping

The definition of the set of primitive data-types used in this specification is given in Table 5.7. The syntax and semantics for the Primitive Type UML/JSON mapping representations is described in Appendix A2.4.

Table 5.7 The UML/JSON Map Primitive Type Definitions.
Primitive Type Name Description
DateTime This is mapped to the JSON "string" data-type with the format of "dateTime".
Namespace This denotes an extension facility. The class is permitted to have proprietary JSON properties i.e. "additionalProperties: true".
NormalizedString This is mapped to the JSON "string" data-type.
String This is mapped to the JSON "string" data-type.

toc | top

6. JSON Payloads

This Section is NOT NORMATIVE.

6.1 "getAllResources" Request Payload

There is no payload for this request.

6.2 "getAllResources" Response Payloads

6.2.1 Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Table 6.2.1 - Tabular representation of the JSON payload for "200" response messages for a "getAllResources" operation.
Property Name Multiplicity JSON Data-type Description
    resources [0..*] Array [ Object ] The set of contained resource identfiers.
            sourcedId [1..1] String All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.
                    extensions [0..*] Set of Proprietary Properties The form of the extension will be determined by the associated binding (for examples see [OR-IMPL-12]).
            title [0..1] String A human readable title/label for the resource.
            roles [0..*] Array [ Union(RoleEnumExt) ] The set of roles, types of users, who are expected to make use of the resource.
            importance [0..1] Enumeration This is an indicator of the significance of the resource i.e. primary or secondary.
            vendorResourceId [1..1] String This is a unique identifier for the resource allocated by the vendor.
            vendorId [0..1] String Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.
            applicationId [0..1] String Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.1b.

Code 6.2.1 - JSON payload example for "200" response messages for a "getAllResources" operation. 
    {
        "resources" : [
            {
                "sourcedId" : "..String..",
                "status" : "active"|"tobedeleted",
                "dateLastModified" : "..Date/Time..",
                "metadata" : {
                    "..permitted extension point.." : "..user defined value.."
                },
                "title" : "..NormalizedString..",
                "roles" : [ "..select from Union..", ..., "..select from Union.." ],
                "importance" : "primary"|"secondary",
                "vendorResourceId" : "..String..",
                "vendorId" : "..String..",
                "applicationId" : "..String.."
            },
            {...},
            {...}
        ]
    }

6.2.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

A tabular description of the response payload is shown in the Table below.

Table 6.2.2 - Tabular representation of the JSON payload for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getAllResources" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.1c.

Code 6.2.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getAllResources" operation. 
    {
        "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
        "imsx_severity" : "status"|"warning"|"error",
        "imsx_description" : "..String..",
        "imsx_CodeMinor" : {
            "imsx_codeMinorField" : [
                {
                    "imsx_codeMinorFieldName" : "..NormalizedString..",
                    "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"forbidden"|"unauthorisedrequest"|"internal_server_error"|"server_busy"|"unknownobject"|"invaliddata"|"invalid_sort_field"|"unsupported"
                },
                {...},
                {...}
            ]
        }
    }

6.3 "getResource" Request Payload

There is no payload for this request.

6.4 "getResource" Response Payloads

6.4.1 Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Table 6.4.1 - Tabular representation of the JSON payload for "200" response messages for a "getResource" operation.
Property Name Multiplicity JSON Data-type Description
    resource [1..1] Object The label for the contained resource.
            sourcedId [1..1] String All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.
                    extensions [0..*] Set of Proprietary Properties The form of the extension will be determined by the associated binding (for examples see [OR-IMPL-12]).
            title [0..1] String A human readable title/label for the resource.
            roles [0..*] Array [ Union(RoleEnumExt) ] The set of roles, types of users, who are expected to make use of the resource.
            importance [0..1] Enumeration This is an indicator of the significance of the resource i.e. primary or secondary.
            vendorResourceId [1..1] String This is a unique identifier for the resource allocated by the vendor.
            vendorId [0..1] String Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.
            applicationId [0..1] String Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.2b.

Code 6.4.1 - JSON payload example for "200" response messages for a "getResource" operation. 
    {
        "resource" : {
            "sourcedId" : "..String..",
            "status" : "active"|"tobedeleted",
            "dateLastModified" : "..Date/Time..",
            "metadata" : {
                "..permitted extension point.." : "..user defined value.."
            },
            "title" : "..NormalizedString..",
            "roles" : [ "..select from Union..", ..., "..select from Union.." ],
            "importance" : "primary"|"secondary",
            "vendorResourceId" : "..String..",
            "vendorId" : "..String..",
            "applicationId" : "..String.."
        }
    }

6.4.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

A tabular description of the response payload is shown in the Table below.

Table 6.4.2 - Tabular representation of the JSON payload for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResource" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.2c.

Code 6.4.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResource" operation. 
    {
        "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
        "imsx_severity" : "status"|"warning"|"error",
        "imsx_description" : "..String..",
        "imsx_CodeMinor" : {
            "imsx_codeMinorField" : [
                {
                    "imsx_codeMinorFieldName" : "..NormalizedString..",
                    "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"forbidden"|"unauthorisedrequest"|"internal_server_error"|"server_busy"|"unknownobject"|"invaliddata"|"invalid_sort_field"|"unsupported"
                },
                {...},
                {...}
            ]
        }
    }

6.5 "getResourcesForClass" Request Payload

There is no payload for this request.

6.6 "getResourcesForClass" Response Payloads

6.6.1 Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Table 6.6.1 - Tabular representation of the JSON payload for "200" response messages for a "getResourcesForClass" operation.
Property Name Multiplicity JSON Data-type Description
    resources [0..*] Array [ Object ] The set of contained resource identfiers.
            sourcedId [1..1] String All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.
                    extensions [0..*] Set of Proprietary Properties The form of the extension will be determined by the associated binding (for examples see [OR-IMPL-12]).
            title [0..1] String A human readable title/label for the resource.
            roles [0..*] Array [ Union(RoleEnumExt) ] The set of roles, types of users, who are expected to make use of the resource.
            importance [0..1] Enumeration This is an indicator of the significance of the resource i.e. primary or secondary.
            vendorResourceId [1..1] String This is a unique identifier for the resource allocated by the vendor.
            vendorId [0..1] String Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.
            applicationId [0..1] String Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.3b.

Code 6.6.1 - JSON payload example for "200" response messages for a "getResourcesForClass" operation. 
    {
        "resources" : [
            {
                "sourcedId" : "..String..",
                "status" : "active"|"tobedeleted",
                "dateLastModified" : "..Date/Time..",
                "metadata" : {
                    "..permitted extension point.." : "..user defined value.."
                },
                "title" : "..NormalizedString..",
                "roles" : [ "..select from Union..", ..., "..select from Union.." ],
                "importance" : "primary"|"secondary",
                "vendorResourceId" : "..String..",
                "vendorId" : "..String..",
                "applicationId" : "..String.."
            },
            {...},
            {...}
        ]
    }

6.6.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

A tabular description of the response payload is shown in the Table below.

Table 6.6.2 - Tabular representation of the JSON payload for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForClass" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.3c.

Code 6.6.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForClass" operation. 
    {
        "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
        "imsx_severity" : "status"|"warning"|"error",
        "imsx_description" : "..String..",
        "imsx_CodeMinor" : {
            "imsx_codeMinorField" : [
                {
                    "imsx_codeMinorFieldName" : "..NormalizedString..",
                    "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"forbidden"|"unauthorisedrequest"|"internal_server_error"|"server_busy"|"unknownobject"|"invaliddata"|"invalid_sort_field"|"unsupported"
                },
                {...},
                {...}
            ]
        }
    }

6.7 "getResourcesForCourse" Request Payload

There is no payload for this request.

6.8 "getResourcesForCourse" Response Payloads

6.8.1 Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Table 6.8.1 - Tabular representation of the JSON payload for "200" response messages for a "getResourcesForCourse" operation.
Property Name Multiplicity JSON Data-type Description
    resources [0..*] Array [ Object ] The set of contained resource identfiers.
            sourcedId [1..1] String All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.
                    extensions [0..*] Set of Proprietary Properties The form of the extension will be determined by the associated binding (for examples see [OR-IMPL-12]).
            title [0..1] String A human readable title/label for the resource.
            roles [0..*] Array [ Union(RoleEnumExt) ] The set of roles, types of users, who are expected to make use of the resource.
            importance [0..1] Enumeration This is an indicator of the significance of the resource i.e. primary or secondary.
            vendorResourceId [1..1] String This is a unique identifier for the resource allocated by the vendor.
            vendorId [0..1] String Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.
            applicationId [0..1] String Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.4b.

Code 6.8.1 - JSON payload example for "200" response messages for a "getResourcesForCourse" operation. 
    {
        "resources" : [
            {
                "sourcedId" : "..String..",
                "status" : "active"|"tobedeleted",
                "dateLastModified" : "..Date/Time..",
                "metadata" : {
                    "..permitted extension point.." : "..user defined value.."
                },
                "title" : "..NormalizedString..",
                "roles" : [ "..select from Union..", ..., "..select from Union.." ],
                "importance" : "primary"|"secondary",
                "vendorResourceId" : "..String..",
                "vendorId" : "..String..",
                "applicationId" : "..String.."
            },
            {...},
            {...}
        ]
    }

6.8.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

A tabular description of the response payload is shown in the Table below.

Table 6.8.2 - Tabular representation of the JSON payload for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForCourse" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.4c.

Code 6.8.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForCourse" operation. 
    {
        "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
        "imsx_severity" : "status"|"warning"|"error",
        "imsx_description" : "..String..",
        "imsx_CodeMinor" : {
            "imsx_codeMinorField" : [
                {
                    "imsx_codeMinorFieldName" : "..NormalizedString..",
                    "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"forbidden"|"unauthorisedrequest"|"internal_server_error"|"server_busy"|"unknownobject"|"invaliddata"|"invalid_sort_field"|"unsupported"
                },
                {...},
                {...}
            ]
        }
    }

6.9 "getResourcesForUser" Request Payload

There is no payload for this request.

6.10 "getResourcesForUser" Response Payloads

6.10.1 Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Table 6.10.1 - Tabular representation of the JSON payload for "200" response messages for a "getResourcesForUser" operation.
Property Name Multiplicity JSON Data-type Description
    resources [0..*] Array [ Object ] The set of contained resource identfiers.
            sourcedId [1..1] String All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.
                    extensions [0..*] Set of Proprietary Properties The form of the extension will be determined by the associated binding (for examples see [OR-IMPL-12]).
            title [0..1] String A human readable title/label for the resource.
            roles [0..*] Array [ Union(RoleEnumExt) ] The set of roles, types of users, who are expected to make use of the resource.
            importance [0..1] Enumeration This is an indicator of the significance of the resource i.e. primary or secondary.
            vendorResourceId [1..1] String This is a unique identifier for the resource allocated by the vendor.
            vendorId [0..1] String Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.
            applicationId [0..1] String Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.5b.

Code 6.10.1 - JSON payload example for "200" response messages for a "getResourcesForUser" operation. 
    {
        "resources" : [
            {
                "sourcedId" : "..String..",
                "status" : "active"|"tobedeleted",
                "dateLastModified" : "..Date/Time..",
                "metadata" : {
                    "..permitted extension point.." : "..user defined value.."
                },
                "title" : "..NormalizedString..",
                "roles" : [ "..select from Union..", ..., "..select from Union.." ],
                "importance" : "primary"|"secondary",
                "vendorResourceId" : "..String..",
                "vendorId" : "..String..",
                "applicationId" : "..String.."
            },
            {...},
            {...}
        ]
    }

6.10.2 Response Payloads for the HTTP Codes (400, 401, 403, 404, 422, 429, 500, default)

A tabular description of the response payload is shown in the Table below.

Table 6.10.2 - Tabular representation of the JSON payload for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForUser" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix C1.5c.

Code 6.10.2 - JSON payload example for "400, 401, 403, 404, 422, 429, 500, default" response messages for a "getResourcesForUser" operation. 
    {
        "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
        "imsx_severity" : "status"|"warning"|"error",
        "imsx_description" : "..String..",
        "imsx_CodeMinor" : {
            "imsx_codeMinorField" : [
                {
                    "imsx_codeMinorFieldName" : "..NormalizedString..",
                    "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"forbidden"|"unauthorisedrequest"|"internal_server_error"|"server_busy"|"unknownobject"|"invaliddata"|"invalid_sort_field"|"unsupported"
                },
                {...},
                {...}
            ]
        }
    }

toc | top

7. OpenAPI Description

This Section is NORMATIVE.

7.1 General Information

The set of General Information defined in the OpenAPI description, and realised in both the JSON and YAML instances, are listed in Tables 7.1a (version 2) and 7.1b (version 3). The syntax and semantics for this information are described in Appendix A3.1.

Table 7.1a - The Set of General Information Defined in the OpenAPI(2) Description.
Swagger Version 2.0
Specification Title OneRoster Resources
Specification Version 1.2
Description The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.
Terms of Service 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 API DEFINITION 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 IMPLEMENTERS 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 API DEFINITION.
Contact Vice President of Operations, 1EdTech (https://www.1edtech.org). Email: operations@1edtech.org.
License 1EdTech - https://www.1edtech.org/license.html
Host www.1edtech.org
Base Path /ims/oneroster/resources/v1p2
Schemes http, https
Consumes application/json
Produces application/json

Table 7.1b - The Set of General Information Defined in the OpenAPI(3) Description.
OpenAPI Version 3.0.0 or 3.1.0
Specification Title OneRoster Resources
Specification Version 1.2
Description The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.
Terms of Service https://www.1edtech.org/license.html
Contact Vice President of Operations, 1EdTech (http://www.1edtech.org). Email: operations@1edtech.org.
License 1EdTech - https://www.1edtech.org/license.html
Servers https://{hostName=www.1edtech.org}{basePath=/ims/oneroster/resources/v1p2}
www.1edtech.org/ims/oneroster/resources/v1p2

7.2 Tags Information

The set of Tags defined in the OpenAPI description, and realised in both the JSON and YAML instances, is listed in Table 7.2. The syntax and semantics for these Tags are described in Appendix A3.2.

Table 7.2 - The Set of Tags Defined in the OpenAPI Description.
Tag Name Description
ClassesManagement This enables the management of information about resources i.e. the allocation of resources to classes. The set of endpoints assigned to this tag are:
CoursesManagement This enables the management of information about resources i.e. the allocation of resources to courses. The set of endpoints assigned to this tag are:
ResourcesManagement This enables the management of information about resources. The set of endpoints assigned to this tag are:
UsersManagement This enables the management of information about resources i.e. the allocation of resources to courses. The set of endpoints assigned to this tag are:

7.3 Security Information

The OAuth 2 Client Credentials security mode is used for this service. Table 7.3.1 describes the OpenAPI information for the configuration of the OAuth 2.0 Client Credentials. The syntax and semantics for this information are described in Appendix A3.3.

Table 7.3.1 - The Set of OAuth 2.0 Client Credentials Security Information Defined in the OpenAPI Description.
Security Label OAuth2CC
Type oauth2
Description OAuth 2 Client Credentials (as per the requirements in the IMS Security Framework) is to be used.
Flow OAS2 - application
OAS3 - clientCredentials
Token URL https://www.imsglobal.org
Scopes
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
Global Scope OAuth2CC : [ https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly, https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly ]

7.4 Paths Information

The following Tables describe the OpenAPI information for each of the Paths. The syntax and semantics for these Paths are described in Appendix A3.4.

7.4.1 "/classes/{classSourcedId}/resources" Path

The following Table describes the OpenAPI information for the HTTP Verb "GET" on the "/classes/{classSourcedId}/resources" Path.

Table 7.4.1a - The Path Details for the 'GET' verb with the '/classes/{classSourcedId}/resources' Path.
HTTP Verb: GET
Operation ID getResourcesForClass
Summary The REST "read" request message for the "getResourcesForClass()" API call.
Tags ClassesManagement
Security and Scopes The security modes protecting access to this endpoint are:
  • OAuth2CC - OAuth 2 Client Credentials Grant
The scopes that enable access to this endpoint are:
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
Description To read, get, the collection of resources associated to the specified class. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported.
Path Placeholders
  • {classSourcedId} - the unique identifier, GUID, for this class.
Query Parameters
Name Type Multiplicity Default
limit Positive Integer [0..1] 100
offset Non-negative Integer [0..1] 0
sort String [0..1] -
orderBy [ Enumeration ] [0..1] -
filter String [0..1] -
fields String [0..*] -
Responses
Name Type Description
200 ResourceSetDType The requested read has been fully serviced and all of the required data returned.
Headers
* "X-Total-Count" - the total number of resources that are available to be returned
Links
* "next (limit | offset)" - get the next set of resources i.e. from offset to offset+limit
* "last (limit | offset)" - get the last set of resources i.e. from offset to end
* "first (limit | offset)" - get the first set of resources i.e. from first to limit
* "prev (limit | offset)" - get the previous set of resources i.e. from last_offset to last_offset+limit
400 imsx_StatusInfoDType Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'.
401 imsx_StatusInfoDType The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
403 imsx_StatusInfoDType This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
404 imsx_StatusInfoDType Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
422 imsx_StatusInfoDType This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
429 imsx_StatusInfoDType The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
500 imsx_StatusInfoDType This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
default imsx_StatusInfoDType This is the default payload when none of the other HTTP codes are to be supplied.

7.4.2 "/courses/{courseSourcedId}/resources" Path

The following Table describes the OpenAPI information for the HTTP Verb "GET" on the "/courses/{courseSourcedId}/resources" Path.

Table 7.4.2a - The Path Details for the 'GET' verb with the '/courses/{courseSourcedId}/resources' Path.
HTTP Verb: GET
Operation ID getResourcesForCourse
Summary The REST "read" request message for the "getResourcesForCourse()" API call.
Tags CoursesManagement
Security and Scopes The security modes protecting access to this endpoint are:
  • OAuth2CC - OAuth 2 Client Credentials Grant
The scopes that enable access to this endpoint are:
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
Description To read, get, the collection of resources associated to the specified course. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported.
Path Placeholders
  • {courseSourcedId} - the unique identifier, GUID, for the course.
Query Parameters
Name Type Multiplicity Default
limit Positive Integer [0..1] 100
offset Non-negative Integer [0..1] 0
sort String [0..1] -
orderBy [ Enumeration ] [0..1] -
filter String [0..1] -
fields String [0..*] -
Responses
Name Type Description
200 ResourceSetDType The requested read has been fully serviced and all of the required data returned.
Headers
* "X-Total-Count" - the total number of resources that are available to be returned
Links
* "next (limit | offset)" - get the next set of resources i.e. from offset to offset+limit
* "last (limit | offset)" - get the last set of resources i.e. from offset to end
* "first (limit | offset)" - get the first set of resources i.e. from first to limit
* "prev (limit | offset)" - get the previous set of resources i.e. from last_offset to last_offset+limit
400 imsx_StatusInfoDType Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'.
401 imsx_StatusInfoDType The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
403 imsx_StatusInfoDType This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
404 imsx_StatusInfoDType Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
422 imsx_StatusInfoDType This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
429 imsx_StatusInfoDType The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
500 imsx_StatusInfoDType This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
default imsx_StatusInfoDType This is the default payload when none of the other HTTP codes are to be supplied.

7.4.3 "/resources" Path

The following Table describes the OpenAPI information for the HTTP Verb "GET" on the "/resources" Path.

Table 7.4.3a - The Path Details for the 'GET' verb with the '/resources' Path.
HTTP Verb: GET
Operation ID getAllResources
Summary The REST "read" request message for the "getAllResources()" API call.
Tags ResourcesManagement
Security and Scopes The security modes protecting access to this endpoint are:
  • OAuth2CC - OAuth 2 Client Credentials Grant
The scopes that enable access to this endpoint are:
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
Description To read, get, a collection of resources i.e. all resources. This is the OneRoster description of the resources and not the actual resources.
Path Placeholders Path placeholders are not permitted.
Query Parameters
Name Type Multiplicity Default
limit Positive Integer [0..1] 100
offset Non-negative Integer [0..1] 0
sort String [0..1] -
orderBy [ Enumeration ] [0..1] -
filter String [0..1] -
fields String [0..*] -
Responses
Name Type Description
200 ResourceSetDType The requested read has been fully serviced and all of the required data returned.
Headers
* "X-Total-Count" - the total number of resources that are available to be returned
Links
* "next (limit | offset)" - get the next set of resources i.e. from offset to offset+limit
* "last (limit | offset)" - get the last set of resources i.e. from offset to end
* "first (limit | offset)" - get the first set of resources i.e. from first to limit
* "prev (limit | offset)" - get the previous set of resources i.e. from last_offset to last_offset+limit
400 imsx_StatusInfoDType Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'.
401 imsx_StatusInfoDType The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
403 imsx_StatusInfoDType This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
404 imsx_StatusInfoDType Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
422 imsx_StatusInfoDType This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
429 imsx_StatusInfoDType The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
500 imsx_StatusInfoDType This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
default imsx_StatusInfoDType This is the default payload when none of the other HTTP codes are to be supplied.

7.4.4 "/resources/{sourcedId}" Path

The following Table describes the OpenAPI information for the HTTP Verb "GET" on the "/resources/{sourcedId}" Path.

Table 7.4.4a - The Path Details for the 'GET' verb with the '/resources/{sourcedId}' Path.
HTTP Verb: GET
Operation ID getResource
Summary The REST "read" request message for the "getResource()" API call.
Tags ResourcesManagement
Security and Scopes The security modes protecting access to this endpoint are:
  • OAuth2CC - OAuth 2 Client Credentials Grant
The scopes that enable access to this endpoint are:
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
Description To read, get, a specific OneRoster resource description. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported.
Path Placeholders
  • {sourcedId} - the unique identifier, GUID, for the resource.
Query Parameters
Name Type Multiplicity Default
fields String [0..*] -
Responses
Name Type Description
200 SingleResourceDType The requested read has been fully serviced and all of the required data returned.
400 imsx_StatusInfoDType Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'.
401 imsx_StatusInfoDType The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
403 imsx_StatusInfoDType This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
404 imsx_StatusInfoDType Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
422 imsx_StatusInfoDType This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
429 imsx_StatusInfoDType The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
500 imsx_StatusInfoDType This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
default imsx_StatusInfoDType This is the default payload when none of the other HTTP codes are to be supplied.

7.4.5 "/users/{userSourcedId}/resources" Path

The following Table describes the OpenAPI information for the HTTP Verb "GET" on the "/users/{userSourcedId}/resources" Path.

Table 7.4.5a - The Path Details for the 'GET' verb with the '/users/{userSourcedId}/resources' Path.
HTTP Verb: GET
Operation ID getResourcesForUser
Summary The REST "read" request message for the "getResourcesForUser()" API call.
Tags UsersManagement
Security and Scopes The security modes protecting access to this endpoint are:
  • OAuth2CC - OAuth 2 Client Credentials Grant
The scopes that enable access to this endpoint are:
  • https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
Description To read, get, the collection of resources available to the specified user. This is the OneRoster description of the resources and not the actual resources. If the specified user cannot be identified within the service provider then a status code of 'unknownobject' must be reported.
Path Placeholders
  • {userSourcedId} - the unique identifier, GUID, for the user.
Query Parameters
Name Type Multiplicity Default
limit Positive Integer [0..1] 100
offset Non-negative Integer [0..1] 0
sort String [0..1] -
orderBy [ Enumeration ] [0..1] -
filter String [0..1] -
fields String [0..*] -
Responses
Name Type Description
200 ResourceSetDType The requested read has been fully serviced and all of the required data returned.
Headers
* "X-Total-Count" - the total number of resources that are available to be returned
Links
* "next (limit | offset)" - get the next set of resources i.e. from offset to offset+limit
* "last (limit | offset)" - get the last set of resources i.e. from offset to end
* "first (limit | offset)" - get the first set of resources i.e. from first to limit
* "prev (limit | offset)" - get the previous set of resources i.e. from last_offset to last_offset+limit
400 imsx_StatusInfoDType Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'.
401 imsx_StatusInfoDType The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
403 imsx_StatusInfoDType This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
404 imsx_StatusInfoDType Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
422 imsx_StatusInfoDType This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
429 imsx_StatusInfoDType The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
500 imsx_StatusInfoDType This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
default imsx_StatusInfoDType This is the default payload when none of the other HTTP codes are to be supplied.

7.5 Definitions Information

The following Tables describe the OpenAPI information for each of the JSON Schema Definitions. The syntax and semantics for these JSON Schema Definition descriptions are described in Appendix A3.5.

7.5.1 "MetadataDType" Definition

The OpenAPI JSON Schema description for the "MetadataDType" Complex Type is given in Table 7.5.1.

Table 7.5.1 - OpenAPI JSON Schema description for the "MetadataDType" Complex Type.
Annotations This is the container for the data model extensions that may be assigned to the associated class of objects.
Diagram JSON Schema diagram of the Metadata object.
Model Namespace-based Extension
Source (OAS2) 
    "MetadataDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
        },
        "additionalProperties" : true
    },
Source (OAS3) 
    "MetadataDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
        },
        "additionalProperties" : true
    },

7.5.2 "ResourceDType" Definition

The OpenAPI JSON Schema description for the "ResourceDType" Complex Type is given in Table 7.5.2.

Table 7.5.2 - OpenAPI JSON Schema description for the "ResourceDType" Complex Type.
Annotations A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience. A resource MUST be associated to a course and/or a class.
Diagram JSON Schema diagram of the Resource object.
Model sourcedId{1..1}, status{1..1}, dateLastModified{1..1}, metadata{0..1}, title{0..1}, roles{0..*}, importance{0..1}, vendorResourceId{1..1}, vendorId{0..1}, applicationId{0..1}
Source (OAS2) 
    "ResourceDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "sourcedId" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
            "status" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "active","tobedeleted" ]
            },
            "dateLastModified" : {
                "description" : "Model Primitive Datatype = DateTime. ",
                "type" : "string",
                "format" : "date-time"
            },
            "metadata" : {
                "$ref" : "#/definitions/MetadataDType"
            },
            "title" : {
                "description" : "Model Primitive Datatype = NormalizedString. ",
                "type" : "string"
            },
            "roles" : {
                "description" : "...",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "type" : "string"
                }
            },
            "importance" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "primary","secondary" ]
            },
            "vendorResourceId" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
            "vendorId" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
            "applicationId" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
        },
        "required" : [ "vendorResourceId" ],
        "additionalProperties" : false
    },
Source (OAS3) 
    "ResourceDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "sourcedId" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
            "status" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "active","tobedeleted" ]
            },
            "dateLastModified" : {
                "description" : "Model Primitive Datatype = DateTime. ",
                "type" : "string",
                "format" : "date-time"
            },
            "metadata" : {
                "$ref" : "#/components/schemas/MetadataDType"
            },
            "title" : {
                "description" : "Model Primitive Datatype = NormalizedString. ",
                "type" : "string"
            },
            "roles" : {
                "description" : "...",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "anyOf" : [
                        {
                            "type" : "string",
                            "enum" : [ "administrator","aide","guardian","parent","proctor","relative","student","teacher" ]
                        },
                        {
                            "description" : "Model Primitive Datatype = NormalizedString.",
                            "type" : "string",
                            "pattern" : "(ext:)[a-zA-Z0-9\\.\\-_]+"
                        }
                    ]
                }
            },
            "importance" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "primary","secondary" ]
            },
            "vendorResourceId" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
            "vendorId" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
            "applicationId" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
        },
        "required" : [ "vendorResourceId" ],
        "additionalProperties" : false
    },

7.5.3 "ResourceSetDType" Definition

The OpenAPI JSON Schema description for the "ResourceSetDType" Complex Type is given in Table 7.5.3.

Table 7.5.3 - OpenAPI JSON Schema description for the "ResourceSetDType" Complex Type.
Annotations The container for a collection of resource records. The order is not significant. This may be empty. The service provider may not have any resources or cannot identfiy any resources that fit the specified filter constraints.
Diagram JSON Schema diagram of the ResourceSet object.
Model resources{0..*}
Source (OAS2) 
    "ResourceSetDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "resources" : {
                "description" : "...",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/ResourceDType"
                }
            },
        },
        "additionalProperties" : false
    },
Source (OAS3) 
    "ResourceSetDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "resources" : {
                "description" : "...",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/components/schemas/ResourceDType"
                }
            },
        },
        "additionalProperties" : false
    },

7.5.4 "SingleResourceDType" Definition

The OpenAPI JSON Schema description for the "SingleResourceDType" Complex Type is given in Table 7.5.4.

Table 7.5.4 - OpenAPI JSON Schema description for the "SingleResourceDType" Complex Type.
Annotations The container for a single resource. This may be empty i.e. the resource has no properties that obey any of the specified selection criteria.
Diagram JSON Schema diagram of the SingleResource object.
Model resource{1..1}
Source (OAS2) 
    "SingleResourceDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "resource" : {
                "$ref" : "#/definitions/ResourceDType"
            },
        },
        "required" : [ "resource" ],
        "additionalProperties" : false
    },
Source (OAS3) 
    "SingleResourceDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "resource" : {
                "$ref" : "#/components/schemas/ResourceDType"
            },
        },
        "required" : [ "resource" ],
        "additionalProperties" : false
    },

7.5.5 "imsx_CodeMinorDType" Definition

The OpenAPI JSON Schema description for the "imsx_CodeMinorDType" Complex Type is given in Table 7.5.5.

Table 7.5.5 - OpenAPI JSON Schema description for the "imsx_CodeMinorDType" Complex Type.
Annotations This is the container for the set of code minor status codes reported in the responses from the Service Provider.
Diagram JSON Schema diagram of the imsx_CodeMinor object.
Model imsx_codeMinorField{1..*}
Source (OAS2) 
    "imsx_CodeMinorDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMinorField" : {
                "description" : "...",
                "type" : "array",
                "minItems" : 1,
                "items" : {
                    "$ref" : "#/definitions/imsx_CodeMinorFieldDType"
                }
            },
        },
        "required" : [ "imsx_codeMinorField" ],
        "additionalProperties" : false
    },
Source (OAS3) 
    "imsx_CodeMinorDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMinorField" : {
                "description" : "...",
                "type" : "array",
                "minItems" : 1,
                "items" : {
                    "$ref" : "#/components/schemas/imsx_CodeMinorFieldDType"
                }
            },
        },
        "required" : [ "imsx_codeMinorField" ],
        "additionalProperties" : false
    },

7.5.6 "imsx_CodeMinorFieldDType" Definition

The OpenAPI JSON Schema description for the "imsx_CodeMinorFieldDType" Complex Type is given in Table 7.5.6.

Table 7.5.6 - OpenAPI JSON Schema description for the "imsx_CodeMinorFieldDType" Complex Type.
Annotations This is the container for a single code minor status code.
Diagram JSON Schema diagram of the imsx_CodeMinorField object.
Model imsx_codeMinorFieldName{1..1}, imsx_codeMinorFieldValue{1..1}
Source (OAS2) 
    "imsx_CodeMinorFieldDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMinorFieldName" : {
                "description" : "Model Primitive Datatype = NormalizedString. ",
                "type" : "string",
                "default" : "TargetEndSystem"
            },
            "imsx_codeMinorFieldValue" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                            "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
            },
        },
        "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
        "additionalProperties" : false
    },
Source (OAS3) 
    "imsx_CodeMinorFieldDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMinorFieldName" : {
                "description" : "Model Primitive Datatype = NormalizedString. ",
                "type" : "string",
                "default" : "TargetEndSystem"
            },
            "imsx_codeMinorFieldValue" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                            "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
            },
        },
        "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
        "additionalProperties" : false
    },

7.5.7 "imsx_StatusInfoDType" Definition

The OpenAPI JSON Schema description for the "imsx_StatusInfoDType" Complex Type is given in Table 7.5.7.

Table 7.5.7 - OpenAPI JSON Schema description for the "imsx_StatusInfoDType" Complex Type.
Annotations This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Resources service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request. See Appendix B for further information on the interpretation of the information contained within this class.
Diagram JSON Schema diagram of the imsx_StatusInfo object.
Model imsx_codeMajor{1..1}, imsx_severity{1..1}, imsx_description{0..1}, imsx_CodeMinor{0..1}
Source (OAS2) 
    "imsx_StatusInfoDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMajor" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "success","processing","failure","unsupported" ]
            },
            "imsx_severity" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "status","warning","error" ]
            },
            "imsx_description" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
            "imsx_CodeMinor" : {
                "$ref" : "#/definitions/imsx_CodeMinorDType"
            },
        },
        "required" : [ "imsx_codeMajor","imsx_severity" ],
        "additionalProperties" : false
    },
Source (OAS3) 
    "imsx_StatusInfoDType" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMajor" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "success","processing","failure","unsupported" ]
            },
            "imsx_severity" : {
                "description" : "...",
                "type" : "string",
                "enum" : [ "status","warning","error" ]
            },
            "imsx_description" : {
                "description" : "Model Primitive Datatype = String. ",
                "type" : "string"
            },
            "imsx_CodeMinor" : {
                "$ref" : "#/components/schemas/imsx_CodeMinorDType"
            },
        },
        "required" : [ "imsx_codeMajor","imsx_severity" ],
        "additionalProperties" : false
    },

toc | top

8. Extending and Profiling the Binding

This Section is NOT NORMATIVE.

8.1. Extending the Binding

Proprietary extensions of the service are based upon three approaches:

It is NOT permitted to change the behavior of the current set of operations. Such changes MUST be supported by the creation of new operations.

8.1.1. Proprietary Operations

The definition of new operations should follow the same format as adopted herein. The new operations should be defined using a new interface type. Every operation must result in the return of a status code that describes the final state of the request on the target end system. A new version of the OpenAPI files should also be generated with the new operation definitions.

An example of creating such an extension is given in the accompanying Implementation Guide document [OR-IMPL-12].

8.1.2. Proprietary Scopes

It is permitted to create extra OAuth 2 scopes to provide more control over the availability of various endpoints.

An example of proprietary scopes is given in the accompanying Implementation Guide document [OR-IMPL-12].

8.1.3. Proprietary Data Elements

It is recognized that implementers may wish to extend the specification. The preferred mechanism for doing this is for implementers to use an extension space within the OneRoster data model, and then set their parsers to read those extension attributes. Extensions are ONLY permitted using the 'metadata' attribute within the 'Base' class.

These extensions take the form of name/value pairs. The name is the label of the extension field, and the value is the value of the extension. For example, if wanting to show the extension of field "classification", with value "private" that was added/provided by "ims", the name/value pair is: "ims.classification" : "private".

It is RECOMMENDED that where extensions are used, whenever possible the name/value pairs are based upon vocabulary controlled files. This eliminates a proliferation of free text equivalencies from entering the data e.g. "Florida" vs "FL", vs "Florida, USA". In such cases either the attribute, or the value (or both) MUST be a URI that references the attribute and/or value from an appropriate vocabulary file. For example:

"http://www.nbrs.org" : "FL"

Within the OpenAPI files, uncontrolled data extensions are explicitly prohibited by the JSON Schema definition.

8.1.4. Proprietary Vocabulary Terms

In this version the capability to extend the 'RoleEnum' enumerated vocabulary has been added. Each proprietary term must start with the characters 'ext:'. An example is adding the two proprietary roles of 'ext:teachingasssistant' and 'ext:principal'.

It is essential that the capabilities of any new roles are clearly defined so that mapping between other proprietary roles can be established.

8.2. Profiling the Binding

This Service can be profiled. In general, Profiling is used to:

Valid Profiles must be restrictive i.e. optional features can be removed or constraints increased but new features must not be added. A Profile of this service is made by annotating the UML supplied with the documentation for the specification.

It is strongly recommended that a profile of this specification is undertaken either by, or with the close support, of 1EdTech However, no matter who is responsible for creating the profile artefacts (documents, OpenAPI files, XSDs, etc.), it is strongly recommended that the 1EdTech specification tools are used. This will ensure that the artefacts are consistent with the base specifications and that useful support documentation is automatically produced e.g. creation of a document that summarises the differences between the base specification and the profile. Organizations wishing to produce a profile of this specification should contact the 1EdTech VP of Operations at: operations@1edtech.org.

toc | top

References

[I-BAT, 06] IMS Binding Auto-generation Toolkit (I-BAT), C.Smythe, IMS Global Learning Consortium Inc., July 2006.
[ISO 8601] ISO8601:2004 Data elements and interchange formats - Information interchange - Representation of dates and times, ISO, International Standards Organization (ISO), , 2000.
[OAS, 14] OpenAPI Specification (version 2), D.Miller, J.Harmon, J.Whitlock, K.Hahn, M.Gardiner, M.Ralphson, R.Dolin, R.Ratovsky and T.Tam, OpenAPI Initiative (Linux Foundation), September 2014, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md.
[OAS, 17] D.Miller, J.Whitlock, M.Gardiner, M.Ralphson, R.Ratovsky and U.Sarid, OpenAPI Specification (version 3), OpenAPI Initiative (Linux Foundation), July 2017, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md.
[OR-CERT-12] IMS OneRoster 1.2 Conformance and Certification Final Release, M.Richards, J.McGhee and C.Smythe, IMS Global Learning Consortium Inc., June 2022, https://www.imsglobal.org/spec/oneroster/v1p2/cert.
[OR-GBK-SM-12] IMS OneRoster 1.2 Gradebook Services Final Release, M.Richards, J.McGhee and C.Smythe, IMS Global Learning Consortium Inc., June 2022, https://www.imsglobal.org/spec/oneroster/v1p2/gradebook/info.
[OR-IMPL-12] IMS OneRoster 1.2 Best Practices and Implementation Guide Final Release, M.Richards, J.McGhee and C.Smythe, IMS Global Learning Consortium Inc., June 2022, https://www.imsglobal.org/spec/oneroster/v1p2/impl.
[OR-RES-SM-12] IMS OneRoster 1.2 Resources Service Model Final Release, M.Richards, J.McGhee and C.Smythe, IMS Global Learning Consortium Inc., June 2022, https://www.imsglobal.org/spec/oneroster/v1p2/resource/info.
[OR-ROS-SM-12] IMS OneRoster 1.2 Rostering Services Final Release, M.Richards, J.McGhee and C.Smythe, IMS Global Learning Consortium Inc., June 2022, https://www.imsglobal.org/spec/oneroster/v1p2/rostering/info.
[RFC 2119] Key words for use in RFCs to Indicate Requirement Levels, S. Bradner, IETF (RFC 2119), March 1997, https://www.ietf.org/rfc/rfc3066.txt.
[RFC 2617] HTTP Authentication: Basic and Digest Access Authentication, J. Franks, P. Hallam-Baker, J. Hostetler, S. Lawrence, P. Leach, A. Luotonen and L. Stewart, IETF (RFC 2167), 1999, https://tools.ietf.org/pdf/rfc2617.pdf.
[RFC 3066] Tags for the Identification of Languages, H.Alvestrand, IETF (RFC 3066), January 2001, https://www.ietf.org/rfc/rfc3066.txt.
[RFC 5849] OAuth Version 1.0, IETF, IETF (RFC 5849), April 2010, https://tools.ietf.org/pdf/rfc5849.pdf.
[RFC 6749] The OAuth 2.0 Authorization Framework, D.Hardt, IETF (RFC 6749), 2012, https://tools.ietf.org/pdf/rfc6749.pdf.
[RFC 6750] The OAuth 2.0 Authorization Framework: Bearer Token Usage, D.Hardt, IETF (RFC 6750), 2012, https://tools.ietf.org/pdf/rfc6750.pdf.
[Security, 21] IMS Security Framework 1.1, C.Smythe, N.Mills, C.Vervoort and M.Mckell, IMS Global Learning Consortium Inc., July 2021, https://www.imsglobal.org/spec/security/v1p1/.
[UNICODE, 16] UNICODE Collation Algorithm Version 9.0, M.Davis, K.Whistler and M.Scheer, Unicode Technical Standard #10, May 2016.

toc | top

Appendix A Model Binding Terms and Concepts

This Section is NOT NORMATIVE.

A1 REST Endpoint Description Explanations

A1.1 REST Endpoint Mapping Table Explanation

Table A1.1 provides the key to the descriptions of the mapping between a service calls and its REST endpoint URL-leaf.

Table A1.1 The key to the descriptions of the mapping between a service calls and its REST endpoint URL-leaf.
Category Definition and Usage
Service Call The name of the service call as defined in the associated Behavioral Model.
REST Endpoint The REST endpoint URL leaf that is used to complete the request URL. This value must be appended to the host server (defined by the implementation) and API Root URL and version (defined in the specification).
HTTP Verb The HTTP verb that must be used for the request message. This is enumerated as: GET, PUT, POST and DELETE. The rules of mapping are:
  • GET - request to read the identified resource from the service provider;
  • PUT - request to write the supplied resource on the service provider using the given resource identifier;
  • POST - request to write the supplied resource on the service provider and the service provider must assign the unique identifier;
  • DELETE - request to delete the identified resource.

toc | top

A1.2 Query Parameter Table Explanation

Table A1.2 provides the key to the descriptions of the query parameters that are permitted for an endpoint.

Table A1.2 The key to the descriptions of the data attribute/characteristic tables.
Category Definition and Usage
Parameter Name The name given to the query parameter being described.
Data Type This is the data-type of the parameter. The data-type can take many forms:
  • Enumeration - a list of the permitted values;
  • Primitive Data-types from:-
    • AnyTypeLax - the namespace data-type i.e. defining data from any context (this is used for allowing any form of extension);
    • AnyURI - the AnyURI data-type (absolute or relative URI);
    • Base - the base data-type for defining a base URI/URL link reference;
    • Boolean - the boolean data-type (with permitted values of "true" and "false");
    • Date - the date data-type (using the [ISO 8601] format);
    • DateTime - the date/time data-type (using the [ISO 8601] format);
    • Decimal - the decimal data-type (a variable precision number that is either positive or negative);
    • Double - the double data-type (double precision floating point number - 64bit);
    • Duration - the duration data-type (using the [ISO 8601] format)
    • Empty - the associated instance must be empty;
    • Float - the float data-type (single precision floating point number - 32bit);
    • ID - the unique identifier data-type;
    • IDREF - the reference to a previously defined unique identifier data-type (ID);
    • IDREFS - a list, whitespace separated, of references to a previously defined unique identifier data-type (ID);
    • Int - the int data-type (this is derived from the "decimal" data-type);
    • Integer - the integer data-type (using the);
    • Language - the language data-type as defined in [BCP 47];
    • Namespace - the namespace data-type i.e. defining data from a context other than that as the default for the data model (this is used for importing other data models);
    • NamespaceLax - the namespace data-type i.e. defining data from a context other than that as the default for the data model (this is used for importing other data models but being lax on the validation);
    • NonNegativeInteger - the non-negative integer data-type (this is derived from the "integer" data-type) i.e. an integer that is zero or higher;
    • NCName - the NCName data-type (derived from the Name data-type);
    • NormalizedString - the normalized string data type (strings with line feeds, carriage returns and tab characters removed);
    • PositiveInteger - the positive integer data-type (this is derived from the "nonNegativeinteger" data-type) i.e. an integer that is one or higher;
    • String - the normalized string data type;
    • Time - the time data-type (using the [ISO 8601] format).
Value Space The range of valid values for this parameter (including any default value). If the value space is unspecified, it is not known or is not important. This value space must be defined in terms of the associated data-type.
Multiplicity A property of the parameter indicating the number of values that may be assigned to the parameter (this occurs as a comma separated list). The values of this property are expressed as a range or shorthand for a range using the notation:
  • "0..1" [optional; restricted]
  • "0..*" [optional; unrestricted]
  • "1" [mandatory; restricted]
  • "1..*" [mandatory; unrestricted]
Description Contains descriptions relating to the query parameter and its values space.

toc | top

A1.3 HTTP Codes and Handling for each Endpoint Table Explanation

Table A1.3 provides the key to the descriptions of the list of HTTP codes and handling for each endpoint.

Table A1.3 The key to the descriptions of the list of HTTP codes and handling for each endpoint.
Category Definition and Usage
REST Endpoint The REST endpoint URL leaf that is used to complete the request URL. This value must be appended to the host server (defined by the implementation) and API Root URL and version (defined in the specification).
HTTP Verb The HTTP verb that must be used for the request message. This is enumerated as: GET, PUT, POST and DELETE. The rules of mapping are:
  • GET - request to read the identified resource from the service provider;
  • PUT - request to write the supplied resource on the service provider using the given resource identifier;
  • POST - request to write the supplied resource on the service provider and the service provider must assign the unique identifier;
  • DELETE - request to delete the identified resource.
HTTP Codes and Handling The list of HTTP codes that may be returned by the service provider. A description of the cause of the HTTP code is supplied along with a link to the definition of the associated JSON payload structure that contains the detailed status information.

toc | top

A2 UML to JSON Mapping Description Explanations

A2.1 Service Parameter Payload Properties UML/JSON Mapping Table Definition

Table A2.1 provides the key to the descriptions of UML to JSON service parameter mapping tables.

Table A2.1 The key to the descriptions of UML to JSON service parameter mapping tables.
Feature Definition and Usage
Operation Name The name operation (this will be a list of all of the operations for the set of defined interfaces).
Parameter Name The name of the service parameter (these are the parameters listed for the operation that are not mapped to endpoint query parameters).
UML Class The name of the class, the type of the parameter, in the UML diagrams (each class will have an associated stereotype label to denote its modelling interpretation). If the information model description is contained within the same document, this value is hot-linked to that description.
JSON Name The equivalent name of the JSON parameter name in the JSON payload.
JSON Type The JSON type - this will be either "Object" or "Array of Objects".
JSON Schema Data Type The data-type in the context of the JSON Schema. This is hot-linked to the corresponding description table in the binding.

toc | top

A2.2 UML/JSON Payload Class Mapping Table Definition

Table A2.2 provides the key to the descriptions of UML to JSON payload class mapping tables. This table shows the relationship between the two modelling components:

Table A2.2 The key to the descriptions of UML to JSON payload class mapping tables.
Feature Definition and Usage
Name The name of the UML class and the associated set of attributes and characteristics. The first row is used to describe the UML class. Camel-case is used for the attribute and characteristic names.
UML Artefact The UML Class will be denoted as "Root" or "Core" depending on the nature of the class. The list of attributes (mapped to JSON properties) and characteristics (mapped to JSON properties) will be identified as either "Attributes" or "Characteristics".
Data Type The data-type has several permitted values:
  • PT:... - denotes a primitive type with "..." replaced by the actual primitiveType name
  • DT:... (PT:...) - denotes a derived type of name "..." derived from the primitive type "PT:..."
  • [Enumeration(...)] - denotes an enumeration of name "..."
  • [List(...)] - denotes a list of the name "..."
  • [Union(...)] - denotes a union of one or more data-types with the name "..."
  • [Imported(...)] - denotes a class with the name "..." has been imported from another specification
  • "Container[...]" - denotes a class of stereotype "..."
Multiplicity The multiplicity of the child attribute/characteristic. The value for the Class itself is "-N/A-". The multiplicity values are:
  • "0..1" [optional; restricted]
  • "0..*" [optional; unrestricted]
  • "1" [mandatory; restricted]
  • "1..*" [mandatory; unrestricted]
The multiplicity will also indicate when groups of elements have variable multiplicity. In the case when a selection between groups of elements is used then this is denoted by "XOR" being displayed above the multiplicity for each of the grouped elements. Alongside the XOR is the multiplicity of the group as a whole.
JSON Name This is the equivalent name of the UML artefact in the JSON.
JSON Type The JSON data-type. For the Class this will have the value "Object". For the attributes the value is either "Property" or "Array of Properties" depending on the multiplicity. For the characteristics the value is either "Properties" or "Array of Properties" depending on the multiplicity.

toc | top

A2.3 UML/JSON Enumerated and Enumerated List Class Mapping Table Definition

Table A2.3 provides the key to the descriptions of UML to JSON enumerated and enumerated list class mapping tables.

Table A2.3 The key to the descriptions of UML to JSON enumerated and enumerated list class mapping tables.
Feature Definition and Usage
Enumeration Class Name or Enumeration List Class Name The name of the enumeration class or the enumeration list class.
Description The list of permitted tokens for the enumeration or list. Each value is separated by the "|" character.

toc | top

A2.4 UML/JSON Primitive Types Mapping Table Definition

Table A2.4 provides the key to the descriptions of UML to JSON primitive-type mapping tables.

Table A2.4 The key to the descriptions of UML to JSON primitive-type mapping tables.
Feature Definition and Usage
Primitive Type Name The name of the primitve type used in the specification. Links to the definition of the primitive types, if provided elsewhere in the document, are supplied.
Description The equivalent base data type that is used in the JSON binding.

toc | top

A3 OpenAPI (v2 and v3) Descriptions Explanations

These definitions are with respect to the OpenAPI version 2 [OAS, 14] and version 3 [OAS, 17] specifications.

A3.1 OpenAPI General Information Table Explanation

Tables A3.1a and A3.1b provide the key to the OpenAPI(2) and OpenAPI(3) general information respectively.

Table A3.1a The key to the tabular description of the OpenAPI(2) general information.
Category Definition and Usage
Swagger Version The version of the OpenAPI/Swagger specification for this OpenAPI description (this must be set as 2.0).
Specification Title The title of the specification being described.
Specification Version The version of the specification being described.
Description A short, human readable description of the specification being described using OpenAPI.
Terms of Service The Terms of Service for the API.
Contact The contact information for the API. For the IMS OpenAPI released files this will be set as "Lisa Mattson (IMS COO)". When used for an implementation this should be changed to the actual contact person.
License The URL for the associated IMS License for the use of this OpenAPI description.
Host The host (name or ip) serving the API. For the IMS OpenAPI(2) released files this will be set as "www.imsglobal.org". When used for an implementation this should be changed to the actual host.
Base Path The base path that MUST be used in the endpoint URLs (this is relative to the host).
Schemes The set of transfer protocols that are supported using this API. This is a comma separated list.
Consumes A list of MIME types the APIs can consume. This is a comma separated list.
Produces A list of MIME types the APIs can produce. This is a comma separated list.

Table A3.1b The key to the tabular description of the OpenAPI(3) general information.
Category Definition and Usage
OpenAPI Version The version of the OpenAPI specification for this OpenAPI description (this must be set as 3.0.0).
Specification Title The title of the specification being described.
Specification Version The version of the specification being described.
Description A short, human readable description of the specification being described using OpenAPI.
Terms of Service The URL for the associated Terms of Service for the use of this OpenAPI description.
Contact The contact information for the API. For the IMS OpenAPI released files this will be set as "Lisa Mattson (IMS COO)". When used for an implementation this should be changed to the actual contact person.
License The URL for the associated IMS License for the use of this OpenAPI description.
Servers The host (name or ip) serving the API. For the IMS OpenAPI(3) released files this will be set as "www.imsglobal.org/{base-path}". When used for an implementation this should be changed to the actual host.

toc | top

A3.2 OpenAPI Tags Table Explanation

Table A3.2 provides the key to the tabular description of the OpenAPI tags information (versions 2 and 3).

Table A3.2 The key to the tabular description of the OpenAPI tags information.
Category Definition and Usage
Tag Name The title of the tag (this must be unique). The tags are derived from the set of Interfaces defined in the Behavioral Model.
Description A human readable description of the tag. This is the comment associated with the Interface in the Behavioral Model. The list of associated endpoints assigned to this tag are listed with links to the OpenAPI description of those endpoints.

toc | top

A3.3 OpenAPI Security Table Explanation

Table A3.3 provides the key to the tabular description of the OpenAPI security information.

Table A3.3 The key to the tabular description of the OpenAPI security information.
Category Definition and Usage
Security Label The label by which this mode is identified within the OpenAPI file.
Type The security mode supported. The permitted values are:
  • "basic" - use of basic authentication
  • "apikey" - use of an API key (in the header or as a query parameter)
  • "oauth2" - use of OAuth 2.0
Description A human readable description of the usage of this security scheme.
Flow The flow used by the OAuth2 security scheme. The permitted values in OAS2 are:
  • "implicit" - implicit grant type is used to obtain access tokens (see [RFC 6749] sub-section 4.2)
  • "password" - resource owner password credentials grant type (see [RFC 6749] sub-section 4.3)
  • "application" - client credentials grant type (see [RFC 6749] sub-section 4.4)
  • "accessCode" - authorization code grant type (see [RFC 6749] sub-section 4.1)

The permitted values in OAS3 are:
  • "clientCredentials" - client credentials grant type (see [RFC 6749] sub-section 4.4)
  • "authorizationCode" - authorization code grant type (see [RFC 6749] sub-section 4.1)
Token URL The token URL to be used for this flow. A value MUST be supplied for the "password", "application" and "accessMode" flows in OAuth 2.
Authorization URL The authorization URL to be used for this flow. A value MUST be supplied for the "accessMode" flows in OAuth 2.
Refresh URL The refresh URL to be used for this flow. A value MAY be supplied for the "accessMode" flows in OAuth 2.
Scopes The set of labels by which the global scope will be identified.
Global Scope The default identification of the security mode to be applied to an endpoint.

toc | top

A3.4 OpenAPI Paths Table Explanation

Table A3.4 provides the key to the OpenAPI paths information for an HTTP Verb.

Table A3.4 The key to the tabular description of the OpenAPI paths information for an HTTP Verb.
Category Definition and Usage
Operation ID A unique identifier for the service operation. This is the name of the operation defined in the Behavioral Model.
Summary A human readable summary of the objective of the service operation.
Tags The tag which has been assigned to this operation. The tag is determined by the Interface under which the operation is defined in the Behavioral Model.
Security and Scopes The list of security modes and scopes that MUST be used enable access to this endpoint.
Description A human readable summary of the objective of the service operation. This is derived from the associated description of the operation supplied in the Behavioral Model.
Path Placeholders The set of placeholders, and their meaning, in the URL path that will be replaced by the appropriate values in the request calls.
Query Parameters The set of query parameters that are permitted on the request calls. For each query parameter the following information is supplied:
  • Name - the name of the parameter;
  • Type - the data type for the parameter;
  • Multiplicity - the permitted multiplicity of the parameter. This takes the form of:-
    • "0..1" [optional; restricted]
    • "0..*" [optional; unrestricted] - this will normally be achieved as a comma separated list
    • "1" [mandatory; restricted]
    • "1..*" [mandatory; unrestricted] - this will normally be achieved as a comma separated list
  • Default - the default value for the parameter.
Responses The set of query responses that are permitted for the request. For each response the following information is supplied:
  • Name - the name of the response (this is either a valid HTTP code or the value "default");
  • Type - the data type for the response payload (this is linked to the corresponding OpenAPI definition). If there is no payload then this will be denoted by "N/A";
  • Description - the description of the response including any specific status code values.

toc | top

A3.5 OpenAPI Definitions Table Explanation

Table A3.5 provides the key to the OpenAPI definitions information.

Table A3.5 The key to the tabular description of the OpenAPI definitions information.
Category Definition and Usage
Annotations The definition of the complex-type as supplied in the data model definition for the associated class.
Diagram This diagram consists of two types of linked blocks. Straight link lines denote the set of unordered JSON properties. The block forms are:
  • ComplexType Block - a purple and grey shaded rectangle containing the name of the complexType and whether or not the addition of proprietary properties is permitted;
  • Property Blocks - blue and grey shaded rounded rectangles containing the name of the property, its data-type, and the multiplicity (denoted by a circle containing either the symbol "?", "1", "*" or "+" representing optional, required, optionally many or at least). Anything with a multiplicity of more than one is identified as an ARRAY[].
Type Hierachy The identification of the superclass upon which this type is based (the superclass is shown on the top line). This indicates the source of the inherited set of JSON properties (this line is only displayed when there is a type hierarchy).
Model The set of child properties. This is an ordered list of properties (as per the implied or actual sequence in the object) and accompanied by their multiplicity. In the case where the type is an enumeration or primitiveType then the value is "N/A". The value may also be "Empty" to indicate that no children are permitted. In some situations the value may be "None" denoting that there are no children defined e.g. for a base class from which other classes are derived and which may have children as part of the extension.
Source (OAS2) The equivalent JSON Schema (OpenAPI dialect) code for the declaration of the complex-type. This is the full declaration. See the corresponding OpenAPI 2 documentation [OAS, 14] for the description of the permitted contents for this declaration.
Source (OAS3) The equivalent JSON Schema (OpenAPI dialect) code for the declaration of the complex-type. This is the full declaration. See the corresponding OpenAPI 3 documentation [OAS, 17] for the description of the permitted contents for this declaration.

toc | top

Appendix B OpenAPI Listings

This Section is NORMATIVE.

B1 Listing of the OpenAPI (JSON) File

B1.1 OpenAPI 2.0 JSON Listing

The OpenAPI 2 (JSON) listing (based upon [OAS, 14]) is shown below (the OpenAPI JSON is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2resourcesservice_openapi2_v1p0.json).

{
    "swagger" : "2.0",
    "info" : {
        "version" : "1.2",
        "title" : "OneRoster Resources OpenAPI (JSON) Definition",
        "description" : "The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.",
        "termsOfService" : "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 API DEFINITION 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 IMPLEMENTERS 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 API DEFINITION.",
        "contact" : {
            "name" : "Vice President of Operations, 1EdTech",
            "url" : "https://www.1edtech.org",
            "email" : "operations@1edtech.org"
        },
        "license" : {
            "name" : "1EdTech",
            "url" : "https://www.1edtech.org/license.html"
        }
    },
    "host" : "www.1edtech.org",
    "basePath" : "/ims/oneroster/resources/v1p2",
    "schemes" : [ "http","https" ],
    "tags" : [
        {
            "name" : "ClassesManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to classes. "
        },
        {
            "name" : "CoursesManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to courses. "
        },
        {
            "name" : "ResourcesManagement",
            "description" : "This enables the management of information about resources."
        },
        {
            "name" : "UsersManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to courses. "
        }
    ],
    "securityDefinitions" : {
        "OAuth2CC" : {
            "type" : "oauth2",
            "description" : "OAuth 2 Client Credentials (as per the requirements in the IMS Security Framework) is to be used.",
            "flow" : "application",
            "tokenUrl" : "https://www.imsglobal.org",
            "scopes" : {
                "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" : "To enable access to ALL of the endpoints for the resources service.",
                "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" : "The core set of scopes to enable information about all resources or a single resource to be obtained."
            }
        }
    },
    "paths" : {
        "/classes/{classSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForClass",
                "summary" : "The REST read request message for the getResourcesForClass() API call.",
                "tags" : [ "ClassesManagement" ],
                "description" : "To read, get, the collection of resources associated to the specified class. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "classSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for this class.",
                        "required" : true,
                        "type" : "string"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 100,
                        "minimum" : 1,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 0,
                        "minimum" : 0,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "enum" : [ "asc","desc" ],
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/ResourceSetDType"
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "type" : "integer"
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        },
        "/courses/{courseSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForCourse",
                "summary" : "The REST read request message for the getResourcesForCourse() API call.",
                "tags" : [ "CoursesManagement" ],
                "description" : "To read, get, the collection of resources associated to the specified course. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "courseSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the course.",
                        "required" : true,
                        "type" : "string"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 100,
                        "minimum" : 1,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 0,
                        "minimum" : 0,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "enum" : [ "asc","desc" ],
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/ResourceSetDType"
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "type" : "integer"
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        },
        "/resources" : {
            "get" : {
                "operationId" : "getAllResources",
                "summary" : "The REST read request message for the getAllResources() API call.",
                "tags" : [ "ResourcesManagement" ],
                "description" : "To read, get, a collection of resources i.e. all resources. This is the OneRoster description of the resources and not the actual resources.",
                "parameters" : [
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 100,
                        "minimum" : 1,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 0,
                        "minimum" : 0,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "enum" : [ "asc","desc" ],
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly",
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/ResourceSetDType"
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "type" : "integer"
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        },
        "/resources/{sourcedId}" : {
            "get" : {
                "operationId" : "getResource",
                "summary" : "The REST read request message for the getResource() API call.",
                "tags" : [ "ResourcesManagement" ],
                "description" : "To read, get, a specific OneRoster resource description. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "sourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the resource.",
                        "required" : true,
                        "type" : "string"
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly",
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/SingleResourceDType"
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        },
        "/users/{userSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForUser",
                "summary" : "The REST read request message for the getResourcesForUser() API call.",
                "tags" : [ "UsersManagement" ],
                "description" : "To read, get, the collection of resources available to the specified user. This is the OneRoster description of the resources and not the actual resources. If the specified user cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "userSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the user.",
                        "required" : true,
                        "type" : "string"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 100,
                        "minimum" : 1,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 0,
                        "minimum" : 0,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "enum" : [ "asc","desc" ],
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/ResourceSetDType"
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "type" : "integer"
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        }
    },
    "definitions" : {
        "MetadataDType" : {
            "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
            "type" : "object",
            "properties" : {

            },
            "additionalProperties" : true
        },
        "ResourceDType" : {
            "description" : "A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.",
            "type" : "object",
            "properties" : {
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String. All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.",
                    "type" : "string"
                },
                "status" : {
                    "description" : "All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.",
                    "type" : "string",
                    "enum" : [ "active","tobedeleted" ]
                },
                "dateLastModified" : {
                    "description" : "Model Primitive Datatype = DateTime. All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.",
                    "type" : "string",
                    "format" : "date-time"
                },
                "metadata" : {
                    "$ref" : "#/definitions/MetadataDType"
                },
                "title" : {
                    "description" : "Model Primitive Datatype = NormalizedString. A human readable title/label for the resource.",
                    "type" : "string"
                },
                "roles" : {
                    "description" : "The set of roles, types of users, who are expected to make use of the resource.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "type" : "string"
                    }
                },
                "importance" : {
                    "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
                    "type" : "string",
                    "enum" : [ "primary","secondary" ]
                },
                "vendorResourceId" : {
                    "description" : "Model Primitive Datatype = String. This is a unique identifier for the resource allocated by the vendor.",
                    "type" : "string"
                },
                "vendorId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
                    "type" : "string"
                },
                "applicationId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
                    "type" : "string"
                }
            },
            "required" : [ "sourcedId","status","dateLastModified","vendorResourceId" ],
            "additionalProperties" : false
        },
        "ResourceSetDType" : {
            "description" : "The container for a collection of resource records. The order is not significant. This may be empty. The service provider may not have any resources or cannot identfiy any resources that fit the specified filter constraints.",
            "type" : "object",
            "properties" : {
                "resources" : {
                    "description" : "The set of contained resource identfiers.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/ResourceDType"
                    }
                }
            },
            "additionalProperties" : false
        },
        "SingleResourceDType" : {
            "description" : "The container for a single resource. This may be empty i.e. the resource has no properties that obey any of the specified selection criteria.",
            "type" : "object",
            "properties" : {
                "resource" : {
                    "$ref" : "#/definitions/ResourceDType"
                }
            },
            "required" : [ "resource" ],
            "additionalProperties" : false
        },
        "imsx_CodeMinorDType" : {
            "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorField" : {
                    "description" : "Each reported code minor status code.",
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/imsx_CodeMinorFieldDType"
                    }
                }
            },
            "required" : [ "imsx_codeMinorField" ],
            "additionalProperties" : false
        },
        "imsx_CodeMinorFieldDType" : {
            "description" : "This is the container for a single code minor status code.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorFieldName" : {
                    "description" : "Model Primitive Datatype = NormalizedString. This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.",
                    "type" : "string",
                    "default" : "TargetEndSystem"
                },
                "imsx_codeMinorFieldValue" : {
                    "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                                "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
                }
            },
            "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
            "additionalProperties" : false
        },
        "imsx_StatusInfoDType" : {
            "description" : "This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Resources service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request. See Appendix B for further information on the interpretation of the information contained within this class.",
            "type" : "object",
            "properties" : {
                "imsx_codeMajor" : {
                    "description" : "The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.",
                    "type" : "string",
                    "enum" : [ "success","processing","failure","unsupported" ]
                },
                "imsx_severity" : {
                    "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
                    "type" : "string",
                    "enum" : [ "status","warning","error" ]
                },
                "imsx_description" : {
                    "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
                    "type" : "string"
                },
                "imsx_CodeMinor" : {
                    "$ref" : "#/definitions/imsx_CodeMinorDType"
                }
            },
            "required" : [ "imsx_codeMajor","imsx_severity" ],
            "additionalProperties" : false
        }
    },
    "consumes" : [ "application/json" ],
    "produces" : [ "application/json" ]
}

B1.2 OpenAPI 3.0 JSON Listing

The OpenAPI 3 (JSON) listing (based upon [OAS, 17]) is shown below (the OpenAPI JSON is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2resourcesservice_openapi3_v1p0.json).

{
    "openapi" : "3.0.0",
    "info" : {
        "version" : "1.2",
        "title" : "OneRoster Resources OpenAPI (JSON) Definition",
        "description" : "The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.",
        "termsOfService" : "https://www.imsglobal.org/license.html",
        "contact" : {
            "name" : "Vice President of Operations, 1EdTech",
            "url" : "https://www.1edtech.org",
            "email" : "operations@1edtech.org"
        },
        "license" : {
            "name" : "1EdTech",
            "url" : "https://www.1edtech.org/license.html"
        }
    },
    "servers" : [
        {
            "url" : "https://{hostName}{basePath}",
            "description" : "The pattern for the Server URL should be configured for the actual server location.",
            "variables" : {
                "hostName" : {
                    "description" : "This is the hostname for the server and MUST be set to the actual service provider (the 1EdTech url is given as a default value).",
                    "default" : "www.1edtech.org"
                },
                "basePath" : {
                    "description" : "This is the base-path for the full URL and MUST be a part of the service endpoints.",
                    "enum" : ["/ims/oneroster/resources/v1p2"],
                    "default" : "/ims/oneroster/resources/v1p2"
                }
            }
        }
    ],
    "tags" : [
        {
            "name" : "ClassesManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to classes. "
        },
        {
            "name" : "CoursesManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to courses. "
        },
        {
            "name" : "ResourcesManagement",
            "description" : "This enables the management of information about resources."
        },
        {
            "name" : "UsersManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to courses. "
        }
    ],
    "paths" : {
        "/classes/{classSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForClass",
                "summary" : "The REST read request message for the getResourcesForClass() API call.",
                "tags" : [ "ClassesManagement" ],
                "description" : "To read, get, the collection of resources associated to the specified class. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "classSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for this class.",
                        "required" : true,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "simple"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "schema" : {
                            "type" : "integer",
                            "format" : "int32",
                            "default" : 100,
                            "minimum" : 1
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "integer",
                            "format" : "int32",
                            "default" : 0,
                            "minimum" : 0
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "schema" : {
                            "type" : "string",
                            "enum" : [ "asc","desc" ]
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "array",
                            "items" : {
                                "type" : "string"
                            }
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/ResourceSetDType"
                                }
                            }
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "schema" : {
                                    "type" : "integer"
                                }
                            }
                        },
                        "links" : {
                            "next" : {
                                "description" : "Get the next set of resources i.e. from offset to offset+limit",
                                "operationId" : "getResourcesForClass",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "last" : {
                                "description" : "Get the last set of resources i.e. from offset to end",
                                "operationId" : "getResourcesForClass",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "first" : {
                                "description" : "Get the first set of resources i.e. from first to limit",
                                "operationId" : "getResourcesForClass",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "prev" : {
                                "description" : "Get the previous set of resources i.e. from last_offset to last_offset+limit",
                                "operationId" : "getResourcesForClass",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/courses/{courseSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForCourse",
                "summary" : "The REST read request message for the getResourcesForCourse() API call.",
                "tags" : [ "CoursesManagement" ],
                "description" : "To read, get, the collection of resources associated to the specified course. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "courseSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the course.",
                        "required" : true,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "simple"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "schema" : {
                            "type" : "integer",
                            "format" : "int32",
                            "default" : 100,
                            "minimum" : 1
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "integer",
                            "format" : "int32",
                            "default" : 0,
                            "minimum" : 0
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "schema" : {
                            "type" : "string",
                            "enum" : [ "asc","desc" ]
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "array",
                            "items" : {
                                "type" : "string"
                            }
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/ResourceSetDType"
                                }
                            }
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "schema" : {
                                    "type" : "integer"
                                }
                            }
                        },
                        "links" : {
                            "next" : {
                                "description" : "Get the next set of resources i.e. from offset to offset+limit",
                                "operationId" : "getResourcesForCourse",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "last" : {
                                "description" : "Get the last set of resources i.e. from offset to end",
                                "operationId" : "getResourcesForCourse",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "first" : {
                                "description" : "Get the first set of resources i.e. from first to limit",
                                "operationId" : "getResourcesForCourse",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "prev" : {
                                "description" : "Get the previous set of resources i.e. from last_offset to last_offset+limit",
                                "operationId" : "getResourcesForCourse",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/resources" : {
            "get" : {
                "operationId" : "getAllResources",
                "summary" : "The REST read request message for the getAllResources() API call.",
                "tags" : [ "ResourcesManagement" ],
                "description" : "To read, get, a collection of resources i.e. all resources. This is the OneRoster description of the resources and not the actual resources.",
                "parameters" : [
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "schema" : {
                            "type" : "integer",
                            "format" : "int32",
                            "default" : 100,
                            "minimum" : 1
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "integer",
                            "format" : "int32",
                            "default" : 0,
                            "minimum" : 0
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "schema" : {
                            "type" : "string",
                            "enum" : [ "asc","desc" ]
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "array",
                            "items" : {
                                "type" : "string"
                            }
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly",
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/ResourceSetDType"
                                }
                            }
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "schema" : {
                                    "type" : "integer"
                                }
                            }
                        },
                        "links" : {
                            "next" : {
                                "description" : "Get the next set of resources i.e. from offset to offset+limit",
                                "operationId" : "getAllResources",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "last" : {
                                "description" : "Get the last set of resources i.e. from offset to end",
                                "operationId" : "getAllResources",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "first" : {
                                "description" : "Get the first set of resources i.e. from first to limit",
                                "operationId" : "getAllResources",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "prev" : {
                                "description" : "Get the previous set of resources i.e. from last_offset to last_offset+limit",
                                "operationId" : "getAllResources",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/resources/{sourcedId}" : {
            "get" : {
                "operationId" : "getResource",
                "summary" : "The REST read request message for the getResource() API call.",
                "tags" : [ "ResourcesManagement" ],
                "description" : "To read, get, a specific OneRoster resource description. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "sourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the resource.",
                        "required" : true,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "simple"
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "array",
                            "items" : {
                                "type" : "string"
                            }
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly",
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/SingleResourceDType"
                                }
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/users/{userSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForUser",
                "summary" : "The REST read request message for the getResourcesForUser() API call.",
                "tags" : [ "UsersManagement" ],
                "description" : "To read, get, the collection of resources available to the specified user. This is the OneRoster description of the resources and not the actual resources. If the specified user cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "userSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the user.",
                        "required" : true,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "simple"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "schema" : {
                            "type" : "integer",
                            "format" : "int32",
                            "default" : 100,
                            "minimum" : 1
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "integer",
                            "format" : "int32",
                            "default" : 0,
                            "minimum" : 0
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "schema" : {
                            "type" : "string",
                            "enum" : [ "asc","desc" ]
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "string"
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "schema" : {
                            "type" : "array",
                            "items" : {
                                "type" : "string"
                            }
                        },
                        "style" : "form",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/ResourceSetDType"
                                }
                            }
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "schema" : {
                                    "type" : "integer"
                                }
                            }
                        },
                        "links" : {
                            "next" : {
                                "description" : "Get the next set of resources i.e. from offset to offset+limit",
                                "operationId" : "getResourcesForUser",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "last" : {
                                "description" : "Get the last set of resources i.e. from offset to end",
                                "operationId" : "getResourcesForUser",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "first" : {
                                "description" : "Get the first set of resources i.e. from first to limit",
                                "operationId" : "getResourcesForUser",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            },
                            "prev" : {
                                "description" : "Get the previous set of resources i.e. from last_offset to last_offset+limit",
                                "operationId" : "getResourcesForUser",
                                "parameters" : {
                                    "limit" : "$request.path.limit",
                                    "offset" : "$request.path.offset"
                                }
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "content" : {
                            "application/json" : {
                                "schema" : {
                                    "$ref" : "#/components/schemas/imsx_StatusInfoDType"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components" : {
        "securitySchemes" : {
            "OAuth2CC" : {
                "type" : "oauth2",
                "description" : "OAuth 2 Client Credentials (as per the requirements in the IMS Security Framework) is to be used.",
                "flows" : {
                    "clientCredentials" : {
                        "tokenUrl" : "https://www.imsglobal.org",
                        "scopes" : {
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" : "To enable access to ALL of the endpoints for the resources service.",
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" : "The core set of scopes to enable information about all resources or a single resource to be obtained."
                        }
                    }
                }
            }
        },
        "schemas" : {
            "MetadataDType" : {
                "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
                "type" : "object",
                "properties" : {

                },
                "additionalProperties" : true
            },
            "ResourceDType" : {
                "description" : "A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.",
                "type" : "object",
                "properties" : {
                    "sourcedId" : {
                        "description" : "Model Primitive Datatype = String. All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.",
                        "type" : "string"
                    },
                    "status" : {
                        "description" : "All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.",
                        "type" : "string",
                        "enum" : [ "active","tobedeleted" ]
                    },
                    "dateLastModified" : {
                        "description" : "Model Primitive Datatype = DateTime. All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.",
                        "type" : "string",
                        "format" : "date-time"
                    },
                    "metadata" : {
                        "$ref" : "#/components/schemas/MetadataDType"
                    },
                    "title" : {
                        "description" : "Model Primitive Datatype = NormalizedString. A human readable title/label for the resource.",
                        "type" : "string"
                    },
                    "roles" : {
                        "description" : "The set of roles, types of users, who are expected to make use of the resource.",
                        "type" : "array",
                        "minItems" : 0,
                        "items" : {
                            "anyOf" : [
                                {
                                    "type" : "string",
                                    "enum" : [ "administrator","aide","guardian","parent","proctor","relative","student","teacher" ]
                                },
                                {
                                    "description" : "Model Primitive Datatype = NormalizedString.",
                                    "type" : "string",
                                    "pattern" : "(ext:)[a-zA-Z0-9\\.\\-_]+"
                                }
                            ]
                        }
                    },
                    "importance" : {
                        "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
                        "type" : "string",
                        "enum" : [ "primary","secondary" ]
                    },
                    "vendorResourceId" : {
                        "description" : "Model Primitive Datatype = String. This is a unique identifier for the resource allocated by the vendor.",
                        "type" : "string"
                    },
                    "vendorId" : {
                        "description" : "Model Primitive Datatype = String. Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
                        "type" : "string"
                    },
                    "applicationId" : {
                        "description" : "Model Primitive Datatype = String. Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
                        "type" : "string"
                    }
                },
                "required" : [ "sourcedId","status","dateLastModified","vendorResourceId" ],
                "additionalProperties" : false
            },
            "ResourceSetDType" : {
                "description" : "The container for a collection of resource records. The order is not significant. This may be empty. The service provider may not have any resources or cannot identfiy any resources that fit the specified filter constraints.",
                "type" : "object",
                "properties" : {
                    "resources" : {
                        "description" : "The set of contained resource identfiers.",
                        "type" : "array",
                        "minItems" : 0,
                        "items" : {
                            "$ref" : "#/components/schemas/ResourceDType"
                        }
                    }
                },
                "additionalProperties" : false
            },
            "SingleResourceDType" : {
                "description" : "The container for a single resource. This may be empty i.e. the resource has no properties that obey any of the specified selection criteria.",
                "type" : "object",
                "properties" : {
                    "resource" : {
                        "$ref" : "#/components/schemas/ResourceDType"
                    }
                },
                "required" : [ "resource" ],
                "additionalProperties" : false
            },
            "imsx_CodeMinorDType" : {
                "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
                "type" : "object",
                "properties" : {
                    "imsx_codeMinorField" : {
                        "description" : "Each reported code minor status code.",
                        "type" : "array",
                        "minItems" : 1,
                        "items" : {
                            "$ref" : "#/components/schemas/imsx_CodeMinorFieldDType"
                        }
                    }
                },
                "required" : [ "imsx_codeMinorField" ],
                "additionalProperties" : false
            },
            "imsx_CodeMinorFieldDType" : {
                "description" : "This is the container for a single code minor status code.",
                "type" : "object",
                "properties" : {
                    "imsx_codeMinorFieldName" : {
                        "description" : "Model Primitive Datatype = NormalizedString. This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.",
                        "type" : "string",
                        "default" : "TargetEndSystem"
                    },
                    "imsx_codeMinorFieldValue" : {
                        "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                        "type" : "string",
                        "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                                    "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
                    }
                },
                "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
                "additionalProperties" : false
            },
            "imsx_StatusInfoDType" : {
                "description" : "This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Resources service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request. See Appendix B for further information on the interpretation of the information contained within this class.",
                "type" : "object",
                "properties" : {
                    "imsx_codeMajor" : {
                        "description" : "The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.",
                        "type" : "string",
                        "enum" : [ "success","processing","failure","unsupported" ]
                    },
                    "imsx_severity" : {
                        "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
                        "type" : "string",
                        "enum" : [ "status","warning","error" ]
                    },
                    "imsx_description" : {
                        "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
                        "type" : "string"
                    },
                    "imsx_CodeMinor" : {
                        "$ref" : "#/components/schemas/imsx_CodeMinorDType"
                    }
                },
                "required" : [ "imsx_codeMajor","imsx_severity" ],
                "additionalProperties" : false
            }
        }
    }
}

B1.3 OpenAPI 3.1 JSON Listing

The OpenAPI 3.1 (JSON) listing (based upon [OAS, 21]) is shown below (the OpenAPI JSON is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2resourcesservice_openapi3p1_v1p0.json).

{
    "openapi" : "3.1.0",
    "info" : {
        "version" : "1.2",
        "title" : "OneRoster Resources OpenAPI (JSON) Definition",
        "description" : "The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.",
        "termsOfService" : "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 API DEFINITION 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 IMPLEMENTERS 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 API DEFINITION.",
        "contact" : {
            "name" : "Vice President of Operations, 1EdTech",
            "url" : "https://www.1edtech.org",
            "email" : "operations@1edtech.org"
        },
        "license" : {
            "name" : "1EdTech",
            "url" : "https://www.1edtech.org/license.html"
        }
    },
    "servers" : [
        {
            "url" : "https://{hostName}{basePath}",
            "description" : "The pattern for the Server URL should be configured for the actual server location.",
            "variables" : {
                "hostName" : {
                    "description" : "This is the hostname for the server and MUST be set to the actual service provider (the 1EdTech url is given as a default value).",
                    "default" : "www.1edtech.org"
                },
                "basePath" : {
                    "description" : "This is the base-path for the full URL and MUST be a part of the service endpoints.",
                    "enum" : ["/ims/oneroster/resources/v1p2"],
                    "default" : "/ims/oneroster/resources/v1p2"
                }
            }
        }
    ],
    "tags" : [
        {
            "name" : "ClassesManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to classes. "
        },
        {
            "name" : "CoursesManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to courses. "
        },
        {
            "name" : "ResourcesManagement",
            "description" : "This enables the management of information about resources."
        },
        {
            "name" : "UsersManagement",
            "description" : "This enables the management of information about resources i.e. the allocation of resources to courses. "
        }
    ],
    "paths" : {
        "/classes/{classSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForClass",
                "summary" : "The REST read request message for the getResourcesForClass() API call.",
                "tags" : [ "ClassesManagement" ],
                "description" : "To read, get, the collection of resources associated to the specified class. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "classSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for this class.",
                        "required" : true,
                        "type" : "string"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 100,
                        "minimum" : 1,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 0,
                        "minimum" : 0,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "enum" : [ "asc","desc" ],
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/ResourceSetDType"
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "type" : "integer"
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        },
        "/courses/{courseSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForCourse",
                "summary" : "The REST read request message for the getResourcesForCourse() API call.",
                "tags" : [ "CoursesManagement" ],
                "description" : "To read, get, the collection of resources associated to the specified course. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "courseSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the course.",
                        "required" : true,
                        "type" : "string"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 100,
                        "minimum" : 1,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 0,
                        "minimum" : 0,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "enum" : [ "asc","desc" ],
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/ResourceSetDType"
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "type" : "integer"
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        },
        "/resources" : {
            "get" : {
                "operationId" : "getAllResources",
                "summary" : "The REST read request message for the getAllResources() API call.",
                "tags" : [ "ResourcesManagement" ],
                "description" : "To read, get, a collection of resources i.e. all resources. This is the OneRoster description of the resources and not the actual resources.",
                "parameters" : [
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 100,
                        "minimum" : 1,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 0,
                        "minimum" : 0,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "enum" : [ "asc","desc" ],
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly",
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/ResourceSetDType"
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "type" : "integer"
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        },
        "/resources/{sourcedId}" : {
            "get" : {
                "operationId" : "getResource",
                "summary" : "The REST read request message for the getResource() API call.",
                "tags" : [ "ResourcesManagement" ],
                "description" : "To read, get, a specific OneRoster resource description. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "sourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the resource.",
                        "required" : true,
                        "type" : "string"
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly",
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/SingleResourceDType"
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        },
        "/users/{userSourcedId}/resources" : {
            "get" : {
                "operationId" : "getResourcesForUser",
                "summary" : "The REST read request message for the getResourcesForUser() API call.",
                "tags" : [ "UsersManagement" ],
                "description" : "To read, get, the collection of resources available to the specified user. This is the OneRoster description of the resources and not the actual resources. If the specified user cannot be identified within the service provider then a status code of 'unknownobject' must be reported. ",
                "parameters" : [
                    {
                        "name" : "userSourcedId",
                        "in" : "path",
                        "description" : "The unique identifier, GUID, for the user.",
                        "required" : true,
                        "type" : "string"
                    },
                    {
                        "name" : "limit",
                        "in" : "query",
                        "description" : "To define the download segmentation value i.e. the maximum number of records to be contained in the response.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 100,
                        "minimum" : 1,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "offset",
                        "in" : "query",
                        "description" : "The number of the first record to be supplied in the segmented response message.",
                        "required" : false,
                        "type" : "integer",
                        "format" : "int32",
                        "default" : 0,
                        "minimum" : 0,
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "sort",
                        "in" : "query",
                        "description" : "Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "orderBy",
                        "in" : "query",
                        "description" : "The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.",
                        "required" : false,
                        "type" : "string",
                        "enum" : [ "asc","desc" ],
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "filter",
                        "in" : "query",
                        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
                        "required" : false,
                        "type" : "string",
                        "allowEmptyValue" : false
                    },
                    {
                        "name" : "fields",
                        "in" : "query",
                        "description" : "To identify the range of fields that should be supplied in the response message.",
                        "required" : false,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "security" : [
                    {
                        "OAuth2CC" : [
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly"
                        ]
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "The requested read has been fully serviced and all of the required data returned.",
                        "schema" : {
                            "$ref" : "#/definitions/ResourceSetDType"
                        },
                        "headers" : {
                            "X-Total-Count" : {
                                "description" : "The total number of resources that are available to be returned",
                                "type" : "integer"
                            }
                        }
                    },
                    "400" : {
                        "description" : "Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "403" : {
                        "description" : "This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "404" : {
                        "description" : "Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "422" : {
                        "description" : "This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "429" : {
                        "description" : "The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "500" : {
                        "description" : "This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    },
                    "default" : {
                        "description" : "This is the default payload when none of the other HTTP codes are to be supplied.",
                        "schema" : {
                            "$ref" : "#/definitions/imsx_StatusInfoDType"
                        }
                    }
                }
            }
        }
    },
    "components" : {
        "securitySchemes" : {
            "OAuth2CC" : {
                "type" : "oauth2",
                "description" : "OAuth 2 Client Credentials (as per the requirements in the IMS Security Framework) is to be used.",
                "flows" : {
                    "clientCredentials" : {
                        "tokenUrl" : "https://www.imsglobal.org",
                        "scopes" : {
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" : "To enable access to ALL of the endpoints for the resources service.",
                            "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" : "The core set of scopes to enable information about all resources or a single resource to be obtained."
                        }
                    }
                }
            }
        },
        "schemas" : {
            "MetadataDType" : {
                "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
                "type" : "object",
                "properties" : {

                },
                "additionalProperties" : true
            },
            "ResourceDType" : {
                "description" : "A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.",
                "type" : "object",
                "properties" : {
                    "sourcedId" : {
                        "description" : "Model Primitive Datatype = String. All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.",
                        "type" : "string"
                    },
                    "status" : {
                        "description" : "All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.",
                        "type" : "string",
                        "enum" : [ "active","tobedeleted" ]
                    },
                    "dateLastModified" : {
                        "description" : "Model Primitive Datatype = DateTime. All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.",
                        "type" : "string",
                        "format" : "date-time"
                    },
                    "metadata" : {
                        "$ref" : "#/definitions/MetadataDType"
                    },
                    "title" : {
                        "description" : "Model Primitive Datatype = NormalizedString. A human readable title/label for the resource.",
                        "type" : "string"
                    },
                    "roles" : {
                        "description" : "The set of roles, types of users, who are expected to make use of the resource.",
                        "type" : "array",
                        "minItems" : 0,
                        "items" : {
                            "type" : "string"
                        }
                    },
                    "importance" : {
                        "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
                        "type" : "string",
                        "enum" : [ "primary","secondary" ]
                    },
                    "vendorResourceId" : {
                        "description" : "Model Primitive Datatype = String. This is a unique identifier for the resource allocated by the vendor.",
                        "type" : "string"
                    },
                    "vendorId" : {
                        "description" : "Model Primitive Datatype = String. Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
                        "type" : "string"
                    },
                    "applicationId" : {
                        "description" : "Model Primitive Datatype = String. Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
                        "type" : "string"
                    }
                },
                "required" : [ "sourcedId","status","dateLastModified","vendorResourceId" ],
                "additionalProperties" : false
            },
            "ResourceSetDType" : {
                "description" : "The container for a collection of resource records. The order is not significant. This may be empty. The service provider may not have any resources or cannot identfiy any resources that fit the specified filter constraints.",
                "type" : "object",
                "properties" : {
                    "resources" : {
                        "description" : "The set of contained resource identfiers.",
                        "type" : "array",
                        "minItems" : 0,
                        "items" : {
                            "$ref" : "#/definitions/ResourceDType"
                        }
                    }
                },
                "additionalProperties" : false
            },
            "SingleResourceDType" : {
                "description" : "The container for a single resource. This may be empty i.e. the resource has no properties that obey any of the specified selection criteria.",
                "type" : "object",
                "properties" : {
                    "resource" : {
                        "$ref" : "#/definitions/ResourceDType"
                    }
                },
                "required" : [ "resource" ],
                "additionalProperties" : false
            },
            "imsx_CodeMinorDType" : {
                "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
                "type" : "object",
                "properties" : {
                    "imsx_codeMinorField" : {
                        "description" : "Each reported code minor status code.",
                        "type" : "array",
                        "minItems" : 1,
                        "items" : {
                            "$ref" : "#/definitions/imsx_CodeMinorFieldDType"
                        }
                    }
                },
                "required" : [ "imsx_codeMinorField" ],
                "additionalProperties" : false
            },
            "imsx_CodeMinorFieldDType" : {
                "description" : "This is the container for a single code minor status code.",
                "type" : "object",
                "properties" : {
                    "imsx_codeMinorFieldName" : {
                        "description" : "Model Primitive Datatype = NormalizedString. This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.",
                        "type" : "string",
                        "default" : "TargetEndSystem"
                    },
                    "imsx_codeMinorFieldValue" : {
                        "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                        "type" : "string",
                        "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                                    "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
                    }
                },
                "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
                "additionalProperties" : false
            },
            "imsx_StatusInfoDType" : {
                "description" : "This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Resources service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request. See Appendix B for further information on the interpretation of the information contained within this class.",
                "type" : "object",
                "properties" : {
                    "imsx_codeMajor" : {
                        "description" : "The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.",
                        "type" : "string",
                        "enum" : [ "success","processing","failure","unsupported" ]
                    },
                    "imsx_severity" : {
                        "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
                        "type" : "string",
                        "enum" : [ "status","warning","error" ]
                    },
                    "imsx_description" : {
                        "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
                        "type" : "string"
                    },
                    "imsx_CodeMinor" : {
                        "$ref" : "#/definitions/imsx_CodeMinorDType"
                    }
                },
                "required" : [ "imsx_codeMajor","imsx_severity" ],
                "additionalProperties" : false
            }
        }
    }
}

B2 Listing of the OpenAPI (YAML) File

B2.1 OpenAPI 2.0 YAML Listing

The OpenAPI 2 (YAML) listing (based upon [OAS, 14]) is shown below (the OpenAPI YAML is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2resourcesservice_openapi2_v1p0.yaml).

# #####################################################################################
# YAML File Information
# #####################################################################################
# 
# Author:         Colin Smythe (1EdTech)
# Date:           19th September, 2022
# Version:        1.0
# Status:         IMS Final Release
# Description:    The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.
# 
# History:        Version 1.2: This is the first release of the OneRoster 1.2 Resources service binding in REST/JSON and OpenAPI.
# 
# License:        IPR and Distribution Notices
# 
#                 This machine readable file is derived from the IMS OneRoster Resources Version 1.2
#                 found at http://www.imsglobal.org/lis and the original IMS Global schema binding or code base
#                 http://www.imsglobal.org/lis.
# 
#                 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 procedures with respect to rights in IMS 
#                 specifications can be found at the IMS Global Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.
# 
#                 Copyright (c) IMS Global Learning Consortium 1999-2022. All Rights Reserved.
# 
#                 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/license.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 IMPLEMENTERS 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.
# 
# Source UML File Information
# ===========================
# The source file information must be supplied as an XMI file (without diagram layout information).
# The supported UML authoring tools are:
# (a) Poseidon - v6 (and later)
# (b) Papyrus - v1.1.3 (and later)
# 
# Source XSLT File Information
# ============================
# XSL Generator:    Specificationv1p0_GenerationToolv1.xsl
# XSLT Processor:   Saxon
# Release:          1.0
# Date:             31st January, 2021
# Autogen Engineer: Colin Smythe (IMS Global, UK)
# Autogen Date:     2022-09-13
# 
# IMS Global Auto-generation Binding Tool-kit (I-BAT)
# ===================================================
# This file was auto-generated using the IMS Global Binding Auto-generation Tool-kit (I-BAT).  While every
# attempt has been made to ensure that this tool auto-generates the files correctly, users should be aware
# that this is an experimental tool.  Permission is given to make use of this tool.  IMS Global makes no
# claim on the materials created by third party users of this tool.  Details on how to use this tool
# are contained in the IMS Global "I-BAT" documentation available at the IMS Global web-site:
# http://www.imsglobal.org.
# 
# Tool Copyright:  2012-2022  (c) IMS Global Learning Consortium Inc.  All Rights Reserved.
# 
# #####################################################################################

swagger: '2.0'

#####################################################################################
#                               API Information                                     #
#####################################################################################
info: 
    version: '1.2'
    title: OneRoster Resources OpenAPI (YAML) Definition
    description: The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.
    termsOfService: 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 API DEFINITION 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 IMPLEMENTERS 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 API DEFINITION.
    contact: 
        name: Vice President of Operations, 1EdTech
        url: https://www.1edtech.org
        email: operations@1edtech.org
    license: 
        name: 1EdTech Consortium
        url: https://www.1edtech.org/license.html

#####################################################################################
#                   Host, Base Path, Schemes and Content Types                      #
#####################################################################################
host: www.1edtech.org
basePath: /ims/oneroster/resources/v1p2
schemes: 
    - http
    - https
consumes: 
    - application/json
produces: 
    - application/json

#####################################################################################
#                                  Tags                                             #
#####################################################################################
tags: 
    - name: ClassesManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to classes. 
    - name: CoursesManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to courses. 
    - name: ResourcesManagement
      description: |
        This enables the management of information about resources.
    - name: UsersManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to courses. 

#####################################################################################
#                                 Security                                          #
#####################################################################################
securityDefinitions:
    OAuth2CC:
        type: oauth2
        description: OAuth 2 Client Credentials (as per the requirements in the IMS Security Framework) is to be used.
        flow: application
        tokenUrl: https://www.imsglobal.org
        scopes: 
            https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly: To enable access to ALL of the endpoints for the resources service.
            https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly: The core set of scopes to enable information about all resources or a single resource to be obtained.


#####################################################################################
#                                   Paths                                           #
#####################################################################################
paths: 
    /classes/{classSourcedId}/resources:
        get:
            operationId: getResourcesForClass
            summary: The REST read request message for the getResourcesForClass() API call.
            tags: 
                - ClassesManagement
            description: |
                To read, get, the collection of resources associated to the specified class. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: classSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for this class.
                  required: true
                  type: string
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 100
                  minimum: 1
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 0
                  minimum: 0
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  enum: 
                    - asc
                    - desc
                  allowEmptyValue: false
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            type: integer
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"

    /courses/{courseSourcedId}/resources:
        get:
            operationId: getResourcesForCourse
            summary: The REST read request message for the getResourcesForCourse() API call.
            tags: 
                - CoursesManagement
            description: |
                To read, get, the collection of resources associated to the specified course. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: courseSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the course.
                  required: true
                  type: string
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 100
                  minimum: 1
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 0
                  minimum: 0
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  enum: 
                    - asc
                    - desc
                  allowEmptyValue: false
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            type: integer
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"

    /resources:
        get:
            operationId: getAllResources
            summary: The REST read request message for the getAllResources() API call.
            tags: 
                - ResourcesManagement
            description: |
                To read, get, a collection of resources i.e. all resources. This is the OneRoster description of the resources and not the actual resources.
            parameters: 
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 100
                  minimum: 1
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 0
                  minimum: 0
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  enum: 
                    - asc
                    - desc
                  allowEmptyValue: false
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            type: integer
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"

    /resources/{sourcedId}:
        get:
            operationId: getResource
            summary: The REST read request message for the getResource() API call.
            tags: 
                - ResourcesManagement
            description: |
                To read, get, a specific OneRoster resource description. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: sourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the resource.
                  required: true
                  type: string
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/SingleResourceDType"
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"

    /users/{userSourcedId}/resources:
        get:
            operationId: getResourcesForUser
            summary: The REST read request message for the getResourcesForUser() API call.
            tags: 
                - UsersManagement
            description: |
                To read, get, the collection of resources available to the specified user. This is the OneRoster description of the resources and not the actual resources. If the specified user cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: userSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the user.
                  required: true
                  type: string
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 100
                  minimum: 1
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 0
                  minimum: 0
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  enum: 
                    - asc
                    - desc
                  allowEmptyValue: false
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            type: integer
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"


#####################################################################################
#                               Definitions                                         #
#####################################################################################
definitions: 
    MetadataDType:
        description: |
            This is the container for the data model extensions that may be assigned to the associated class of objects.
        type: object
        properties: {}
        additionalProperties: true
    ResourceDType:
        description: |
            A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.
        type: object
        required: 
            - sourcedId
            - status
            - dateLastModified
            - vendorResourceId
        properties: 
            sourcedId: 
                description: All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record. Model Primitive Datatype = String.
                type: string
            status: 
                description: |
                    All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
                type: string
                enum: 
                   - active
                   - tobedeleted
            dateLastModified: 
                description: All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone. Model Primitive Datatype = DateTime.
                type: string
                format: date-time
            metadata: 
                $ref: "#/definitions/MetadataDType"
            title: 
                description: A human readable title/label for the resource. Model Primitive Datatype = NormalizedString.
                type: string
            roles: 
                description: |
                    The set of roles, types of users, who are expected to make use of the resource.
                type: array
                minItems: 0
                items: 
                    type: string
            importance: 
                description: |
                    This is an indicator of the significance of the resource i.e. primary or secondary.
                type: string
                enum: 
                   - primary
                   - secondary
            vendorResourceId: 
                description: This is a unique identifier for the resource allocated by the vendor. Model Primitive Datatype = String.
                type: string
            vendorId: 
                description: Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification. Model Primitive Datatype = String.
                type: string
            applicationId: 
                description: Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification. Model Primitive Datatype = String.
                type: string
        additionalProperties: false
    ResourceSetDType:
        description: |
            The container for a collection of resource records. The order is not significant. This may be empty. The service provider may not have any resources or cannot identfiy any resources that fit the specified filter constraints.
        type: object
        properties: 
            resources: 
                description: |
                    The set of contained resource identfiers.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/ResourceDType"
        additionalProperties: false
    SingleResourceDType:
        description: |
            The container for a single resource. This may be empty i.e. the resource has no properties that obey any of the specified selection criteria.
        type: object
        required: 
            - resource
        properties: 
            resource: 
                $ref: "#/definitions/ResourceDType"
        additionalProperties: false
    imsx_CodeMinorDType:
        description: |
            This is the container for the set of code minor status codes reported in the responses from the Service Provider.
        type: object
        required: 
            - imsx_codeMinorField
        properties: 
            imsx_codeMinorField: 
                description: |
                    Each reported code minor status code.
                type: array
                minItems: 1
                items: 
                    $ref: "#/definitions/imsx_CodeMinorFieldDType"
        additionalProperties: false
    imsx_CodeMinorFieldDType:
        description: |
            This is the container for a single code minor status code.
        type: object
        required: 
            - imsx_codeMinorFieldName
            - imsx_codeMinorFieldValue
        properties: 
            imsx_codeMinorFieldName: 
                description: This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'. Model Primitive Datatype = NormalizedString.
                type: string
                default: TargetEndSystem
            imsx_codeMinorFieldValue: 
                description: |
                    The code minor status code (this is a value from the corresponding enumerated vocabulary).
                type: string
                enum: 
                   - fullsuccess
                   - invalid_filter_field
                   - invalid_selection_field
                   - forbidden
                   - unauthorisedrequest
                   - internal_server_error
                   - server_busy
                   - unknownobject
                   - invaliddata
                   - invalid_sort_field
                   - unsupported
        additionalProperties: false
    imsx_StatusInfoDType:
        description: |
            This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Resources service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request. See Appendix B for further information on the interpretation of the information contained within this class.
        type: object
        required: 
            - imsx_codeMajor
            - imsx_severity
        properties: 
            imsx_codeMajor: 
                description: |
                    The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
                type: string
                enum: 
                   - success
                   - processing
                   - failure
                   - unsupported
            imsx_severity: 
                description: |
                    The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
                type: string
                enum: 
                   - status
                   - warning
                   - error
            imsx_description: 
                description: A human readable description supplied by the entity creating the status code information. Model Primitive Datatype = String.
                type: string
            imsx_CodeMinor: 
                $ref: "#/definitions/imsx_CodeMinorDType"
        additionalProperties: false

B2.2 OpenAPI 3.0 YAML Listing

The OpenAPI 3 (YAML) listing (based upon [OAS, 17]) is shown below (the OpenAPI YAML is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2resourcesservice_openapi3_v1p0.yaml).

# #####################################################################################
# YAML File Information
# #####################################################################################
# 
# Author:         Colin Smythe (1EdTech)
# Date:           19th September, 2022
# Version:        1.0
# Status:         IMS Final Release
# Description:    The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.
# 
# History:        Version 1.2: This is the first release of the OneRoster 1.2 Resources service binding in REST/JSON and OpenAPI.
# 
# License:        IPR and Distribution Notices
# 
#                 This machine readable file is derived from the IMS OneRoster Resources Version 1.2
#                 found at http://www.imsglobal.org/lis and the original IMS Global schema binding or code base
#                 http://www.imsglobal.org/lis.
# 
#                 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 procedures with respect to rights in IMS 
#                 specifications can be found at the IMS Global Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.
# 
#                 Copyright (c) IMS Global Learning Consortium 1999-2022. All Rights Reserved.
# 
#                 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/license.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 IMPLEMENTERS 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.
# 
# Source UML File Information
# ===========================
# The source file information must be supplied as an XMI file (without diagram layout information).
# The supported UML authoring tools are:
# (a) Poseidon - v6 (and later)
# (b) Papyrus - v1.1.3 (and later)
# 
# Source XSLT File Information
# ============================
# XSL Generator:    Specificationv1p0_GenerationToolv1.xsl
# XSLT Processor:   Saxon
# Release:          1.0
# Date:             31st January, 2021
# Autogen Engineer: Colin Smythe (IMS Global, UK)
# Autogen Date:     2022-09-13
# 
# IMS Global Auto-generation Binding Tool-kit (I-BAT)
# ===================================================
# This file was auto-generated using the IMS Global Binding Auto-generation Tool-kit (I-BAT).  While every
# attempt has been made to ensure that this tool auto-generates the files correctly, users should be aware
# that this is an experimental tool.  Permission is given to make use of this tool.  IMS Global makes no
# claim on the materials created by third party users of this tool.  Details on how to use this tool
# are contained in the IMS Global "I-BAT" documentation available at the IMS Global web-site:
# http://www.imsglobal.org.
# 
# Tool Copyright:  2012-2022  (c) IMS Global Learning Consortium Inc.  All Rights Reserved.
# 
# #####################################################################################

openapi: '3.0.0'

#####################################################################################
#                               API Information                                     #
#####################################################################################
info: 
    version: '1.2'
    title: OneRoster Resources OpenAPI (YAML) Definition
    description: The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.
    termsOfService: https://www.imsglobal.org/license.html
    contact: 
        name: Vice President of Operations, 1EdTech
        url: https://www.1edtech.org
        email: operations@1edtech.org
    license: 
        name: 1EdTech Consortium
        url: https://www.1edtech.org/license.html

#####################################################################################
#                                 Servers                                           #
#####################################################################################
servers: 
    - url: https://{hostName}{basePath}
      description: The pattern for the Server URL should be configured for the actual server location.
      variables: 
          "hostName": 
              description: This is the hostname for the server and MUST be set to the actual service provider (the 1EdTech url is given as a default value).
              default: www.1edtech.org
          "basePath": 
              description: This is the base-path for the full URL and MUST be a part of the service endpoints.
              enum: 
                - /ims/oneroster/resources/v1p2
              default: /ims/oneroster/resources/v1p2

#####################################################################################
#                                  Tags                                             #
#####################################################################################
tags: 
    - name: ClassesManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to classes. 
    - name: CoursesManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to courses. 
    - name: ResourcesManagement
      description: |
        This enables the management of information about resources.
    - name: UsersManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to courses. 

#####################################################################################
#                                   Paths                                           #
#####################################################################################
paths: 
    /classes/{classSourcedId}/resources:
        get:
            operationId: getResourcesForClass
            summary: The REST read request message for the getResourcesForClass() API call.
            tags: 
                - ClassesManagement
            description: |
                To read, get, the collection of resources associated to the specified class. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: classSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for this class.
                  required: true
                  schema: 
                      type: string
                  style: simple
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  schema: 
                      type: integer
                      format: int32
                      default: 100
                      minimum: 1
                  allowEmptyValue: false
                  style: form
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  schema: 
                      type: integer
                      format: int32
                      default: 0
                      minimum: 0
                  allowEmptyValue: false
                  style: form
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  schema: 
                      type: string
                  allowEmptyValue: false
                  style: form
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  schema: 
                      type: string
                      enum: 
                        - asc
                        - desc
                  allowEmptyValue: false
                  style: form
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  schema: 
                      type: string
                  allowEmptyValue: false
                  style: form
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  schema: 
                      type: array
                      items: 
                          type: string
                  allowEmptyValue: false
                  style: form
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            schema: 
                                type: integer
                    links: 
                        "next" :
                            description: |
                                Get the next set of resources i.e. from offset to offset+limit
                            operationId: getResourcesForClass
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "last" :
                            description: |
                                Get the last set of resources i.e. from offset to end
                            operationId: getResourcesForClass
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "first" :
                            description: |
                                Get the first set of resources i.e. from first to limit
                            operationId: getResourcesForClass
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "prev" :
                            description: |
                                Get the previous set of resources i.e. from last_offset to last_offset+limit
                            operationId: getResourcesForClass
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"

    /courses/{courseSourcedId}/resources:
        get:
            operationId: getResourcesForCourse
            summary: The REST read request message for the getResourcesForCourse() API call.
            tags: 
                - CoursesManagement
            description: |
                To read, get, the collection of resources associated to the specified course. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: courseSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the course.
                  required: true
                  schema: 
                      type: string
                  style: simple
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  schema: 
                      type: integer
                      format: int32
                      default: 100
                      minimum: 1
                  allowEmptyValue: false
                  style: form
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  schema: 
                      type: integer
                      format: int32
                      default: 0
                      minimum: 0
                  allowEmptyValue: false
                  style: form
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  schema: 
                      type: string
                  allowEmptyValue: false
                  style: form
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  schema: 
                      type: string
                      enum: 
                        - asc
                        - desc
                  allowEmptyValue: false
                  style: form
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  schema: 
                      type: string
                  allowEmptyValue: false
                  style: form
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  schema: 
                      type: array
                      items: 
                          type: string
                  allowEmptyValue: false
                  style: form
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            schema: 
                                type: integer
                    links: 
                        "next" :
                            description: |
                                Get the next set of resources i.e. from offset to offset+limit
                            operationId: getResourcesForCourse
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "last" :
                            description: |
                                Get the last set of resources i.e. from offset to end
                            operationId: getResourcesForCourse
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "first" :
                            description: |
                                Get the first set of resources i.e. from first to limit
                            operationId: getResourcesForCourse
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "prev" :
                            description: |
                                Get the previous set of resources i.e. from last_offset to last_offset+limit
                            operationId: getResourcesForCourse
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"

    /resources:
        get:
            operationId: getAllResources
            summary: The REST read request message for the getAllResources() API call.
            tags: 
                - ResourcesManagement
            description: |
                To read, get, a collection of resources i.e. all resources. This is the OneRoster description of the resources and not the actual resources.
            parameters: 
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  schema: 
                      type: integer
                      format: int32
                      default: 100
                      minimum: 1
                  allowEmptyValue: false
                  style: form
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  schema: 
                      type: integer
                      format: int32
                      default: 0
                      minimum: 0
                  allowEmptyValue: false
                  style: form
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  schema: 
                      type: string
                  allowEmptyValue: false
                  style: form
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  schema: 
                      type: string
                      enum: 
                        - asc
                        - desc
                  allowEmptyValue: false
                  style: form
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  schema: 
                      type: string
                  allowEmptyValue: false
                  style: form
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  schema: 
                      type: array
                      items: 
                          type: string
                  allowEmptyValue: false
                  style: form
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            schema: 
                                type: integer
                    links: 
                        "next" :
                            description: |
                                Get the next set of resources i.e. from offset to offset+limit
                            operationId: getAllResources
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "last" :
                            description: |
                                Get the last set of resources i.e. from offset to end
                            operationId: getAllResources
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "first" :
                            description: |
                                Get the first set of resources i.e. from first to limit
                            operationId: getAllResources
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "prev" :
                            description: |
                                Get the previous set of resources i.e. from last_offset to last_offset+limit
                            operationId: getAllResources
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"

    /resources/{sourcedId}:
        get:
            operationId: getResource
            summary: The REST read request message for the getResource() API call.
            tags: 
                - ResourcesManagement
            description: |
                To read, get, a specific OneRoster resource description. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: sourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the resource.
                  required: true
                  schema: 
                      type: string
                  style: simple
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  schema: 
                      type: array
                      items: 
                          type: string
                  allowEmptyValue: false
                  style: form
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/SingleResourceDType"
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"

    /users/{userSourcedId}/resources:
        get:
            operationId: getResourcesForUser
            summary: The REST read request message for the getResourcesForUser() API call.
            tags: 
                - UsersManagement
            description: |
                To read, get, the collection of resources available to the specified user. This is the OneRoster description of the resources and not the actual resources. If the specified user cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: userSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the user.
                  required: true
                  schema: 
                      type: string
                  style: simple
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  schema: 
                      type: integer
                      format: int32
                      default: 100
                      minimum: 1
                  allowEmptyValue: false
                  style: form
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  schema: 
                      type: integer
                      format: int32
                      default: 0
                      minimum: 0
                  allowEmptyValue: false
                  style: form
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  schema: 
                      type: string
                  allowEmptyValue: false
                  style: form
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  schema: 
                      type: string
                      enum: 
                        - asc
                        - desc
                  allowEmptyValue: false
                  style: form
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  schema: 
                      type: string
                  allowEmptyValue: false
                  style: form
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  schema: 
                      type: array
                      items: 
                          type: string
                  allowEmptyValue: false
                  style: form
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            schema: 
                                type: integer
                    links: 
                        "next" :
                            description: |
                                Get the next set of resources i.e. from offset to offset+limit
                            operationId: getResourcesForUser
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "last" :
                            description: |
                                Get the last set of resources i.e. from offset to end
                            operationId: getResourcesForUser
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "first" :
                            description: |
                                Get the first set of resources i.e. from first to limit
                            operationId: getResourcesForUser
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                        "prev" :
                            description: |
                                Get the previous set of resources i.e. from last_offset to last_offset+limit
                            operationId: getResourcesForUser
                            parameters: 
                                "limit" : "$request.path.limit"
                                "offset" : "$request.path.offset"
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    content: 
                        application/json: 
                            schema: 
                                $ref: "#/components/schemas/imsx_StatusInfoDType"


#####################################################################################
#                               Components                                          #
#####################################################################################
components:
    securitySchemes:
        OAuth2CC:
            type: oauth2
            description: |
                OAuth 2 Client Credentials (as per the requirements in the IMS Security Framework) is to be used.
            flows:
                clientCredentials:
                    tokenUrl: https://www.imsglobal.org
                    scopes: 
                        https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly: To enable access to ALL of the endpoints for the resources service.
                        https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly: The core set of scopes to enable information about all resources or a single resource to be obtained.
    schemas: 
        MetadataDType:
            description: |
                This is the container for the data model extensions that may be assigned to the associated class of objects.
            type: object
            properties: {}
            additionalProperties: true
        ResourceDType:
            description: |
                A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.
            type: object
            required: 
                - sourcedId
                - status
                - dateLastModified
                - vendorResourceId
            properties: 
                sourcedId: 
                    description: All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record. Model Primitive Datatype = String.
                    type: string
                status: 
                    description: |
                        All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
                    type: string
                    enum: 
                       - active
                       - tobedeleted
                dateLastModified: 
                    description: All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone. Model Primitive Datatype = DateTime.
                    type: string
                    format: date-time
                metadata: 
                    $ref: "#/components/schemas/MetadataDType"
                title: 
                    description: A human readable title/label for the resource. Model Primitive Datatype = NormalizedString.
                    type: string
                roles: 
                    description: |
                        The set of roles, types of users, who are expected to make use of the resource.
                    type: array
                    minItems: 0
                    items: 
                        anyOf: 
                            - enum: 
                                - administrator
                                - aide
                                - guardian
                                - parent
                                - proctor
                                - relative
                                - student
                                - teacher
                              type: string
                            - description: The data-type that enables the 'RoleEnum' vocabulary to be extended. Model Primitive Datatype = NormalizedString.
                              type: string
                              pattern: "(ext:)[a-zA-Z0-9\\.\\-_]+"
                importance: 
                    description: |
                        This is an indicator of the significance of the resource i.e. primary or secondary.
                    type: string
                    enum: 
                       - primary
                       - secondary
                vendorResourceId: 
                    description: This is a unique identifier for the resource allocated by the vendor. Model Primitive Datatype = String.
                    type: string
                vendorId: 
                    description: Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification. Model Primitive Datatype = String.
                    type: string
                applicationId: 
                    description: Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification. Model Primitive Datatype = String.
                    type: string
            additionalProperties: false
        ResourceSetDType:
            description: |
                The container for a collection of resource records. The order is not significant. This may be empty. The service provider may not have any resources or cannot identfiy any resources that fit the specified filter constraints.
            type: object
            properties: 
                resources: 
                    description: |
                        The set of contained resource identfiers.
                    type: array
                    minItems: 0
                    items: 
                        $ref: "#/components/schemas/ResourceDType"
            additionalProperties: false
        SingleResourceDType:
            description: |
                The container for a single resource. This may be empty i.e. the resource has no properties that obey any of the specified selection criteria.
            type: object
            required: 
                - resource
            properties: 
                resource: 
                    $ref: "#/components/schemas/ResourceDType"
            additionalProperties: false
        imsx_CodeMinorDType:
            description: |
                This is the container for the set of code minor status codes reported in the responses from the Service Provider.
            type: object
            required: 
                - imsx_codeMinorField
            properties: 
                imsx_codeMinorField: 
                    description: |
                        Each reported code minor status code.
                    type: array
                    minItems: 1
                    items: 
                        $ref: "#/components/schemas/imsx_CodeMinorFieldDType"
            additionalProperties: false
        imsx_CodeMinorFieldDType:
            description: |
                This is the container for a single code minor status code.
            type: object
            required: 
                - imsx_codeMinorFieldName
                - imsx_codeMinorFieldValue
            properties: 
                imsx_codeMinorFieldName: 
                    description: This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'. Model Primitive Datatype = NormalizedString.
                    type: string
                    default: TargetEndSystem
                imsx_codeMinorFieldValue: 
                    description: |
                        The code minor status code (this is a value from the corresponding enumerated vocabulary).
                    type: string
                    enum: 
                       - fullsuccess
                       - invalid_filter_field
                       - invalid_selection_field
                       - forbidden
                       - unauthorisedrequest
                       - internal_server_error
                       - server_busy
                       - unknownobject
                       - invaliddata
                       - invalid_sort_field
                       - unsupported
            additionalProperties: false
        imsx_StatusInfoDType:
            description: |
                This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Resources service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request. See Appendix B for further information on the interpretation of the information contained within this class.
            type: object
            required: 
                - imsx_codeMajor
                - imsx_severity
            properties: 
                imsx_codeMajor: 
                    description: |
                        The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
                    type: string
                    enum: 
                       - success
                       - processing
                       - failure
                       - unsupported
                imsx_severity: 
                    description: |
                        The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
                    type: string
                    enum: 
                       - status
                       - warning
                       - error
                imsx_description: 
                    description: A human readable description supplied by the entity creating the status code information. Model Primitive Datatype = String.
                    type: string
                imsx_CodeMinor: 
                    $ref: "#/components/schemas/imsx_CodeMinorDType"
            additionalProperties: false

B2.3 OpenAPI 3.1 YAML Listing

The OpenAPI 3.1 (YAML) listing (based upon [OAS, 21]) is shown below (the OpenAPI YAML is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/onerosterv1p2resourcesservice_openapi3p1_v1p0.yaml).

# #####################################################################################
# YAML File Information
# #####################################################################################
# 
# Author:         Colin Smythe (1EdTech)
# Date:           19th September, 2022
# Version:        1.0
# Status:         IMS Final Release
# Description:    The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.
# 
# History:        Version 1.2: This is the first release of the OneRoster 1.2 Resources service binding in REST/JSON and OpenAPI.
# 
# License:        IPR and Distribution Notices
# 
#                 This machine readable file is derived from the IMS OneRoster Resources Version 1.2
#                 found at http://www.imsglobal.org/lis and the original IMS Global schema binding or code base
#                 http://www.imsglobal.org/lis.
# 
#                 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 procedures with respect to rights in IMS 
#                 specifications can be found at the IMS Global Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.
# 
#                 Copyright (c) IMS Global Learning Consortium 1999-2022. All Rights Reserved.
# 
#                 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/license.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 IMPLEMENTERS 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.
# 
# Source UML File Information
# ===========================
# The source file information must be supplied as an XMI file (without diagram layout information).
# The supported UML authoring tools are:
# (a) Poseidon - v6 (and later)
# (b) Papyrus - v1.1.3 (and later)
# 
# Source XSLT File Information
# ============================
# XSL Generator:    Specificationv1p0_GenerationToolv1.xsl
# XSLT Processor:   Saxon
# Release:          1.0
# Date:             31st January, 2021
# Autogen Engineer: Colin Smythe (IMS Global, UK)
# Autogen Date:     2022-09-13
# 
# IMS Global Auto-generation Binding Tool-kit (I-BAT)
# ===================================================
# This file was auto-generated using the IMS Global Binding Auto-generation Tool-kit (I-BAT).  While every
# attempt has been made to ensure that this tool auto-generates the files correctly, users should be aware
# that this is an experimental tool.  Permission is given to make use of this tool.  IMS Global makes no
# claim on the materials created by third party users of this tool.  Details on how to use this tool
# are contained in the IMS Global "I-BAT" documentation available at the IMS Global web-site:
# http://www.imsglobal.org.
# 
# Tool Copyright:  2012-2022  (c) IMS Global Learning Consortium Inc.  All Rights Reserved.
# 
# #####################################################################################

openapi: '3.1.0'

#####################################################################################
#                               API Information                                     #
#####################################################################################
info: 
    version: '1.2'
    title: OneRoster Resources OpenAPI (YAML) Definition
    description: The OneRoster 1.2 Resources service binding is available in REST/JSON and described using OpenAPI. The model is based upon the IMS PSM modelling approach.
    termsOfService: 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 API DEFINITION 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 IMPLEMENTERS 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 API DEFINITION.
    contact: 
        name: Vice President of Operations, 1EdTech
        url: https://www.1edtech.org
        email: operations@1edtech.org
    license: 
        name: 1EdTech Consortium
        url: https://www.1edtech.org/license.html

#####################################################################################
#                                 Servers                                           #
#####################################################################################
servers: 
    - url: https://{hostName}{basePath}
      description: The pattern for the Server URL should be configured for the actual server location.
      variables: 
          "hostName": 
              description: This is the hostname for the server and MUST be set to the actual service provider (the 1EdTech url is given as a default value).
              default: www.1edtech.org
          "basePath": 
              description: This is the base-path for the full URL and MUST be a part of the service endpoints.
              enum: 
                - /ims/oneroster/resources/v1p2
              default: /ims/oneroster/resources/v1p2

#####################################################################################
#                                  Tags                                             #
#####################################################################################
tags: 
    - name: ClassesManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to classes. 
    - name: CoursesManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to courses. 
    - name: ResourcesManagement
      description: |
        This enables the management of information about resources.
    - name: UsersManagement
      description: |
        This enables the management of information about resources i.e. the allocation of resources to courses. 

#####################################################################################
#                                   Paths                                           #
#####################################################################################
paths: 
    /classes/{classSourcedId}/resources:
        get:
            operationId: getResourcesForClass
            summary: The REST read request message for the getResourcesForClass() API call.
            tags: 
                - ClassesManagement
            description: |
                To read, get, the collection of resources associated to the specified class. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: classSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for this class.
                  required: true
                  type: string
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 100
                  minimum: 1
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 0
                  minimum: 0
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  enum: 
                    - asc
                    - desc
                  allowEmptyValue: false
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            type: integer
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"

    /courses/{courseSourcedId}/resources:
        get:
            operationId: getResourcesForCourse
            summary: The REST read request message for the getResourcesForCourse() API call.
            tags: 
                - CoursesManagement
            description: |
                To read, get, the collection of resources associated to the specified course. This is the OneRoster description of the resources and not the actual resources. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: courseSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the course.
                  required: true
                  type: string
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 100
                  minimum: 1
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 0
                  minimum: 0
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  enum: 
                    - asc
                    - desc
                  allowEmptyValue: false
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            type: integer
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"

    /resources:
        get:
            operationId: getAllResources
            summary: The REST read request message for the getAllResources() API call.
            tags: 
                - ResourcesManagement
            description: |
                To read, get, a collection of resources i.e. all resources. This is the OneRoster description of the resources and not the actual resources.
            parameters: 
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 100
                  minimum: 1
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 0
                  minimum: 0
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  enum: 
                    - asc
                    - desc
                  allowEmptyValue: false
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            type: integer
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"

    /resources/{sourcedId}:
        get:
            operationId: getResource
            summary: The REST read request message for the getResource() API call.
            tags: 
                - ResourcesManagement
            description: |
                To read, get, a specific OneRoster resource description. If the specified class cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: sourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the resource.
                  required: true
                  type: string
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/SingleResourceDType"
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"

    /users/{userSourcedId}/resources:
        get:
            operationId: getResourcesForUser
            summary: The REST read request message for the getResourcesForUser() API call.
            tags: 
                - UsersManagement
            description: |
                To read, get, the collection of resources available to the specified user. This is the OneRoster description of the resources and not the actual resources. If the specified user cannot be identified within the service provider then a status code of 'unknownobject' must be reported. 
            parameters: 
                - name: userSourcedId
                  in: path
                  description: |
                      The unique identifier, GUID, for the user.
                  required: true
                  type: string
                - name: limit
                  in: query
                  description: |
                      To define the download segmentation value i.e. the maximum number of records to be contained in the response.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 100
                  minimum: 1
                - name: offset
                  in: query
                  description: |
                      The number of the first record to be supplied in the segmented response message.
                  required: false
                  type: integer
                  format: int32
                  allowEmptyValue: false
                  default: 0
                  minimum: 0
                - name: sort
                  in: query
                  description: |
                      Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: orderBy
                  in: query
                  description: |
                      The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE, 16] standard.
                  required: false
                  type: string
                  enum: 
                    - asc
                    - desc
                  allowEmptyValue: false
                - name: filter
                  in: query
                  description: |
                      The filtering rules to be applied when identifying the records to be supplied in the response message.
                  required: false
                  type: string
                  allowEmptyValue: false
                - name: fields
                  in: query
                  description: |
                      To identify the range of fields that should be supplied in the response message.
                  required: false
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            security:
                - OAuth2CC:
                    - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
            responses: 
                "200" : 
                    description: |
                        The requested read has been fully serviced and all of the required data returned.
                    schema: 
                        $ref: "#/definitions/ResourceSetDType"
                    headers: 
                        "X-Total-Count" :
                            description: |
                                The total number of resources that are available to be returned
                            type: integer
                "400" : 
                    description: |
                        Either an invalid selection field or invalid filter field was supplied and data filtering on the specified criteria was not possible i.e. 'invalid_selection_field' or 'invalid_filter_field' respectively. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "403" : 
                    description: |
                        This is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "404" : 
                    description: |
                        Either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "422" : 
                    description: |
                        This error condition may occur if a JSON request body contains well-formed (i.e., syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "429" : 
                    description: |
                        The server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "500" : 
                    description: |
                        This code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"
                "default" : 
                    description: |
                        This is the default payload when none of the other HTTP codes are to be supplied.
                    schema: 
                        $ref: "#/definitions/imsx_StatusInfoDType"


#####################################################################################
#                               Definitions                                         #
#####################################################################################
definitions: 
    MetadataDType:
        description: |
            This is the container for the data model extensions that may be assigned to the associated class of objects.
        type: object
        properties: {}
        additionalProperties: true
    ResourceDType:
        description: |
            A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.
        type: object
        required: 
            - sourcedId
            - status
            - dateLastModified
            - vendorResourceId
        properties: 
            sourcedId: 
                description: All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record. Model Primitive Datatype = String.
                type: string
            status: 
                description: |
                    All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
                type: string
                enum: 
                   - active
                   - tobedeleted
            dateLastModified: 
                description: All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone. Model Primitive Datatype = DateTime.
                type: string
                format: date-time
            metadata: 
                $ref: "#/definitions/MetadataDType"
            title: 
                description: A human readable title/label for the resource. Model Primitive Datatype = NormalizedString.
                type: string
            roles: 
                description: |
                    The set of roles, types of users, who are expected to make use of the resource.
                type: array
                minItems: 0
                items: 
                    type: string
            importance: 
                description: |
                    This is an indicator of the significance of the resource i.e. primary or secondary.
                type: string
                enum: 
                   - primary
                   - secondary
            vendorResourceId: 
                description: This is a unique identifier for the resource allocated by the vendor. Model Primitive Datatype = String.
                type: string
            vendorId: 
                description: Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification. Model Primitive Datatype = String.
                type: string
            applicationId: 
                description: Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification. Model Primitive Datatype = String.
                type: string
        additionalProperties: false
    ResourceSetDType:
        description: |
            The container for a collection of resource records. The order is not significant. This may be empty. The service provider may not have any resources or cannot identfiy any resources that fit the specified filter constraints.
        type: object
        properties: 
            resources: 
                description: |
                    The set of contained resource identfiers.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/ResourceDType"
        additionalProperties: false
    SingleResourceDType:
        description: |
            The container for a single resource. This may be empty i.e. the resource has no properties that obey any of the specified selection criteria.
        type: object
        required: 
            - resource
        properties: 
            resource: 
                $ref: "#/definitions/ResourceDType"
        additionalProperties: false
    imsx_CodeMinorDType:
        description: |
            This is the container for the set of code minor status codes reported in the responses from the Service Provider.
        type: object
        required: 
            - imsx_codeMinorField
        properties: 
            imsx_codeMinorField: 
                description: |
                    Each reported code minor status code.
                type: array
                minItems: 1
                items: 
                    $ref: "#/definitions/imsx_CodeMinorFieldDType"
        additionalProperties: false
    imsx_CodeMinorFieldDType:
        description: |
            This is the container for a single code minor status code.
        type: object
        required: 
            - imsx_codeMinorFieldName
            - imsx_codeMinorFieldValue
        properties: 
            imsx_codeMinorFieldName: 
                description: This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'. Model Primitive Datatype = NormalizedString.
                type: string
                default: TargetEndSystem
            imsx_codeMinorFieldValue: 
                description: |
                    The code minor status code (this is a value from the corresponding enumerated vocabulary).
                type: string
                enum: 
                   - fullsuccess
                   - invalid_filter_field
                   - invalid_selection_field
                   - forbidden
                   - unauthorisedrequest
                   - internal_server_error
                   - server_busy
                   - unknownobject
                   - invaliddata
                   - invalid_sort_field
                   - unsupported
        additionalProperties: false
    imsx_StatusInfoDType:
        description: |
            This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Resources service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request. See Appendix B for further information on the interpretation of the information contained within this class.
        type: object
        required: 
            - imsx_codeMajor
            - imsx_severity
        properties: 
            imsx_codeMajor: 
                description: |
                    The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
                type: string
                enum: 
                   - success
                   - processing
                   - failure
                   - unsupported
            imsx_severity: 
                description: |
                    The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
                type: string
                enum: 
                   - status
                   - warning
                   - error
            imsx_description: 
                description: A human readable description supplied by the entity creating the status code information. Model Primitive Datatype = String.
                type: string
            imsx_CodeMinor: 
                $ref: "#/definitions/imsx_CodeMinorDType"
        additionalProperties: false

toc | top

Appendix C JSON Schema Listings

C1 JSON Schemas for Payload Validation

This is the set of JSON Schema listing that are used to validate the set of JSON payloads used by this service.

C1.1a JSON Schema for the "getAllResources" Operation Request Payload Validation.

No request parameters are sent for this request and so there is no JSON Schema listing.

C1.1b JSON Schema for the "getAllResources" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getallresources-200-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getAllResources-200-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getAllResources-200-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "resources" : {
            "description" : "The set of contained resource identfiers.",
            "type" : "array",
            "minItems" : 0,
            "items" : {
                "$ref" : "#/definitions/ResourceDType"
            }
        }
    },
    "additionalProperties" : false,
    "definitions" : {
        "MetadataDType" : {
            "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
            "type" : "object",
            "properties" : {

            },
            "patternProperties" : {
                "^[^:][^:]*:[^:][^:]*$" : {
                    "oneOf": [{ "type": "string" }, { "type": "array" }, { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "object" }]
                }
            },
            "additionalProperties" : true
        },
        "ResourceDType" : {
            "description" : "A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.",
            "type" : "object",
            "properties" : {
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String. All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.",
                    "type" : "string"
                },
                "status" : {
                    "description" : "All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.",
                    "type" : "string",
                    "enum" : [ "active","tobedeleted" ]
                },
                "dateLastModified" : {
                    "description" : "Model Primitive Datatype = DateTime. All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.",
                    "type" : "string",
                    "format" : "date-time"
                },
                "metadata" : {
                    "description" : "All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.",
                    "$ref" : "#/definitions/MetadataDType"
                },
                "title" : {
                    "description" : "Model Primitive Datatype = NormalizedString. A human readable title/label for the resource.",
                    "type" : "string"
                },
                "roles" : {
                    "description" : "The set of roles, types of users, who are expected to make use of the resource.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "anyOf" : [
                            {
                                "type" : "string",
                                "enum" : [ "administrator","aide","guardian","parent","proctor","relative","student","teacher" ]
                            },
                            {
                                "description" : "Model Primitive Datatype = NormalizedString.",
                                "type" : "string",
                                "pattern" : "(ext:)[a-zA-Z0-9\\.\\-_]+"
                            }
                        ]
                    }
                },
                "importance" : {
                    "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
                    "type" : "string",
                    "enum" : [ "primary","secondary" ]
                },
                "vendorResourceId" : {
                    "description" : "Model Primitive Datatype = String. This is a unique identifier for the resource allocated by the vendor.",
                    "type" : "string"
                },
                "vendorId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
                    "type" : "string"
                },
                "applicationId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
                    "type" : "string"
                }
            },
            "required" : [ "sourcedId","status","dateLastModified","vendorResourceId" ],
            "additionalProperties" : false
        }
    }
}

C1.1c JSON Schema for the "getAllResources" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getallresources-400-401-403-404-422-429-500-default-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getAllResources-400-401-403-404-422-429-500-default-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getAllResources-400-401-403-404-422-429-500-default-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "imsx_codeMajor" : {
            "description" : "The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.",
            "type" : "string",
            "enum" : [ "success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported" ]
        },
        "imsx_severity" : {
            "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
            "type" : "string",
            "enum" : [ "status","warning","error","status","warning","error","status","warning","error" ]
        },
        "imsx_description" : {
            "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
            "type" : "string"
        },
        "imsx_CodeMinor" : {
            "description" : "The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.",
            "$ref" : "#/definitions/imsx_CodeMinorDType"
        }
    },
    "required" : [ "imsx_codeMajor","imsx_severity" ],
    "additionalProperties" : false,
    "definitions" : {
        "imsx_CodeMinorDType" : {
            "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorField" : {
                    "description" : "Each reported code minor status code.",
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/imsx_CodeMinorFieldDType"
                    }
                }
            },
            "required" : [ "imsx_codeMinorField" ],
            "additionalProperties" : false
        },
        "imsx_CodeMinorFieldDType" : {
            "description" : "This is the container for a single code minor status code.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorFieldName" : {
                    "description" : "Model Primitive Datatype = NormalizedString. This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.",
                    "type" : "string",
                    "default" : "TargetEndSystem"
                },
                "imsx_codeMinorFieldValue" : {
                    "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                                "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
                }
            },
            "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
            "additionalProperties" : false
        }
    }
}

C1.2a JSON Schema for the "getResource" Operation Request Payload Validation.

No request payload is sent for this request, only a single path parameter is supplied, and so there is no JSON Schema listing.

C1.2b JSON Schema for the "getResource" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getresource-200-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getResource-200-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getResource-200-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "resource" : {
            "description" : "The label for the contained resource.",
            "$ref" : "#/definitions/ResourceDType"
        }
    },
    "required" : [ "resource" ],
    "additionalProperties" : false,
    "definitions" : {
        "MetadataDType" : {
            "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
            "type" : "object",
            "properties" : {

            },
            "patternProperties" : {
                "^[^:][^:]*:[^:][^:]*$" : {
                    "oneOf": [{ "type": "string" }, { "type": "array" }, { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "object" }]
                }
            },
            "additionalProperties" : true
        },
        "ResourceDType" : {
            "description" : "A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.",
            "type" : "object",
            "properties" : {
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String. All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.",
                    "type" : "string"
                },
                "status" : {
                    "description" : "All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.",
                    "type" : "string",
                    "enum" : [ "active","tobedeleted" ]
                },
                "dateLastModified" : {
                    "description" : "Model Primitive Datatype = DateTime. All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.",
                    "type" : "string",
                    "format" : "date-time"
                },
                "metadata" : {
                    "description" : "All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.",
                    "$ref" : "#/definitions/MetadataDType"
                },
                "title" : {
                    "description" : "Model Primitive Datatype = NormalizedString. A human readable title/label for the resource.",
                    "type" : "string"
                },
                "roles" : {
                    "description" : "The set of roles, types of users, who are expected to make use of the resource.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "anyOf" : [
                            {
                                "type" : "string",
                                "enum" : [ "administrator","aide","guardian","parent","proctor","relative","student","teacher" ]
                            },
                            {
                                "description" : "Model Primitive Datatype = NormalizedString.",
                                "type" : "string",
                                "pattern" : "(ext:)[a-zA-Z0-9\\.\\-_]+"
                            }
                        ]
                    }
                },
                "importance" : {
                    "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
                    "type" : "string",
                    "enum" : [ "primary","secondary" ]
                },
                "vendorResourceId" : {
                    "description" : "Model Primitive Datatype = String. This is a unique identifier for the resource allocated by the vendor.",
                    "type" : "string"
                },
                "vendorId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
                    "type" : "string"
                },
                "applicationId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
                    "type" : "string"
                }
            },
            "required" : [ "sourcedId","status","dateLastModified","vendorResourceId" ],
            "additionalProperties" : false
        }
    }
}

C1.2c JSON Schema for the "getResource" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getresource-400-401-403-404-422-429-500-default-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getResource-400-401-403-404-422-429-500-default-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getResource-400-401-403-404-422-429-500-default-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "imsx_codeMajor" : {
            "description" : "The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.",
            "type" : "string",
            "enum" : [ "success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported" ]
        },
        "imsx_severity" : {
            "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
            "type" : "string",
            "enum" : [ "status","warning","error","status","warning","error","status","warning","error" ]
        },
        "imsx_description" : {
            "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
            "type" : "string"
        },
        "imsx_CodeMinor" : {
            "description" : "The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.",
            "$ref" : "#/definitions/imsx_CodeMinorDType"
        }
    },
    "required" : [ "imsx_codeMajor","imsx_severity" ],
    "additionalProperties" : false,
    "definitions" : {
        "imsx_CodeMinorDType" : {
            "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorField" : {
                    "description" : "Each reported code minor status code.",
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/imsx_CodeMinorFieldDType"
                    }
                }
            },
            "required" : [ "imsx_codeMinorField" ],
            "additionalProperties" : false
        },
        "imsx_CodeMinorFieldDType" : {
            "description" : "This is the container for a single code minor status code.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorFieldName" : {
                    "description" : "Model Primitive Datatype = NormalizedString. This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.",
                    "type" : "string",
                    "default" : "TargetEndSystem"
                },
                "imsx_codeMinorFieldValue" : {
                    "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                                "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
                }
            },
            "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
            "additionalProperties" : false
        }
    }
}

C1.3a JSON Schema for the "getResourcesForClass" Operation Request Payload Validation.

No request payload is sent for this request, only a single path parameter is supplied, and so there is no JSON Schema listing.

C1.3b JSON Schema for the "getResourcesForClass" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getresourcesforclass-200-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getResourcesForClass-200-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getResourcesForClass-200-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "resources" : {
            "description" : "The set of contained resource identfiers.",
            "type" : "array",
            "minItems" : 0,
            "items" : {
                "$ref" : "#/definitions/ResourceDType"
            }
        }
    },
    "additionalProperties" : false,
    "definitions" : {
        "MetadataDType" : {
            "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
            "type" : "object",
            "properties" : {

            },
            "patternProperties" : {
                "^[^:][^:]*:[^:][^:]*$" : {
                    "oneOf": [{ "type": "string" }, { "type": "array" }, { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "object" }]
                }
            },
            "additionalProperties" : true
        },
        "ResourceDType" : {
            "description" : "A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.",
            "type" : "object",
            "properties" : {
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String. All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.",
                    "type" : "string"
                },
                "status" : {
                    "description" : "All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.",
                    "type" : "string",
                    "enum" : [ "active","tobedeleted" ]
                },
                "dateLastModified" : {
                    "description" : "Model Primitive Datatype = DateTime. All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.",
                    "type" : "string",
                    "format" : "date-time"
                },
                "metadata" : {
                    "description" : "All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.",
                    "$ref" : "#/definitions/MetadataDType"
                },
                "title" : {
                    "description" : "Model Primitive Datatype = NormalizedString. A human readable title/label for the resource.",
                    "type" : "string"
                },
                "roles" : {
                    "description" : "The set of roles, types of users, who are expected to make use of the resource.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "anyOf" : [
                            {
                                "type" : "string",
                                "enum" : [ "administrator","aide","guardian","parent","proctor","relative","student","teacher" ]
                            },
                            {
                                "description" : "Model Primitive Datatype = NormalizedString.",
                                "type" : "string",
                                "pattern" : "(ext:)[a-zA-Z0-9\\.\\-_]+"
                            }
                        ]
                    }
                },
                "importance" : {
                    "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
                    "type" : "string",
                    "enum" : [ "primary","secondary" ]
                },
                "vendorResourceId" : {
                    "description" : "Model Primitive Datatype = String. This is a unique identifier for the resource allocated by the vendor.",
                    "type" : "string"
                },
                "vendorId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
                    "type" : "string"
                },
                "applicationId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
                    "type" : "string"
                }
            },
            "required" : [ "sourcedId","status","dateLastModified","vendorResourceId" ],
            "additionalProperties" : false
        }
    }
}

C1.3c JSON Schema for the "getResourcesForClass" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getresourcesforclass-400-401-403-404-422-429-500-default-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getResourcesForClass-400-401-403-404-422-429-500-default-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getResourcesForClass-400-401-403-404-422-429-500-default-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "imsx_codeMajor" : {
            "description" : "The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.",
            "type" : "string",
            "enum" : [ "success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported" ]
        },
        "imsx_severity" : {
            "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
            "type" : "string",
            "enum" : [ "status","warning","error","status","warning","error","status","warning","error" ]
        },
        "imsx_description" : {
            "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
            "type" : "string"
        },
        "imsx_CodeMinor" : {
            "description" : "The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.",
            "$ref" : "#/definitions/imsx_CodeMinorDType"
        }
    },
    "required" : [ "imsx_codeMajor","imsx_severity" ],
    "additionalProperties" : false,
    "definitions" : {
        "imsx_CodeMinorDType" : {
            "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorField" : {
                    "description" : "Each reported code minor status code.",
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/imsx_CodeMinorFieldDType"
                    }
                }
            },
            "required" : [ "imsx_codeMinorField" ],
            "additionalProperties" : false
        },
        "imsx_CodeMinorFieldDType" : {
            "description" : "This is the container for a single code minor status code.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorFieldName" : {
                    "description" : "Model Primitive Datatype = NormalizedString. This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.",
                    "type" : "string",
                    "default" : "TargetEndSystem"
                },
                "imsx_codeMinorFieldValue" : {
                    "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                                "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
                }
            },
            "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
            "additionalProperties" : false
        }
    }
}

C1.4a JSON Schema for the "getResourcesForCourse" Operation Request Payload Validation.

No request payload is sent for this request, only a single path parameter is supplied, and so there is no JSON Schema listing.

C1.4b JSON Schema for the "getResourcesForCourse" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getresourcesforcourse-200-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getResourcesForCourse-200-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getResourcesForCourse-200-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "resources" : {
            "description" : "The set of contained resource identfiers.",
            "type" : "array",
            "minItems" : 0,
            "items" : {
                "$ref" : "#/definitions/ResourceDType"
            }
        }
    },
    "additionalProperties" : false,
    "definitions" : {
        "MetadataDType" : {
            "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
            "type" : "object",
            "properties" : {

            },
            "patternProperties" : {
                "^[^:][^:]*:[^:][^:]*$" : {
                    "oneOf": [{ "type": "string" }, { "type": "array" }, { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "object" }]
                }
            },
            "additionalProperties" : true
        },
        "ResourceDType" : {
            "description" : "A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.",
            "type" : "object",
            "properties" : {
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String. All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.",
                    "type" : "string"
                },
                "status" : {
                    "description" : "All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.",
                    "type" : "string",
                    "enum" : [ "active","tobedeleted" ]
                },
                "dateLastModified" : {
                    "description" : "Model Primitive Datatype = DateTime. All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.",
                    "type" : "string",
                    "format" : "date-time"
                },
                "metadata" : {
                    "description" : "All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.",
                    "$ref" : "#/definitions/MetadataDType"
                },
                "title" : {
                    "description" : "Model Primitive Datatype = NormalizedString. A human readable title/label for the resource.",
                    "type" : "string"
                },
                "roles" : {
                    "description" : "The set of roles, types of users, who are expected to make use of the resource.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "anyOf" : [
                            {
                                "type" : "string",
                                "enum" : [ "administrator","aide","guardian","parent","proctor","relative","student","teacher" ]
                            },
                            {
                                "description" : "Model Primitive Datatype = NormalizedString.",
                                "type" : "string",
                                "pattern" : "(ext:)[a-zA-Z0-9\\.\\-_]+"
                            }
                        ]
                    }
                },
                "importance" : {
                    "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
                    "type" : "string",
                    "enum" : [ "primary","secondary" ]
                },
                "vendorResourceId" : {
                    "description" : "Model Primitive Datatype = String. This is a unique identifier for the resource allocated by the vendor.",
                    "type" : "string"
                },
                "vendorId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
                    "type" : "string"
                },
                "applicationId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
                    "type" : "string"
                }
            },
            "required" : [ "sourcedId","status","dateLastModified","vendorResourceId" ],
            "additionalProperties" : false
        }
    }
}

C1.4c JSON Schema for the "getResourcesForCourse" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getresourcesforcourse-400-401-403-404-422-429-500-default-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getResourcesForCourse-400-401-403-404-422-429-500-default-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getResourcesForCourse-400-401-403-404-422-429-500-default-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "imsx_codeMajor" : {
            "description" : "The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.",
            "type" : "string",
            "enum" : [ "success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported" ]
        },
        "imsx_severity" : {
            "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
            "type" : "string",
            "enum" : [ "status","warning","error","status","warning","error","status","warning","error" ]
        },
        "imsx_description" : {
            "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
            "type" : "string"
        },
        "imsx_CodeMinor" : {
            "description" : "The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.",
            "$ref" : "#/definitions/imsx_CodeMinorDType"
        }
    },
    "required" : [ "imsx_codeMajor","imsx_severity" ],
    "additionalProperties" : false,
    "definitions" : {
        "imsx_CodeMinorDType" : {
            "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorField" : {
                    "description" : "Each reported code minor status code.",
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/imsx_CodeMinorFieldDType"
                    }
                }
            },
            "required" : [ "imsx_codeMinorField" ],
            "additionalProperties" : false
        },
        "imsx_CodeMinorFieldDType" : {
            "description" : "This is the container for a single code minor status code.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorFieldName" : {
                    "description" : "Model Primitive Datatype = NormalizedString. This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.",
                    "type" : "string",
                    "default" : "TargetEndSystem"
                },
                "imsx_codeMinorFieldValue" : {
                    "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                                "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
                }
            },
            "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
            "additionalProperties" : false
        }
    }
}

C1.5a JSON Schema for the "getResourcesForUser" Operation Request Payload Validation.

No request payload is sent for this request, only a single path parameter is supplied, and so there is no JSON Schema listing.

C1.5b JSON Schema for the "getResourcesForUser" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getresourcesforuser-200-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getResourcesForUser-200-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getResourcesForUser-200-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "resources" : {
            "description" : "The set of contained resource identfiers.",
            "type" : "array",
            "minItems" : 0,
            "items" : {
                "$ref" : "#/definitions/ResourceDType"
            }
        }
    },
    "additionalProperties" : false,
    "definitions" : {
        "MetadataDType" : {
            "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
            "type" : "object",
            "properties" : {

            },
            "patternProperties" : {
                "^[^:][^:]*:[^:][^:]*$" : {
                    "oneOf": [{ "type": "string" }, { "type": "array" }, { "type": "boolean" }, { "type": "number" }, { "type": "integer" }, { "type": "object" }]
                }
            },
            "additionalProperties" : true
        },
        "ResourceDType" : {
            "description" : "A resource is a description of learning content that is related to a course and/or a class and/or a user. This identifies a resource that is used by a teacher, learner, etc. as part of the learning experience.  A resource MUST be associated to a course and/or a class.",
            "type" : "object",
            "properties" : {
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String. All Objects MUST be identified by a Source Identifier. This is a GUID i.e. a unique system interoperability  identifier for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local identifiers (e.g. database key fields) they use to the corresponding SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.",
                    "type" : "string"
                },
                "status" : {
                    "description" : "All objects MUST BE either 'active' or 'tobedeleted'.  Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. NOTE: In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.",
                    "type" : "string",
                    "enum" : [ "active","tobedeleted" ]
                },
                "dateLastModified" : {
                    "description" : "Model Primitive Datatype = DateTime. All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.",
                    "type" : "string",
                    "format" : "date-time"
                },
                "metadata" : {
                    "description" : "All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions.",
                    "$ref" : "#/definitions/MetadataDType"
                },
                "title" : {
                    "description" : "Model Primitive Datatype = NormalizedString. A human readable title/label for the resource.",
                    "type" : "string"
                },
                "roles" : {
                    "description" : "The set of roles, types of users, who are expected to make use of the resource.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "anyOf" : [
                            {
                                "type" : "string",
                                "enum" : [ "administrator","aide","guardian","parent","proctor","relative","student","teacher" ]
                            },
                            {
                                "description" : "Model Primitive Datatype = NormalizedString.",
                                "type" : "string",
                                "pattern" : "(ext:)[a-zA-Z0-9\\.\\-_]+"
                            }
                        ]
                    }
                },
                "importance" : {
                    "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
                    "type" : "string",
                    "enum" : [ "primary","secondary" ]
                },
                "vendorResourceId" : {
                    "description" : "Model Primitive Datatype = String. This is a unique identifier for the resource allocated by the vendor.",
                    "type" : "string"
                },
                "vendorId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
                    "type" : "string"
                },
                "applicationId" : {
                    "description" : "Model Primitive Datatype = String. Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
                    "type" : "string"
                }
            },
            "required" : [ "sourcedId","status","dateLastModified","vendorResourceId" ],
            "additionalProperties" : false
        }
    }
}

C1.5c JSON Schema for the "getResourcesForUser" Operation Response Payload Validation for HTTP Codes (400,401,403,404,422,429,500,default)

The JSON Schema listing is shown below (the JSON Schema is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerosterresourcesservicev1p2-getresourcesforuser-400-401-403-404-422-429-500-default-responsepayload-schemav1p0.json).

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "$id" : "getResourcesForUser-400-401-403-404-422-429-500-default-responsepayload-schema.json",
    "title" : " Version  IMS Final Release JSON Schema Binding (getResourcesForUser-400-401-403-404-422-429-500-default-responsepayload-schema)",
    "description" : "Author-Colin Smythe (1EdTech);  Version-1.2;  Release Date-19th September, 2022. ",
    "type" : "object",
    "properties" : {
        "imsx_codeMajor" : {
            "description" : "The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.",
            "type" : "string",
            "enum" : [ "success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported","success","processing","failure","unsupported" ]
        },
        "imsx_severity" : {
            "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
            "type" : "string",
            "enum" : [ "status","warning","error","status","warning","error","status","warning","error" ]
        },
        "imsx_description" : {
            "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
            "type" : "string"
        },
        "imsx_CodeMinor" : {
            "description" : "The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.",
            "$ref" : "#/definitions/imsx_CodeMinorDType"
        }
    },
    "required" : [ "imsx_codeMajor","imsx_severity" ],
    "additionalProperties" : false,
    "definitions" : {
        "imsx_CodeMinorDType" : {
            "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorField" : {
                    "description" : "Each reported code minor status code.",
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/imsx_CodeMinorFieldDType"
                    }
                }
            },
            "required" : [ "imsx_codeMinorField" ],
            "additionalProperties" : false
        },
        "imsx_CodeMinorFieldDType" : {
            "description" : "This is the container for a single code minor status code.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorFieldName" : {
                    "description" : "Model Primitive Datatype = NormalizedString. This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.",
                    "type" : "string",
                    "default" : "TargetEndSystem"
                },
                "imsx_codeMinorFieldValue" : {
                    "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "fullsuccess","invalid_filter_field","invalid_selection_field","forbidden","unauthorisedrequest","internal_server_error",
                                "server_busy","unknownobject","invaliddata","invalid_sort_field","unsupported" ]
                }
            },
            "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
            "additionalProperties" : false
        }
    }
}

toc | top

About this Document

Title: IMS OneRoster Resources Service REST/JSON Binding v1.2
Editors: Colin Smythe (1EdTech) and Joshua McGhee (1EdTech)
Co-chairs: Matt Richards (Infinite Campus, USA)
Version: 1.0
Version Date: 19th September, 2022
Status: IMS Final Release
Summary: This is the OneRoster 1.2 Resources Service specification. It defines the exchange of the identification resources that are linked to classes, courses and users. This service is made available as a REST/JSON based binding to support resources allocation to classes, courses and users data exchange.
Revision Information: The first release of the OneRoster Resources 1.2 Service REST/JSON Binding specification based upon the I-BAT. Support for the obtaining the resources assigned to a user has been added in this version.
Purpose: For public adoption.
Document Location: https://www.imsglobal.org/spec/oneroster/v1p2/resource/bind/rest

toc | top

List of Contributors

The following individuals contributed to the development of this document:

Eric Adams Instructure (USA)
Barry Brahier Infinite Campus (USA)
Tom Clark Pearson (USA)
Linda Feng Unicon (USA)
Viktor Haag Desire2Learn (Canada)
Richard Heim LearningMate (USA)
Tom Ingram Escambia County School District (USA)
Oxana Jurosevic Instructure (USA)
Jong Kim Pearson (USA)
Andrew Kuritzky Edmentum (USA)
David Mayes Gwinnett County Schools (USA)
Joshua McGhee 1EdTech (USA)
Phil Nicholls 1EdTech (UK)
Padraig O'hiceadha HMH (UK)
Upendra Penegalapati Pearson (USA)
James Perreault FLVS (USA)
Patrick Porter Houston ISD (USA)
Matthew Richards Infinite Campus (USA)
Wendy Riedy Microsoft (USA)
Kurt Rompot Pearson (USA)
Gabrielle Sanderson Illuminate Education (USA)
Colin Smythe 1EdTech (UK)
Konrad Stimeling K12 Inc (USA)
Aditya Subramaniam Schoology (USA)
Matt Vella Schoology (USA)
TJ Vering Microsoft (USA)
Mark Walls Gwinnett County Schools (USA)

toc | top

Revision History

Version No. Release Date Comments
Final Release 1.0 / Docment 1.0 1st July, 2015 First release of the OneRoster Service specification.
Final Release 1.1 / Docment 1.0 1st November, 2016 This second release includes new operations to create and delete single objects, support for the exchange of Result, LineItem, Category and Resource objects.
Final Release 1.2 / Docment 1.0 19th September, 2022 This is the first release of the OneRoster 1.2 Resources Service as a standalone document. The new functionality added is support for the exchange information about the availability of resources for users using the new endpoint getResourcesForUser().

toc | top

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: IMS OneRoster Resources Service REST/JSON Binding v1.2

Date: 19th September, 2022

toc | top