IMS Final Release

Tool Settings in the application/vnd.ims.lti.v2.toolsettings+json format.

Final Version 1.0
Media Type application/vnd.ims.lti.v2.toolsettings+json
RDF Type http://purl.imsglobal.org/vocab/lti/v2/lti#ToolSettingsContainer
JSON-LD http://purl.imsglobal.org/ctx/lti/v2/ToolSettings

Date Issued: 10 September 2015
Latest version: http://www.imsglobal.org/lti

Abstract

In the IMS LTI standard, a Tool may attach settings to certain resources within the Tool Consumer system. This specification defines a JSON representation for those Tool Settings.

Table of Contents

1. Introduction

In the IMS LTI standard, a Tool may attach settings to certain resources within the Tool Consumer system. Tool Settings may be attached to an individual LTI link, to the learning context within which the link is used, or at a system-wide scope. Link-level Tool Settings are stored within the link itself. Context-level Tool Settings are stored within a ToolProxyBinding. System-level Tool Settings are stored within the ToolProxy. This specification defines a JSON representation that can provide details about Tool Settings within a single container or all the relevant containers.

When accessing settings via the REST API [LTI, 14 TSS], a client may specify whether the response should provide settings from one particular container or all relevant containers. The example in Figure 1 shows Tool Settings from three containers: LtiLink, ToolProxyBinding, and ToolProxy.

The various containers are nested within an array labeled by the @graph property. The type of each container is specified by the @type property, and the REST endpoint for the container itself is specified by the @id property. Thus, in Figure 1, the REST endpoint for the LtiLink is given by:

      http://tc.example.com/resources/LtiLink/17001/custom

A client may read or update the settings by issuing an HTTP GET or PUT request at this endpoint in accordance with [LTI, 15 TSS].

{
  "@context" : "http://purl.imsglobal.org/ctx/lti/v2/ToolSettings",
  "@graph" : [ 
    { "@type" : "LtiLink",
      "@id" : "http://tc.example.com/resources/LtiLink/17001",
      "custom" : {
         "@id" : "http://tc.example.com/resources/LtiLink/17001/custom",
         "chapter" : "3",
         "section" : "1"
      }
    },
    { "@type" : "ToolProxyBinding",
      "@id" : "http://tc.example.com/courses/0294823738/bindings/tp.example.com/ebook",
      "custom" : {
        "@id" : "http://tc.example.com/courses/0294823738/bindings/tp.example.com/ebook/custom",
        "isbn" : "978-0321558145",
        "style" : "jazzy"
      }
    },
    { "@type" : "ToolProxy",
      "@id" : "http://tc.example.com/resources/ToolProxy/79833",
      "custom" : {
        "@id" : "http://tc.example.com/resources/ToolProxy/79833/custom",
        "customerId" : "394892759526"
      }
    }
  ]
}

Figure 1.  Example JSON document containing a ToolSettingsContainer object

1.1 How To Read this Document

This specification defines the structure of a JSON document using a graphical notation. In this notatation, an object is represented by a box that branches out to other boxes corresponding to the properties of that object, as shown in Figure 2.

Figure 2.  Representation of a JSON object

Figure 2 is not a complete representation of a ToolSettingsContainer object because custom is an embedded object. A complete diagram would show branches emanating from custom to reveal its properties, and so on, recursively. For a complete representation, see Figure 5 below.

Each box representing a property specifies the name and type of the property , as shown in Figure 3.

Figure 3.  Graphical notation for a property

If a property is optional, its box will be decorated with a circle that contains a question mark, as shown in Figure 3.

An object within a JSON-LD document may have one of four possible representations:

  1. The object may be identified by a fully-qualified URI reference.
  2. The object may be identified by a Compact URI reference, known as a CURIE [CURIE-syntax], that can be expanded to a fully qualified URI
  3. The object may be identified by a simple name that is mapped to a fully-qualified URI. This mapping is defined by the JSON-LD context.
  4. The object may be embedded within the document.

When an object or enumerable value is to be identified by a simple name, the box representing the corresponding property will be decorated with the #sn hash tag, as shown in Figure 4.

Figure 4.  Property whose value is a simple name reference for an individual object or enumerable value

1.2 Reserved Terms

The JSON-LD standard reserves a handful of property names and tokens that have special meaning. These names and tokens, described below, begin with the '@' symbol.

@context
Used to reference (by URI or by value) a context which declares the simple names that appear throughout a JSON document.
@id
Used to uniquely identify things that are being described in the JSON document. The value of an @id property is either a fully-qualified URI, a CURIE, or a simple name that expands to a fully-qualified URI by virtue of the rules defined in the JSON-LD Context.

The @id property may identify a so-called blank node by using a CURIE with an underscore as the prefix. The binding of a JSON-LD document MAY include identifiers for blank nodes, but these identifiers are not required.

@type
Used to set the data type of an object or property value.

JSON-LD specifies four other reserved terms (@value, @language, @container, @list). Ordinarily, these terms are not used in the JSON binding for ToolSettingsContainer objects. However, implementations that extend this specification by including additional properties may utilize these reserved terms in accordance with the rules defined by [JSON-LD-syntax].

1.3 The JSON-LD Context

In JSON-LD, a context is used to map simple names that appear in a JSON document to URI values for properties or data types in a formal vocabulary (typically an RDF ontology). For example, the standard context [LTI, 14 TSS] for a ToolSettingsContainer contains the following rewrite rules (among others):

  {
    "@context" = {
      "lti" : "http://purl.imsglobal.org/vocab/lti/v2/lti#",
      "custom" : "lti:custom",
      ...
    }
  }

2. The ToolSettingsContainer Media Type

The following list defines the necessary and sufficient conditions for a document to conform to the application/vnd.ims.lti.v2.toolsettings+json media type.

  1. The document MUST be a valid JSON document, in accordance with [RFC4627].
  2. The document MUST contain either a single top-level JSON object, or an array of top-level JSON objects. The first object encountered (either the single top-level object or the first element of the array) is called the root object.
  3. The root object must have a @type property whose value is "ToolSettingsContainer" or a subtype of ToolSettingsContainer.
  4. Every top-level object MUST have a @context property that references one or more JSON-LD contexts (either by URI or by value).
  5. Collectively, the set of contexts imported by the root object MUST contain all of the terms found in the standard context [LTI, 14 TSS]. In particular, the set of imported contexts must contain all the simple names that appear in the standard context, and those simple names must resolve to the same values that appear in the standard context. This requirement may be satisfied by ensuring that the root object imports the standard context explicitly, or by importing a collection of other contexts that contain equivalent terms.
  6. The set of contexts imported by the root object MAY include additional terms that do not appear in the standard context [LTI, 14 TSS].
  7. Duplicate mappings for names among the imported contexts MUST be overwritten on a last-defined-overrides basis.
  8. If the JSON-LD context coerces a property to a URI reference, then values of that property MUST be expressed as a fully-qualified URI reference, or a CURIE or a simple name declared by the context.
  9. A collection property is any property whose maximum cardinality is greater than 1. Except for the @context property, a non-empty collection MUST always be represented as a JSON array whose values are enclosed in square brackets. Whereas, in general, the JSON-LD syntax specification allows a collection containing a single value to omit the square brackets, the application/vnd.ims.lti.v2.toolsettings+json media type requires square brackets for all non-empty collections other than the @context property.
  10. An empty collection property may be represented either by an empty array (i.e. square brackets containing no elements), or by omitting the property altogether.
  11. Like all other properties, the @id property of a given object is mandatory if the minimum cardinality of that property, as defined by this specification, is greater than zero. The @id property is optional for all other objects (even if it is not explicitly listed in the set of properties for an object). Conforming implementations SHOULD include the @id property for all addressable objects.
  12. If the @id property is mandatory, then the value MUST NOT treat the object as a blank node. In this case, the @id value MUST NOT be a CURIE with an underscore as the prefix.
  13. Every top-level object MUST contain a @type property and a @context property.
  14. An embedded object MUST contain a @type property if the object value is a subtype of the declared range of the property.
  15. Values for properties named in the standard context [LTI, 14 TSS], MUST not utilize the String Internationalization or Typed Value syntax as described in [JSON-LD-syntax].
  16. If the context does not coerce the value of an object property to a URI reference, then the object must be rendered as an embedded object.
  17. The properties of embedded objects must respect the cardinality constraints specified in the section titled JSON Data Bindings.

3. JSON Data Bindings

Figure 5 presents a complete graphical representation of the JSON binding for a ToolSettingsContainer object. The subsections following this figure provide details about each object that appears in the JSON binding for a ToolSettingsContainer object.

Figure 5.  Complete JSON representation of ToolSettingsContainer
Figure 6.  LtiLink
Property Mult Description Type
@id 0..1 The URI that identifies this LtiLink instance. xs:anyURI
custom 0..1 A collection of custom properties defined by the Tool Provider and stored in this ToolSettingsContainer. PropertyMap
Table 1.  LtiLink properties

3.2 PropertyMap

An abstract class whose properties are defined by the Tool Provider and stored in the Tool Consumer. When represented in JSON-LD, the PropertyMap object typically appears as a plain-old JSON object (though it may have a custom JSON-LD context that defines the semantics for the custom properties). It is a best practice for the values in a PropertyMap to be strings. This best practice may be revised if the development community expresses a desire to support other data types in a PropertyMap.
Figure 7.  PropertyMap

3.3 ToolProxy

This entity defines the integration contract between a ToolConsumer and a Tool. It is called a "ToolProxy" because its primary purpose is to provide the ToolConsumer with all of the information needed to embed a given Tool within the ToolConsumer system.
Figure 8.  ToolProxy
Property Mult Description Type
@id 0..1 The URI that identifies this ToolProxy instance. xs:anyURI
custom 0..1 A collection of custom properties defined by the Tool Provider and stored in this ToolSettingsContainer. PropertyMap
Table 2.  ToolProxy properties

3.4 ToolProxyBinding

A ToolProxyBinding associates a ToolProxy with a learning Context (such as a Course Section). This association must be established before the corresponding Tool can be used within the Context. The ToolProxyBinding also serves as a container that holds tool settings associated with the learning Context.
Figure 9.  ToolProxyBinding
Property Mult Description Type
@id 0..1 The URI that identifies this ToolProxyBinding instance. xs:anyURI
custom 0..1 A collection of custom properties defined by the Tool Provider and stored in this ToolSettingsContainer. PropertyMap
Table 3.  ToolProxyBinding properties

4. References

[CURIE-syntax]
Mark Birbeck, Shane McCarron. CURIE Syntax 1.0. W3C Working Group Note. 16 December 2010.
[JSON-LD-syntax]
Manu Sporny, Dave Longley, Gregg Kellogg, Markus Lanthaler, Mark Birbeck. Json-LD Syntax 1.0. 12 July 2012. W3C Working Draft.
[LTI, 14 TSS]
Stephen Vickers. The application/vnd.ims.lti.v2.toolsettings.simple+json format. IMS Final Release. 10 September 2015.
[LTI, 15 TSS]
Greg McFall, Lance Neumann, Stephen Vickers. Tool Settings Service. June 2015. IMS Specification.
[RFC4627]
D. Crockford. The application/json Media Type for JavaScript Object Notation (JSON). Internet RFC 4627. July 2006.

About this Document

Title: Tool Settings in the application/vnd.ims.lti.v2.toolsettings+json format.
Editor:Stephen Vickers (IMS Global)
Version: 2.0
Version Date: 10 September 2015
Release: Final Release
Status: IMS Final Release
Purpose: This document is made available for review and comment by the public community at large.

List of Contributors

The following list of individuals contributed to the authoring of this document:

Greg McFallPearsonJohn TibbettsVitalSource
Lance NeumannBlackboardStephen VickersIMS Global Learning Consortium

Revision History

The following changes have been made to this document since it was first released:

VersionDateComment
1.023 June 2015Amended wording to use only the @id for endpoints and remove any references the custom_uri property.