IMS Public Draft

# Content-Item Placements in the `application/vnd.ims.lti.v1.contentitemplacement+json` format.

Public Draft - Content-Item Message

Media Type | application/vnd.ims.lti.v1.contentitemplacement+json
RDF Type | http://purl.imsglobal.org/vocab/lti/v1/ci#ContentItemPlacement
JSON-LD | http://purl.imsglobal.org/ctx/lti/v1/ContentItemPlacement

Date Issued: 7 April 2014
Latest version: http://www.imsglobal.org/lti

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 © 2014 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/license.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.

Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

© 2014 IMS Global Learning Consortium, Inc.
All Rights Reserved.
The IMS Logo and Learning Tools Interoperability (LTI) are trademarks of the IMS Global Learning Consortium, Inc. in the United States and/or other countries.
v1.0 Public Draft - Revision: 7 April 2014

## Table of Contents

## 1. Introduction

The Content-Item Message allows a Tool Provider (TP) to be involved in the process of adding items to a content page within a Tool Consumer (TC). The TP is launched by the TC with the `ContentItemSelectionRequest` message type allowing the TP to provide the user with an interface for selecting one, or more, items for placement into the TC. This JSON binding describes the format used to return the selected items back to the TC.

Figure 1 shows the representation of a ContentItemPlacement resource in the `application/vnd.ims.lti.v1.contentitemplacement+json` format.

    {
      "@context" : "http://purl.imsglobal.org/ctx/lti/v1/ContentItemPlacement",
      "@graph" : [
        { "@type" : "ContentItemPlacement",
          "presentation_document_target" : "window",
          "placementOf" : {
            "@type" : "LtiLink",
            "icon" : {
              "@id" : "http://tool.provider.com/icons/small.png",
              "width" : 50,
              "height" : 50
            },
            "thumbnail" : {
              "@id" : "http://tool.provider.com/images/thumb.jpg",
              "width" : 100,
              "height" : 150
            },
            "text" : "The <em>sIMSon</em> application provides a collaborative space for developing semantic modelling skills.",
            "mediaType" : "application/vnd.ims.lti.v1.launch+json",
            "title" : "Open sIMSon application",
            "custom" : {
              "level" : "novice",
              "mode" : "interactive"
            }
          },
          "windowTarget" : "anLTIApp"
        },
        { "@type" : "ContentItemPlacement",
          "copyAdvice" : false,
          "displayWidth" : 800,
          "presentation_document_target" : "iframe",
          "displayHeight" : 600,
          "placementOf" : {
            "@type" : "FileItem",
            "@id" : "http://tool.provider2.com/animation/sample.swf",
            "icon" : {
              "@id" : "http://tool.provider2.com/icon/sample.png",
              "width" : 45,
              "height" : 45
            },
            "text" : "Watch this animation.",
            "mediaType" : "application/x-shockwave-flash"
          }
        }
      ]
    }

Figure 1. Example JSON document containing a ContentItemPlacement 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 `ContentItemPlacement` object because `placementOf` is an embedded object. A complete diagram would show branches emanating from `placementOf` 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 `ContentItemPlacement` 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 CI] for a ContentItemPlacement contains the following rewrite rules (among others):

      {
        "@context" = {
          "ci" : "http://purl.imsglobal.org/vocab/lti/v1/ci#",
          "placementOf" : "ci:placementOf",
          ...
        }
      }

A context may specify that the values of certain object properties must be rendered as URI references. The following snippet presents an example of such a rule.

      {
        "@context" = {
          ...
          "presentation_document_target" : {
            "@id" : "ci:presentation_document_target",
            "@type" : "@id"
          }
          ...
      }

This rule is an example of type coercion. For more details about the syntax of a JSON-LD context, see [JSON-LD-syntax].

## 2. The ContentItemPlacement Media Type

The following list defines the necessary and sufficient conditions for a document to conform to the `application/vnd.ims.lti.v1.contentitemplacement+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 "`ContentItemPlacement`".
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 CI]. 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 CI].
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.v1.contentitemplacement+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 CI], 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 ContentItemPlacement object. The subsections following this figure provide details about each object that appears in the JSON binding for a ContentItemPlacement object.

Figure 5. Complete JSON representation of ContentItemPlacement

### 3.1 ContentItem

Figure 6. ContentItem
Direct Known Subtypes:
LtiLink, FileItem

Property | Mult | Description | Type
--- | --- | --- | ---
@id | 0..1 | The URI that identifies this `ContentItem` instance. | xs:anyURI
icon | 0..1 | An image which may be used as an icon for the content-item. | Image
mediaType | 1 | The MIME type of the content-item. | xs:normalizedString
text | 0..1 | A plain text description of the content-item. | xs:string
thumbnail | 0..1 | An image which may be used as a thumbnail for the content-item. | Image
title | 0..1 | A plain text title of the content-item. | xs:normalizedString

Table 1. ContentItem properties

### 3.2 ContentItemPlacement

Figure 7. ContentItemPlacement

Property | Mult | Description | Type
--- | --- | --- | ---
displayHeight | 0..1 | The height in pixels of the display area. | xs:integer
displayWidth | 0..1 | The width in pixels of the display area. | xs:integer
placementOf | 1 | The content-item to be placed. | ContentItem
presentation_document_target | 0..1 | The intended destination where the content-item is displayed to users. The value is taken from a list of permitted targets. | DocumentTarget (Simple Name reference)
windowTarget | 0..1 | The value for the `target` attribute of any anchor tag which is used to make the content-item available to users. | xs:normalizedString

Table 2. ContentItemPlacement properties

### 3.3 DocumentTarget

Figure 8. DocumentTarget

`DocumentTarget` instances are enumerable, and they must be referenced by a simple name. The default vocabulary of simple names for instances of the `DocumentTarget` class are listed in Table 3.

Simple Name | URI / Description
--- | ---
embed | http://purl.imsglobal.org/vocab/lti/v2/lti#embed
frame | http://purl.imsglobal.org/vocab/lti/v2/lti#frame
iframe | http://purl.imsglobal.org/vocab/lti/v2/lti#iframe
overlay | http://purl.imsglobal.org/vocab/lti/v2/lti#overlay
popup | http://purl.imsglobal.org/vocab/lti/v2/lti#popup
window | http://purl.imsglobal.org/vocab/lti/v2/lti#window

Table 3. Known simple names for DocumentTarget objects

### 3.4 FileItem

Figure 9. FileItem

Property | Mult | Description | Type
--- | --- | --- | ---
@id | 0..1 | The URI that identifies this `FileItem` instance. | xs:anyURI
copyAdvice | 0..1 |  | xs:boolean
expiresAt | 0..1 |  | xs:dateTime
icon | 0..1 | An image which may be used as an icon for the content-item. | Image
mediaType | 1 | The MIME type of the content-item. | xs:normalizedString
text | 0..1 | A plain text description of the content-item. | xs:string
thumbnail | 0..1 | An image which may be used as a thumbnail for the content-item. | Image
title | 0..1 | A plain text title of the content-item. | xs:normalizedString

Table 4. FileItem properties

### 3.5 Image

Figure 10. Image

Property | Mult | Description | Type
--- | --- | --- | ---
@id | 0..1 | The URI that identifies this `Image` instance. | xs:anyURI
height | 0..1 | The height in pixels of the image. | xs:integer
width | 0..1 | The width in pixels of the image. | xs:integer

Table 5. Image properties

### 3.6 LtiLink

An `LtiLink` represents a link within the Tool Consumer system pointing to a resource within the Tool Provider.
Figure 11. LtiLink
Direct Known Subtypes:

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
icon | 0..1 | An image which may be used as an icon for the content-item. | Image
mediaType | 1 | The MIME type of the content-item. | xs:normalizedString
text | 0..1 | A plain text description of the content-item. | xs:string
thumbnail | 0..1 | An image which may be used as a thumbnail for the content-item. | Image
title | 0..1 | A plain text title of the content-item. | xs:normalizedString

Table 6. LtiLink properties

### 3.7 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 12. PropertyMap

## 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 CI]
  Bracken Mosbacker, Claude Vervoort, Stephen Vickers. Content-Item Message. February 2014. IMS Standard.
[RFC4627]
  D. Crockford. The application/json Media Type for JavaScript Object Notation (JSON). Internet RFC 4627. July 2006.

## About this Document

Title: | Content-Item Placements in the `application/vnd.ims.lti.v1.contentitemplacement+json` format.
Editor: | Stephen Vickers (IMS Global)
Version: | 1.0
Version Date: | 7 April 2014
Release: | Public Draft
Status: | IMS Public Draft
Purpose: | This document is made available for review and comment by the public community at large.
Document Location: | Join the discussion and post comments on the LTI Public Forum: http://www.imsglobal.org/community/forum/categories.cfm?catid=44

### List of Contributors

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

Viktor Haag | Desire2Learn | Bracken Mosbacker | Instructure
Brad Humphrey | Instructure | Claude Vervoort | Cengage
Greg McFall | Pearson | Stephen Vickers | IMS Global Learning Consortium

IMS Global Learning Consortium, Inc. (“IMS Global”) is publishing the information contained in this (“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 Global Learning Tools Interoperability - Content-Item Message Public Draft v1.0
Revision: 7 April 2014