LTI Resource Search Implementation Guide 1.0 1EdTech Candidate Final
LTI Resource Search Implementation Guide
Version 1.0
| Date Issued: | 10th September 2018 |
| Status: | This document is made available for adoption by the public community at large. |
| This version: | https://www.imsglobal.org/spec/lti-rs/v1p0/impl/ |
IPR and Distribution Notices
Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.
1EdTech takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on 1EdTech's procedures with respect to rights in 1EdTech specifications can be found at the 1EdTech Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.
Copyright © 2018 1EdTech Consortium. All Rights Reserved.
Use of this specification to develop products or services is governed by the license with 1EdTech found on the 1EdTech website: http://www.imsglobal.org/speclicense.html.
Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.
The limited permissions granted above are perpetual and will not be revoked by 1EdTech or its successors or assigns.
THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.
Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources.
© 2018 1EdTech Consortium, Inc. All Rights Reserved.
Trademark information: http://www.imsglobal.org/copyright.html
1. 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.
2. Introduction
This section is non-normative.
2.1 Scope and Context
The purpose of this document is provide the collected and collated best practice recommendations for the 1EdTech LTI Resource Search 1.0 standard. This information was produced during the development of the standard and from the feedback of the 1EdTech Members who have are implementing Resource Search.
3. Resource Search Consumer Recommendations
Consumers of the Resource Search specification (primarily Learning Management Systems) should consider following the practices to create the best experience for teacher and student users.
3.1 Allow Searching By Key Important Attributes
3.1.1 Use of the Special “Search” Attribute
The special filter attribute, “search”, allows powerful retrieval from the name, description, learning objective, and subject fields.
It is recommended that the ‘search’ attribute be complimented with other filter options, to retrieve a small concentrated list of resources for effective learning.
3.1.2 “Exact match” VS “contains”
The specification provides two options for searching based on keywords or phrases.
In the case where the search url includes “filter=search=[XYZ]”, an exact match of the search string, XYZ, is performed within name, description, learning objective, and subject fields on search provider side. This often results in limited or zero results.
In the case where the search url includes “filter=search~[XYZ]”, a ‘contains’ match of the search string, XYZ, is performed within name, description, learning objective, and subject fields on search provider side. This often results in larger set of results.
3.1.3 Other Recommended Attributes to Expose to Users for Selecting Resources
While a search consumer can still be certified as conformant to the specification by only providing search with this one attribute, it is recommended that at least the following additional attributes be available to users for search:
- learningResourceType (with ability to multiselect types, see section 2.1.4 Be Careful with Contains Searches)
- typicalAgeRange (particularly important for an educational resource catalog)
- learningObjectives (searching based on standard, skill or learning goal is critical for a learning object repository)
- subject
3.1.4 Be Careful with Contains Searches
The Search attribute described above allows CONTAINS searches for keywords supplied against multiple fields. For other fields the CONTAINS search can result in very long search times. Care should be taken to perform exact match searches for fields besides name, description and subject whenever possible.
3.2 Present Selections of Valid Values for Important Attributes
3.2.1 LearningResourceType
In order to allow the user to understand the available search options, a dropdown list or other selection field should be made available to let users see what can be selected. Note that it should be possible to select more than one resource type. Below is the list of available values for learningResourceType. It is NOT necessary to show every possible value. There may be resource types that are less relevant for the learning tool being used or for the audience of that learning tool.
The resource types list implies a hierarchy. It is not necessary that the hierarchy be presented to the user. It is also not necessary that the exact names used here are presented to the user. For example, in a learning tool that anticipates use of many text-oriented resources, the tool may present these as just a selection of:
“Book”, “Chapter”, “Document”, “Article”, “Passage”, “Textbook” and “Reference”. The learning tool may decide not to list “Website” as one of the types.
If it is desired to expose all or a large number of resource types, the hierarchy present in the list may be an efficient way to make the list less overwhelming. For example, a tree or indented menu of types organized by the top level type such as “Text” or “Assessment”.
3.2.2 Technical Formats
Technical formats are listed as MIME types, such as “video/mpeg” and “text/html”. Most users will not know what these stand for. Presenting a list of technical formats with explanations of each format (such as “Video (video/mpeg)” or “Website (text/html)” is suggested.
3.2.3 LearningObjectives
A list of available learning objectives should be displayed. To prepare such a list, it is recommended to connect to a Competencies and Academic Standards Exchange® (CASE®) -compliant repository of learning objectives (CASE is an 1EdTech standard for representing the content of learning goals). For more information see the 1EdTech CASE Technical Activity Page. Then the caseItemURI attribute of the standard or objective selected can be used in the resource search query.
3.2.4 Subjects
The Resource Search standard has a REST /subjects call for returning the topics available in the Resource Search provider’s repository. In order for the user to understand the subjects available for search it is recommended to make the subject list available to the user. A REST call to retrieve subjects need not occur every time the user is presented with search options. The subjects list can be cached at intervals that are deemed to be appropriate by the learning tool.
3.2.5 Grades for TypicalAgeRange
In order to make the standard internationally relevant, the Resource Search standard uses typicalAgeRange instead of grade range. Users will expect to see grade ranges appropriate to their locality. It is a best practice to present the appropriate grade range for selection to the user and then translate to an appropriate age range for the call to the API.
3.3 Implement OAuth to Authenticate to the Search Provider
In today’s education space, most of the search providers, such as a LOR, control access to their repository via some authentication. Though the Resource Search does not require an authenticated access to the search provider, it is recommended that applications/ systems secure their Resource Search endpoints behind authentication.
The suggested method of authentication is oAuth 2.0.
3.4 Aggregating Results from Multiple Search Providers
There are two dominant methods of aggregating resource search and results from multiple Learning Object Repositories (or Resource Search Providers): tabbed separation of results, and aggregated single list results.
3.4.1 Tabbed Separation of Results
This is the easiest method to implement for the Resource Search Consumer. Each resource search provider’s /resources endpoint can be invoked with the same search criteria. Results are then presented to users from each search provider on separate tabs. It is important for understandability to the search user to present each resource entry with similar metadata attributes.3.4.2 Aggregated Results
Results from multiple Resource Search searches can be interleaved according to the sort criteria desired, such as rating, publication date, title, author, or publisher. Some attributes are not ideal for using as the aggregation sort because it is difficult to compare them across search providers. Such attributes include relevance (which is subjectively determined by each search provider independently) and subject (since each search provider typically has its own subject taxonomy).
3.4.3 Aggregated Results with Tabbed Separation of Results
Results from multiple Resource Search searches can be interleaved according to the sort criteria desired, such as rating, publication date (most recent first), title, author, or publisher on the first tab. Results may be presented to users from each search provider on separate tabs. It is important for understandability to the search user to present each resource entry with similar metadata attributes.
3.5 Try Not to Frustrate Users by Presenting Inaccessible Resources
It is often observed in K-12 integration that the search provider resources are made available to a search consumer application/ system at a business partnership level but the access to deployment of such resources at a district or school level is governed by the specific subscription of the resources to the school/ district. As an administrative configuration for a district or school level deployment, a consuming application, like an LMS, could control the access to only search API certain search providers.
Additionally, the consuming application could use the metadata returned through the search API, to control the access/ display of results to teachers/ students. For example, if the search consumer does not want to include learning resources from publishers that require students to register to their website separately, they could use the ‘publisher’ metadata for the search results to filter out those resources for better user experience.
Note that the identity and role of the accessing user is not known to the search provider via the specification. So a consuming application, such as an LMS, should follow guidelines such as these to optimize the user experience.
3.6 Search for Resources by Learning Objective
A consuming application should allow its users to search for resources aligned to specific state or international standards. This should be presented to users with some form of browsing of the standard taxonomies.
The consuming application should then take selected standards and pass them to the search provider via Resource Search specification. Ideally this is done with a “caseItemURI” attribute, using the 1EdTech Competencies and Academic Standard Exchange® (CASE®) standard. That is, the consuming application should retrieve the appropriate caseItemURI from a CASE-supporting learning standards repository whose caseItemURIs are also used by the search provider. Then provide the caseItemURI in the learningObjective parameter. Failing use of a shared CASE-based standards repository, a consuming application may also search for resources using the standard’s identifier name in the learningObjective query parameter.
4. Resource Search Provider Recommendations
4.1 Recommended Search Provider Privacy Approach
The Resource Search specification enables search providers to have no knowledge of user identity, user roles, or organization identity. This is important as making search and retrieval behavior dependent on user identities and roles drastically expands the scope of work for search providers. Storing and utilizing user information also subjects search providers to a whole class of regulatory issues that they would otherwise not have to be concerned with. It is also not optimal separation of concerns from a system architecture perspective.
We recommend that the search provider defer any user role dependent behavior, such as which resource attributes to display or allow searches by, to the search consumer. Knowledge of which resources or publishers a user or organization has access to should also be left to the search consumer. The search provider should return all matching resources for any search. The LTI link will be used to provide access. The search provider should not try to filter resources that a user does not have access to as this would involved storing user, organization or role information.
4.2 Resource Consumption Data Should Be Stored and Exposed to Consuming Apps via Caliper
Resource Search consuming applications may want to get information about how the resources they present as the result of searches are consumed by their users. For example, if a video is returned by the search a search consumer may want to see how all students using their service watched the video (with statistics such as view duration, frequency, and finish rate).
Rather than the search provider exposing additional endpoints to enable this scenario, search consumers should store resource consumption data (if they have access to it) in a Learning Record Store (LRS) via Caliper. If the search consumer does not have access to end user usage and behavior with the resource, the search provider should store this information to a Caliper LRS.
In order to allow the search consumer to query events on users, the search provider needs to insure that Caliper events are generated based on the (anonymized) user IDs sent to it by the consuming application. Aggregate usage of resources (e.g. total number of views of a specific video, average scores on a particular assessments) can also be captured via Caliper event retrieval. This should also not be exposed as individual endpoints by the search provider.
A. Use cases
This section is non-normative.
The following use cases are supported by this specification:
A.1 Use-case 1
| Title: | Use keywords to search for learning objects provided by external sources (search providers) within a platform (search consumer) |
| Local ID: | LTI-RS-01 |
| Description: | Basic search: Use keywords (search terms) to search for learning objects in restricted- and unrestricted-access libraries.
Availability: search provisioned for certain educational audiences Results, each should comprise:
Results should be organized and:
Results can suggest organization: Icons or tags to indicate media type, content type, etc (results sent back need to include meta-data) |
| Level: | Summary |
| Actors: | Primary - Search Consumer -- thing that makes the search request
Secondary - Search Provider -- thing that responds to the request with search results |
| Stakeholder: | Student/Teacher/Parent Role in Learning Platform
Primary: People who search (Learner/Parent/Instructor (curriculum assistance)) Primary: Instructor/Instructional Designer (those who create or assist in creating courses/curriculum) Secondary: People who want other people to search because it helps them (Instructor/Parent) (Learner -- they want good curriculum) Secondary: Administrator (may need to install/provision access to results) |
| Interest: | -- Search to learn more about something, want relevant results (illuminate curriculum, or provide extension)
-- Search to find resources to make available to others (curriculum building), want relevant results that meet curriculum needs (learning objectives) |
| Notes: | This use case could be implemented by the best practice suggested in the section "Use The Special 'Search' Attribute" of the Implementation Guide. |
A.2 Use-case 2
| Title: | Use keywords and metadata to search for learning objects provided by external sources (search providers) within a platform (search consumer) |
| Local ID: | LTI-RS-02 |
| Description: | Advanced search: Use keywords(search terms) and metadata (filter values) to search for learning objects in restricted- and unrestricted-access libraries.
Results should be organized/filterable: could vary by role (for example -- search results “public”, and search results “restricted to view by role”: e.g. resources that are assessments to go with curriculum plus answer key for same assessments) could vary by relevance (i.e. “best matches first”) could group by content type (i.e. assessments, videos , reference topics, etc) could group by media type (i.e videos, images, documents) could vary by license/rights (i.e. “open matches first”) could group by source (matches from sources together) |
| Level: | Summary |
| Actors: | Primary - Search Consumer -- thing that makes the search request
Secondary - Search Provider -- thing that responds to the request with |
| Stakeholder: | Student/Teacher/Parent Role in Learning Platform |
| Interest: | -- Search to learn more about something, want relevant results (illuminate curriculum, or provide extension)
-- Search to find resources to make available to others (curriculum building), want relevant results that meet curriculum needs (learning objectives) |
| Notes: | This use case could be implemented by best practice suggested in the section "'Exact match' VS 'contains'" of the Implementation Guide. |
A.3 Use-case 3
| Title: | Take action on search results |
| Local ID: | LTI-RS-03 |
| Description: | Student/Teacher/Parent gain access to one or more items returned in the results. Resolve authentication of resource access (if necessary).
Launch item If an open item on the web and the search provider doesn’t care to have data about the launch of the item, the link can be provided as a straight URL. If the item requires authentication, then the link will be provided as an LTI link. Add item to course content. The user should have the ability to add the content to his/her course(s), when the appropriate role exists within the Search Consumer from the search results. |
| Level: | Summary |
| Actors: | Primary - Search Consumer -- thing that makes the search request
Secondary - Search Provider -- thing that responds to the request with |
| Stakeholder: | Teacher/Curriculum Admin Role in Learning Platform
Primary: People who search (Learner/Parent/Instructor (curriculum assistance)) Primary: Instructor/Instructional Designer (those who create or assist in creating courses/curriculum) Secondary: People who want other people to search because it helps them (Instructor/Parent) (Learner -- they want good curriculum) Secondary: Administrator (may need to install/provision access to results) |
| Interest: | Search to find resources to make available to others (curriculum building), want relevant results that meet curriculum needs (learning objectives) |
| Notes: | This use case could be implemented by use of ‘URL’ metadata that is returned as part of search response payload. |
A.4 Use-case 4
| Title: | Provision various restricted and unrestricted access libraries for search within the learning platform. |
| Local ID: | LTI-RS-04 |
| Description: | Provision restricted access libraries by providing appropriate credentials to verify access. Provision unrestricted access libraries. Provision which learning platform user roles should be able to perform searches. |
| Level: | Summary |
| Actors: | Primary - Technical Administrator for the Search Consumer Product
Secondary - Technical Administrator for the Search Provider |
| Stakeholder: | Technical Administrator |
| Interest: | Technical Administrator wants to authorize appropriate search access. |
| Notes: | This use case could be implemented by best practice suggested in the section "Recommended Search Provider Privacy Approach" of the Implementation Guide. |
A.5 Use-case 5
| Title: | Use of metadata to restrict access to libraries for search within the learning platform. |
| Local ID: | LTI-RS-05 |
| Description: | Use metadata to restrict material that has copyright restrictions for example, restrict to grade levels, ability to send in preferences from a search consumer (such as an LMS) to search consumer (such as a LOR) to restrict access to specific context |
| Level: | Summary |
| Actors: | Primary - Technical Administrator for Search Consumer
Secondary - Search Provider |
| Stakeholder: | Technical Administrator |
| Interest: | Technical Administrator wants to authorize appropriate search access. |
| Notes: | This use case could be implemented by the best practice suggested in the section "Present Selections of Valid Values for Important Attributes" of the Implementation Guide. |
A.6 Use-case 6
| Title: | Limiting type of resources that may be searched |
| Local ID: | LTI-RS-06 |
| Description: | Technical administrator limiting types of resources that could be searched by students. For example, we wouldn't want students to be able to search assessments, teacher editions, answer keys, etc. |
| Level: | Summary |
| Actors: | Primary - Technical Administrator for Search Consumer
Secondary - Search Provider |
| Stakeholder: | Technical Administrator |
| Interest: | Primary - Technical Administrator would want to control the type of Search allowed in the
learning platform (Search Consumer)
Secondary - Search Providers need to tag resources via Learning Resource Type or keyword appropriately to comply with this use case. |
| Notes: | This use case could be implemented by the best practice suggested in the section "Present Selections of Valid Values for Important Attributes" of the Implementation Guide. |
A.7 Use-case 7
| Title: | Prioritize search results |
| Local ID: | LTI-RS-07 |
| Description: | Technical administrators being able to prioritize returned search
results. For example, with aggregated results, tech administrator may
want to prioritize certain search providers, relevance from certain
search providers, etc.
Another example is a district wants their curated resources to appear for generally available resources. |
| Level: | Summary |
| Actors: | Technical Administrator for the learning platform (Search Consumer) |
| Stakeholder: | Technical Administrator |
| Interest: | Primary - Technical Administrator should be able to prioritize results, for display to students/ teachers, based on publisher or search provider so that high value resources are available first. |
| Notes: | This use case could be implemented by the best practices suggested in the "Present Selections of Valid Values for Important Attributes" and "Try Not to Frustrate Users by Presenting Inaccessible Resources" sections of the Implementation Guide. |
A.8 Use-case 8
| Title: | Search for learning objects by the human readable identifier |
| Local ID: | LTI-RS-08 |
| Description: | End users in the learning platform want to be able to search for learning objects by the human readable identifier (e.g. CCSSO.Math.G.1)
Alternately, searching by standard via pick list of standards so the user can select to which standards the content should be aligned |
| Level: | Summary |
| Actors: | Primary - Users in the learning platform (Search Consumer)
Primary - Technical Administrator (Search Consumer) Secondary - Search Provider |
| Stakeholder: | Primary: People who search (Learner/Parent/Instructor (curriculum assistance))
Primary: Instructor/Instructional Designer (those who create or assist in creating courses/curriculum) Secondary: People who want other people to search because it helps them (Instructor/Parent) (Learner -- they want good curriculum) Secondary: Administrator (may need to install/provision access to results) |
| Interest: | Search to find resources to make available to others (curriculum building), want relevant results that meet curriculum needs (learning objectives) |
| Notes: | This use case could be implemented by the best practice suggested in the "LearningObjectives" section of the Implementation Guide. |
A.9 Use-case 9
| Title: | Narrow search result set based on learning resource ratings |
| Local ID: | LTI-RS-09 |
| Description: | Allow users to view/ filter resources based on ratings |
| Level: | Subfunction |
| Actors: | Primary - Users in the learning platform (Search Consumer)
Primary - Technical Administrator (Search Consumer) Secondary - Search Provider |
| Stakeholder: | Primary: People who search (Learner/Parent/Instructor (curriculum assistance))
Primary: Instructor/Instructional Designer (those who create or assist in creating courses/curriculum) Secondary: People who want other people to search because it helps them (Instructor/Parent) (Learner -- they want good curriculum) Secondary: Administrator (may need to install/provision access to results) |
| Interest: | Allow users to narrow result sets based on ratings |
| Notes: | This use case could be implemented by utilizing the attribute rating filter |
A.10 Use-case 10
| Title: | Analyzing the performance of learning objects and their metadata |
| Local ID: | LTI-RS-10 |
| Description: | Learning Object Repository search providers and Technical and Curriculum Administrators want to understand how learning objects are being used, how searches are surfacing results and what action the user is taking on objects (adding to course content, saving for later use, etc). |
| Level: | Summary |
| Actors: | Primary - Learning Object Repositories (Search Providers)
Secondary - Learning Platforms (Search Consumer) |
| Stakeholder: | Technical Administrator for the Learning Object Repository (Search Provider)
Technical Administrator for the Learning Platform (Search Consumer) |
| Interest: | Technical Administrator and/ or Search Providers may be interested in understanding the effectiveness of resources, in the teaching/ learning environment |
| Notes: | This use case could be implemented by the best practice suggested in the "Resource Consumption Data Should Be Stored and Exposed to Consuming Apps via Caliper" section of the Implementation Guide. |
B. Revision History
This section is non-normative.
B.1 Version History
| Version No. | Release Date | Comments |
|---|---|---|
| 1EdTech Final Release [LTI-RS-10] | 10th September 2018 | First release of this specification. |
C. References
C.1 Informative references
- [LTI-RS-10]
- LTI Resource Search 1.0. 1EdTech Consortium. URL: https://www.imsglobal.org/lti-rs/v1p0/
D. List of Contributors
The following individuals contributed to the development of this document:
| Name | Organization | Role |
|---|---|---|
| Jill Hobson | 1EdTech Consortium (USA) | Editor |
| Adam Blum | ACT (USA) | Task Force Co-chair |
| Tom Ingram | Escambia County School District (USA) | Task Force Co-chair |
| Vikash Jaiswal | Knovation, Inc (USA) | Task Force Co-chair |
| Ray Baranoski | SAFARI Montage (USA) | |
| Paul DeVe | Pearson Education (USA) | |
| Viktor Haag | D2L Corporation (USA) | |
| Vikash Jaiswal | Knovation (USA) | |
| Elizabeth Neuman | Wisconsin Department of Public Instruction (USA) | |
| Colin Smythe | 1EdTech Consortium (USA) | Editor |