IMS Public Draft

LineItem JSON Binding
in the application/vnd.ims.lis.v2.lineitemresults+json format

Public Draft
Media Type application/vnd.ims.lis.v2.lineitemresults+json
RDF Type http://purl.imsglobal.org/vocab/lis/v2/outcomes#LineItem
JSON-LD http://purl.imsglobal.org/ctx/lis/v2/LineItem

Date Issued: 15 December 2014
Latest version: http://www.imsglobal.org/lti

Abstract

This specification defines a JSON-LD representation of an LIS LineItem object which embeds the associated Result objects.

Table of Contents

1. Introduction

Figure 1 shows the representation of a LineItem resource in the application/vnd.ims.lis.v2.lineitemresults+json format.

{
  "@context" : [
    "http://purl.imsglobal.org/ctx/lis/v2/LineItem",
    {
      "res" : "http://purl.imsglobal.org/ctx/lis/v2p1/Result#"
    }
  ],
  "@type" : "LineItem",
  "@id" : "http://lms.example.com/sections/2923/gradebook/items/1",
  "label" : "Chapter 5 Test",
  "reportingMethod" : "res:totalScore",
  "lineItemOf" : {
    "@id" : "http://lms.example.com/resources/Context/2272",
    "contextId" : "123-abc"
  },
  "assignedActivity" : {
    "@id" : "http://toolprovider.example.com/assessment/66400",
    "activityId" : "a-9334df-33"
  },
  "scoreConstraints" : {
    "@type" : "NumericLimits",
    "normalMaximum" : 100,
    "extraCreditMaximum" : 10,
    "totalMaximum" : 110
  },
  "result" : [
    {
      "@id" : "http://server.example.com/sections/2923/gradebook/items/1/results/43",
      "resultOf" : "http://server.example.com/sections/2923/gradebook/items/1",
      "resultAgent" : {
        "@type" : "Person",
        "@id" : "http://server.example.com/persons/54062",
        "userId" : "54062"
      },
      "comment" : "Nice work!",
      "normalScore" : 85,
      "extraCreditScore" : 3,
      "penaltyScore" : 0,
      "totalScore" : 88,
      "resultScore" : "88",
      "status" : "res:Completed"
    },
    {
      "@id" : "http://server.example.com/sections/2923/gradebook/items/1/results/44",
      "resultOf" : "http://server.example.com/sections/2923/gradebook/items/1",
      "resultAgent" : {
        "@type" : "Person",
        "@id" : "http://server.example.com/persons/72003",
        "userId" : "72003"
      },
      "comment" : "Please come see me",
      "normalScore" : 52,
      "extraCreditScore" : 0,
      "penaltyScore" : 10,
      "totalScore" : 42,
      "resultScore" : "42",
      "status" : "res:Started"
    }
  ]
}

Figure 1.  Example JSON document containing a LineItem 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 LineItem object because there are embedded objects (lineItemOf, assignedActivity, result). A complete diagram would show branches emanating from the embedded objects to reveal their properties, and so on, recursively. For a complete representation, see Figure 8 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 4.

Figure 4.  Example of an optional property

If a property can have multiple values, then its box in the graphical notation is decorated with a circle that contains a plus sign (+) as shown in Figure 5. In this example, the result property may reference more than one LISResult object. Ordinarily, these values are encapsulated within a JSON array, but if it turns out that only one value is present, then the square brackets for the array are optional.

Figure 5.  Example of a repeatable property

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 is to be identified by a fully-qualified URI or a CURIE, the box representing the object will be decorated with the #uri hash tag, as shown in null.

Figure 6.  Property whose value is a URI reference

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 7.

Figure 7.  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 LineItem 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 [LIS-v2-LineItemResults] for a LineItem contains the following rewrite rules (among others):

  {
    "@context" = {
      "liso" : "http://purl.imsglobal.org/vocab/lis/v2/outcomes#",
      "scoreConstraints" : "liso:scoreConstraints",
      ...
    }
  }

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" = {
      ...
      "resultStatus" : {
        "@id" : "liso:resultStatus",
        "@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 LineItem Media Type

The following list defines the necessary and sufficient conditions for a document to conform to the application/vnd.ims.lis.v2.lineitemresults+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 "LineItem".
  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 [LIS-v2-LineItemResults]. 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 [LIS-v2-LineItemResults].
  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.lis.v2.lineitemresults+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 [LIS-v2-LineItemResults], 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 8 presents a complete graphical representation of the JSON binding for a LineItem object. The subsections following this figure provide details about each object that appears in the JSON binding for a LineItem object.

Figure 8.  Complete JSON representation of LineItem

3.1 Activity

A resource that a person may experience such as a video or an assessment. This entity represents the resource itself, not the person's engagement with the resource.
{
  "@id" : "http://toolprovider.example.com/assessment/66400",
  "activityId" : "a-9334df-33"
}
Figure 9.  Activity
Property Mult Description Type
@id 0..1 The URI that identifies this Activity instance. xs:anyURI
activityId 1 The unique ID for the activity as used by the tool provider. xs:normalizedString
Table 1.  Activity properties

3.2 Context

A learning context, such as a Course Section.
{
  "@id" : "http://lms.example.com/resources/Context/2272",
  "contextId" : "123-abc"
}
Figure 10.  Context
Property Mult Description Type
@id 0..1 The URI that identifies this Context instance. xs:anyURI
contextId 1 A unique string provided by the tool consumer to identify the context (as passed in the context_id launch parameter). xs:normalizedString
Table 2.  Context properties

3.3 LISPerson

A container for all the information about a single person.
Figure 11.  LISPerson
Property Mult Description Type
@id 0..1 The URI that identifies this LISPerson instance. xs:anyURI
userId 1 A unique identifier for the person. xs:normalizedString
Table 3.  LISPerson properties

3.4 LISResult

A container that holds the result of some scorable activity or assignment.
{
  "@id" : "http://server.example.com/sections/2923/gradebook/items/1/results/43",
  "resultOf" : "http://server.example.com/sections/2923/gradebook/items/1",
  "resultAgent" : { ... },
  "comment" : "Nice work!",
  "normalScore" : 85,
  "extraCreditScore" : 3,
  "penaltyScore" : 0,
  "totalScore" : 88,
  "resultScore" : "88",
  "status" : "res:Completed"
}
Figure 12.  LISResult
Property Mult Description Type
@id 0..1 The URI that identifies this LISResult instance. xs:anyURI
resultAgent 1 The person whose score is recorded in this Result. LISPerson
comment 0..1 A comment about this Result suitable for display to the learner. Typically, this is a comment made by the instructor or grader. DataValue.Type
normalScore 0..1 The score earned by the learner before adding extra credit or subtracting penalties. xs:decimal
extraCreditScore 0..1 The number of exta credit points earned by the learner. xs:decimal
penaltyScore 0..1 The number of points deducted from the normal score due to some penalty such as submitting an assignment after the due date. xs:decimal
totalScore 0..1 The total score on the assignment given by
    totalScore = normalScore + extraCreditScore - penalty
This value does not take into account the effects of curving.
xs:decimal
resultScore 0..1 The final score that should be displayed in a gradebook for this Result object. Literal
gradedBy 0..1 The agent who generated the result. Agent
(URI reference)
resultStatus 0..1 The status of the result for this user and line item. ResultStatus
(Simple Name reference)
timestamp 0..1 The time at which the result was generated. xs:dateTime
Table 4.  LISResult properties

3.5 LineItem

A class representing a column in a gradebook capable of holding result values for different users for a single activity.
{
  "@context" : [ ... ],
  "@type" : "LineItem",
  "@id" : "http://lms.example.com/sections/2923/gradebook/items/1",
  "label" : "Chapter 5 Test",
  "reportingMethod" : "res:totalScore",
  "lineItemOf" : { ... },
  "assignedActivity" : { ... },
  "scoreConstraints" : { ... },
  "result" : [ ... ]
}
Figure 13.  LineItem
Property Mult Description Type
@context 1..*

This value specifies one or more JSON-LD contexts, either by reference or by value. When multiple contexts are specified, they must be encapsulated within an array.

For most implementations, the value will be the single URI for the standard context associated with the application/vnd.ims.lis.v2.lineitemresults+json media type. In this case, the value will be

"http://purl.imsglobal.org/ctx/lis/v2/LineItem"
JSON-LD Context
@type 1 A simple name identifying the object's type. The standard context [LIS-v2-LineItemResults] defines the following simple names that are applicable:
  • LineItem

Implementations may use a custom JSON-LD context which defines simple names for additional types that are subtypes of LineItem.

owl:Class
(Simple Name reference)
@id 0..1 The URI that identifies this LineItem instance. xs:anyURI
label 0..1 A human-friendly label for this LineItem suitable for display. For example, this label might be used as the heading of a column in a gradebook. xs:normalizedString
reportingMethod 1 Identifies the property that is reported as the resultScore of the Results within this LineItem. Property
(URI reference)
lineItemOf 1 The context to which this LineItem belongs. Context
assignedActivity 0..1 The Activity that learners engage with to produce the Results recorded in this LineItem. Activity
scoreConstraints 0..1 Constraints on the scores recorded in the Results associated with this LineItem. NumericLimits
result * A Result associated with this LineItem. LISResult
Table 5.  LineItem properties

3.6 NumericLimits

Defines the maximum values for numerical scores.
{
  "@type" : "NumericLimits",
  "normalMaximum" : 100,
  "extraCreditMaximum" : 10,
  "totalMaximum" : 110
}
Figure 14.  NumericLimits
Property Mult Description Type
@id 0..1 The URI that identifies this NumericLimits instance. xs:anyURI
normalMaximum 0..1 The maximum number of points that a learner may earn without extra credit. xs:float
extraCreditMaximum 0..1 The maximum number of extra credit points that a learner may earn. xs:float
totalMaximum 0..1 The maximum number of points that a learner may earn. This value is given by
    totalMaximum = normalMaximum + extraCreditMaximum
xs:float
Table 6.  NumericLimits properties

3.7 ResultStatus

Possible status values for result resources.
Figure 15.  ResultStatus

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

Simple Name URI / Description
Completed
http://purl.imsglobal.org/vocab/lis/v2/outcomes#Completed
Final
http://purl.imsglobal.org/vocab/lis/v2/outcomes#Final
Initialized
http://purl.imsglobal.org/vocab/lis/v2/outcomes#Initialized
Started
http://purl.imsglobal.org/vocab/lis/v2/outcomes#Started
Table 7.  Known simple names for ResultStatus objects

3.8 ScoreConstraints

The abstract base class for all the various kinds of constraints that might be imposed on the Results associated with a LineItem.
Figure 16.  ScoreConstraints
Direct Known Subtypes:
NumericLimits

3.9 DataValue.Type

Restriction Base http://www.w3.org/2001/XMLSchema#string
maxLength 4096
Table 8.  Facets of DataValue.Type

3.10 Literal

Restriction Base http://www.w3.org/2001/XMLSchema#string
Table 9.  Facets of Literal

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.
[RFC4627]
D. Crockford. The application/json Media Type for JavaScript Object Notation (JSON). Internet RFC 4627. July 2006.

About this Document

Title: LineItem JSON Binding in the application/vnd.ims.lis.v2.lineitemresults+json format
Editor:Stephen Vickers (IMS Global)
Version: 2.0
Version Date: 15 December 2014
Release: Public Draft
Status: IMS Public Draft
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:

Viktor HaagDesire2LearnCharles SeveranceUniversity of Michigan
Brad HumphreyInstructureJohn TibbettsVitalsource
Greg McFallPearsonClaude VervoortCengage
Bracken MosbackerInstructureStephen VickersIMS Global Learning ConsortiumZ
Padraig O'hiceadhaHoughton Mifflin Harcourt