IMS Final Release

IMS Global Logo

IMS LTI Resource Search Service REST/JSON Binding Version 1.0

IMS Final Release
Version 1.0

Date Issued: 10th September, 2018
Latest version: http://www.imsglobal.org/lti-rs/

IPR and Distribution Notices

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

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

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

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

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

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

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

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

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

Document Name: IMS LTI Resource Search Service REST/JSON Binding v1.0

Revision: 10th September, 2018

toc | top

Abstract

The Learning Tools Interoperability (LTI) Resource Search specification defines how to search digital repositories for a set of resources via a web services API. The standard addresses searching learning object repositories (LORs), and other catalogs of learning resources. The specification supports executing these search from learning tools using various attributes of resources and returning full metadata about the resources to the learning tools. Results can be launched either as URLs or LTI links. The goal of the LTI Resource Search standard is a standard way for students and teachers to be able to search resource providers, such as learning object repositories, from single sources or aggregated from multiple sources, within a learning object consumer such as a learning management system or other educational platform.

toc | top

Table of Contents

Abstract

1. Introduction

1.1 Scope and Context

1.2 Conventions

1.3 Structure of this Document

1.4 Nomenclature

2. The REST Endpoints

2.1 Mapping of the Service Operations to the REST Endpoints

2.2 API Root URL and Versioning

2.3 Predefined Endpoint Query Parameters

2.3.1 "getAllSubjects" Endpoint Query Parameters

2.3.2 "searchForResources" Endpoint Query Parameters

2.3.2.1 "limit" Query Parameter

2.3.2.2 "offset" Query Parameter

2.3.2.3 "filter" Query Parameter

2.3.2.4 "sort" Query Parameter

2.3.2.5 "orderBy" Query Parameter

2.3.2.6 "fields" Query Parameter

2.4 HTTP Code Handling

3. Using the Endpoint Query Parameters

3.1 Searching for Resources

3.2 Field Selection

3.3 Sorting and Ordering

3.4 Pagination

4. Security Framework

5. UML to JSON Payload Mapping

5.1 Service Parameter Payload Properties UML/JSON Mapping

5.2 Service Parameter Payload Class UML/JSON Mapping

5.2.1 ResourceSet Service Parameter Payload Class Mapping

5.2.2 SubjectSet Service Parameter Payload Class Mapping

5.3 Payload Classes UML/JSON Mapping

5.3.1 CCLTILink Payload Class Mapping

5.3.2 CSMSet Payload Class Mapping

5.3.3 CurriculumStandardsMetadata Payload Class Mapping

5.3.4 LTILink Payload Class Mapping

5.3.5 LTILinkResourceRef Payload Class Mapping

5.3.6 LabelledGUID Payload Class Mapping

5.3.7 LearningObjectives Payload Class Mapping

5.3.8 Metadata Payload Class Mapping

5.3.9 PlatformPropertySet Payload Class Mapping

5.3.10 Property Payload Class Mapping

5.3.11 PropertySet Payload Class Mapping

5.3.12 Resource Payload Class Mapping

5.3.13 SetOfGUIDs Payload Class Mapping

5.3.14 Subject Payload Class Mapping

5.3.15 TextComplexity Payload Class Mapping

5.3.16 Vendor Payload Class Mapping

5.3.17 imsx_CodeMinor Payload Class Mapping

5.3.18 imsx_CodeMinorField Payload Class Mapping

5.3.19 imsx_StatusInfo Payload Class Mapping

5.4 Enumerated Class UML/JSON Mapping

5.5 Enumerated List Class UML/JSON Mapping

5.6 Primitive Type UML/JSON Mapping

6. JSON Payloads

6.1 "getAllSubjects" Request Payload

6.2 "getAllSubjects" Response Payload

6.2.1 Response Payloads for the HTTP Codes (200)

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

6.3 "searchForResources" Request Payload

6.4 "searchForResources" Response Payload

6.4.1 Response Payloads for the HTTP Codes (200)

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

7. Extending and Profiling the Service

7.1 Extending the Service

7.1.1 Proprietary Operations

7.1.2 Proprietary Data Elements

7.2 Profiling the Service

References

Appendix A REST/JSON Modeling Terms

A1 REST Endpoint Description Explanations

A1.1 REST Endpoint Mapping Table Explanation

A1.2 Query Parameter Table Explanation

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

A2 UML to JSON Mapping Description Explanations

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

A2.2 UML/JSON Payload Class Mapping Table Definition

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

A2.4 UML/JSON Primitive Types Mapping Table Definition

About this Document

List of Contributors

Revision History

toc | top

List of Tables

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

Table 2.3.2.1 - The definition of the "limit" query parameter for the "searchForResources" operation.

Table 2.3.2.2 - The definition of the "offset" query parameter for the "searchForResources" operation.

Table 2.3.2.3 - The definition of the "filter" query parameter for the "searchForResources" operation.

Table 2.3.2.4 - The definition of the "sort" query parameter for the "searchForResources" operation.

Table 2.3.2.5 - The definition of the "orderBy" query parameter for the "searchForResources" operation.

Table 2.3.2.6 - The definition of the "fields" query parameter for the "searchForResources" operation.

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

Table 5.1 - UML/JSON Mapping for the Service Parameters

Table 5.2.1 - UML/JSON Mapping for the "ResourceSet" Service Parameter Payload Class

Table 5.2.2 - UML/JSON Mapping for the "SubjectSet" Service Parameter Payload Class

Table 5.3.1 - Payload UML/JSON Mapping for the "CCLTILink" Class

Table 5.3.2 - Payload UML/JSON Mapping for the "CSMSet" Class

Table 5.3.3 - Payload UML/JSON Mapping for the "CurriculumStandardsMetadata" Class

Table 5.3.4 - Payload UML/JSON Mapping for the "LTILink" Class

Table 5.3.5 - Payload UML/JSON Mapping for the "LTILinkResourceRef" Class

Table 5.3.6 - Payload UML/JSON Mapping for the "LabelledGUID" Class

Table 5.3.7 - Payload UML/JSON Mapping for the "LearningObjectives" Class

Table 5.3.8 - Payload UML/JSON Mapping for the "Metadata" Class

Table 5.3.9 - Payload UML/JSON Mapping for the "PlatformPropertySet" Class

Table 5.3.10 - Payload UML/JSON Mapping for the "Property" Class

Table 5.3.11 - Payload UML/JSON Mapping for the "PropertySet" Class

Table 5.3.12 - Payload UML/JSON Mapping for the "Resource" Class

Table 5.3.13 - Payload UML/JSON Mapping for the "SetOfGUIDs" Class

Table 5.3.14 - Payload UML/JSON Mapping for the "Subject" Class

Table 5.3.15 - Payload UML/JSON Mapping for the "TextComplexity" Class

Table 5.3.16 - Payload UML/JSON Mapping for the "Vendor" Class

Table 5.3.17 - Payload UML/JSON Mapping for the "imsx_CodeMinor" Class

Table 5.3.18 - Payload UML/JSON Mapping for the "imsx_CodeMinorField" Class

Table 5.3.19 - Payload UML/JSON Mapping for the "imsx_StatusInfo" Class

Table 5.4 - UML/JSON Mapping for the Enumerated Class Definitions

Table 5.6 - UML/JSON Mapping for the Primitive Type Definitions

Table 6.2.1 - Tabular representation of the JSON payload for "200" response messages for a "getAllSubjects" operation.

Table 6.2.2 - Tabular representation of the JSON payload for "400, 401, 403, 422, 429, 500, default" response messages for a "getAllSubjects" operation.

Table 6.4.1 - Tabular representation of the JSON payload for "200" response messages for a "searchForResources" operation.

Table 6.4.2 - Tabular representation of the JSON payload for "400, 401, 403, 500, default, 422, 429" response messages for a "searchForResources" operation.

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

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

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

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

Table A2.2 The key to the descriptions of UML to JSON payload class mapping tables.

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

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

toc | top

List of Code Blocks

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

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

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

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

toc | top

1. Introduction

1.1 Scope and Context

This document is the LTI Resources Search (RS) REST/JSON Binding v1.0 and as such it is used as the basis for implementing the RS 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 IMS Global Model Driven Specification approach and the associated modelling toolkit [I-BAT, 06]. This specification is based upon the concepts of:

A key artifact produced as part of the REST/JSON binding description is the associated OpenAPI file based upon the OpenAPI Specification [OAS, 14] version 2.

1.2 Conventions

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

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

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

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

1.3 Structure of this Document

The structure of the rest of this document is:

2. The REST Endpoints An explanation of the relationship between the logical service operations (as defined in the Resource Search Service Model [RS-SM, 18]) and how these are realised as the corresponding set of REST endpoints (including the set of query parameters that are permitted);
3. Using the Endpoint Query Parameters A detailed explanation of how the permitted set of query parameters should be used to control the volume and type of information that will be supplied by the service provider;
4. Security Framework The underlying security framework within which this REST/JSON binding is required to operate;
5. UML to JSON Payload Mapping The description of how the JSON payloads are derived from the equivalent UML data model definitions [RS-SM, 18]. Each UML class and attribute is mapped to the equivalent JSON object and property;
6. JSON Payloads Examples of the set of JSON payloads that are sent by the consumer (the request) and returned by the service provider (response). These examples are focused on the expected structure of a request/response and do not include actual payloads;
7. Extending and Profiling the Service An explanation of how the service can be extended, using the permitted points of extension and/or profiled. Profiling is the process by which the specification is tailored to a specific set of market/domain requirements;
References The references cited throughout this document.
Appendix A REST/JSON Modeling Terms An overview of the model driven approach, the concepts and the terms used by IMS to create the service model REST/JSON binding definitions (based upon a profile of UML) and the accompanying documentation (including this binding).

1.4 Nomenclature

API Application Programming Interface
AfAPNP Access for All Personal Needs and Preferences
CASE Competencies and Academic Standards Exchange
HTTP Hypertext Transfer Protocol
I-BAT IMS Binding Autogeneration Toolkit
IETF Internet Engineering Task Force
ISO International Standards Organization
JSON Java Script Object Notation
LOR Learning Object Repository
LTI Learning Tools Interoperability
OAS OpenAPI Specification
PNP Personal Needs and Preferences
REST Representation State Transfer
RFC Request for Comments
RS LTI Resource Search
TLS Transport Layer Security
UML Unified Modeling Language
URI Uniform Resource Identifier
URL Uniform Resource Locator
YAML Yet Another Markup Language

toc | top

2. The REST Endpoints

This Section is NORMATIVE.

2.1 Mapping of the Service Operations to the REST Endpoints

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

Table 2.1 - The Set of REST Endpoint URL-leaf Values.
Service Call REST Endpoint HTTP Verb
getAllSubjects /subjects GET
searchForResources /resources GET

2.2 API Root URL and Versioning

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

2.3 Predefined Endpoint Query Parameters

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

2.3.1 "getAllSubjects" Endpoint Query Parameters

There are no pre-defined query parameters for this endpoint.

2.3.2 "searchForResources" Endpoint Query Parameters

2.3.2.1 "fields" Query Parameter

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

Table 2.3.2.1 - The definition of the "fields" query parameter for the "searchForResources" operation.
Descriptor Definition
Parameter Name fields
Data Type NormalizedString (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..*]
Description To identify the range of fields, and only those fields, that should be supplied in the response message. The permitted vocabulary for these fields is determined by the payloads that are returned in the corresponding response messages.

2.3.2.2 "filter" Query Parameter

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

Table 2.3.2.2 - The definition of the "filter" query parameter for the "searchForResources" operation.
Descriptor Definition
Parameter Name filter
Data Type NormalizedString (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description The filtering rules to be applied when identifying the records to be supplied in the response message. Filtering defines the search criteria to be applied at the service provider for the identification and selection of the resources to be returned. A strict vocabulary is used for the permitted search terms (see the RS REST/JSON binding document 'Keyword Searching' in Sub-section 3.1 [RS-RJ, 18]).

2.3.2.3 "limit" Query Parameter

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

Table 2.3.2.3 - The definition of the "limit" query parameter for the "searchForResources" operation.
Descriptor Definition
Parameter Name limit
Data Type PositiveInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "100".
Multiplicity [0..1]
Description This is used as part of the data pagination mechanism to control the number of records returned in any one response message. The 'limit' defines the download segmentation value i.e. the maximum number of records to be contained in the response. The form of implementation is described in the corresponding binding document(s).

2.3.2.4 "offset" Query Parameter

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

Table 2.3.2.4 - The definition of the "offset" query parameter for the "searchForResources" operation.
Descriptor Definition
Parameter Name offset
Data Type NonNegativeInteger (Primitive-type)
Value Space See Appendix A1.2.
Default = "0".
Multiplicity [0..1]
Description This is used as part of the data pagination mechanism to control the download rate of data. The 'offset' is the number of the first record to be supplied in the segmented response message. The form of implementation is described in the corresponding binding document(s).

2.3.2.5 "orderBy" Query Parameter

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

Table 2.3.2.5 - The definition of the "orderBy" query parameter for the "searchForResources" operation.
Descriptor Definition
Parameter Name orderBy
Data Type Enumeration
Value Space Enumerated value set of: { asc | desc }
Multiplicity [0..1]
Description This is used as part of the sorting mechanism to be use by the service provider. This defines the form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The form of implementation is described in the corresponding binding document(s).

2.3.2.6 "sort" Query Parameter

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

Table 2.3.2.6 - The definition of the "sort" query parameter for the "searchForResources" operation.
Descriptor Definition
Parameter Name sort
Data Type NormalizedString (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [0..1]
Description This is used as part of the sorting mechanism to be use by the service provider. The 'sort' identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The form of implementation is described in the corresponding binding document(s).

2.4 HTTP Code Handling

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

Table 2.4 - The List of HTTP Codes and Handling for each Endpoint.
REST Endpoint HTTP Verb HTTP Codes and Handling
/resources GET
  • 200 - the response code for when the query request has been successfully completed and the set of identified resources returned. This would be accompanied by the 'codeMajor/severity' values of 'success/status' The payload is defined by the structure ResourceSet.Type.
  • 400 - the request has been declared as 'bad'. This will be due to the provision of bad data in the request query parameters. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 403 - 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'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 422 - this error condition may occur if a JSON request body contains well-formed i.e. syntactically correct, but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
/subjects GET
  • 200 - the response code for when the query request has been successfully completed and the set of subjects returned. This would be accompanied by the 'codeMajor/severity' values of 'success/status' The payload is defined by the structure SubjectSet.Type.
  • 400 - the request has been declared as 'bad'. This will be due to the provision of bad data in the request query parameters. This is accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 403 - 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'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 422 - this error condition may occur if a JSON request body contains well-formed i.e. syntactically correct, but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure imsx_StatusInfo.Type.

toc | top

3. Using the Endpoint Query Parameters

This Section is NORMATIVE.

3.1 Searching for Resources

When making a search, it is possible to apply a to filter to define matching for certain criteria. It is possible to filter collections based on predefined vocabulary. Filter requests MUST take the form:

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

or

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

The list of permitted terms for 'data_field' is given in Table 3.1:

Table 3.1 List of terms used for filtering.
Term Type Description
search Normalized String This is a special term that requires the associated filter term to be applied to the 'name', 'subject' and 'description' values.
name Normalised String The name/title of resource.
description Normalized String A human readable description of the contents of the resource.
subject Normalized String A subject of the resource.
learningResourceType Enumerated List (see [RS-SM, 18]) The type of the resource.
language Enumerated List (see [RFC 3066]) Language used in the resource.
typicalAgeRange Normalized String (Constrained pattern) Age of the typical intended user. This is described as the minimum and maximum ages.
textComplexity.name Enumerated List (see [RS-SM, 18]) A number indicating text complexity based on number of established measures. The filter is applied to the 'name' part of this complex structure.
textComplexity.value Normalized String A number indicating text complexity based on number of established measures. The filter is applied to the 'value' part of this complex structure.
learningObjectives.alignmentType Enumerated List (see [RS-SM, 18]) Learning objective addressed by the resource. The filter is applied to the 'alignmentType' part of this complex structure.
learningObjectives.educationalFramework Normalized String Learning objective addressed by the resource. The filter is applied to the 'educationalFramework' part of this complex structure.
learningObjectives.targetDescription Normalized String Learning objective addressed by the resource. The filter is applied to the 'targetDescription' part of this complex structure.
learningObjectives.targetName Normalized String Learning objective addressed by the resource. The filter is applied to the 'targetName' part of this complex structure.
learningObjectives.targetURL URL Learning objective addressed by the resource. The filter is applied to the 'targetURL' part of this complex structure.
learningObjectives.caseItemURI URI Learning objective addressed by the resource. The filter is applied to the 'caseItemUR' part of this complex structure.
learningObjectives.caseItemGUID GUID Learning objective addressed by the resource. The filter is applied to the 'caseItemGUID' part of this complex structure.
author Normalised String Author or creator of the resource.
publisher Normalised String Owner of the rights to the resource or who made it available (company or person).
timeRequired Duration (see [ISO 8601]) Time that the resource takes to consume.
technicalFormat Normalised String MIME format of the resource.
educationalAudience Enumerated List (see [RS-SM, 18]) For whom the resource is intended.
accessibilityAPI Enumerated List (see [RS-SM, 18]) Accessibility API supported by the resource.
accessibilityInputMethods Enumerated List (see [RS-SM, 18]) How the resource can be controlled by the user, includeing full keyboard controllability, mouse controllability, and voice controllability.
accessMode Enumerated List (see [RS-SM, 18]) The human sensory perceptual system or cognitive faculty through which a person may process or perceive information.
publishDate Date (see [ISO 8601]) Date the resource was published by the publisher.
rating Enumerated List (see [RS-SM, 18]) A rating of the quality of the resource determined by the SearchProvider.

A 'NULL' value can supplied as part of a valid search request and MUST be processed accordingly i.e. no special processing is required. When searching on the above terms a value of 'NULL' being returned by the service provider in the 'name' or 'learningResourceType', or 'url' fields MUST be detected and reported as an error by the consuming system. How this error is reported is beyond the scope of this specification.

When filtering it is also permitted to use the term search as a short-hand form to request all terms that have the appropriate values in the 'name' and/or 'description' and/or 'subject' attributes.

Predicates MUST be chosen from those listed in Table 3.2:

Table 3.2 List of predicates used for filtering.
Predicate Representation
Equal =
Not Equal !=
Greater Than >
Greater Than or Equal >=
Lesser Than <
Lesser Than or Equal <=
Contains ~

Values MUST be enclosed within single quotes and they MUST be handled as case insensitive. If any part of syntax of the filter request is incorrect then the whole request must be treated as invalid and the appropriate error code returned. When the response is returned it is the receiving system that should consider whether or not case-sensitivity is important.

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

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

    ?filter=<Nested_Object>.<Property>

Note then when querying on metadata, the property is loosely typed. An example or a request to find resources with a type Media/Video is:

    GET https://imsglobal.org/ims/rs/v1p0/resources?filter=learningResourceType='Media/Video'

URL encoded as:

    GET https://imsglobal.org/ims/rs/v1p0/resources?filter=learningResourceType%3D%27Media%2fVideo%27

Filter queries MUST be URL encoded.

An example of a complex query for all resources with a subject='geometry' AND publishDate>'2017-01-01' is:

    GET https://imsglobal.org/ims/rs/v1p0/resources?filter=subject%3D%27geometry%27%20AND%20publishDate%3E%272017%3D01%3D01%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 the 'subject' field when the value of the field is "subject1,subject2,subject3" the following filters would return:

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

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

3.2 Field Selection

When requesting a search it should be possible to constrain the range of fields to be returned. By default, all mandatory and optional 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 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 'name' and 'url':

    GET https://imsglobal.org/ims/rs/v1p0/resources?fields=name,url

If the consumer requests that data be selected using a 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:

3.3 Sorting and Ordering

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

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

    GET https://imsglobal.org/ims/ims/rs/v1p0/resources?sort=name&orderBy=asc

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

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

When a sorted request is made, the service provider MAY supply only a subset of the identified set resources. In this case the service provider MUST supply the corresponding pagination Link Headers (see Section 3.4). Therefore, it is the responsibility of the consumer to understand the context within which the sorted response is delivered.

3.4 Pagination

For requests of collections i.e. the response for the 'searchForResources()' call, there is a danger of data overload. To avoid this, implementations MUST use this pagination mechanism. Pagination can occur in two situations:

Pagination is controlled via two parameters that are appended to the request:

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

    GET https://imsglobal.org/ims/rs/v1p0/resources?limit=10

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

    GET https://imsglobal.org/ims/rs/v1p0/resources?limit=10&offset=10

Implementations MAY pass the total resource count in collection back to the requester. This MUST be provided in the custom HTTP header: X-Total-Count.

Implementation MAY 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/rs/v1p0/resources?limit=10&offset=20>; rel="next",
    <https://imsglobal.org/ims/rs/v1p0/resources?limit=3&offset=500>; rel="last",
    <https://imsglobal.org/ims/rs/v1p0/resources?limit=10&offset=0>; rel="first",
    <https://imsglobal.org/ims/rs/v1p0/resources?limit=10&offset=0>; rel="prev"

toc | top

4. Security Framework

This Section is NORMATIVE.

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 is REQUIRED and SSL MUST NOT be used.

toc | top

5. UML to JSON Payload Mapping

This Section is INFORMATIVE.

5.1 Service Parameter Payload Properties UML/JSON Mapping

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

Table 5.1 UML/JSON Mapping for the Service Parameters.
Operation Name Parameter Name UML Class JSON Name JSON Type JSON Schema Data Type
getAllSubjects subjects SubjectSet subjects Array of Objects SubjectSet.Type
searchForResources resources ResourceSet resources Array of Objects ResourceSet.Type

5.2 Service Parameter Payload Class UML/JSON Mapping

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

5.2.1 ResourceSet Service Parameter Payload Class Mapping

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

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

5.2.2 SubjectSet Service Parameter Payload Class Mapping

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

Table 5.2.2 UML/JSON Mapping for the "SubjectSet" Service Parameter Payload Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
SubjectSet Payload Parameter Container [ Unordered ] - N/A - SubjectSet.Type Object
  • subjects
Attribute Subject [0.. *] subjects Array of Properties

5.3 Payload Classes UML/JSON Mapping

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

5.3.1 CCLTILink Payload Class Mapping

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

Table 5.3.1 Payload UML/JSON Mapping for the "CCLTILink" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
CCLTILink Core Container [ Unordered ] AND Inherits [ LTILink ] - N/A - CCLTILink.Type
^---LTILink.Type
Object
  • cartridge_bundle
Attribute LTILinkResourceRef [0..1] cartridge_bundle Property
  • cartridge_icon
Attribute LTILinkResourceRef [0..1] cartridge_icon Property
  • metadata
Attribute Metadata [0..1] metadata Property

5.3.2 CSMSet Payload Class Mapping

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

Table 5.3.2 Payload UML/JSON Mapping for the "CSMSet" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
CSMSet Core Container [ Unordered ] - N/A - CSMSet.Type Object
  • resourceLabel
Attribute PT: NormalizedString [0..1] resourceLabel Property
  • resourcePartId
Attribute PT: NormalizedString [0..1] resourcePartId Property
  • curriculumStandardsMetadata
Attribute CurriculumStandardsMetadata [1.. *] curriculumStandardsMetadata Array of Properties

5.3.3 CurriculumStandardsMetadata Payload Class Mapping

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

Table 5.3.3 Payload UML/JSON Mapping for the "CurriculumStandardsMetadata" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
CurriculumStandardsMetadata Core Container [ Unordered ] - N/A - CurriculumStandardsMetadata.Type Object
  • providerId
Attribute PT: NormalizedString [0..1] providerId Property
  • setOfGUIDs
Attribute SetOfGUIDs [1.. *] setOfGUIDs Array of Properties

5.3.4 LTILink Payload Class Mapping

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

Table 5.3.4 Payload UML/JSON Mapping for the "LTILink" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
LTILink Core Container [ Unordered ] - N/A - LTILink.Type Object
  • title
Attribute PT: NormalizedString [1] title Property
  • description
Attribute PT: String [0..1] description Property
  • custom
Attribute PropertySet [0..1] custom Property
  • extensions
Attribute PlatformPropertySet [0..1] extensions Property
  • launch_url
Attribute DT: URL (PT: AnyURI) [0..1] launch_url Property
  • secure_launch_url
Attribute DT: URL (PT: AnyURI) [0..1] secure_launch_url Property
  • icon
Attribute DT: URL (PT: AnyURI) [0..1] icon Property
  • secure_icon
Attribute DT: URL (PT: AnyURI) [0..1] secure_icon Property
  • vendor
Attribute Vendor [1] vendor Property

5.3.5 LTILinkResourceRef Payload Class Mapping

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

Table 5.3.5 Payload UML/JSON Mapping for the "LTILinkResourceRef" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
LTILinkResourceRef Core Container [ Unordered ] - N/A - LTILinkResourceRef.Type Object
  • name
Attribute PT: NormalizedString [1] name Property
  • resourceUri
Attribute PT: AnyURI [1] resourceUri Property

5.3.6 LabelledGUID Payload Class Mapping

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

Table 5.3.6 Payload UML/JSON Mapping for the "LabelledGUID" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
LabelledGUID Core Container [ Unordered ] - N/A - LabelledGUID.Type Object
  • label
Attribute PT: NormalizedString [0..1] label Property
  • caseItemURI
Attribute PT: AnyURI [0..1] caseItemURI Property
  • GUID
Attribute DT: GUID (PT: NormalizedString) [1] GUID Property

5.3.7 LearningObjectives Payload Class Mapping

The Payload UML/JSON Mapping for the "LearningObjectives" Class is given in Table 5.3.7.

Table 5.3.7 Payload UML/JSON Mapping for the "LearningObjectives" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
LearningObjectives Core Container [ Unordered ] - N/A - LearningObjectives.Type Object
  • alignmentType
Attribute [ Enumeration (AlignmentTypeEnum) ] [1] alignmentType Property
  • educationalFramework
Attribute PT: NormalizedString [0..1] educationalFramework Property
  • targetDescription
Attribute PT: NormalizedString [0..1] targetDescription Property
  • targetName
Attribute PT: NormalizedString [0..1] targetName Property
  • targetURL
Attribute DT: URL (PT: AnyURI) [0..1] targetURL Property
  • caseItemUri
Attribute PT: AnyURI [0..1] caseItemUri Property
  • caseItemGUID
Attribute DT: GUID (PT: NormalizedString) [0..1] caseItemGUID Property

5.3.8 Metadata Payload Class Mapping

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

Table 5.3.8 Payload UML/JSON Mapping for the "Metadata" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
Metadata Core Container [ Unordered ] - N/A - Metadata.Type Object
  • curriculumStandardsMetadataSet
Attribute CSMSet [0..1] curriculumStandardsMetadataSet Property

5.3.9 PlatformPropertySet Payload Class Mapping

The Payload UML/JSON Mapping for the "PlatformPropertySet" Class is given in Table 5.3.9.

Table 5.3.9 Payload UML/JSON Mapping for the "PlatformPropertySet" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
PlatformPropertySet Core Container [ Unordered ] - N/A - PlatformPropertySet.Type Object
  • platform
Attribute PT: NormalizedString [1] platform Property
  • properties
Attribute Property [1.. *] properties Array of Properties

5.3.10 Property Payload Class Mapping

The Payload UML/JSON Mapping for the "Property" Class is given in Table 5.3.10.

Table 5.3.10 Payload UML/JSON Mapping for the "Property" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
Property Core Container [ Unordered ] - N/A - Property.Type Object
  • name
Attribute PT: NormalizedString [1] name Property
  • value
Attribute PT: NormalizedString [1] value Property

5.3.11 PropertySet Payload Class Mapping

The Payload UML/JSON Mapping for the "PropertySet" Class is given in Table 5.3.11.

Table 5.3.11 Payload UML/JSON Mapping for the "PropertySet" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
PropertySet Core Container [ Unordered ] - N/A - PropertySet.Type Object
  • properties
Attribute Property [1.. *] properties Array of Properties

5.3.12 Resource Payload Class Mapping

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

Table 5.3.12 Payload UML/JSON Mapping for the "Resource" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
Resource Core Container [ Unordered ] - N/A - Resource.Type Object
  • name
Attribute DT: NString1024 (PT: NormalizedString) [1] name Property
  • description
Attribute DT: NString2048 (PT: NormalizedString) [0..1] description Property
  • subject
Attribute DT: NString1024 (PT: NormalizedString) [0.. *] subject Array of Properties
  • url
Attribute DT: URL (PT: AnyURI) [0..1] url Property
  • ltiLink
Attribute CCLTILink [0..1] ltiLink Property
  • learningResourceType
Attribute [ Enumeration (LRTEnum) ] [1.. *] learningResourceType Array of Properties
  • language
Attribute PT: Language [0.. *] language Array of Properties
  • thumbnailUrl
Attribute DT: URL (PT: AnyURI) [0..1] thumbnailUrl Property
  • typicalAgeRange
Attribute DT: AgeRange (PT: NormalizedString) [0..1] typicalAgeRange Property
  • textComplexity
Attribute TextComplexity [0.. *] textComplexity Array of Properties
  • learningObjectives
Attribute LearningObjectives [0.. *] learningObjectives Array of Properties
  • author
Attribute DT: NString2048 (PT: NormalizedString) [0.. *] author Array of Properties
  • publisher
Attribute DT: NString2048 (PT: NormalizedString) [1] publisher Property
  • useRightsURL
Attribute DT: URL (PT: AnyURI) [0..1] useRightsURL Property
  • timeRequired
Attribute PT: Duration [0..1] timeRequired Property
  • technicalFormat
Attribute PT: NormalizedString [0..1] technicalFormat Property
  • educationalAudience
Attribute [ Enumeration (EducationalAudienceEnum) ] [0.. *] educationalAudience Array of Properties
  • accessibilityAPI
Attribute [ Enumeration (AccessibilityAPIEnum) ] [0.. *] accessibilityAPI Array of Properties
  • accessibilityInputMethods
Attribute [ Enumeration (AccessibilityInputEnum) ] [0.. *] accessibilityInputMethods Array of Properties
  • accessibilityFeatures
Attribute PT: NormalizedString [0.. *] accessibilityFeatures Array of Properties
  • accessibilityHazards
Attribute [ Enumeration (HazardEnum) ] [0.. *] accessibilityHazards Array of Properties
  • accessMode
Attribute [ Enumeration (AccessModeEnum) ] [0.. *] accessMode Array of Properties
  • publishDate
Attribute PT: Date [0..1] publishDate Property
  • rating
Attribute [ Enumeration (RatingEnum) ] [0..1] rating Property
  • relevance
Attribute DT: Float0to1 (PT: Float) [0..1] relevance Property
  • extensions
Attribute PT: Namespace [0.. *] Set of Proprietary Properties Set of Proprietary Properties

5.3.13 SetOfGUIDs Payload Class Mapping

The Payload UML/JSON Mapping for the "SetOfGUIDs" Class is given in Table 5.3.13.

Table 5.3.13 Payload UML/JSON Mapping for the "SetOfGUIDs" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
SetOfGUIDs Core Container [ Unordered ] - N/A - SetOfGUIDs.Type Object
  • region
Attribute PT: NormalizedString [0..1] region Property
  • version
Attribute PT: NormalizedString [0..1] version Property
  • labelledGUID
Attribute LabelledGUID [1.. *] labelledGUID Array of Properties

5.3.14 Subject Payload Class Mapping

The Payload UML/JSON Mapping for the "Subject" Class is given in Table 5.3.14.

Table 5.3.14 Payload UML/JSON Mapping for the "Subject" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
Subject Core Container [ Unordered ] - N/A - Subject.Type Object
  • identifier
Attribute PT: PositiveInteger [1] identifier Property
  • name
Attribute PT: NormalizedString [1] name Property
  • parent
Attribute PT: PositiveInteger [1] parent Property

5.3.15 TextComplexity Payload Class Mapping

The Payload UML/JSON Mapping for the "TextComplexity" Class is given in Table 5.3.15.

Table 5.3.15 Payload UML/JSON Mapping for the "TextComplexity" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
TextComplexity Core Container [ Unordered ] - N/A - TextComplexity.Type Object
  • name
Attribute [ Enumeration (TextComplexityNameEnum) ] [1] name Property
  • value
Attribute PT: NormalizedString [1] value Property

5.3.16 Vendor Payload Class Mapping

The Payload UML/JSON Mapping for the "Vendor" Class is given in Table 5.3.16.

Table 5.3.16 Payload UML/JSON Mapping for the "Vendor" Class.
Information Model Details JSON Binding Details
Name UML Artefact Data Type Multiplicity Name Type
Vendor Core Container [ Unordered ] - N/A - Vendor.Type Object
  • code
Attribute PT: NormalizedString [1] code Property
  • name
Attribute PT: NormalizedString [1] name Property
  • description
Attribute PT: String [0..1] description Property
  • url
Attribute DT: URL (PT: AnyURI) [0..1] url Property
  • emailContact
Attribute PT: NormalizedString [0..1] emailContact Property

5.3.17 imsx_CodeMinor Payload Class Mapping

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

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

5.3.18 imsx_CodeMinorField Payload Class Mapping

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

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

5.3.19 imsx_StatusInfo Payload Class Mapping

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

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

5.4 Enumerated Class UML/JSON Mapping

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

Table 5.4 The UML/JSON Map Enumerated Class Definitions.
Enumeration Class Name Description
AccessModeEnum Enumerated value set of: { auditory | color | itemSize | olfactory | orientation | position | tactile | textOnImage | textual | visual }.
AccessibilityAPIEnum Enumerated value set of: { MSAA | UIAutomation | ARIAv1 | IAccessible2 | AndroidAccessibility | ATK | AT-SPI | BlackberryAccessibility | JavaAccessibility | MacOSXAccessibility }.
AccessibilityInputEnum Enumerated value set of: { fullKeyboardControl | fullMouseControl | fullVoiceControl }.
AlignmentTypeEnum Enumerated value set of: { assesses | teaches | requires | textComplexity | readingLevel | educationalSubject | educationLevel }.
EducationalAudienceEnum Enumerated value set of: { student | teacher | administrator | parent | aide | proctor | guardian | relative }.
HazardEnum Enumerated value set of: { flashing | sound | olfactoryHazard | motionSimulation }.
LRTEnum Enumerated value set of: { Assessment/Item | Assessment/Formative | Assessment/Interim | Assessment/Rubric | Assessment/Preparation | Collection/Course | Collection/Unit | Collection/Curriculum Guide | Collection/Lesson | Game | Interactive/Simulation | Interactive/Animation | Interactive/Whiteboard | Activity/Worksheet | Activity/Learning | Activity/Experiment | Lecture | Text/Book | Text/Chapter | Text/Document | Text/Article | Text/Passage | Text/Textbook | Text/Reference | Text/Website | Media/Audio | Media/Images/Visuals | Media/Video | Other }.
RatingEnum Enumerated value set of: { 1 | 2 | 3 | 4 | 5 }.
TextComplexityNameEnum Enumerated value set of: { Lexile | Flesch-Kincaid | Dale-Schall | DRA | Fountas-Pinnell }.
imsx_CodeMajorEnum Enumerated value set of: { success | processing | failure | unsupported }.
imsx_CodeMinorValueEnum Enumerated value set of: { fullsuccess | forbidden | invalid_query_parameter | unauthorisedrequest | internal_server_error | server_busy | invalid_data }.
imsx_SeverityEnum Enumerated value set of: { status | warning | error }.

5.5 Enumerated List Class UML/JSON Mapping

There are no enumerated list class definitions.

5.6 Primitive Type UML/JSON Mapping

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

Table 5.6 The UML/JSON Map Primitive Type Definitions.
Primitive Type Name Description
AnyURI This is mapped to the JSON "string" data-type with the format of "uri".
Date This is mapped to the JSON "string" data-type with the format of "date".
Duration This is mapped to the JSON "string" data-type.
Float This is mapped to the JSON "number" data-type with the format of "float".
Language This is mapped to the JSON "string" data-type.
Namespace This denotes an extension facility. The class is permitted to have proprietary JSON properties i.e. "additionalProperties: true".
NormalizedString This is mapped to the JSON "string" data-type.
PositiveInteger This is mapped to the JSON "integer" data-type with the format of "int32" and a minimum value of "1".
String This is mapped to the JSON "string" data-type.

toc | top

6. JSON Payloads

This Section is NON-NORMATIVE.

6.1 "getAllSubjects" Request Payload

There is no payload for this request.

6.2 "getAllSubjects" Response Payloads

6.2.1 Response Payloads for the HTTP Codes (200)

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

Table 6.2.1 - Tabular representation of the JSON payload for "200" response messages for a "getAllSubjects" operation.
Property Name Multiplicity JSON Data-type Description
    subjects [0..*] Array [ Object ] The actual list of subject supplied by the service provider. The order of subjects is not significant.
            identifier [1..1] Integer (Format: int32; Minimum: 1) The unique identifier, an integer, of the subject node. For the root node the value will be 'null'.
            name [1..1] String The name of the subject node, which may have any character and need not be unique with the returned taxonomy.
            parent [1..1] Integer (Format: int32; Minimum: 1) An integer (the identifier of that subject node) that references the single parent of this node. The returned data must be a true rooted tree, where each node returned has a single parent.

An example of the response JSON payload is shown in the code block below.

Code 6.2.1 - JSON payload example for "200" response messages for a "getAllSubjects" operation.
    {
        "subjects" : [
            {
                "identifier" : ..Number(PositiveInteger)..,
                "name" : "..NormalizedString..",
                "parent" : ..Number(PositiveInteger)..
            },
            {...},
            {...}
        ]
    }
                        

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

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

Table 6.2.2 - Tabular representation of the JSON payload for "400, 401, 403, 422, 429, 500, default" response messages for a "getAllSubjects" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary).
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary).
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_codeMinor [0..1] Object The set of reported code minor status codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below.

Code 6.2.2 - JSON payload example for "400, 401, 403, 422, 429, 500, default" response messages for a "getAllSubjects" operation.
    {
        "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
        "imsx_severity" : "status"|"warning"|"error",
        "imsx_description" : "..String..",
        "imsx_codeMinor" : {
            "imsx_codeMinorField" : [
                {
                    "imsx_codeMinorFieldName" : "..NormalizedString..",
                    "imsx_codeMinorFieldValue" : "fullsuccess"|"forbidden"|"invalid_query_parameter"|"unauthorisedrequest"|"internal_server_error"|"server_busy"|"invalid_data"
                },
                {...},
                {...}
            ]
        }
    }
                        

6.3 "searchForResources" Request Payload

There is no payload for this request.

6.4 "searchForResources" Response Payloads

6.4.1 Response Payloads for the HTTP Codes (200)

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

Table 6.4.1 - Tabular representation of the JSON payload for "200" response messages for a "searchForResources" operation.
Property Name Multiplicity JSON Data-type Description
    resources [0..*] Array [ Object ] The actual resources supplied by the service provider. The order of resources is not significant.
            name [1..1] String The name/title of resource.
            description [0..1] String A human readable description of the contents of the resource.
            subject [0..*] Array [ String ] The subject(s) of the resource. May have multiple subjects tagged.
            url [0..1] String (Format: uri) How to access resource over Internet e.g. HTTP, FTP, etc. A resource must have either a URL or or a LTI Link.
            ltiLink [0..1] Object Fully encapsulated LTI link, generally with method of access.
                    title [1..1] String The human readable title/label for the activity being addressed by the content available through the LTI link.
                    description [0..1] String A human readable description of the activity addressed by the content supplied via the LTI link.
                    custom [0..1] Object A set of custom key value pairs that were placed in the link in the system that originally authored the link. These will be supplied as parameters on the launch call.
                            properties [1..*] Array [ Object ] The set of properties for the identified platform or orginal authoring platform.
                                    name [1..1] String The name of the key for the property.
                                    value [1..1] String The value for the property.
                    extensions [0..1] Object The extensions allows the hosting Tool Consumer (TC) to add its own key/value pairs to the link. The TC may use extensions to store information that the TC or authoring environment might use across an export-import cycle. In order to allow multiple sets of extensions to be contained in the same LTI descriptor, authoring environments should add the platform attribute and include an identifier that identifies the authoring environment.
                            platform [1..1] String The identifier for the authoring environment.
                            properties [1..*] Array [ Object ] The set of extension properties for the identified platform.
                                    name [1..1] String The name of the key for the property.
                                    value [1..1] String The value for the property.
                    launch_url [0..1] String (Format: uri) The URL for the LTI launch. One of either the launch_url or the secure_launch_url must be specified. It is acceptable to specify both and if both are specified, the Tool Consumer (TC) decides which to use. Typically, the TC will use a secure_launch_url when embedding the Tool in a secure page and the launch_url when embedding the tool in a non-secure page. So, it is important that the Tool Provider (TP) provides the same functionality whether the launch_url or secure_launch_url is used.
                    secure_launch_url [0..1] String (Format: uri) A secure URL for the LTI launch. One of either the launch_url or the secure_launch_url must be specified. It is acceptable to specify both and if both are specified, the Tool Consumer (TC) decides which to use. Typically, the TC will use a secure_launch_url when embedding the Tool in a secure page and the launch_url when embedding the tool in a non-secure page. So, it is important that the Tool Provider (TP) provides the same functionality whether the launch_url or secure_launch_url is used.
                    icon [0..1] String (Format: uri) A URL to an icon for this tool.
                    secure_icon [0..1] String (Format: uri) A secure URL to an icon for this tool.
                    vendor [1..1] Object The information about the vendor of the tool accessed via this LTI link.
                            code [1..1] String An identification code for the vendor.
                            name [1..1] String The name of the vendor.
                            description [0..1] String A human readable description of the vendor.
                            url [0..1] String (Format: uri) A URL for the vendor.
                            emailContact [0..1] String Contact email for the vendor.
                    cartridge_bundle [0..1] Object A link to a bundled set of files. For example this could be a link to zip file that contains all of the icons.
                            name [1..1] String The name of the type of content supplied by the link.
                            resourceUri [1..1] String (Format: uri) The URI for the link.
                    cartridge_icon [0..1] Object An icon for the link to the cartridge. This could be used to provide an alternative visualisation to the use of the URL itself.
                            name [1..1] String The name of the type of content supplied by the link.
                            resourceUri [1..1] String (Format: uri) The URI for the link.
                    metadata [0..1] Object The set of metadata that is associated with the LTI Link.
                            curriculumStandardsMetadataSet [0..1] Object The set of curriculum standards annotations i.e. identification of the set of curriculum standards that are supported by the content supplied by this resource link.
                                    resourceLabel [0..1] String This is a human readable label used to identify the type of resource, or part of resource, to which the enclosed metadata refers.
                                    resourcePartId [0..1] String This is used to contain the appropriate identifier that is used to identify the resource part.
                                    curriculumStandardsMetadata [1..*] Array [ Object ] The curriculum standards associated from a single source of the curriculum standards definition.
                                            providerId [0..1] String This is used to denote the originator of the GUID scheme.
                                            setOfGUIDs [1..*] Array [ Object ] The set of curriculum standards GUIDs that apply to the learning associated resource.
                                                    region [0..1] String The region responsible for the definition.
                                                    version [0..1] String This is used to denote any relevant versioning information.
                                                    labelledGUID [1..*] Array [ Object ] The actual GUID plus the corresponding labelling information.
                                                            label [0..1] String A human readable string to provide a clue about the nature of the curriculum standard.
                                                            caseItemURI [0..1] String (Format: uri) The corresponding Competency and Academic Standards (CASE) URI. This is the URI used for alignment with the IMS CASE Service 1.0 specification [CASE, 17].
                                                            GUID [1..1] String The GUID itself.
            learningResourceType [1..*] Array [ Enumeration ] The type of the resource. There may be multiple types.
            language [0..*] Array [ String ] The languages used in the resource. International two digit code for language e.g. 'en' for English. Use the [RFC 3066] annotation.
            thumbnailUrl [0..1] String (Format: uri) Link to a thumbnail representing resource.
            typicalAgeRange [0..1] String Age of the typical intended user. This is described as EITHER the minimum-maximum age range (the format is '11-12', '5-7', etc. with ONLY integers permitted) OR the age as a single integer e.g. '9'.
            textComplexity [0..*] Array [ Object ] A number indicating text complexity based on number of established measures.
                    name [1..1] Enumeration The name of the complexity measure. This is taken from an enumerated vocabulary.
                    value [1..1] String The text complexity measure in terms of the named measuring scale.
            learningObjectives [0..*] Array [ Object ] The set of learning objectives addressed by the resource.
                    alignmentType [1..1] Enumeration A category of alignment between the learning resource and the framework node.
                    educationalFramework [0..1] String The framework to which the resource being described is aligned.
                    targetDescription [0..1] String The description of a node in an established educational framework.
                    targetName [0..1] String The name of a node in an established educational framework.
                    targetURL [0..1] String (Format: uri) The URL of a node in an established educational framework.
                    caseItemUri [0..1] String (Format: uri) Reference to a CASE CFItem for a standard or skill [CASE, 17].
                    caseItemGUID [0..1] String Reference to CASE CFItem as a GUID [CASE, 17].
            author [0..*] Array [ String ] Author or creator of the resource.
            publisher [1..1] String Owner of the rights to the resource or who made it available (company or person).
            useRightsURL [0..1] String (Format: uri) URL describing how resource can be licensed. Could be Creative Commons license link or link to other specific open or proprietary license.
            timeRequired [0..1] String Time that the resource takes to consume. Use the [ISO 8601] format for a duration.
            technicalFormat [0..1] String A valid MIME type format for the resource e.g. text, HTML, PDF, MPEG, MP3, etc. See https://www.iana.org/assignments/media-types/media-types.xhtml.
            educationalAudience [0..*] Array [ Enumeration ] For whom the resource is intended.
            accessibilityAPI [0..*] Array [ Enumeration ] Which (if any) accessibility API is supported by the resource.
            accessibilityInputMethods [0..*] Array [ Enumeration ] How the resource can be controlled by the user, which includes full keyboard controllability, mouse controllability, and voice controllability.
            accessibilityFeatures [0..*] Array [ String ] These include alternatives and listed enhancements for the resource. These can be transformation features, navigation features, control features or augmentation features.
            accessibilityHazards [0..*] Array [ Enumeration ] The set of accessibility hazards which are encountered when using this resource.
            accessMode [0..*] Array [ Enumeration ] The human sensory perceptual system or cognitive faculty through which a person may process or perceive information.
            publishDate [0..1] String (Format: date) Date the resource was published by the publisher. The 'date' using the [ISO 8601] format.
            rating [0..1] Enumeration A rating of the quality of the resource determined by the Search Provider. Often derived from crowdsource ratings.
            relevance [0..1] Float This is a floating point value based on relevance to the specific search. Higher relevance has a higher number.
            extensions [0..*] Set of Proprietary Properties The set of proprietary attributes that can be added to the data model. The actual way in which this is achieved is dependent on the data model binding technology used.

An example of the response JSON payload is shown in the code block below.

Code 6.4.1 - JSON payload example for "200" response messages for a "searchForResources" operation.
    {
        "resources" : [
            {
                "name" : "..NormalizedString..",
                "description" : "..NormalizedString..",
                "subject" : [ "..NormalizedString..", ..., "..NormalizedString.." ],
                "url" : "..URI..",
                "ltiLink" : {
                    "title" : "..NormalizedString..",
                    "description" : "..String..",
                    "custom" : {
                        "properties" : [
                            {
                                "name" : "..NormalizedString..",
                                "value" : "..NormalizedString.."
                            },
                            {...},
                            {...}
                        ]
                    },
                    "extensions" : {
                        "platform" : "..NormalizedString..",
                        "properties" : [
                            {
                                "name" : "..NormalizedString..",
                                "value" : "..NormalizedString.."
                            },
                            {...},
                            {...}
                        ]
                    },
                    "launch_url" : "..URI..",
                    "secure_launch_url" : "..URI..",
                    "icon" : "..URI..",
                    "secure_icon" : "..URI..",
                    "vendor" : {
                        "code" : "..NormalizedString..",
                        "name" : "..NormalizedString..",
                        "description" : "..String..",
                        "url" : "..URI..",
                        "emailContact" : "..NormalizedString.."
                    },
                    "cartridge_bundle" : {
                        "name" : "..NormalizedString..",
                        "resourceUri" : "..URI.."
                    },
                    "cartridge_icon" : {
                        "name" : "..NormalizedString..",
                        "resourceUri" : "..URI.."
                    },
                    "metadata" : {
                        "curriculumStandardsMetadataSet" : {
                            "resourceLabel" : "..NormalizedString..",
                            "resourcePartId" : "..NormalizedString..",
                            "curriculumStandardsMetadata" : [
                                {
                                    "providerId" : "..NormalizedString..",
                                    "setOfGUIDs" : [
                                        {
                                            "region" : "..NormalizedString..",
                                            "version" : "..NormalizedString..",
                                            "labelledGUID" : [
                                                {
                                                    "label" : "..NormalizedString..",
                                                    "caseItemURI" : "..URI..",
                                                    "GUID" : "..NormalizedString.."
                                                },
                                                {...},
                                                {...}
                                            ]
                                        },
                                        {...},
                                        {...}
                                    ]
                                },
                                {...},
                                {...}
                            ]
                        }
                    }
                },
                "learningResourceType" : [ "Assessment/Item"|"Assessment/Formative"|"Assessment/Interim"|"Assessment/Rubric"|"Assessment/Preparation"|"Collection/Course"|"Collection/Unit"|"Collection/Curriculum Guide"|"Collection/Lesson"|"Game"|"Interactive/Simulation"|"Interactive/Animation"|"Interactive/Whiteboard"|"Activity/Worksheet"|"Activity/Learning"|"Activity/Experiment"|"Lecture"|"Text/Book"|"Text/Chapter"|"Text/Document"|"Text/Article"|"Text/Passage"|"Text/Textbook"|"Text/Reference"|"Text/Website"|"Media/Audio"|"Media/Images/Visuals"|"Media/Video"|"Other", ..., "..." ] ,
                "language" : [ "..String(Language Code)..", ..., "..String(Language Code).." ],
                "thumbnailUrl" : "..URI..",
                "typicalAgeRange" : "..NormalizedString..",
                "textComplexity" : [
                    {
                        "name" : "Lexile"|"Flesch-Kincaid"|"Dale-Schall"|"DRA"|"Fountas-Pinnell",
                        "value" : "..NormalizedString.."
                    },
                    {...},
                    {...}
                ],
                "learningObjectives" : [
                    {
                        "alignmentType" : "assesses"|"teaches"|"requires"|"textComplexity"|"readingLevel"|"educationalSubject"|"educationLevel",
                        "educationalFramework" : "..NormalizedString..",
                        "targetDescription" : "..NormalizedString..",
                        "targetName" : "..NormalizedString..",
                        "targetURL" : "..URI..",
                        "caseItemUri" : "..URI..",
                        "caseItemGUID" : "..NormalizedString.."
                    },
                    {...},
                    {...}
                ],
                "author" : [ "..NormalizedString..", ..., "..NormalizedString.." ],
                "publisher" : "..NormalizedString..",
                "useRightsURL" : "..URI..",
                "timeRequired" : "..String(Duration)..",
                "technicalFormat" : "..NormalizedString..",
                "educationalAudience" : [ "student"|"teacher"|"administrator"|"parent"|"aide"|"proctor"|"guardian"|"relative", ..., "..." ] ,
                "accessibilityAPI" : [ "MSAA"|"UIAutomation"|"ARIAv1"|"IAccessible2"|"AndroidAccessibility"|"ATK"|"AT-SPI"|"BlackberryAccessibility"|"JavaAccessibility"|"MacOSXAccessibility", ..., "..." ] ,
                "accessibilityInputMethods" : [ "fullKeyboardControl"|"fullMouseControl"|"fullVoiceControl", ..., "..." ] ,
                "accessibilityFeatures" : [ "..NormalizedString..", ..., "..NormalizedString.." ],
                "accessibilityHazards" : [ "flashing"|"sound"|"olfactoryHazard"|"motionSimulation", ..., "..." ] ,
                "accessMode" : [ "auditory"|"color"|"itemSize"|"olfactory"|"orientation"|"position"|"tactile"|"textOnImage"|"textual"|"visual", ..., "..." ] ,
                "publishDate" : "..String(Date)..",
                "rating" : "1"|"2"|"3"|"4"|"5",
                "relevance" : ..Number(Float)..,
                "..permitted extension point.." : "..user defined value.."
            },
            {...},
            {...}
        ]
    }
                        

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

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

Table 6.4.2 - Tabular representation of the JSON payload for "400, 401, 403, 500, default, 422, 429" response messages for a "searchForResources" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary).
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary).
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_codeMinor [0..1] Object The set of reported code minor status codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below.

Code 6.4.2 - JSON payload example for "400, 401, 403, 500, default, 422, 429" response messages for a "searchForResources" operation.
    {
        "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
        "imsx_severity" : "status"|"warning"|"error",
        "imsx_description" : "..String..",
        "imsx_codeMinor" : {
            "imsx_codeMinorField" : [
                {
                    "imsx_codeMinorFieldName" : "..NormalizedString..",
                    "imsx_codeMinorFieldValue" : "fullsuccess"|"forbidden"|"invalid_query_parameter"|"unauthorisedrequest"|"internal_server_error"|"server_busy"|"invalid_data"
                },
                {...},
                {...}
            ]
        }
    }
                        

toc | top

7. Extending and Profiling the Service

This Section is NOT NORMATIVE.

7.1 Extending the Service

Proprietary extensions of the service are based upon two approaches:

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

7.1.1 Proprietary Operations

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

An example of creating such an extension is given in the accompanying Best Practices document [RS-BP, 18].

7.1.2 Proprietary Data Elements

It is recognized that implementers may wish to extend the specification. Extensions are ONLY permitted using the within the 'Resource' class.

Within the OpenAPI files, uncontrolled data extensions are explicitly prohibited by the JSON Schema definition. If extensions are permitted in the 'Resource' class then an appropriately amended OpenAPI should be created (complying to the OpenAPI v2 specification [OAS, 14]) and made available.

7.2 Profiling the Service

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

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

It is strongly recommended that a profile of this specification is undertaken either by, or with the close support, of IMS Global. However, no matter who is responsible for creating the profile artefacts (documents, OpenAPI files, XSDs, etc.), it is strongly recommended that the IMS 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 Lisa Mattson (IMS Global Chief Operations Officer) at: lmattson@imsglobal.org.

toc | top

References

[CASE, 17] Competencies and Academic Standards Exchange (CASE) Service, B.Grogan, G.Nadeau, C.Smythe and J.Hobson, IMS Global Learning Consortium Inc., July 2017, https://www.imsglobal.org/sites/default/files/CASE/casev1p0/information_model/caseservicev1p0_infomodelv1p0.html.
[I-BAT, 06] IMS Binding Auto-generation Toolkit (I-BAT), C.Smythe, IMS Global Learning Consortium Inc., July 2006.
[ISO 8601] ISO8601:2004 Data elements and interchange formats - Information interchange - Representation of dates and times, ISO, International Standards Organization (ISO), 2000.
[OAS, 14] OpenAPI Specification (version 2), D.Miller, J.Harmon, J.Whitlock, K.Hahn, M.Gardiner, M.Ralphson, R.Dolin, R.Ratovsky and T.Tam, OpenAPI Initiative (Linux Foundation), September 2014, https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md.
[RFC 2119] Key words for use in RFCs to Indicate Requirement Levels., S. Bradner, IETF (RFC 2119), March 1997, https://tools.ietf.org/html/rfc2119.
[RFC 3066] Tags for the Identification of Languages, H.Alvestrand, IETF (RFC 3066), January 2001, https://www.ietf.org/rfc/rfc3066.txt.
[RS-BP, 18] IMS LTI Resources Search Service 1.0 Best Practices and Implementation Guide Final Release, A.Blum, T.Ingram, V.Jaiswal and J.Hobson, IMS Global Learning Consortium Inc., September 2018, http://www.imsglobal.org/lti/rsv1p0/rsservicev1p0_bpigv1p0.html.
[RS-CC, 18] IMS LTI Resources Search Service 1.0 Conformance and Certification Final Release, A.Blum, T.Ingram, V.Jaiswal and C.Smythe, IMS Global Learning Consortium Inc., September 2018, http://www.imsglobal.org/lti/rsv1p0/rsservicev1p0_conformancev1p0.html.
[RS-OA, 18] IMS LTI Resources Search Service 1.0 OpenAPI Definition Candidate Final, A.Blum, T.Ingram, V.Jaiswal and C.Smythe, IMS Global Learning Consortium Inc., March 2018, https://www.imsglobal.org/spec/lti-rs/v1p0/rsservicev1p0_openapiv1p0.html.
[RS-RJ, 18] IMS LTI Resources Search Service 1.0 REST/JSON Final Release, A.Blum, T.Ingram, V.Jaiswal and C.Smythe, IMS Global Learning Consortium Inc., September 2018, http://www.imsglobal.org/lti/rsv1p0/rsservicev1p0_restbindv1p0.html.
[RS-SM, 18] IMS LTI Resources Search Service 1.0 Service Model Final Release, A.Blum, T.Ingram, V.Jaiswal and C.Smythe, IMS Global Learning Consortium Inc., September 2018, http://www.imsglobal.org/lti/rsv1p0/rsservicev1p0_infomodelv1p0.html.
[RS-UC, 18] IMS LTI Resources Search Service 1.0 Use-cases Final Release, T.Ingram, A.Blum, V.Jaiswal and J.Hobson, IMS Global Learning Consortium Inc., September 2018, http://www.imsglobal.org/lti/rsv1p0/rsservicev1p0_usecasesv1p0.html.
[UNICODE, 16] UNICODE Collation Algorithm Version 9.0, M.Davis, K.Whistler and M.Scheer, Unicode Technical Standard #10, May 2016.

toc | top

Appendix A REST/JSON Modeling Terms

This Section is NOT NORMATIVE.

A1 REST Endpoint Description Explanations

A1.1 REST Endpoint Mapping Table Explanation

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

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

toc | top

A1.2 Query Parameter Table Explanation

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

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

toc | top

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

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

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

toc | top

A2 UML to JSON Mapping Description Explanations

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

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

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

toc | top

A2.2 UML/JSON Payload Class Mapping Table Definition

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

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

toc | top

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

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

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

toc | top

A2.4 UML/JSON Primitive Types Mapping Table Definition

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

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

toc | top

toc | top

About this Document

Title: IMS LTI Resource Search Service REST/JSON Binding v1.0
Editors: Colin Smythe, IMS Global (UK)
Jill Hobson, IMS Global (USA)

Co-chairs: Adam Blum, OpenEd (USA)
Tom Ingram, Escambia County School District (USA)

Version: 1.0
Version Date: 10th September, 2018
Status: IMS Final Release
Summary: The IMS LTI Resource Search (RS) Service defines how to search digital repositories for a set of resources. The standard addresses searching learning object repositories (LORs), and other catalogs of learning resources, from learning tools using various attributes of resources and returning full metadata about the resources to the learning tools. Results include resource access specification as either URLs or LTI links. The benefit for an educator or student using the learning tool (such as a Learning Management System) is seamless ability to search resource libraries for appropriate resources and transparent launching of those resources. This document contains the REST/JSON binding for the RS service.

Revision Information: First release of this specification.
Purpose: For public adoption.
Document Location: IMS Public Website (Specifications Download): https://www.imsglobal.org/specifications.html

toc | top

List of Contributors

The following individuals contributed to the development of this document:

Ray Baranoski Safari Montage (USA)
Adam Blum Open Ed (USA)
Stacy Cohen Framingham State University (USA)
Paul DeVey Pearson (USA)
Viktor Haag Desire2learn (Canada)
Mark Hannah Knovation (USA)
Jill Hobson IMS Global (USA)
Tom Ingram Escambia County School District (USA)
Vikash Jaiswal Knovation (USA)
Joshua Marks PCG (USA)
Justin Mason University of Wisconsin Extension (USA)
Elizabeth Neuman State of Wisconsin Dept. of Public Instruction (USA)
Colin Smythe IMS Global (UK)

toc | top

Revision History

Version No. Release Date Comments
Final Release 1.0 10th September, 2018 The first formal release for the specification. This specification is made available for public adoption.

toc | top

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

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

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

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

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

IMS Global would appreciate receiving your comments and suggestions.

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

Please refer to Document Name: IMS LTI Resource Search Service REST/JSON Binding v1.0

Date: 10th September, 2018

toc | top