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.
© 2018 IMS Global Learning Consortium, Inc.
All Rights Reserved.
Trademark information: http://www.imsglobal.org/copyright.html
Document Name: IMS LTI Resource Search Service REST/JSON Binding v1.0
Revision: 10th September, 2018
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.
1. Introduction
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
3. Using the Endpoint Query Parameters
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
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.1 Proprietary Operations
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
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.4.1 - Tabular representation of the JSON payload for "200" 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.
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.
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.
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.
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). |
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 |
This Section is NORMATIVE.
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.
Service Call | REST Endpoint | HTTP Verb |
---|---|---|
getAllSubjects | /subjects | GET |
searchForResources | /resources | GET |
All of the paths MUST also contain, as the base of the path, excluding the host name, the string: "/ims/rs/v1p0".
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.
There are no pre-defined query parameters for this endpoint.
The description of the "fields" query parameter is presented in Table 2.3.2.1
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. |
The description of the "filter" query parameter is presented in Table 2.3.2.2
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]). |
The description of the "limit" query parameter is presented in Table 2.3.2.3
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). |
The description of the "offset" query parameter is presented in Table 2.3.2.4
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). |
The description of the "orderBy" query parameter is presented in Table 2.3.2.5
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). |
The description of the "sort" query parameter is presented in Table 2.3.2.6
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). |
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.
REST Endpoint | HTTP Verb | HTTP Codes and Handling |
---|---|---|
/resources | GET |
|
/subjects | GET |
|
This Section is NORMATIVE.
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:
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:
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:
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:
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.
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"
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.
This Section is INFORMATIVE.
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.
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 |
The syntax and semantics for the Root Class UML/JSON mapping representations is described in Appendix A2.2.
The UML/JSON Mapping for the "ResourceSet" Service Parameter Payload Class is given in Table 5.2.1.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
ResourceSet | Payload Parameter | Container [ Unordered ] | - N/A - | ResourceSet.Type | Object |
|
Attribute | Resource | [0.. *] | resources | Array of Properties |
The UML/JSON Mapping for the "SubjectSet" Service Parameter Payload Class is given in Table 5.2.2.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
SubjectSet | Payload Parameter | Container [ Unordered ] | - N/A - | SubjectSet.Type | Object |
|
Attribute | Subject | [0.. *] | subjects | Array of Properties |
The syntax and semantics for the Data Class UML/JSON mapping representations is described in Appendix A2.2.
The Payload UML/JSON Mapping for the "CCLTILink" Class is given in Table 5.3.1.
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 |
|
Attribute | LTILinkResourceRef | [0..1] | cartridge_bundle | Property |
|
Attribute | LTILinkResourceRef | [0..1] | cartridge_icon | Property |
|
Attribute | Metadata | [0..1] | metadata | Property |
The Payload UML/JSON Mapping for the "CSMSet" Class is given in Table 5.3.2.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
CSMSet | Core | Container [ Unordered ] | - N/A - | CSMSet.Type | Object |
|
Attribute | PT: NormalizedString | [0..1] | resourceLabel | Property |
|
Attribute | PT: NormalizedString | [0..1] | resourcePartId | Property |
|
Attribute | CurriculumStandardsMetadata | [1.. *] | curriculumStandardsMetadata | Array of Properties |
The Payload UML/JSON Mapping for the "CurriculumStandardsMetadata" Class is given in Table 5.3.3.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
CurriculumStandardsMetadata | Core | Container [ Unordered ] | - N/A - | CurriculumStandardsMetadata.Type | Object |
|
Attribute | PT: NormalizedString | [0..1] | providerId | Property |
|
Attribute | SetOfGUIDs | [1.. *] | setOfGUIDs | Array of Properties |
The Payload UML/JSON Mapping for the "LTILink" Class is given in Table 5.3.4.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
LTILink | Core | Container [ Unordered ] | - N/A - | LTILink.Type | Object |
|
Attribute | PT: NormalizedString | [1] | title | Property |
|
Attribute | PT: String | [0..1] | description | Property |
|
Attribute | PropertySet | [0..1] | custom | Property |
|
Attribute | PlatformPropertySet | [0..1] | extensions | Property |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | launch_url | Property |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | secure_launch_url | Property |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | icon | Property |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | secure_icon | Property |
|
Attribute | Vendor | [1] | vendor | Property |
The Payload UML/JSON Mapping for the "LTILinkResourceRef" Class is given in Table 5.3.5.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
LTILinkResourceRef | Core | Container [ Unordered ] | - N/A - | LTILinkResourceRef.Type | Object |
|
Attribute | PT: NormalizedString | [1] | name | Property |
|
Attribute | PT: AnyURI | [1] | resourceUri | Property |
The Payload UML/JSON Mapping for the "LabelledGUID" Class is given in Table 5.3.6.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
LabelledGUID | Core | Container [ Unordered ] | - N/A - | LabelledGUID.Type | Object |
|
Attribute | PT: NormalizedString | [0..1] | label | Property |
|
Attribute | PT: AnyURI | [0..1] | caseItemURI | Property |
|
Attribute | DT: GUID (PT: NormalizedString) | [1] | GUID | Property |
The Payload UML/JSON Mapping for the "LearningObjectives" Class is given in Table 5.3.7.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
LearningObjectives | Core | Container [ Unordered ] | - N/A - | LearningObjectives.Type | Object |
|
Attribute | [ Enumeration (AlignmentTypeEnum) ] | [1] | alignmentType | Property |
|
Attribute | PT: NormalizedString | [0..1] | educationalFramework | Property |
|
Attribute | PT: NormalizedString | [0..1] | targetDescription | Property |
|
Attribute | PT: NormalizedString | [0..1] | targetName | Property |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | targetURL | Property |
|
Attribute | PT: AnyURI | [0..1] | caseItemUri | Property |
|
Attribute | DT: GUID (PT: NormalizedString) | [0..1] | caseItemGUID | Property |
The Payload UML/JSON Mapping for the "Metadata" Class is given in Table 5.3.8.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
Metadata | Core | Container [ Unordered ] | - N/A - | Metadata.Type | Object |
|
Attribute | CSMSet | [0..1] | curriculumStandardsMetadataSet | Property |
The Payload UML/JSON Mapping for the "PlatformPropertySet" Class is given in Table 5.3.9.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
PlatformPropertySet | Core | Container [ Unordered ] | - N/A - | PlatformPropertySet.Type | Object |
|
Attribute | PT: NormalizedString | [1] | platform | Property |
|
Attribute | Property | [1.. *] | properties | Array of Properties |
The Payload UML/JSON Mapping for the "Property" Class is given in Table 5.3.10.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
Property | Core | Container [ Unordered ] | - N/A - | Property.Type | Object |
|
Attribute | PT: NormalizedString | [1] | name | Property |
|
Attribute | PT: NormalizedString | [1] | value | Property |
The Payload UML/JSON Mapping for the "PropertySet" Class is given in Table 5.3.11.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
PropertySet | Core | Container [ Unordered ] | - N/A - | PropertySet.Type | Object |
|
Attribute | Property | [1.. *] | properties | Array of Properties |
The Payload UML/JSON Mapping for the "Resource" Class is given in Table 5.3.12.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
Resource | Core | Container [ Unordered ] | - N/A - | Resource.Type | Object |
|
Attribute | DT: NString1024 (PT: NormalizedString) | [1] | name | Property |
|
Attribute | DT: NString2048 (PT: NormalizedString) | [0..1] | description | Property |
|
Attribute | DT: NString1024 (PT: NormalizedString) | [0.. *] | subject | Array of Properties |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | url | Property |
|
Attribute | CCLTILink | [0..1] | ltiLink | Property |
|
Attribute | [ Enumeration (LRTEnum) ] | [1.. *] | learningResourceType | Array of Properties |
|
Attribute | PT: Language | [0.. *] | language | Array of Properties |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | thumbnailUrl | Property |
|
Attribute | DT: AgeRange (PT: NormalizedString) | [0..1] | typicalAgeRange | Property |
|
Attribute | TextComplexity | [0.. *] | textComplexity | Array of Properties |
|
Attribute | LearningObjectives | [0.. *] | learningObjectives | Array of Properties |
|
Attribute | DT: NString2048 (PT: NormalizedString) | [0.. *] | author | Array of Properties |
|
Attribute | DT: NString2048 (PT: NormalizedString) | [1] | publisher | Property |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | useRightsURL | Property |
|
Attribute | PT: Duration | [0..1] | timeRequired | Property |
|
Attribute | PT: NormalizedString | [0..1] | technicalFormat | Property |
|
Attribute | [ Enumeration (EducationalAudienceEnum) ] | [0.. *] | educationalAudience | Array of Properties |
|
Attribute | [ Enumeration (AccessibilityAPIEnum) ] | [0.. *] | accessibilityAPI | Array of Properties |
|
Attribute | [ Enumeration (AccessibilityInputEnum) ] | [0.. *] | accessibilityInputMethods | Array of Properties |
|
Attribute | PT: NormalizedString | [0.. *] | accessibilityFeatures | Array of Properties |
|
Attribute | [ Enumeration (HazardEnum) ] | [0.. *] | accessibilityHazards | Array of Properties |
|
Attribute | [ Enumeration (AccessModeEnum) ] | [0.. *] | accessMode | Array of Properties |
|
Attribute | PT: Date | [0..1] | publishDate | Property |
|
Attribute | [ Enumeration (RatingEnum) ] | [0..1] | rating | Property |
|
Attribute | DT: Float0to1 (PT: Float) | [0..1] | relevance | Property |
|
Attribute | PT: Namespace | [0.. *] | Set of Proprietary Properties | Set of Proprietary Properties |
The Payload UML/JSON Mapping for the "SetOfGUIDs" Class is given in Table 5.3.13.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
SetOfGUIDs | Core | Container [ Unordered ] | - N/A - | SetOfGUIDs.Type | Object |
|
Attribute | PT: NormalizedString | [0..1] | region | Property |
|
Attribute | PT: NormalizedString | [0..1] | version | Property |
|
Attribute | LabelledGUID | [1.. *] | labelledGUID | Array of Properties |
The Payload UML/JSON Mapping for the "Subject" Class is given in Table 5.3.14.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
Subject | Core | Container [ Unordered ] | - N/A - | Subject.Type | Object |
|
Attribute | PT: PositiveInteger | [1] | identifier | Property |
|
Attribute | PT: NormalizedString | [1] | name | Property |
|
Attribute | PT: PositiveInteger | [1] | parent | Property |
The Payload UML/JSON Mapping for the "TextComplexity" Class is given in Table 5.3.15.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
TextComplexity | Core | Container [ Unordered ] | - N/A - | TextComplexity.Type | Object |
|
Attribute | [ Enumeration (TextComplexityNameEnum) ] | [1] | name | Property |
|
Attribute | PT: NormalizedString | [1] | value | Property |
The Payload UML/JSON Mapping for the "Vendor" Class is given in Table 5.3.16.
Information Model Details | JSON Binding Details | ||||
---|---|---|---|---|---|
Name | UML Artefact | Data Type | Multiplicity | Name | Type |
Vendor | Core | Container [ Unordered ] | - N/A - | Vendor.Type | Object |
|
Attribute | PT: NormalizedString | [1] | code | Property |
|
Attribute | PT: NormalizedString | [1] | name | Property |
|
Attribute | PT: String | [0..1] | description | Property |
|
Attribute | DT: URL (PT: AnyURI) | [0..1] | url | Property |
|
Attribute | PT: NormalizedString | [0..1] | emailContact | Property |
The Payload UML/JSON Mapping for the "imsx_CodeMinor" Class is given in Table 5.3.17.
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 |
|
Attribute | imsx_CodeMinorField | [1.. *] | imsx_codeMinorField | Array of Properties |
The Payload UML/JSON Mapping for the "imsx_CodeMinorField" Class is given in Table 5.3.18.
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 |
|
Attribute | PT: NormalizedString | [1] | imsx_codeMinorFieldName | Property |
|
Attribute | [ Enumeration (imsx_CodeMinorValueEnum) ] | [1] | imsx_codeMinorFieldValue | Property |
The Payload UML/JSON Mapping for the "imsx_StatusInfo" Class is given in Table 5.3.19.
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 |
|
Attribute | [ Enumeration (imsx_CodeMajorEnum) ] | [1] | imsx_codeMajor | Property |
|
Attribute | [ Enumeration (imsx_SeverityEnum) ] | [1] | imsx_severity | Property |
|
Attribute | PT: String | [0..1] | imsx_description | Property |
|
Attribute | imsx_CodeMinor | [0..1] | imsx_codeMinor | Property |
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.
There are no enumerated list class definitions.
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.
This Section is NON-NORMATIVE.
There is no payload for this request.
A tabular description of the response payload is shown in the Table below.
An example of the response JSON payload is shown in the code block below.
A tabular description of the response payload is shown in the Table below.
An example of the response JSON payload is shown in the code block below.
There is no payload for this request.
A tabular description of the response payload is shown in the Table below.
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.
A tabular description of the response payload is shown in the Table below.
An example of the response JSON payload is shown in the code block below.
This Section is NOT NORMATIVE.
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.
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].
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.
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.
[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. |
This Section is NOT NORMATIVE.
Table A1.1 provides 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:
|
Table A1.2 provides the key to the descriptions of the query parameters that are permitted for an endpoint.
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:
|
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:
|
Description | Contains descriptions relating to the query parameter and its values space. |
Table A1.3 provides 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:
|
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. |
Table A2.1 provides 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. |
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:
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:
|
Multiplicity | The multiplicity of the child attribute/characteristic. The value for the Class itself is "-N/A-". The multiplicity values are:
|
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. |
Table A2.3 provides 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. |
Table A2.4 provides 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. |
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 |
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) |
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. |
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