1EdTech
Final

OneRoster Resources Service REST/JSON Binding

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.

IPR and Distribution Notices

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

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

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

Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: https://www.1edtech.org/standards/specification-license.

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

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

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

Trademark information: https://www.1edtech.org/about/legal/trademarks

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.

Introduction

This Section is NOT NORMATIVE.

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 1EdTech Binding Auto-generation Toolkit (I-BAT). This means that this specification is based upon the concepts of:

  • Interoperability - the OneRoster Resources service focuses on the exchange of information about the relationship between resurces and the classes and/or courses for which they are to be used. There are no definitions in the specification on how the data is managed within the end-systems;
  • Service-oriented - the OneRoster Resources service specification defines the exchange of information in terms of the services being supplied by the collaboration of the systems.

Key artefacts produced as part of the REST/JSON binding description are the associated OpenAPI files based upon the OpenAPI Specifications version 2 OpenAPI Specification (version 2) and version 3 OpenAPI Specification (version 3).

Conventions

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, NOT RECOMMENDED, NOT REQUIRED, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document $are to be interpreted as described in Key words for use in RFCs to Indicate Requirement Levels.

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

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

Changes in the Resources Service 1.2

The only changes made in this new version are:

  • The Resource Management parts of the OneRoster specification have been separated out into their own Service Model and REST/JSON Binding documents;
  • The endpoint 'getResourcesForUser()' has been add;
  • The endpoints have been annotated as '/ims/oneroster/resources/v1p2' to replace the '/ims/oneroster/v1p1';
  • The 'RoleEnum' vocabulary has been made extensible to enable easier profiling for internationalisation;
  • Use of OAuth 1.0a message signing has been removed. The use of OAuth 2.0 Bearer Tokens (Client Credentials Grant) is required instead. The security architecture has been aligned to the 1EdTech Security Framework 1EdTech Security Framework 1.1 Final Release;
  • A Service Provider is REQUIRED to make a localized OpenAPI file available to enable Service Discovery 1EdTech Security Framework 1.1 Final Release.

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

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);

Mapping of the Service Operations to the REST Endpoints

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

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".

getAllResources Operation

To read, get, a collection of resources i.e. all resources. This is the OneRoster description of the resources and not the actual resources.

Request

GET /ims/oneroster/resources/v1p2/resources?limit={limit}&offset={offset}&sort={sort}&orderBy={orderBy}&filter={filter}&fields={fields}

Request header, path, and query parameters

Parameter Parameter Type Description Required
limit (parameter.type?lower_case) PositiveInteger To define the download segmentation value i.e. the maximum number of records to be contained in the response. Optional
offset (parameter.type?lower_case) NonNegativeInteger The number of the first record to be supplied in the segmented response message. Optional
sort (parameter.type?lower_case) String 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. Optional
orderBy (parameter.type?lower_case) OrderByEnum 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. Optional
filter (parameter.type?lower_case) String The filtering rules to be applied when identifying the records to be supplied in the response message. Optional
fields (parameter.type?lower_case) String To identify the range of fields that should be supplied in the response message. Optional

Responses

Allowed response codes and content types

Status Code Content-Type Header Content Type Content Description Content Required Confidentiality
200 application/json ResourceSet No Description Required N/A
400 application/json imsx_StatusInfo No Description Required N/A
401 application/json imsx_StatusInfo No Description Required N/A
403 application/json imsx_StatusInfo No Description Required N/A
404 application/json imsx_StatusInfo No Description Required N/A
422 application/json imsx_StatusInfo No Description Required N/A
429 application/json imsx_StatusInfo No Description Required N/A
500 application/json imsx_StatusInfo No Description Required N/A
DEFAULT application/json imsx_StatusInfo No Description Required N/A

getResource Operation

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.

Request

GET /ims/oneroster/resources/v1p2/resources/{sourcedId}?fields={fields}

Request header, path, and query parameters

Parameter Parameter Type Description Required
sourcedId (parameter.type?lower_case) GUID The unique identifier, GUID, for the resource. Required
fields (parameter.type?lower_case) String To identify the range of fields that should be supplied in the response message. Optional

Responses

Allowed response codes and content types

Status Code Content-Type Header Content Type Content Description Content Required Confidentiality
200 application/json SingleResource No Description Required N/A
400 application/json imsx_StatusInfo No Description Required N/A
401 application/json imsx_StatusInfo No Description Required N/A
403 application/json imsx_StatusInfo No Description Required N/A
404 application/json imsx_StatusInfo No Description Required N/A
422 application/json imsx_StatusInfo No Description Required N/A
429 application/json imsx_StatusInfo No Description Required N/A
500 application/json imsx_StatusInfo No Description Required N/A
DEFAULT application/json imsx_StatusInfo No Description Required N/A

getResourcesForClass Operation

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.

Request

GET /ims/oneroster/resources/v1p2/classes/{classSourcedId}/resources?limit={limit}&offset={offset}&sort={sort}&orderBy={orderBy}&filter={filter}&fields={fields}

Request header, path, and query parameters

Parameter Parameter Type Description Required
classSourcedId (parameter.type?lower_case) GUID The unique identifier, GUID, for this class. Required
limit (parameter.type?lower_case) PositiveInteger To define the download segmentation value i.e. the maximum number of records to be contained in the response. Optional
offset (parameter.type?lower_case) NonNegativeInteger The number of the first record to be supplied in the segmented response message. Optional
sort (parameter.type?lower_case) String 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. Optional
orderBy (parameter.type?lower_case) OrderByEnum 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. Optional
filter (parameter.type?lower_case) String The filtering rules to be applied when identifying the records to be supplied in the response message. Optional
fields (parameter.type?lower_case) String To identify the range of fields that should be supplied in the response message. Optional

Responses

Allowed response codes and content types

Status Code Content-Type Header Content Type Content Description Content Required Confidentiality
200 application/json ResourceSet No Description Required N/A
400 application/json imsx_StatusInfo No Description Required N/A
401 application/json imsx_StatusInfo No Description Required N/A
403 application/json imsx_StatusInfo No Description Required N/A
404 application/json imsx_StatusInfo No Description Required N/A
422 application/json imsx_StatusInfo No Description Required N/A
429 application/json imsx_StatusInfo No Description Required N/A
500 application/json imsx_StatusInfo No Description Required N/A
DEFAULT application/json imsx_StatusInfo No Description Required N/A

getResourcesForCourse Operation

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.

Request

GET /ims/oneroster/resources/v1p2/courses/{courseSourcedId}/resources?limit={limit}&offset={offset}&sort={sort}&orderBy={orderBy}&filter={filter}&fields={fields}

Request header, path, and query parameters

Parameter Parameter Type Description Required
courseSourcedId (parameter.type?lower_case) GUID The unique identifier, GUID, for the course. Required
limit (parameter.type?lower_case) PositiveInteger To define the download segmentation value i.e. the maximum number of records to be contained in the response. Optional
offset (parameter.type?lower_case) NonNegativeInteger The number of the first record to be supplied in the segmented response message. Optional
sort (parameter.type?lower_case) String 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. Optional
orderBy (parameter.type?lower_case) OrderByEnum 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. Optional
filter (parameter.type?lower_case) String The filtering rules to be applied when identifying the records to be supplied in the response message. Optional
fields (parameter.type?lower_case) String To identify the range of fields that should be supplied in the response message. Optional

Responses

Allowed response codes and content types

Status Code Content-Type Header Content Type Content Description Content Required Confidentiality
200 application/json ResourceSet No Description Required N/A
400 application/json imsx_StatusInfo No Description Required N/A
401 application/json imsx_StatusInfo No Description Required N/A
403 application/json imsx_StatusInfo No Description Required N/A
404 application/json imsx_StatusInfo No Description Required N/A
422 application/json imsx_StatusInfo No Description Required N/A
429 application/json imsx_StatusInfo No Description Required N/A
500 application/json imsx_StatusInfo No Description Required N/A
DEFAULT application/json imsx_StatusInfo No Description Required N/A

getResourcesForUser Operation

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.

Request

GET /ims/oneroster/resources/v1p2/users/{userSourcedId}/resources?limit={limit}&offset={offset}&sort={sort}&orderBy={orderBy}&filter={filter}&fields={fields}

Request header, path, and query parameters

Parameter Parameter Type Description Required
userSourcedId (parameter.type?lower_case) GUID The unique identifier, GUID, for the user. Required
limit (parameter.type?lower_case) PositiveInteger To define the download segmentation value i.e. the maximum number of records to be contained in the response. Optional
offset (parameter.type?lower_case) NonNegativeInteger The number of the first record to be supplied in the segmented response message. Optional
sort (parameter.type?lower_case) String 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. Optional
orderBy (parameter.type?lower_case) OrderByEnum 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. Optional
filter (parameter.type?lower_case) String The filtering rules to be applied when identifying the records to be supplied in the response message. Optional
fields (parameter.type?lower_case) String To identify the range of fields that should be supplied in the response message. Optional

Responses

Allowed response codes and content types

Status Code Content-Type Header Content Type Content Description Content Required Confidentiality
200 application/json ResourceSet No Description Required N/A
400 application/json imsx_StatusInfo No Description Required N/A
401 application/json imsx_StatusInfo No Description Required N/A
403 application/json imsx_StatusInfo No Description Required N/A
404 application/json imsx_StatusInfo No Description Required N/A
422 application/json imsx_StatusInfo No Description Required N/A
429 application/json imsx_StatusInfo No Description Required N/A
500 application/json imsx_StatusInfo No Description Required N/A
DEFAULT application/json imsx_StatusInfo No Description Required N/A

Service Discovery

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

Using the Endpoint Parameters

This SECTION is NOT NORMATIVE.

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:

  • 'limit' - the number of results to return (the default value is 100);
  • 'offset' - the index of the first record to return (zero index and so the default value is 0).

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"

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:

  • 'data_field' MUST be used in the request to ask for the collection to be sorted on data field. The form of ordering is implementation dependent if the 'orderBy' attribute is not used;
  • 'orderBy' MAY be used in the request to ask for the collection to be ordered ascending (asc) or descending (desc).

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 Collation Algorithm Version 9.0 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>

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:

  • Equals is represented by '='
  • Not Equal is represented by '!='
  • Greater Than is represented by '>'
  • Greater Than or Equal is represented by '>='
  • Lesser Than is represented by '<'
  • Lesser Than or Equal is represented by '<='
  • Contains is represented by '~'

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 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:

  • ?filter=role='role1' - record not returned;
  • ?filter=role='role1,role2' - record not returned;
  • ?filter=role='role1,role2,role3' - record returned;
  • ?filter=role~'role1' - record returned;
  • ?filter=role~'role1,role2' - record returned;
  • ?filter=role~'role1,role2,role3' - record returned.

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 Collation Algorithm Version 9.0 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:

  • CodeMajor value is 'failure';
  • Severity value is 'error';
  • CodeMinor value is 'invalid_filter_field'.

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:

  • CodeMajor value is 'failure';
  • Severity value is 'error';
  • CodeMinor value is 'invalid_selection_field'.

Security Framework

This Section is NORMATIVE.

The information in this section is taken from the IMS Security Framework 1EdTech Security Framework 1.1 Final Release: that document describes the security approaches to be adopted in all IMS specifications.

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.

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.

Scopes

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

Operation HTTP Verb Endpoint
getResource GET /resources/{sourcedId}
getAllResources GET /resources
getResourcesForCourse GET /courses/{courseSourcedId}/resources
getResourcesForUser GET /users/{userSourcedId}/resources
getResourcesForClass GET /classes/{classSourcedId}/resources

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

Operation HTTP Verb Endpoint
getResource GET /resources/{sourcedId}
getAllResources GET /resources

Data Classes

Base Class

This is the base class which all of the first class objects in the Resource service inherit. It defines the instance's unique, interoperability identifier, the status of the instance data and the date the data was last changed. It all defines how the data model can be extended using the 'metadata' structure.

Attribute Type Description Multiplicity Privacy
sourcedId GUID 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. [1] N/A
status BaseStatusEnum 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'. [1] N/A
dateLastModified 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. [1] N/A
metadata Metadata All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. [0..1] N/A

Metadata Class

This is the container for the data model extensions that may be assigned to the associated class of objects.

This class can be extended with additional properties.

Resource Class

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.

Attribute Type Description Multiplicity Privacy
title NormalizedString A human readable title/label for the resource. [0..1] N/A
roles RoleEnumExt The set of roles, types of users, who are expected to make use of the resource. [0..*] N/A
importance ImportanceEnum This is an indicator of the significance of the resource i.e. primary or secondary. [0..1] N/A
vendorResourceId Identifier This is a unique identifier for the resource allocated by the vendor. [1] N/A
vendorId Identifier Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification. [0..1] N/A
applicationId Identifier Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification. [0..1] N/A
sourcedId GUID 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. [1] N/A
status BaseStatusEnum 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'. [1] N/A
dateLastModified 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. [1] N/A
metadata Metadata All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. [0..1] N/A

ResourceSet Class

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.

Attribute Type Description Multiplicity Privacy
resources Resource The set of contained resource identfiers. [0..*] N/A

SingleResource Class

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.

Attribute Type Description Multiplicity Privacy
resource Resource The label for the contained resource. [1] N/A

imsx_CodeMinor Class

This is the container for the set of code minor status codes reported in the responses from the Service Provider.

Attribute Type Description Multiplicity Privacy
imsx_codeMinorField imsx_CodeMinorField Each reported code minor status code. [1..*] N/A

imsx_CodeMinorField Class

This is the container for a single code minor status code.

Attribute Type Description Multiplicity Privacy
imsx_codeMinorFieldName 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'. [1] N/A
imsx_codeMinorFieldValue imsx_CodeMinorValueEnum The code minor status code (this is a value from the corresponding enumerated vocabulary). [1] N/A

imsx_StatusInfo Class

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.

Attribute Type Description Multiplicity Privacy
imsx_codeMajor imsx_CodeMajorEnum 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. [1] N/A
imsx_severity imsx_SeverityEnum The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. [1] N/A
imsx_description String A human readable description supplied by the entity creating the status code information. [0..1] N/A
imsx_CodeMinor imsx_CodeMinor The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes. [0..1] N/A

Enumeration Classes

BaseStatusEnum Enumeration

The permitted vocabulary for the status value of a record.

Attribute Type Description Multiplicity Privacy
active String An active record. [1] N/A
tobedeleted String Denotes that it is safe to delete the record. [1] N/A

ImportanceEnum Enumeration

The permitted vocabulary for the 'importance' value of a resource.

Attribute Type Description Multiplicity Privacy
primary String A resource of primary usage. [1] N/A
secondary String A resource of secondary usage/significance. [1] N/A

RoleEnum Enumeration

The permitted vocabulary for the 'role' value for the targeted user of a resource.

Attribute Type Description Multiplicity Privacy
administrator String Administrator in the organization (e.g. School). [1] N/A
aide String Someone who provides appropriate aide to the user but NOT also one of the other roles. [1] N/A
guardian String Guardian of the user and NOT the Mother or Father. May also be a Relative. [1] N/A
parent String Mother or father of the user. [1] N/A
proctor String Exam proctor. May be used for enrollment. [1] N/A
relative String A relative of the user and NOT the Mother or Father. May also be the Guardian. [1] N/A
student String A student at an organization (e.g. School). [1] N/A
teacher String A Teacher at an organization (e.g. School). [1] N/A

RoleEnumExt Enumeration

The data-type for the 'role' characteristic used to identify the type of user for whom the resources are targetted. This is an extensible enumerated vocabulary. Extending the vocabulary makes use of a naming convention.

Attribute Type Description Multiplicity Privacy
pattern String The regular expression to constrain the structure of the string that MUST be used when creating a new, proprietary, vocabulary term. The term must start with the substring 'ext:'. [1] N/A
administrator String Administrator in the organization (e.g. School). [1] N/A
aide String Someone who provides appropriate aide to the user but NOT also one of the other roles. [1] N/A
guardian String Guardian of the user and NOT the Mother or Father. May also be a Relative. [1] N/A
parent String Mother or father of the user. [1] N/A
proctor String Exam proctor. May be used for enrollment. [1] N/A
relative String A relative of the user and NOT the Mother or Father. May also be the Guardian. [1] N/A
student String A student at an organization (e.g. School). [1] N/A
teacher String A Teacher at an organization (e.g. School). [1] N/A

imsx_CodeMajorEnum Enumeration

The permitted vocabulary for the values for the CodeMajor field.

Attribute Type Description Multiplicity Privacy
success String Denotes that the request has been successfully completed. If the associated 'severity' value is 'warning' then the request has been partially successful i.e. best effort by the service provider. Other parts of the status information may provide more insight into a partial success response. [1] N/A
processing String Denotes that the request is being processed at the destination or there has been a local transmission failure. This value is used in asynchronous services. [1] N/A
failure String Denotes that the transaction request has failed. The detailed reason will be reported in the accompanying 'codeMinor' fields. [1] N/A
unsupported String Denotes that the service provider does not support the requested operation. This is the required default response for an unsupported operation by an implementation. [1] N/A

imsx_CodeMinorValueEnum Enumeration

The permitted vocabulary for the values for the CodeMinorValue field.

Attribute Type Description Multiplicity Privacy
fullsuccess String The request has been fully and successfully implemented by the Service Provider. For a REST binding this will have an HTTP code of '200' for a successful 'GET' request; '201' for a successful 'PUT' request; '204' for a successful 'DELETE' request. [1] N/A
invalid_filter_field String An invalid filter field was supplied and so the filtering was not possible. No data has been reurned. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '400'. [1] N/A
invalid_selection_field String An invalid selection field field was supplied and data filtering on the selection criteria was not possible. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '400'. [1] N/A
forbidden String This is used to indicate that the server can be reached and process the request but refuses to take any further action. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '403'. [1] N/A
unauthorisedrequest String The request was not correctly authorised. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '401'. [1] N/A
internal_server_error String This should be used only if there is catastrophic error and there is not a more appropriate code. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '500'. [1] N/A
server_busy String The server is receiving too many requests. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '429'. [1] N/A
unknownobject String The supplied identifier is unknown in the Service Provider and so the object could not be changed. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '404'. [1] N/A
invaliddata String This error condition may occur if a JSON request/response 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' and a HTTP code of '422'. [1] N/A
invalid_sort_field String An invalid sort field field was supplied and sorting on the given value was not possible. This would be accompanied by the 'codeMajor/severity' values of 'failure/error' and for a REST binding a HTTP code of '400'. [1] N/A
unsupported String Denotes that the service provider does not support the requested operation. This is the required default response for an unsupported operation by an implementation. This would be accompanied by the 'codeMajor/severity' values of 'unsupported/error' and for a REST binding a HTTP code of '500'. [1] N/A

imsx_SeverityEnum Enumeration

The permitted vocabulary for the values for the Severity field.

Attribute Type Description Multiplicity Privacy
status String The request has been completed and a response was received from the Service Provider. [1] N/A
warning String The request has only been partially completed. For an asynchronous service a further response should be expected. [1] N/A
error String A significant error has occurred in processing the request and so the request was not completed (the Service Provider may not even have received the request). [1] N/A

OrderByEnum Enumeration

The set of permitted values for the 'orderBy' query parameter.

Attribute Type Description Multiplicity Privacy
asc String No Description [1] N/A
desc String No Description [1] N/A

Derived Classes

GUID Class

The data-type for establishing a Globally Unique Identifier (GUID). This is the data-type used for a 'sourcedId'. There is no predefined structure for the GUID.

Identifier Class

The data-type for a unique identifier (but not a GUID). The format/structure of such an identifier is undefined.

RoleExtString Class

The data-type that enables the 'RoleEnum' vocabulary to be extended.

Attribute Type Description Multiplicity Privacy
pattern String The regular expression to constrain the structure of the string that MUST be used when creating a new, proprietary, vocabulary term. The term must start with the substring 'ext:'. [1] N/A

AnyURI Class

No Description

Boolean Class

No Description

Date Class

No Description

DateTime Class

No Description

Decimal Class

No Description

Integer Class

No Description

Namespace Class

No Description

This class can be extended with additional properties.

NonNegativeInteger Class

No Description

NormalizedString Class

No Description

PositiveInteger Class

No Description

String Class

No Description

Void Class

No Description

Union Classes

RoleEnumExt Class

The data-type for the 'role' characteristic used to identify the type of user for whom the resources are targetted. This is an extensible enumerated vocabulary. Extending the vocabulary makes use of a naming convention.

Attribute Type Description Multiplicity Privacy
pattern String The regular expression to constrain the structure of the string that MUST be used when creating a new, proprietary, vocabulary term. The term must start with the substring 'ext:'. [1] N/A
administrator String Administrator in the organization (e.g. School). [1] N/A
aide String Someone who provides appropriate aide to the user but NOT also one of the other roles. [1] N/A
guardian String Guardian of the user and NOT the Mother or Father. May also be a Relative. [1] N/A
parent String Mother or father of the user. [1] N/A
proctor String Exam proctor. May be used for enrollment. [1] N/A
relative String A relative of the user and NOT the Mother or Father. May also be the Guardian. [1] N/A
student String A student at an organization (e.g. School). [1] N/A
teacher String A Teacher at an organization (e.g. School). [1] N/A

Primitive Types

AnyURI Primitive Type

No Description

Boolean Primitive Type

No Description

Date Primitive Type

No Description

DateTime Primitive Type

No Description

Decimal Primitive Type

No Description

Integer Primitive Type

No Description

Namespace Primitive Type

No Description

This class can be extended with additional properties.

NonNegativeInteger Primitive Type

No Description

NormalizedString Primitive Type

No Description

PositiveInteger Primitive Type

No Description

String Primitive Type

No Description

Void Primitive Type

No Description

Extending and Profiling the Binding

This Section is NOT NORMATIVE.

Extending the Binding

Proprietary extensions of the service are based upon three approaches:

The extension of the data models being manipulated by the current set of operations (including extending vocabularies); The inclusion of new operations to support new proprietary functionality; The inclusion of new OAuth 2 scopes. 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.

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 1EdTech OneRoster 1.2 Implementation Guide Final Release 1.0.

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 1EdTech OneRoster 1.2 Implementation Guide Final Release 1.0.

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.

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.

Profiling the Binding

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

  • Refine which Interfaces are used and which operations are supported for each Interface;
  • Refine the data models by increasing the constraints on the base definitions.

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.

Model Binding Terms and Concepts

This Section is NOT NORMATIVE.

REST Endpoint Description Explanations

UML to JSON Mapping Description Explanations

OpenAPI (v2 and v3) Descriptions Explanations

OpenAPI Listings

This Section is NORMATIVE.

Listing of the OpenAPI (JSON) File

{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "OpenAPI schema for OneRoster Resources Service",
    "description" : "The OneRoster Resources Service enables the exchange of K-12 oriented resources data for rostering. This exchange is typically between the Student Information System and the learning delivery systems. The service provides a number of operations, collected as several endpoints, primarily based upon read, create and delete of the first class objects. ",
    "termsOfService" : "https://www.imsglobal.org/license.html",
    "contact" : {
      "name" : "IMS Global",
      "url" : "https://www.imsglobal.org",
      "email" : "support@imsglobal.org"
    },
    "license" : {
      "name" : "IMS Global Specification Document License",
      "url" : "https://www.imsglobal.org/license.html"
    },
    "version" : "1.2",
    "x-status" : "Final",
    "x-model-pid" : "org.1edtech.orresources.v1p2.model",
    "x-service-pid" : "org.1edtech.orresources.v1p2.rest.servicemodel",
    "x-src-operation-count" : 5,
    "x-oas-operation-count" : 5
  },
  "servers" : [ {
    "url" : "https://example.org/ims/oneroster/resources/v1p2",
    "description" : "The above Server URL should be changed to the actual server location."
  } ],
  "tags" : [ {
    "name" : "CoursesManagement",
    "description" : "This enables the management of information about resources i.e. the allocation of resources to courses. "
  }, {
    "name" : "ClassesManagement",
    "description" : "This enables the management of information about resources i.e. the allocation of resources to classes. "
  }, {
    "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" : {
    "/courses/{courseSourcedId}/resources" : {
      "get" : {
        "tags" : [ "CoursesManagement" ],
        "summary" : "The REST GET operation for the getResourcesForCourse() API call.",
        "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. ",
        "operationId" : "getResourcesForCourse",
        "parameters" : [ {
          "name" : "courseSourcedId",
          "in" : "path",
          "description" : "The unique identifier, GUID, for the course.",
          "required" : true,
          "allowEmptyValue" : false,
          "style" : "simple",
          "schema" : {
            "type" : "string",
            "description" : "The data-type for establishing a Globally Unique Identifier (GUID). This is the data-type used for a 'sourcedId'. There is no predefined structure for the GUID."
          }
        }, {
          "$ref" : "#/components/parameters/limit"
        }, {
          "$ref" : "#/components/parameters/offset"
        }, {
          "$ref" : "#/components/parameters/sort"
        }, {
          "$ref" : "#/components/parameters/orderBy"
        }, {
          "$ref" : "#/components/parameters/filter"
        }, {
          "$ref" : "#/components/parameters/fields"
        } ],
        "responses" : {
          "200" : {
            "description" : "The 200 (OK) response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ResourceSet"
                }
              }
            }
          },
          "400" : {
            "description" : "The 400 (BAD_REQUEST) response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "401" : {
            "description" : "The 401 (UNAUTHORIZED) response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "403" : {
            "description" : "The 403 (FORBIDDEN) response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "404" : {
            "description" : "The 404 (NOT_FOUND) response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "422" : {
            "description" : "The 422 (UNPROCESSABLE_ENTTITY) response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "429" : {
            "description" : "The 429 (TOO_MANY_REQUESTS) response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "500" : {
            "description" : "The 500 (INTERNAL_SERVER_ERROR) response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "default" : {
            "description" : "The default response to the getResourcesForCourse() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          }
        },
        "security" : [ {
          "OAuth2CC" : [ "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" ]
        } ],
        "x-operation-pid" : "org.1edtech.orresources.v1p2.rest.getresourcesforcourse.operation"
      }
    },
    "/classes/{classSourcedId}/resources" : {
      "get" : {
        "tags" : [ "ClassesManagement" ],
        "summary" : "The REST GET operation for the getResourcesForClass() API call.",
        "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. ",
        "operationId" : "getResourcesForClass",
        "parameters" : [ {
          "name" : "classSourcedId",
          "in" : "path",
          "description" : "The unique identifier, GUID, for this class.",
          "required" : true,
          "allowEmptyValue" : false,
          "style" : "simple",
          "schema" : {
            "type" : "string",
            "description" : "The data-type for establishing a Globally Unique Identifier (GUID). This is the data-type used for a 'sourcedId'. There is no predefined structure for the GUID."
          }
        }, {
          "$ref" : "#/components/parameters/limit"
        }, {
          "$ref" : "#/components/parameters/offset"
        }, {
          "$ref" : "#/components/parameters/sort"
        }, {
          "$ref" : "#/components/parameters/orderBy"
        }, {
          "$ref" : "#/components/parameters/filter"
        }, {
          "$ref" : "#/components/parameters/fields"
        } ],
        "responses" : {
          "200" : {
            "description" : "The 200 (OK) response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ResourceSet"
                }
              }
            }
          },
          "400" : {
            "description" : "The 400 (BAD_REQUEST) response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "401" : {
            "description" : "The 401 (UNAUTHORIZED) response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "403" : {
            "description" : "The 403 (FORBIDDEN) response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "404" : {
            "description" : "The 404 (NOT_FOUND) response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "422" : {
            "description" : "The 422 (UNPROCESSABLE_ENTTITY) response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "429" : {
            "description" : "The 429 (TOO_MANY_REQUESTS) response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "500" : {
            "description" : "The 500 (INTERNAL_SERVER_ERROR) response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "default" : {
            "description" : "The default response to the getResourcesForClass() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          }
        },
        "security" : [ {
          "OAuth2CC" : [ "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" ]
        } ],
        "x-operation-pid" : "org.1edtech.orresources.v1p2.rest.getresourcesforclass.operation"
      }
    },
    "/resources" : {
      "get" : {
        "tags" : [ "ResourcesManagement" ],
        "summary" : "The REST GET operation for the getAllResources() API call.",
        "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.",
        "operationId" : "getAllResources",
        "parameters" : [ {
          "$ref" : "#/components/parameters/limit"
        }, {
          "$ref" : "#/components/parameters/offset"
        }, {
          "$ref" : "#/components/parameters/sort"
        }, {
          "$ref" : "#/components/parameters/orderBy"
        }, {
          "$ref" : "#/components/parameters/filter"
        }, {
          "$ref" : "#/components/parameters/fields"
        } ],
        "responses" : {
          "200" : {
            "description" : "The 200 (OK) response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ResourceSet"
                }
              }
            }
          },
          "400" : {
            "description" : "The 400 (BAD_REQUEST) response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "401" : {
            "description" : "The 401 (UNAUTHORIZED) response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "403" : {
            "description" : "The 403 (FORBIDDEN) response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "404" : {
            "description" : "The 404 (NOT_FOUND) response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "422" : {
            "description" : "The 422 (UNPROCESSABLE_ENTTITY) response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "429" : {
            "description" : "The 429 (TOO_MANY_REQUESTS) response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "500" : {
            "description" : "The 500 (INTERNAL_SERVER_ERROR) response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "default" : {
            "description" : "The default response to the getAllResources() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          }
        },
        "security" : [ {
          "OAuth2CC" : [ "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly", "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" ]
        } ],
        "x-operation-pid" : "org.1edtech.orresources.v1p2.rest.getallresources.operation"
      }
    },
    "/resources/{sourcedId}" : {
      "get" : {
        "tags" : [ "ResourcesManagement" ],
        "summary" : "The REST GET operation for the getResource() API call.",
        "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. ",
        "operationId" : "getResource",
        "parameters" : [ {
          "name" : "sourcedId",
          "in" : "path",
          "description" : "The unique identifier, GUID, for the resource.",
          "required" : true,
          "allowEmptyValue" : false,
          "style" : "simple",
          "schema" : {
            "type" : "string",
            "description" : "The data-type for establishing a Globally Unique Identifier (GUID). This is the data-type used for a 'sourcedId'. There is no predefined structure for the GUID."
          }
        }, {
          "$ref" : "#/components/parameters/fields"
        } ],
        "responses" : {
          "200" : {
            "description" : "The 200 (OK) response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/SingleResource"
                }
              }
            }
          },
          "400" : {
            "description" : "The 400 (BAD_REQUEST) response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "401" : {
            "description" : "The 401 (UNAUTHORIZED) response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "403" : {
            "description" : "The 403 (FORBIDDEN) response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "404" : {
            "description" : "The 404 (NOT_FOUND) response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "422" : {
            "description" : "The 422 (UNPROCESSABLE_ENTTITY) response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "429" : {
            "description" : "The 429 (TOO_MANY_REQUESTS) response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "500" : {
            "description" : "The 500 (INTERNAL_SERVER_ERROR) response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "default" : {
            "description" : "The default response to the getResource() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          }
        },
        "security" : [ {
          "OAuth2CC" : [ "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly", "https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly" ]
        } ],
        "x-operation-pid" : "org.1edtech.orresources.v1p2.rest.getresource.operation"
      }
    },
    "/users/{userSourcedId}/resources" : {
      "get" : {
        "tags" : [ "UsersManagement" ],
        "summary" : "The REST GET operation for the getResourcesForUser() API call.",
        "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. ",
        "operationId" : "getResourcesForUser",
        "parameters" : [ {
          "name" : "userSourcedId",
          "in" : "path",
          "description" : "The unique identifier, GUID, for the user.",
          "required" : true,
          "allowEmptyValue" : false,
          "style" : "simple",
          "schema" : {
            "type" : "string",
            "description" : "The data-type for establishing a Globally Unique Identifier (GUID). This is the data-type used for a 'sourcedId'. There is no predefined structure for the GUID."
          }
        }, {
          "$ref" : "#/components/parameters/limit"
        }, {
          "$ref" : "#/components/parameters/offset"
        }, {
          "$ref" : "#/components/parameters/sort"
        }, {
          "$ref" : "#/components/parameters/orderBy"
        }, {
          "$ref" : "#/components/parameters/filter"
        }, {
          "$ref" : "#/components/parameters/fields"
        } ],
        "responses" : {
          "200" : {
            "description" : "The 200 (OK) response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/ResourceSet"
                }
              }
            }
          },
          "400" : {
            "description" : "The 400 (BAD_REQUEST) response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "401" : {
            "description" : "The 401 (UNAUTHORIZED) response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "403" : {
            "description" : "The 403 (FORBIDDEN) response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "404" : {
            "description" : "The 404 (NOT_FOUND) response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "422" : {
            "description" : "The 422 (UNPROCESSABLE_ENTTITY) response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "429" : {
            "description" : "The 429 (TOO_MANY_REQUESTS) response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "500" : {
            "description" : "The 500 (INTERNAL_SERVER_ERROR) response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          },
          "default" : {
            "description" : "The default response to the getResourcesForUser() API call.",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/imsx_StatusInfo"
                }
              }
            }
          }
        },
        "security" : [ {
          "OAuth2CC" : [ "https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly" ]
        } ],
        "x-operation-pid" : "org.1edtech.orresources.v1p2.rest.getresourcesforuser.operation"
      }
    }
  },
  "components" : {
    "schemas" : {
      "imsx_StatusInfo" : {
        "required" : [ "imsx_codeMajor", "imsx_severity" ],
        "type" : "object",
        "properties" : {
          "imsx_CodeMinor" : {
            "$ref" : "#/components/schemas/imsx_CodeMinor"
          },
          "imsx_codeMajor" : {
            "type" : "string",
            "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.",
            "enum" : [ "success", "processing", "failure", "unsupported" ],
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.imsx_codemajorenum.class"
          },
          "imsx_description" : {
            "type" : "string",
            "description" : "A human readable description supplied by the entity creating the status code information.",
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.primitive.string.class"
          },
          "imsx_severity" : {
            "type" : "string",
            "description" : "The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.",
            "enum" : [ "status", "warning", "error" ],
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.imsx_severityenum.class"
          }
        },
        "additionalProperties" : false,
        "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.",
        "x-class-pid" : "org.1edtech.orresources.v1p2.imsx_statusinfo.class"
      },
      "imsx_CodeMinor" : {
        "required" : [ "imsx_codeMinorField" ],
        "type" : "object",
        "properties" : {
          "imsx_codeMinorField" : {
            "minItems" : 1,
            "type" : "array",
            "description" : "Each reported code minor status code.",
            "items" : {
              "$ref" : "#/components/schemas/imsx_CodeMinorField"
            },
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.imsx_codeminorfield.class"
          }
        },
        "additionalProperties" : false,
        "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
        "x-class-pid" : "org.1edtech.orresources.v1p2.imsx_codeminor.class"
      },
      "SingleResource" : {
        "required" : [ "resource" ],
        "type" : "object",
        "properties" : {
          "resource" : {
            "$ref" : "#/components/schemas/Resource"
          }
        },
        "additionalProperties" : false,
        "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.",
        "x-class-pid" : "org.1edtech.orresources.v1p2.singleresource.class"
      },
      "Resource" : {
        "required" : [ "vendorResourceId", "sourcedId", "status", "dateLastModified" ],
        "type" : "object",
        "properties" : {
          "sourcedId" : {
            "type" : "string",
            "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.",
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.derived.guid.class"
          },
          "vendorResourceId" : {
            "type" : "string",
            "description" : "This is a unique identifier for the resource allocated by the vendor.",
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.derived.identifier.class"
          },
          "metadata" : {
            "$ref" : "#/components/schemas/Metadata"
          },
          "dateLastModified" : {
            "type" : "string",
            "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.",
            "format" : "date-time",
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.primitive.datetime.class"
          },
          "importance" : {
            "type" : "string",
            "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
            "enum" : [ "primary", "secondary" ],
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.importanceenum.class"
          },
          "roles" : {
            "description" : "The set of roles, types of users, who are expected to make use of the resource.",
            "anyOf" : [ {
              "type" : "string",
              "enum" : [ "administrator", "aide", "guardian", "parent", "proctor", "relative", "student", "teacher" ]
            }, {
              "pattern" : "(ext:)[a-zA-Z0-9\\.\\-_]+",
              "type" : "string"
            } ],
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.roleenumext.class"
          },
          "vendorId" : {
            "type" : "string",
            "description" : "Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.derived.identifier.class"
          },
          "title" : {
            "type" : "string",
            "description" : "A human readable title/label for the resource.",
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.primitive.normalizedstring.class"
          },
          "applicationId" : {
            "type" : "string",
            "description" : "Identifier for the application associated with the resource. The nature, and how this identifier is assigned is not defined by this specification.",
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.derived.identifier.class"
          },
          "status" : {
            "type" : "string",
            "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'.",
            "enum" : [ "active", "tobedeleted" ],
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.basestatusenum.class"
          }
        },
        "additionalProperties" : false,
        "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.",
        "x-class-pid" : "org.1edtech.orresources.v1p2.resource.class"
      },
      "Metadata" : {
        "type" : "object",
        "properties" : { },
        "additionalProperties" : true,
        "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
        "x-class-pid" : "org.1edtech.orresources.v1p2.metadata.class"
      },
      "ResourceSet" : {
        "type" : "object",
        "properties" : {
          "resources" : {
            "minItems" : 0,
            "type" : "array",
            "description" : "The set of contained resource identfiers.",
            "items" : {
              "$ref" : "#/components/schemas/Resource"
            },
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.resource.class"
          }
        },
        "additionalProperties" : false,
        "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.",
        "x-class-pid" : "org.1edtech.orresources.v1p2.resourceset.class"
      },
      "imsx_CodeMinorField" : {
        "required" : [ "imsx_codeMinorFieldName", "imsx_codeMinorFieldValue" ],
        "type" : "object",
        "properties" : {
          "imsx_codeMinorFieldName" : {
            "type" : "string",
            "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'.",
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.primitive.normalizedstring.class"
          },
          "imsx_codeMinorFieldValue" : {
            "type" : "string",
            "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
            "enum" : [ "fullsuccess", "invalid_filter_field", "invalid_selection_field", "forbidden", "unauthorisedrequest", "internal_server_error", "server_busy", "unknownobject", "invaliddata", "invalid_sort_field", "unsupported" ],
            "x-srcprop-pid" : "org.1edtech.orresources.v1p2.imsx_codeminorvalueenum.class"
          }
        },
        "additionalProperties" : false,
        "description" : "This is the container for a single code minor status code.",
        "x-class-pid" : "org.1edtech.orresources.v1p2.imsx_codeminorfield.class"
      }
    },
    "parameters" : {
      "filter" : {
        "name" : "filter",
        "in" : "query",
        "description" : "The filtering rules to be applied when identifying the records to be supplied in the response message.",
        "required" : false,
        "allowEmptyValue" : false,
        "style" : "form",
        "schema" : {
          "type" : "string"
        }
      },
      "offset" : {
        "name" : "offset",
        "in" : "query",
        "description" : "The number of the first record to be supplied in the segmented response message.",
        "required" : false,
        "allowEmptyValue" : false,
        "style" : "form",
        "schema" : {
          "minimum" : 0,
          "type" : "integer",
          "format" : "int32"
        }
      },
      "limit" : {
        "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,
        "allowEmptyValue" : false,
        "style" : "form",
        "schema" : {
          "minimum" : 1,
          "type" : "integer",
          "format" : "int32"
        }
      },
      "orderBy" : {
        "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,
        "allowEmptyValue" : false,
        "style" : "form",
        "schema" : {
          "type" : "string",
          "description" : "The set of permitted values for the 'orderBy' query parameter.",
          "enum" : [ "asc", "desc" ]
        }
      },
      "sort" : {
        "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,
        "allowEmptyValue" : false,
        "style" : "form",
        "schema" : {
          "type" : "string"
        }
      },
      "fields" : {
        "name" : "fields",
        "in" : "query",
        "description" : "To identify the range of fields that should be supplied in the response message.",
        "required" : false,
        "allowEmptyValue" : false,
        "style" : "form",
        "schema" : {
          "type" : "string"
        }
      }
    },
    "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."
            }
          }
        }
      }
    }
  }
}

Listing of the OpenAPI (YAML) File

openapi: 3.0.1
info:
  title: OpenAPI schema for OneRoster Resources Service
  description: "The OneRoster Resources Service enables the exchange of K-12 oriented\
    \ resources data for rostering. This exchange is typically between the Student\
    \ Information System and the learning delivery systems. The service provides a\
    \ number of operations, collected as several endpoints, primarily based upon read,\
    \ create and delete of the first class objects. "
  termsOfService: https://www.imsglobal.org/license.html
  contact:
    name: IMS Global
    url: https://www.imsglobal.org
    email: support@imsglobal.org
  license:
    name: IMS Global Specification Document License
    url: https://www.imsglobal.org/license.html
  version: "1.2"
  x-status: Final
  x-model-pid: org.1edtech.orresources.v1p2.model
  x-service-pid: org.1edtech.orresources.v1p2.rest.servicemodel
  x-src-operation-count: 5
  x-oas-operation-count: 5
servers:
- url: https://example.org/ims/oneroster/resources/v1p2
  description: The above Server URL should be changed to the actual server location.
tags:
- name: CoursesManagement
  description: 'This enables the management of information about resources i.e. the
    allocation of resources to courses. '
- name: ClassesManagement
  description: 'This enables the management of information about resources i.e. the
    allocation of resources to classes. '
- 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:
  /courses/{courseSourcedId}/resources:
    get:
      tags:
      - CoursesManagement
      summary: The REST GET operation for the getResourcesForCourse() API call.
      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. "
      operationId: getResourcesForCourse
      parameters:
      - name: courseSourcedId
        in: path
        description: "The unique identifier, GUID, for the course."
        required: true
        allowEmptyValue: false
        style: simple
        schema:
          type: string
          description: The data-type for establishing a Globally Unique Identifier
            (GUID). This is the data-type used for a 'sourcedId'. There is no predefined
            structure for the GUID.
      - $ref: "#/components/parameters/limit"
      - $ref: "#/components/parameters/offset"
      - $ref: "#/components/parameters/sort"
      - $ref: "#/components/parameters/orderBy"
      - $ref: "#/components/parameters/filter"
      - $ref: "#/components/parameters/fields"
      responses:
        "200":
          description: The 200 (OK) response to the getResourcesForCourse() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceSet"
        "400":
          description: The 400 (BAD_REQUEST) response to the getResourcesForCourse()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "401":
          description: The 401 (UNAUTHORIZED) response to the getResourcesForCourse()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "403":
          description: The 403 (FORBIDDEN) response to the getResourcesForCourse()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "404":
          description: The 404 (NOT_FOUND) response to the getResourcesForCourse()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "422":
          description: The 422 (UNPROCESSABLE_ENTTITY) response to the getResourcesForCourse()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "429":
          description: The 429 (TOO_MANY_REQUESTS) response to the getResourcesForCourse()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "500":
          description: The 500 (INTERNAL_SERVER_ERROR) response to the getResourcesForCourse()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        default:
          description: The default response to the getResourcesForCourse() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
      security:
      - OAuth2CC:
        - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
      x-operation-pid: org.1edtech.orresources.v1p2.rest.getresourcesforcourse.operation
  /classes/{classSourcedId}/resources:
    get:
      tags:
      - ClassesManagement
      summary: The REST GET operation for the getResourcesForClass() API call.
      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. "
      operationId: getResourcesForClass
      parameters:
      - name: classSourcedId
        in: path
        description: "The unique identifier, GUID, for this class."
        required: true
        allowEmptyValue: false
        style: simple
        schema:
          type: string
          description: The data-type for establishing a Globally Unique Identifier
            (GUID). This is the data-type used for a 'sourcedId'. There is no predefined
            structure for the GUID.
      - $ref: "#/components/parameters/limit"
      - $ref: "#/components/parameters/offset"
      - $ref: "#/components/parameters/sort"
      - $ref: "#/components/parameters/orderBy"
      - $ref: "#/components/parameters/filter"
      - $ref: "#/components/parameters/fields"
      responses:
        "200":
          description: The 200 (OK) response to the getResourcesForClass() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceSet"
        "400":
          description: The 400 (BAD_REQUEST) response to the getResourcesForClass()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "401":
          description: The 401 (UNAUTHORIZED) response to the getResourcesForClass()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "403":
          description: The 403 (FORBIDDEN) response to the getResourcesForClass()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "404":
          description: The 404 (NOT_FOUND) response to the getResourcesForClass()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "422":
          description: The 422 (UNPROCESSABLE_ENTTITY) response to the getResourcesForClass()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "429":
          description: The 429 (TOO_MANY_REQUESTS) response to the getResourcesForClass()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "500":
          description: The 500 (INTERNAL_SERVER_ERROR) response to the getResourcesForClass()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        default:
          description: The default response to the getResourcesForClass() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
      security:
      - OAuth2CC:
        - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
      x-operation-pid: org.1edtech.orresources.v1p2.rest.getresourcesforclass.operation
  /resources:
    get:
      tags:
      - ResourcesManagement
      summary: The REST GET operation for the getAllResources() API call.
      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."
      operationId: getAllResources
      parameters:
      - $ref: "#/components/parameters/limit"
      - $ref: "#/components/parameters/offset"
      - $ref: "#/components/parameters/sort"
      - $ref: "#/components/parameters/orderBy"
      - $ref: "#/components/parameters/filter"
      - $ref: "#/components/parameters/fields"
      responses:
        "200":
          description: The 200 (OK) response to the getAllResources() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceSet"
        "400":
          description: The 400 (BAD_REQUEST) response to the getAllResources() API
            call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "401":
          description: The 401 (UNAUTHORIZED) response to the getAllResources() API
            call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "403":
          description: The 403 (FORBIDDEN) response to the getAllResources() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "404":
          description: The 404 (NOT_FOUND) response to the getAllResources() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "422":
          description: The 422 (UNPROCESSABLE_ENTTITY) response to the getAllResources()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "429":
          description: The 429 (TOO_MANY_REQUESTS) response to the getAllResources()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "500":
          description: The 500 (INTERNAL_SERVER_ERROR) response to the getAllResources()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        default:
          description: The default response to the getAllResources() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
      security:
      - OAuth2CC:
        - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
        - https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
      x-operation-pid: org.1edtech.orresources.v1p2.rest.getallresources.operation
  /resources/{sourcedId}:
    get:
      tags:
      - ResourcesManagement
      summary: The REST GET operation for the getResource() API call.
      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. "
      operationId: getResource
      parameters:
      - name: sourcedId
        in: path
        description: "The unique identifier, GUID, for the resource."
        required: true
        allowEmptyValue: false
        style: simple
        schema:
          type: string
          description: The data-type for establishing a Globally Unique Identifier
            (GUID). This is the data-type used for a 'sourcedId'. There is no predefined
            structure for the GUID.
      - $ref: "#/components/parameters/fields"
      responses:
        "200":
          description: The 200 (OK) response to the getResource() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SingleResource"
        "400":
          description: The 400 (BAD_REQUEST) response to the getResource() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "401":
          description: The 401 (UNAUTHORIZED) response to the getResource() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "403":
          description: The 403 (FORBIDDEN) response to the getResource() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "404":
          description: The 404 (NOT_FOUND) response to the getResource() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "422":
          description: The 422 (UNPROCESSABLE_ENTTITY) response to the getResource()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "429":
          description: The 429 (TOO_MANY_REQUESTS) response to the getResource() API
            call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "500":
          description: The 500 (INTERNAL_SERVER_ERROR) response to the getResource()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        default:
          description: The default response to the getResource() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
      security:
      - OAuth2CC:
        - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
        - https://purl.imsglobal.org/spec/or/v1p2/scope/resource-core.readonly
      x-operation-pid: org.1edtech.orresources.v1p2.rest.getresource.operation
  /users/{userSourcedId}/resources:
    get:
      tags:
      - UsersManagement
      summary: The REST GET operation for the getResourcesForUser() API call.
      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. "
      operationId: getResourcesForUser
      parameters:
      - name: userSourcedId
        in: path
        description: "The unique identifier, GUID, for the user."
        required: true
        allowEmptyValue: false
        style: simple
        schema:
          type: string
          description: The data-type for establishing a Globally Unique Identifier
            (GUID). This is the data-type used for a 'sourcedId'. There is no predefined
            structure for the GUID.
      - $ref: "#/components/parameters/limit"
      - $ref: "#/components/parameters/offset"
      - $ref: "#/components/parameters/sort"
      - $ref: "#/components/parameters/orderBy"
      - $ref: "#/components/parameters/filter"
      - $ref: "#/components/parameters/fields"
      responses:
        "200":
          description: The 200 (OK) response to the getResourcesForUser() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ResourceSet"
        "400":
          description: The 400 (BAD_REQUEST) response to the getResourcesForUser()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "401":
          description: The 401 (UNAUTHORIZED) response to the getResourcesForUser()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "403":
          description: The 403 (FORBIDDEN) response to the getResourcesForUser() API
            call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "404":
          description: The 404 (NOT_FOUND) response to the getResourcesForUser() API
            call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "422":
          description: The 422 (UNPROCESSABLE_ENTTITY) response to the getResourcesForUser()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "429":
          description: The 429 (TOO_MANY_REQUESTS) response to the getResourcesForUser()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        "500":
          description: The 500 (INTERNAL_SERVER_ERROR) response to the getResourcesForUser()
            API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
        default:
          description: The default response to the getResourcesForUser() API call.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/imsx_StatusInfo"
      security:
      - OAuth2CC:
        - https://purl.imsglobal.org/spec/or/v1p2/scope/resource.readonly
      x-operation-pid: org.1edtech.orresources.v1p2.rest.getresourcesforuser.operation
components:
  schemas:
    imsx_StatusInfo:
      required:
      - imsx_codeMajor
      - imsx_severity
      type: object
      properties:
        imsx_CodeMinor:
          $ref: "#/components/schemas/imsx_CodeMinor"
        imsx_codeMajor:
          type: string
          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.
          enum:
          - success
          - processing
          - failure
          - unsupported
          x-srcprop-pid: org.1edtech.orresources.v1p2.imsx_codemajorenum.class
        imsx_description:
          type: string
          description: A human readable description supplied by the entity creating
            the status code information.
          x-srcprop-pid: org.1edtech.orresources.v1p2.primitive.string.class
        imsx_severity:
          type: string
          description: The severity value (from the corresponding enumerated vocabulary).
            See Appendix B for further information on the interpretation of this set
            of codes.
          enum:
          - status
          - warning
          - error
          x-srcprop-pid: org.1edtech.orresources.v1p2.imsx_severityenum.class
      additionalProperties: false
      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.
      x-class-pid: org.1edtech.orresources.v1p2.imsx_statusinfo.class
    imsx_CodeMinor:
      required:
      - imsx_codeMinorField
      type: object
      properties:
        imsx_codeMinorField:
          minItems: 1
          type: array
          description: Each reported code minor status code.
          items:
            $ref: "#/components/schemas/imsx_CodeMinorField"
          x-srcprop-pid: org.1edtech.orresources.v1p2.imsx_codeminorfield.class
      additionalProperties: false
      description: This is the container for the set of code minor status codes reported
        in the responses from the Service Provider.
      x-class-pid: org.1edtech.orresources.v1p2.imsx_codeminor.class
    SingleResource:
      required:
      - resource
      type: object
      properties:
        resource:
          $ref: "#/components/schemas/Resource"
      additionalProperties: false
      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.
      x-class-pid: org.1edtech.orresources.v1p2.singleresource.class
    Resource:
      required:
      - vendorResourceId
      - sourcedId
      - status
      - dateLastModified
      type: object
      properties:
        sourcedId:
          type: string
          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."
          x-srcprop-pid: org.1edtech.orresources.v1p2.derived.guid.class
        vendorResourceId:
          type: string
          description: This is a unique identifier for the resource allocated by the
            vendor.
          x-srcprop-pid: org.1edtech.orresources.v1p2.derived.identifier.class
        metadata:
          $ref: "#/components/schemas/Metadata"
        dateLastModified:
          type: string
          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."
          format: date-time
          x-srcprop-pid: org.1edtech.orresources.v1p2.primitive.datetime.class
        importance:
          type: string
          description: This is an indicator of the significance of the resource i.e.
            primary or secondary.
          enum:
          - primary
          - secondary
          x-srcprop-pid: org.1edtech.orresources.v1p2.importanceenum.class
        roles:
          description: "The set of roles, types of users, who are expected to make\
            \ use of the resource."
          anyOf:
          - type: string
            enum:
            - administrator
            - aide
            - guardian
            - parent
            - proctor
            - relative
            - student
            - teacher
          - pattern: "(ext:)[a-zA-Z0-9\\.\\-_]+"
            type: string
          x-srcprop-pid: org.1edtech.orresources.v1p2.roleenumext.class
        vendorId:
          type: string
          description: Identifier for the vendor who created the resource. This will
            be assigned by 1EdTech as part of Conformance Certification.
          x-srcprop-pid: org.1edtech.orresources.v1p2.derived.identifier.class
        title:
          type: string
          description: A human readable title/label for the resource.
          x-srcprop-pid: org.1edtech.orresources.v1p2.primitive.normalizedstring.class
        applicationId:
          type: string
          description: "Identifier for the application associated with the resource.\
            \ The nature, and how this identifier is assigned is not defined by this\
            \ specification."
          x-srcprop-pid: org.1edtech.orresources.v1p2.derived.identifier.class
        status:
          type: string
          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'."
          enum:
          - active
          - tobedeleted
          x-srcprop-pid: org.1edtech.orresources.v1p2.basestatusenum.class
      additionalProperties: false
      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."
      x-class-pid: org.1edtech.orresources.v1p2.resource.class
    Metadata:
      type: object
      properties: {}
      additionalProperties: true
      description: This is the container for the data model extensions that may be
        assigned to the associated class of objects.
      x-class-pid: org.1edtech.orresources.v1p2.metadata.class
    ResourceSet:
      type: object
      properties:
        resources:
          minItems: 0
          type: array
          description: The set of contained resource identfiers.
          items:
            $ref: "#/components/schemas/Resource"
          x-srcprop-pid: org.1edtech.orresources.v1p2.resource.class
      additionalProperties: false
      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.
      x-class-pid: org.1edtech.orresources.v1p2.resourceset.class
    imsx_CodeMinorField:
      required:
      - imsx_codeMinorFieldName
      - imsx_codeMinorFieldValue
      type: object
      properties:
        imsx_codeMinorFieldName:
          type: string
          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'.
          x-srcprop-pid: org.1edtech.orresources.v1p2.primitive.normalizedstring.class
        imsx_codeMinorFieldValue:
          type: string
          description: The code minor status code (this is a value from the corresponding
            enumerated vocabulary).
          enum:
          - fullsuccess
          - invalid_filter_field
          - invalid_selection_field
          - forbidden
          - unauthorisedrequest
          - internal_server_error
          - server_busy
          - unknownobject
          - invaliddata
          - invalid_sort_field
          - unsupported
          x-srcprop-pid: org.1edtech.orresources.v1p2.imsx_codeminorvalueenum.class
      additionalProperties: false
      description: This is the container for a single code minor status code.
      x-class-pid: org.1edtech.orresources.v1p2.imsx_codeminorfield.class
  parameters:
    filter:
      name: filter
      in: query
      description: The filtering rules to be applied when identifying the records
        to be supplied in the response message.
      required: false
      allowEmptyValue: false
      style: form
      schema:
        type: string
    offset:
      name: offset
      in: query
      description: The number of the first record to be supplied in the segmented
        response message.
      required: false
      allowEmptyValue: false
      style: form
      schema:
        minimum: 0
        type: integer
        format: int32
    limit:
      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
      allowEmptyValue: false
      style: form
      schema:
        minimum: 1
        type: integer
        format: int32
    orderBy:
      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
      allowEmptyValue: false
      style: form
      schema:
        type: string
        description: The set of permitted values for the 'orderBy' query parameter.
        enum:
        - asc
        - desc
    sort:
      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
      allowEmptyValue: false
      style: form
      schema:
        type: string
    fields:
      name: fields
      in: query
      description: To identify the range of fields that should be supplied in the
        response message.
      required: false
      allowEmptyValue: false
      style: form
      schema:
        type: string
  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.

JSON Schema Listings

JSON Schemas for Payload Validation

GUID

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "GUID",
  "title" : "JSON Schema for the GUID class.",
  "description" : "The data-type for establishing a Globally Unique Identifier (GUID). This is the data-type used for a 'sourcedId'. There is no predefined structure for the GUID.",
  "type" : "object",
  "properties" : { },
  "required" : [ ],
  "additionalProperties" : false
}

NonNegativeInteger

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "NonNegativeInteger",
  "title" : "JSON Schema for the NonNegativeInteger class.",
  "description" : "No description supplied.",
  "type" : "object",
  "properties" : { },
  "required" : [ ],
  "additionalProperties" : false
}

OrderByEnum

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "OrderByEnum",
  "title" : "JSON Schema for the OrderByEnum class.",
  "description" : "The set of permitted values for the 'orderBy' query parameter.",
  "type" : "object",
  "properties" : {
    "asc" : {
      "description" : "No description supplied.",
      "$comment" : "Origin: String (PrimitiveType)",
      "type" : "string"
    },
    "desc" : {
      "description" : "No description supplied.",
      "$comment" : "Origin: String (PrimitiveType)",
      "type" : "string"
    }
  },
  "required" : [ "asc", "desc" ],
  "additionalProperties" : false
}

PositiveInteger

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "PositiveInteger",
  "title" : "JSON Schema for the PositiveInteger class.",
  "description" : "No description supplied.",
  "type" : "object",
  "properties" : { },
  "required" : [ ],
  "additionalProperties" : false
}

ResourceSet

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "ResourceSet",
  "title" : "JSON Schema for the ResourceSet class.",
  "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" : {
      "type" : "array",
      "items" : {
        "$ref" : "#/$defs/Resource"
      }
    }
  },
  "required" : [ ],
  "additionalProperties" : false,
  "$defs" : {
    "Resource" : {
      "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" : {
        "title" : {
          "description" : "A human readable title/label for the resource.",
          "$comment" : "Origin: NormalizedString (PrimitiveType)",
          "type" : "string"
        },
        "roles" : {
          "type" : "array",
          "items" : {
            "description" : "The set of roles, types of users, who are expected to make use of the resource.",
            "$comment" : "Origin: RoleEnumExt (Union); The data-type for the 'role' characteristic used to identify the type of user for whom the resources are targetted. This is an extensible enumerated vocabulary. Extending the vocabulary makes use of a naming convention.",
            "oneOf" : [ {
              "type" : "string",
              "enum" : [ "administrator", "aide", "guardian", "parent", "proctor", "relative", "student", "teacher" ]
            }, {
              "type" : "string",
              "pattern" : "(ext:)[a-z|A-Z|0-9|.|-|_]+"
            } ]
          }
        },
        "importance" : {
          "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
          "$comment" : "Origin: ImportanceEnum (Enumeration); The permitted vocabulary for the 'importance' value of a resource.",
          "type" : "string",
          "enum" : [ "primary", "secondary" ]
        },
        "vendorResourceId" : {
          "description" : "This is a unique identifier for the resource allocated by the vendor.",
          "$comment" : "Origin: Identifier (DerivedType); The data-type for a unique identifier (but not a GUID). The format/structure of such an identifier is undefined.",
          "type" : "string"
        },
        "vendorId" : {
          "description" : "Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
          "$comment" : "Origin: Identifier (DerivedType); The data-type for a unique identifier (but not a GUID). The format/structure of such an identifier is undefined.",
          "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.",
          "$comment" : "Origin: Identifier (DerivedType); The data-type for a unique identifier (but not a GUID). The format/structure of such an identifier is undefined.",
          "type" : "string"
        },
        "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.",
          "$comment" : "Origin: GUID (DerivedType); The data-type for establishing a Globally Unique Identifier (GUID). This is the data-type used for a 'sourcedId'. There is no predefined structure for the GUID.",
          "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'.",
          "$comment" : "Origin: BaseStatusEnum (Enumeration); The permitted vocabulary for the status value of a record.",
          "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.",
          "$comment" : "Origin: DateTime (PrimitiveType)",
          "type" : "string",
          "format" : "date-time"
        },
        "metadata" : {
          "$ref" : "#/$defs/Metadata"
        }
      },
      "required" : [ "vendorResourceId", "sourcedId", "status", "dateLastModified" ],
      "additionalProperties" : false
    },
    "Metadata" : {
      "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
      "type" : "object",
      "properties" : { },
      "required" : [ ],
      "additionalProperties" : true
    }
  }
}

SingleResource

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "SingleResource",
  "title" : "JSON Schema for the SingleResource class.",
  "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" : "#/$defs/Resource"
    }
  },
  "required" : [ "resource" ],
  "additionalProperties" : false,
  "$defs" : {
    "Resource" : {
      "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" : {
        "title" : {
          "description" : "A human readable title/label for the resource.",
          "$comment" : "Origin: NormalizedString (PrimitiveType)",
          "type" : "string"
        },
        "roles" : {
          "type" : "array",
          "items" : {
            "description" : "The set of roles, types of users, who are expected to make use of the resource.",
            "$comment" : "Origin: RoleEnumExt (Union); The data-type for the 'role' characteristic used to identify the type of user for whom the resources are targetted. This is an extensible enumerated vocabulary. Extending the vocabulary makes use of a naming convention.",
            "oneOf" : [ {
              "type" : "string",
              "enum" : [ "administrator", "aide", "guardian", "parent", "proctor", "relative", "student", "teacher" ]
            }, {
              "type" : "string",
              "pattern" : "(ext:)[a-z|A-Z|0-9|.|-|_]+"
            } ]
          }
        },
        "importance" : {
          "description" : "This is an indicator of the significance of the resource i.e. primary or secondary.",
          "$comment" : "Origin: ImportanceEnum (Enumeration); The permitted vocabulary for the 'importance' value of a resource.",
          "type" : "string",
          "enum" : [ "primary", "secondary" ]
        },
        "vendorResourceId" : {
          "description" : "This is a unique identifier for the resource allocated by the vendor.",
          "$comment" : "Origin: Identifier (DerivedType); The data-type for a unique identifier (but not a GUID). The format/structure of such an identifier is undefined.",
          "type" : "string"
        },
        "vendorId" : {
          "description" : "Identifier for the vendor who created the resource. This will be assigned by 1EdTech as part of Conformance Certification.",
          "$comment" : "Origin: Identifier (DerivedType); The data-type for a unique identifier (but not a GUID). The format/structure of such an identifier is undefined.",
          "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.",
          "$comment" : "Origin: Identifier (DerivedType); The data-type for a unique identifier (but not a GUID). The format/structure of such an identifier is undefined.",
          "type" : "string"
        },
        "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.",
          "$comment" : "Origin: GUID (DerivedType); The data-type for establishing a Globally Unique Identifier (GUID). This is the data-type used for a 'sourcedId'. There is no predefined structure for the GUID.",
          "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'.",
          "$comment" : "Origin: BaseStatusEnum (Enumeration); The permitted vocabulary for the status value of a record.",
          "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.",
          "$comment" : "Origin: DateTime (PrimitiveType)",
          "type" : "string",
          "format" : "date-time"
        },
        "metadata" : {
          "$ref" : "#/$defs/Metadata"
        }
      },
      "required" : [ "vendorResourceId", "sourcedId", "status", "dateLastModified" ],
      "additionalProperties" : false
    },
    "Metadata" : {
      "description" : "This is the container for the data model extensions that may be assigned to the associated class of objects.",
      "type" : "object",
      "properties" : { },
      "required" : [ ],
      "additionalProperties" : true
    }
  }
}

String

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "String",
  "title" : "JSON Schema for the String class.",
  "description" : "No description supplied.",
  "type" : "object",
  "properties" : { },
  "required" : [ ],
  "additionalProperties" : false
}

imsx_StatusInfo

{
  "$schema" : "https://json-schema.org/draft/2019-09/schema#",
  "$id" : "imsx_StatusInfo",
  "title" : "JSON Schema for the imsx_StatusInfo class.",
  "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.",
      "$comment" : "Origin: imsx_CodeMajorEnum (Enumeration); 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.",
      "$comment" : "Origin: imsx_SeverityEnum (Enumeration); The permitted vocabulary for the values for the Severity field.",
      "type" : "string",
      "enum" : [ "status", "warning", "error" ]
    },
    "imsx_description" : {
      "description" : "A human readable description supplied by the entity creating the status code information.",
      "$comment" : "Origin: String (PrimitiveType)",
      "type" : "string"
    },
    "imsx_CodeMinor" : {
      "$ref" : "#/$defs/imsx_CodeMinor"
    }
  },
  "required" : [ "imsx_codeMajor", "imsx_severity" ],
  "additionalProperties" : false,
  "$defs" : {
    "imsx_CodeMinor" : {
      "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" : {
          "type" : "array",
          "minItems" : 1,
          "items" : {
            "$ref" : "#/$defs/imsx_CodeMinorField"
          }
        }
      },
      "required" : [ "imsx_codeMinorField" ],
      "additionalProperties" : false
    },
    "imsx_CodeMinorField" : {
      "description" : "This is the container for a single code minor status code.",
      "type" : "object",
      "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'.",
          "$comment" : "Origin: NormalizedString (PrimitiveType)",
          "type" : "string"
        },
        "imsx_codeMinorFieldValue" : {
          "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
          "$comment" : "Origin: imsx_CodeMinorValueEnum (Enumeration); The permitted vocabulary for the values for the CodeMinorValue field.",
          "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
    }
  }
}

IP Disclosures

The following participating organizations have made explicit license commitments to this specification:

Organization Name Date election made Necessary claims Type
SameGoal Inc 2022-07-21 No RF RAND (Required & Optional Elements)
Infinite Campus Inc 2022-07-25 No RF RAND (Required & Optional Elements)
D2L Corporation 2022-07-21 No RF RAND (Required & Optional Elements)
Gwinnett County Public Schools 2022-07-22 No RF RAND (Required & Optional Elements)
Microsoft Corporation 2022-08-08 No RF RAND (Required & Optional Elements)
Anthology Inc. 2022-08-10 No RF RAND (Required & Optional Elements)

List of Contributors

The following individuals contributed to the development of this document:

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

Changelog

Changelog entries are not listed yet.

Revision History

VersionDoc VersionDateComments
Final Release2015-07-01First release of the OneRoster Service specification.
Final Release2016-11-01This second release includes new operations to create and delete single objects, support for the exchange of Result, LineItem, Category and Resource objects.
Final Release2022-09-19This 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().