1EdTech Assessment Results Profile for Gradebook Service 1.2 1EdTech Candidate Final Public

1EdTech Assessment Results Profile for Gradebook Service

IMS Final Release
Spec Version 1.0
IMS Final Release
Document Version: 1.0
Date Issued: September 19th, 2022
Status: This document is made available for adoption by the public community at large.
This version: https://www.imsglobal.org/spec/results/v1p0/
Latest version: https://www.imsglobal.org/spec/results/latest/
Errata: https://www.imsglobal.org/spec/results/v1p0/errata/

IPR and Distribution Notice

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 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 webpage: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf .

The following participating organizations have made explicit license commitments to this specification:

Org name Date election made Necessary claims Type
Anthology Inc. August 10, 2022 No RF RAND (Required & Optional Elements)
D2L Corporation July 21, 2022 No RF RAND (Required & Optional Elements)
Gwinnett County Public Schools Jull 22, 2022 No RF RAND (Required & Optional Elements)
Infinite Campus Inc July 25, 2022 No RF RAND (Required & Optional Elements)
Microsoft Corporationv August 08, 2022 No RF RAND (Required & Optional Elements)
SameGoal Inc July 21, 2022 No RF RAND (Required & Optional Elements)

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: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources .

© 2022 IMS Global Learning Consortium, Inc. All Rights Reserved.

Trademark information: http://www.imsglobal.org/copyright.html

Abstract

The 'Assessment Results Profile for Gradebook Service' (ARP-GS) is a formal subset of the OneRoster (OR) 1.2 Gradebook Service. The OneRoster standard addresses the exchange of student data (primarily about people, courses, enrollments and grades) between different educational systems for the specific needs of K-12. The OR 1.2 Gradebook Service, one service within the full OR 1.2 specification, provides the ability to manage the exchange of information about gradebooks in the form of results, lineItems, collections of lineItems (categories) and score-scales. It is also possible to exchange information about assessment activities in the form of assessment lineItems and assessment results. ARP-GS is designed to enable the exchange of detailed results that are assigned as part of some form of assessment activity i.e. the assessment lineItems and assessment results parts of the OR 1.2 Gradebook Service.

This single document contains the consolidated core information about the exchange of assessment lineItems and assessment results: in the OR 1.2 Gradebook Service this information is contained in four separate documents. This document does NOT contain all of the information in those four source documents; it is a synthesis of the key information. The ARP-GS can be adopted without implementing any other part of the OR 1.2 specification. A separate certification process is also available (certification for ARP-GS is also avauilable as part of the certification process for the full OR 1.2 specification).

1. Introduction

1.1 Scope and Context

This document is the reference source for the 1EdTech Assessment Results Profile for Gradebook Service 1.0. This profile is a small subset of the full OneRoster 1.2 Gradebook Service. A separate specification document (and separate conformance test systems) was created so that vendors who want to adopt and certify for only this subset can use a single primary reference. It has been created by taking and synthesizing the relevant parts from the following documents:

  • OneRoster 1.2 Gradebook Service Model [ORGBK-SM-12]
  • OneRoster 1.2 Gradebook Service REST/JSON Binding [ORGBK-JSON-12]
  • OneRoster 1.2 Implementation Guide [OR-IG-12]
  • OneRoster 1.2 Conformance & Certification [OR-CC-12]

There has been no attempt to duplicate ALL of the relevant information in this one document. Further details should be obtained by using the four source documents listed above.

1.2 Profile Differences with Respect to the OneRoster 1.2 Gradebook Service

As a formal profile of the 1EdTech OneRoster 1.2 Gradebook Service specification [ORGBK-JSON-12], [ORGBK-JSON-12], the Assessment Results Profile for Gradebook Service is a subset of the full Gradebook Service. This subset is:

  • Only the AssessmentLineItems Management and the AssessmentResults Management interfaces remain i.e. eight endpoints. The endpoints for Categories Management, LineItems Management, Results Management and ScoreScales Management have been removed;
  • Only the AssessmentLineItems and the AssessmentResults data models remain. The data models for Categories, LineItems, Results and ScoreScales have been removed;
  • There has been NO change to the AssessmentLineItems and the AsssessmentResults data models.

1.3 Structure of this Document

The structure of the rest of this document is:

2. Service Description The logical description of the service. This makes use of UML as the representation and visualization technique for the service and data models;
3. REST/JSON Binding Definition of how the information is to be exchanged using a REST-oriented servcie with JSON payloads. This includes the use of OpenAPI files [OAS14][OAS17] to provide a machine-readable form of the REST/JSON binding;
4. Implementation Guide Recommendations regarding adoption of this specification. This includes a description of how to use the OneRoster 1.2 CSV Binding [OR-CSV-12] to exchange the assessment results data using CSV files;
5. Conformance and Certification The conformance and certification process to be used to obtauin certification against this specification;
Appendix A OpenAPI Listings The listings of the OpenAPI(JSON) and OpenAPI(YAML) files that have been created to define the REST/JSON binding in a machine-readable format i.e. conforming to the OpenAPI 2.0 and OpenAPI 3.0 specifications.
Appendix B JSON Schema Listings The listings of the set of JSON Schema files (based upon IETF JSON Schema Draft 7) that have been created for the validation of the set of JSON payloads that are exchanged as part of this service.
Appendix C Summary of Conformance Tests for a Consumer A summary of the set of tests to which a consumer claiming compliance will be subjected. An implementation MUST pass all of the relevant tests;
Appendix D Summary of Conformance Tests for a Service Provider A summary of the set of tests to which a service provider claiming compliance will be subjected. An implementation MUST pass all of the relevant tests;
Appendix E Data Model Details The information model details for the AssessmentLineItem and AssessamentResults data models. It is these models that are the basis for the JSON paylaods that are exchanged.

1.4 Conformance Statements

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, OPTIONAL, RECOMMENDED, REQUIRED, SHALL, SHALL NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in [RFC2119].

An implementation of this specification that fails to implement a MUST/REQUIRED/SHALL requirement or fails to abide by a MUST NOT/SHALL NOT prohibition is considered nonconformant. SHOULD/SHOULD NOT/RECOMMENDED statements constitute a best practice. Ignoring a best practice does not violate conformance but a decision to disregard such guidance should be carefully considered. MAY/OPTIONAL statements indicate that implementers are entirely free to choose whether or not to implement the option.

The Conformance and Certification Guide for this specification may introduce greater normative constraints than those defined here for specific service or implementation categories.

1.5 Terminology and Acronyms

API
Application Programming Interface
Consumer
The entity that is contained with an application/system/tool to obtain data from a Service Provider.
CSV
Comma Separated Values
GUID
Globally Unique Identifier
HTTP
HyperText Transfer Protocol
I-BAT
IMS Binding Autogeneration Toolkit
IETF
Internet Engineering Task Force
IUT
Implementation Under Test. An IUT may be claiming compliance as a Consumer and/or a Service Provider.
JSON
Java Script Object Notation
OAS
OpenAPI Specification
REST
Representational State Transfer
RFC
Request for Comments
Service Provider
The entity that is responsible for supplying data to a Consumer. In general a Service Provider will support many Consumers concurrently.
TLS
Transport Layer Security
UML
Unified Modeling Language
URI
Uniform Resource Identifier
URL
Uniform Resource Locator
UTC
Coordinated Universal Time
YAML
Yet Another Markup Language

2. Service Description

2.1 Service Architecture

2.1.1 An Abstract Representation

It is important to remember that this document contains a description of the underlying service model in terms of the abstract Application Programming Interface (API). The manner in which this abstract representation is visualized is not intended to dictate the implementation form of the Service. The breakdown of the service into its interface classes is a convenient way to document the set of behaviors. The objective for producing these interfaces is to identify and define the messages that are exchanged between the end-systems to realize the system behaviors required of the service.

The internal organization of an implementation of the full abstract API is beyond the scope of this specification. The only constraint is that the external behavior of the abstract API complies with this specification. This means that a .NET, J2EE, etc. physical implementation of this abstract API does not have to represent the functionality using the same breakdown of operations/methods. This physical implementation is not subject to the conformance specification.

It is important to note that the UML representation of the interfaces is used to help develop and document the Service Model and various Bindings. It is not a requirement for a system to implement this interface as defined i.e. to use the same parameters, etc. Conformance against this specification will be confirmed by inspecting the appropriate binding of the information model and ensuring that the relevant information is present and that different sequences of activity result in the predicted and mandated behavior. It is essential that the behaviors described by each of the operations are fully supported and that the behaviors described by different sequences are also maintained.

2.1.2 Assessment Results

A schematic representation of the structure for assessment results is shown in the Figure below.

Diagram of the structure of the assessment results.

Figure 1 A schematic representation of the structure of assessment results.

This structure is based around an Assessment: this may be a Question and Test Interoperability (QTI) test. The assessment results structure enables the exchange of detailed scores for a simple and complex assessment. The Assessment is composed of a set of AssessmentLineItems (similar to LineItems) for which there is a set of AssessmentResults. The key differences between a LineItem and an AssessmentLineItem are:

  • A LineItem MUST be aligned to a 'class' whereas an AssessmentLineItem is aligned to an assessment activity and MAY be aligned with a 'class';
  • An AssessmentLineItem can reference a parent AssessmentLineItem i.e. hierarchical AssessmentLineItem structures are possible.

The management of AssessmentLineItems and AssessmentResults is achieved using a separate set of operations i.e. not using the original LineItem and Result operations.

2.2 Behavior Model

This Section is NORMATIVE

2.2.1 Service Definition

The model for the service representation is shown in the Figure and Table below. Following the service definition are the descriptions for the set of corresponding service operations.

UML model of the service.
Figure 2 Service interface definitions
The set of interfaces.
Interface Description
AssessmentLineItemsManagement This enables the management of the assessment lineItems i.e. lineitems that are used to store results about tests/assessments and where these test/assessments are not aligned to a class.
AssessmentResultsManagement This enables the management of the assessment results i.e. results that are used to store scores for tests/assessments and where these test/assessments are not aligned to a class.

2.2.2 AssessmentLineItemsManagement Interface Description

This enables the management of the assessment lineItems i.e. lineitems that are used to store results about tests/assessments and where these test/assessments are not aligned to a class.

The set of operations for this interface are summarized in the Table below.

The set of operations for the "AssessmentLineItemsManagement" interface.
Operation Description
getAllAssessmentLineItems Get all of the Assessment Line Items on the service provider.
getAssessmentLineItem Get a specific Assessment LineItem on the service provider. If the corresponding record cannot be located then an 'unknown' error code is returned.
deleteAssessmentLineItem Delete a specific Assessment LineItem on the service provider. If the corresponding record cannot be located then an 'unknown' error code is returned.
putAssessmentLineItem To create a new Assessment LineItem. The associated sourcedId for this new record is supplied by the requesting system.
2.2.2.1 "getAllAssessmentLineItems" Operation
Name: getAllAssessmentLineItems ()
Return Function Parameter: imsx_StatusInfo : imsx_StatusInfo - the status information report for the request. This report has end-to-end significance and must map between the messaging technology approach and the business transaction API. For REST-based bindings this structure describes the message payload that must be returned when the request has not been successfully completed.
Supplied (in) Parameters: None.
Returned (out) Parameters: assessmentLineItems : AssessmentLineItemSet - the set of assessment lineItems that have been read from the service provider.
Behavior: Get all of the Assessment Line Items on the service provider.
2.2.2.2 "getAssessmentLineItem" Operation
Name: getAssessmentLineItem ()
Return Function Parameter: imsx_StatusInfo : imsx_StatusInfo - the status information report for the request. This report has end-to-end significance and must map between the messaging technology approach and the business transaction API. For REST-based bindings this structure describes the message payload that must be returned when the request has not been successfully completed.
Supplied (in) Parameters: sourcedId : GUID - the unique identifier, GUID, for this assessment lineItem.
Returned (out) Parameters: assessmentLineItem : SingleAssessmentLineItem - the assessment lineItem that has been read from the service provider.
Behavior: Get a specific Assessment LineItem on the service provider. If the corresponding record cannot be located then an 'unknown' error code is returned.
2.2.2.3 "deleteAssessmentLineItem" Operation
Name: deleteAssessmentLineItem ()
Return Function Parameter: imsx_StatusInfo : imsx_StatusInfo - the status information report for the request. This report has end-to-end significance and must map between the messaging technology approach and the business transaction API. For REST-based bindings this structure describes the message payload that must be returned when the request has not been successfully completed.
Supplied (in) Parameters: sourcedId : GUID - the unique identifier, GUID, for the assessment lineItem to be deleted.
Returned (out) Parameters: None.
Behavior: Delete a specific Assessment LineItem on the service provider. If the corresponding record cannot be located then an 'unknown' error code is returned.
2.2.2.4 "putAssessmentLineItem" Operation
Name: putAssessmentLineItem ()
Return Function Parameter: imsx_StatusInfo : imsx_StatusInfo - the status information report for the request. This report has end-to-end significance and must map between the messaging technology approach and the business transaction API. For REST-based bindings this structure describes the message payload that must be returned when the request has not been successfully completed.
Supplied (in) Parameters: sourcedId : GUID - the unique identifier, GUID, to be allocated to this new assessment lineItem.
assessmentLineItem : SingleAssessmentLineItem - the assessment lineItem data that is to be stored.
Returned (out) Parameters: None.
Behavior: To create a new Assessment LineItem. The associated sourcedId for this new record is supplied by the requesting system.

2.2.3 AssessmentResultsManagement Interface Description

This enables the management of the assessment results i.e. results that are used to store scores for tests/assessments and where these test/assessments are not aligned to a class.

The set of operations for this interface are summarized in the Table below.

The set of operations for the "AssessmentResultsManagement" interface.
Operation Description
getAllAssessmentResults Get all of the Assessment Results on the service provider.
getAssessmentResult Get a specific Assessment Result on the service provider. If the corresponding record cannot be located then an 'unknown' error code is returned.
deleteAssessmentResult Delete a specific Assessment Result on the service provider. If the corresponding record cannot be located then an 'unknown' error code is returned.
putAssessmentResult To create a new Assessment Result. The associated sourcedId for this new record is supplied by the requesting system.
2.2.3.1 "getAllAssessmentResults" Operation
Name: getAllAssessmentResults ()
Return Function Parameter: imsx_StatusInfo : imsx_StatusInfo - the status information report for the request. This report has end-to-end significance and must map between the messaging technology approach and the business transaction API. For REST-based bindings this structure describes the message payload that must be returned when the request has not been successfully completed.
Supplied (in) Parameters: None.
Returned (out) Parameters: assessmentResults : AssessmentResultSet - the set of assessment results that have been read from the service provider.
Behavior: Get all of the Assessment Results on the service provider.
2.2.3.2 "getAssessmentResult" Operation
Name: getAssessmentResult ()
Return Function Parameter: imsx_StatusInfo : imsx_StatusInfo - the status information report for the request. This report has end-to-end significance and must map between the messaging technology approach and the business transaction API. For REST-based bindings this structure describes the message payload that must be returned when the request has not been successfully completed.
Supplied (in) Parameters: sourcedId : GUID - tthe unique identifier, GUID, for this assessment result.
Returned (out) Parameters: assessmentResult : SingleAssessmentResult - the assessment result that has been read from the service provider.
Behavior: Get a specific Assessment Result on the service provider. If the corresponding record cannot be located then an 'unknown' error code is returned.
2.2.3.3 "deleteAssessmentResult" Operation
Name: deleteAssessmentResult ()
Return Function Parameter: imsx_StatusInfo : imsx_StatusInfo - the status information report for the request. This report has end-to-end significance and must map between the messaging technology approach and the business transaction API. For REST-based bindings this structure describes the message payload that must be returned when the request has not been successfully completed.
Supplied (in) Parameters: sourcedId : GUID - the unique identifier, GUID, for the assessment result to be deleted.
Returned (out) Parameters: None.
Behavior: Delete a specific Assessment Result on the service provider. If the corresponding record cannot be located then an 'unknown' error code is returned.
2.2.3.4 "putAssessmentResult" Operation
Name: putAssessmentResult ()
Return Function Parameter: imsx_StatusInfo : imsx_StatusInfo - the status information report for the request. This report has end-to-end significance and must map between the messaging technology approach and the business transaction API. For REST-based bindings this structure describes the message payload that must be returned when the request has not been successfully completed.
Supplied (in) Parameters: sourcedId : GUID - the unique identifier, GUID, to be allocated to this new assessment result.
assessmentResult : SingleAssessmentResult - the assessment result data that is to be stored.
Returned (out) Parameters: None.
Behavior: To create a new Assessment Result. The associated sourcedId for this new record is supplied by the requesting system.

2.3 Interface Model

This Section is NORMATIVE

The set of operations described within the behavior model are based upon class descriptions specific to the parameters of the operations. All parameters are mandatory.

2.3.1 AssessmentLineItemSet Class Description

The data model for the "AssessmentLineItemSet" class is shown in the Figure and the accompanying definition in the Table below.

UML diagram of the AssessmentLineItemSet class.
Figure 3 Figure - AssessmentLineItemSet class definitions.
Table - Description of the "AssessmentLineItemSet" class.
Descriptor Definition
Class Name AssessmentLineItemSet
Class Type Container [ Sequence ]
Parents Service parameter data-type used in the following operations:
Characteristics There are no characteristics.
Children The set of children attributes are:
Description This is the container for a collection of assessment lineItem instances for a message payload. This may be empty if no instances are found that sustain the applied query constraints. The order is not significant.
2.3.1.1 "assessmentLineItems" Attribute Description

The description of the "assessmentLineItems" attribute for the "AssessmentLineItemSet" class is given in the Table below.

Table - Description of the "assessmentLineItems" attribute for the "AssessmentLineItemSet" class.
Descriptor Definition
Attribute Name assessmentLineItems
Data Type AssessmentLineItem
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0.. unbounded]
Description The collection of assessment lineItem instances. The order is not significant. The corresponding query constraints may result in no instances being returned.

2.3.2 AssessmentResultSet Class Description

The data model for the "AssessmentResultSet" class is shown in the Figure and the accompanying definition in the Table below.

UML diagram of the AssessmentResultSet class.
Figure 4 AssessmentResultSet class definitions.
Description of the "AssessmentResultSet" class.
Descriptor Definition
Class Name AssessmentResultSet
Class Type Container [ Sequence ]
Parents Service parameter data-type used in the following operations:
Characteristics There are no characteristics.
Children The set of children attributes are:
Description This is the container for a collection of assessment result instances for a message payload. This may be empty if no instances are found that sustain the applied query constraints. The order is not significant.
2.3.2.1 "assessmentResults" Attribute Description

The description of the "assessmentResults" attribute for the "AssessmentResultSet" class is given in the Table below.

Description of the "assessmentResults" attribute for the "AssessmentResultSet" class.
Descriptor Definition
Attribute Name assessmentResults
Data Type AssessmentResult
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0.. unbounded]
Description The collection of assessment result instances. The order is not significant. The corresponding query constraints may result in no instances being returned.

2.3.3 GUID Class Description

The data model for the "GUID" class is shown in the Figure below and the accompanying definition in the below.

UML diagram of the GUID class.
Figure 5 GUID class definitions.
Description of the "GUID" class.
Descriptor Definition
Class Name GUID
Class Type Container [ DerivedType ]
Parents Service parameter data-type used in the following operations:
Characteristics There are no characteristics.
Children There are no children.
Description The data-type for establishing a Globally Unique Identifier (GUID). There is no predefined structure for the GUID.

2.3.4 SingleAssessmentLineItem Class Description

The data model for the "SingleAssessmentLineItem" class is shown in the Figure below and the accompanying definition in the Table below.

UML diagram of the SingleAssessmentLineItem class.
Figure 6 SingleAssessmentLineItem class definitions.
Description of the "SingleAssessmentLineItem" class.
Descriptor Definition
Class Name SingleAssessmentLineItem
Class Type Container [ Sequence ]
Parents Service parameter data-type used in the following operations:
Characteristics There are no characteristics.
Children The set of children attributes are:
Description This is the container for a single assessment lineItem instance for a message payload.
2.3.4.1 "assessmentLineItem" Attribute Description

The description of the "assessmentLineItem" attribute for the "SingleAssessmentLineItem" class is given in the Table below.

Description of the "assessmentLineItem" attribute for the "SingleAssessmentLineItem" class.
Descriptor Definition
Attribute Name assessmentLineItem
Data Type AssessmentLineItem
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [1]
Description The instance of the single assessment lineItem for a message payload. There must be a data payload otherwise an error report payload for the record not being located should be returned.

2.3.5 SingleAssessmentResult Class Description

The data model for the "SingleAssessmentResult" class is shown in the Figure below and the accompanying definition in the Table below.

UML diagram of the SingleAssessmentResult class.
Figure 7 SingleAssessmentResult class definitions.
Description of the "SingleAssessmentResult" class.
Descriptor Definition
Class Name SingleAssessmentResult
Class Type Container [ Sequence ]
Parents Service parameter data-type used in the following operations:
Characteristics There are no characteristics.
Children The set of children attributes are:
Description This is the container for a single assessment result instance for a message payload.
2.3.5.1 "assessmentResult" Attribute Description

The description of the "assessmentResult" attribute for the "SingleAssessmentResult" class is given in the Table below.

Description of the "assessmentResult" attribute for the "SingleAssessmentResult" class.
Descriptor Definition
Attribute Name assessmentResult
Data Type AssessmentResult
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [1]
Description The instance of the single assessment result for a message payload. There must be a data payload otherwise an error report payload for the record not being located should be returned.

2.3.6 imsx_StatusInfo Class Description

The data model for the "imsx_StatusInfo" class is shown in the Figure and the accompanying definition in the Table below.

UML diagram of the imsx_StatusInfo class.
Figure 8 imsx_StatusInfo class definitions.
Description of the "imsx_StatusInfo" class.
Descriptor Definition
Class Name imsx_StatusInfo
Class Type Container [ Sequence ]
Parents Service parameter data-type used in the following operations:
Characteristics There are no characteristics.
Children The set of children attributes are:
Description This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider. For the OneRoster Rostering service this object will only be returned to provide information about a failed request i.e. it will NOT be in the payload for a successful request. See Appendix B for further information on the interpretation of the information contained within this class.
2.3.6.1 "imsx_codeMajor" Attribute Description

The description of the "imsx_codeMajor" attribute for the "imsx_StatusInfo" class is given in the Table below.

Description of the "imsx_codeMajor" attribute for the "imsx_StatusInfo" class.
Descriptor Definition
Attribute Name imsx_codeMajor
Data Type imsx_CodeMajorEnum
Value Space Enumerated value set of: { success | processing | failure | unsupported }
Scope Local ("-")
Multiplicity [1]
Description The code major value (from the corresponding enumerated vocabulary).
2.3.6.2 "imsx_severity" Attribute Description

The description of the "imsx_severity" attribute for the "imsx_StatusInfo" class is given in the Table below.

Description of the "imsx_severity" attribute for the "imsx_StatusInfo" class.
Descriptor Definition
Attribute Name imsx_severity
Data Type imsx_SeverityEnum
Value Space Enumerated value set of: { status | warning | error }
Scope Local ("-")
Multiplicity [1]
Description The severity value (from the corresponding enumerated vocabulary).
2.3.6.3 "imsx_description" Attribute Description

The description of the "imsx_description" attribute for the "imsx_StatusInfo" class is given in the Table below.

Description of the "imsx_description" attribute for the "imsx_StatusInfo" class.
Descriptor Definition
Attribute Name imsx_description
Data Type String (Primitive-type)
Value Space String of characters.
Scope Local ("-")
Multiplicity [0..1]
Description A human readable description supplied by the entity creating the status code information.
2.3.6.4 "imsx_CodeMinor" Attribute Description

The description of the "imsx_CodeMinor" attribute for the "imsx_StatusInfo" class is given in the Table below.

Description of the "imsx_CodeMinor" attribute for the "imsx_StatusInfo" class.
Descriptor Definition
Attribute Name imsx_CodeMinor
Data Type imsx_CodeMinor
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0..1]
Description The set of reported code minor status codes.

3. REST/JSON Binding

3.1 REST Endpoints

This Section is NORMATIVE.

3.1.1 Mapping of the Service Operations to the REST Endpoints

The mapping between the service operations and the REST Endpoint URL-leaf values are listed in the Table below. The syntax and semantics for this mapping are described in [ORGBK-JSON-12].

The Set of REST Endpoint URL-leaf Values.
Service Call REST Endpoint HTTP Verb
deleteAssessmentLineItem /assessmentLineItems/{sourcedId} DELETE
deleteAssessmentResult /assessmentResults/{sourcedId} DELETE
getAllAssessmentLineItems /assessmentLineItems GET
getAllAssessmentResults /assessmentResults GET
getAssessmentLineItem /assessmentLineItems/{sourcedId} GET
getAssessmentResult /assessmentResults/{sourcedId} GET
putAssessmentLineItem /assessmentLineItems/{sourcedId} PUT
putAssessmentResult /assessmentResults/{sourcedId} PUT

3.1.2 API Root URL and Versioning

All of the paths MUST also contain, as the base of the path, excluding the host name, the string: "/ims/oneroster/gradebook/v1p2".

3.1.3 Predefined Endpoint Query Parameters

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 [ORGBK-JSON-12].

3.1.3.1 "deleteAssessmentLineItem" Endpoint Query Parameters

There are no pre-defined query parameters for this endpoint.

3.1.3.2 "deleteAssessmentResult" Endpoint Query Parameters

There are no pre-defined query parameters for this endpoint.

3.1.3.3 "getAllAssessmentLineItems" and "getAllAssessmentResults" Endpoint Query Parameters
3.1.3.3.1 "limit" Query Parameter

The description of the "limit" query parameter is presented in the Table below

The definition of the "limit" query parameter for the "getAllAssessmentLineItems" and "getAllAssessmentResults" operations.
Descriptor Definition
Parameter Name limit
Data Type PositiveInteger (Primitive-type)
Value Space See [ORGBK-JSON-12].
Default = "100".
Multiplicity [0..1]
Description To define the download segmentation value i.e. the maximum number of records to be contained in the response.
3.1.3.3.2 "offset" Query Parameter

The description of the "offset" query parameter is presented in Table below

The definition of the "offset" query parameter for the "getAllAssessmentLineItems" and "getAllAssessmentResults" operation.
Descriptor Definition
Parameter Name offset
Data Type NonNegativeInteger (Primitive-type)
Value Space See [ORGBK-JSON-12].
Default = "0".
Multiplicity [0..1]
Description The number of the first record to be supplied in the segmented response message.
3.1.3.3.3 "sort" Query Parameter

The description of the "sort" query parameter is presented in the Table below.

The definition of the "sort" query parameter for the "getAllAssessmentLineItems" and "getAllAssessmentResults" operations.
Descriptor Definition
Parameter Name sort
Data Type String (Primitive-type)
Value Space See [ORGBK-JSON-12].
Multiplicity [0..1]
Description Identifies the sort criteria to be used for the records in the response message. Use with the orderBy parameter. The sort order should follow the [UNICODE] standard.
3.1.3.3.4 "orderBy" Query Parameter

The description of the "orderBy" query parameter is presented in the Table below.

The definition of the "orderBy" query parameter for the "getAllAssessmentLineItems" and "getAllAssessmentResults" operation.
Descriptor Definition
Parameter Name orderBy
Data Type Enumeration
Value Space Enumerated value set of: { asc | desc }
Multiplicity [0..1]
Description The form of ordering for response to the sorted request i.e. ascending (asc) or descending (desc). The sort order should follow the [UNICODE] standard.
3.1.3.3.5 "filter" Query Parameter

The description of the "filter" query parameter is presented in the Table below.

The definition of the "filter" query parameter for the "getAllAssessmentLineItems" and "getAllAssessmentResults" operation.
Descriptor Definition
Parameter Name filter
Data Type String (Primitive-type)
Value Space See [ORGBK-JSON-12].
Multiplicity [0..1]
Description The filtering rules to be applied when identifying the records to be supplied in the response message.
3.1.3.3.6 "fields" Query Parameter

The description of the "fields" query parameter is presented in the Table below.

The definition of the "fields" query parameter for the "getAllAssessmentLineItems" and "getAllAssessmentResults" operation.
Descriptor Definition
Parameter Name fields
Data Type String (Primitive-type)
Value Space See [ORGBK-JSON-12].
Multiplicity [0..*]
Description To identify the range of fields that should be supplied in the response message.

3.1.4 HTTP Code Handling

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 the Table below. The syntax and semantics for this tabular description are described in [ORGBK-JSON-12].

The List of HTTP Codes and Handling for each Endpoint.
REST Endpoint HTTP Verb HTTP Codes and Handling
/assessmentLineItems GET
  • 200 - the request was successfully completed and a record has been returned. This would be accompanied by the 'codeMajor/severity' values of 'success/status' and for a REST binding a HTTP code of '200'.
  • 400 - an invalid selection field was supplied and data filtering on the selection criteria was not possible i.e. 'invalid_selection_field'. This is accompanied by the 'codeMajor/severity' values of 'failure/error'
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
/assessmentLineItems/{sourcedId} GET
  • 200 - the request was successfully completed and a record has been returned. This would be accompanied by the 'codeMajor/severity' values of 'success/status' and for a REST binding a HTTP code of '200'.
  • 400 - an invalid selection field was supplied and data filtering on the selection criteria was not possible i.e. 'invalid_selection_field'. This is accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
/assessmentLineItems/{sourcedId} DELETE
  • 204 - the object has been successfully deleted. There is no payload in the response message.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
/assessmentLineItems/{sourcedId} PUT
  • 201 - the object has been successfully stored in the Service Provider repository. There is no payload in the response message.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
/assessmentResults GET
  • 200 - the request was successfully completed and a record has been returned. This would be accompanied by the 'codeMajor/severity' values of 'success/status' and for a REST binding a HTTP code of '200'.
  • 400 - an invalid selection field was supplied and data filtering on the selection criteria was not possible i.e. 'invalid_selection_field'. This is accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
/assessmentResults/{sourcedId} GET
  • 200 - the request was successfully completed and a record has been returned. This would be accompanied by the 'codeMajor/severity' values of 'success/status' and for a REST binding a HTTP code of '200'.
  • 400 - an invalid selection field was supplied and data filtering on the selection criteria was not possible i.e. 'invalid_selection_field'. This is accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
/assessmentResults/{sourcedId} DELETE
  • 204 - the object has been successfully deleted. There is no payload in the response message.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
/assessmentResults/{sourcedId} PUT
  • 201 - the object has been successfully stored in the Service Provider repository. There is no payload in the response message.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 403 - this is used to indicate that the server can be reached and process the request but refuses to take any further action i.e. 'forbidden'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 404 - either the supplied identifier is unknown in the Service Provider and so the object could not be changed or an invalid GUID has been supplied. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The statement 'Unknown Object' should also be presented.
  • 422 - this error condition may occur if a JSON request body contains well-formed (i.e. syntactically correct), but semantically erroneous, JSON instructions. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 429 - the server is receiving too many requests i.e. 'server_busy'. Retry at a later time. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
  • 500 - this code should be used only if there is catastrophic error and there is not a more appropriate code i.e. 'internal_server_error'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.

3.1.5 Service Discovery

A Service Provider MUST provide a localized version of the OpenAPI file (version 3 JSON file format) to enable service discovery [Security]

This file MUST be located at: "...hostname.../ims/oneroster/gradebook/v1p2/discovery/".

The OpenAPI file MUST have the name: "assessmentresultv1p0service_openapi3_v1p0".

Therefore the full URL for this service discovery file is: "...hostname.../ims/oneroster/gradebook/v1p2/discovery/assessmentresultv1p0service_openapi3_v1p0.json".

3.2 Using the Endpoint Parameters

This Section is NORMATIVE.

3.2.1 Pagination

For requests of collections i.e. the response for the 'getAllAssessmentLineItems()', etc. call, there is a danger of data overload. To avoid this, implementations should adopt a pagination mechanism. Pagination is controlled via two parameters that are appended to the request:

  • 'limit' - the number of results to return (the default value is 100);
  • 'offset' - the index of the first record to return (zero index and so the default value is 0).

An example of a request to return the first 10 resources in a collection of lineItems:

    GET https://imsglobal.org/ims/oneroster/gradebook/v1p2/lineItems?limit=10

An example of a request to return the second 10 resources in a collection of lineItems:

    GET https://imsglobal.org/ims/oneroster/gradebook/v1p2/lineItems?limit=10&offset=10

It is RECOMMENDED that implementations pass the total resource count in collection back to the requester. This MUST be provided in the custom HTTP header: X-Total-Count.

It is RECOMMENDED that implementers 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/oneroster/gradebook/v1p2/assessmentLineItems?limit=10&offset=20>; rel="next",
    <https://imsglobal.org/ims/oneroster/gradebook/v1p2/assessmentLineItems?limit=3&offset=500>; rel="last",
    <https://imsglobal.org/ims/oneroster/gradebook/v1p2/assessmentLineItems?limit=10&offset=0>; rel="first",
    <https://imsglobal.org/ims/oneroster/gradebook/v1p2/assessmentLineItems?limit=10&offset=0>; rel="prev"

3.2.2 Sorting

It should be possible for collections, i.e. the response for the 'getAllAssessmentResults()', etc. calls, 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:

  • 'data_field' MUST be used in the request to ask for the collection to be sorted on data field. The form of ordering is implementation dependent if the 'orderBy' attribute is not used;
  • 'orderBy' MAY be used in the request to ask for the collection to be ordered ascending (asc) or descending (desc).

An example of a request to ask for a list of students sorted into ascending familyName order:

    GET https://imsglobal.org/ims/oneroster/gradebook/v1p2/results?sort=score&orderBy=asc

Sorting should conform to the use of the Unicode Collation Algorithm [UNICODE] when using the relevant comparisons.

If the consumer requests that the data is to be sorted by a non-existent field, data MAY be returned in the service provider's default sort order or an error response MAY be returned.

When sorting/ordering is requested on a property that is an array, the first value in the array is used as the basis of the sorting/ordering.

To sort/order on the properties of nested objects, (for example, with metadata properties), a dot-notation approach MUST be used. The format for this is:

    ?sort=<Nested_Object>.<Property>

3.2.3 Filtering

For the calls that request collections e.g. 'getAllLineItems()', etc. call, it should be possible to filter collections for elements matching a certain criteria. It should be possible to filter collections based on any data element in the core description of the resource.Filter requests MUST take the form:

    ?filter=<data_field><predicate><value>

or

    ?filter=<data_field><predicate><value><logical><data_field><predicate><value>

The data fields that can be used are those present in the class definition being filtered. So for example in 'results', it MUST be possible to filter on: 'sourcedId', 'score, 'dateLastModified', etc.

Predicates MUST be chosen from those listed in the Table below:

List of predicates used for filtering.
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. 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 'lineItems' with a 'dueDate' of '2017-01-01T00:00:00Z' is:

    GET https://imsglobal.org/ims/oneroster/gradebook/v1p2/lineItems?filter=dueDate='2017-01-01T00:00:00Z'

URL encoded as:

    GET https://imsglobal.org/ims/oneroster/gradebook/v1p2/lineItems?filter=role%3D%272017-01-01T00:00:00Z%27

Filter queries MUST be URL encoded.

An example of a complex query for all 'lineItems' with a dueDate='2017-01-01T00:00:00Z' AND dateLastModified>'2016-12-12T00:00:00Z' is:

    GET https://imsglobal.org/ims/oneroster/gradebook/v1p2/lineItems?filter=dueDate%3D%272017%3D01%3D01T00%3A00%3A00Z%27%20AND%20dateLastModified%3E%272016%3D12%3D12T00%3A00%3A00Z%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' (this is not a field in 'lineItem' but is used as a generic example of filters for arrays) field when the value of the field is "subject1,subject2,subject3" the following filters would return:

  • ?filter=subject='subject1' - record not returned;
  • ?filter=subject='subject1,subject2' - record not returned;
  • ?filter=subject='subject1,subject2,subject3' - record returned;
  • ?filter=subject~'subject1' - record returned;
  • ?filter=subject~'subject1,subject2' - record returned;
  • ?filter=subject~'subject1,subject2,subject3' - record returned.

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:

  • CodeMajor value is 'failure';
  • Severity value is 'error';
  • CodeMinor value is 'invalid_filter_field'.

3.2.4 Field Selection

For the read collection calls, such as 'getAllAssessmentResults()', etc. it should be possible for requesters to select 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 Results returning only the 'sourcedId' and 'score':

    GET https://imsglobal.org/ims/oneroster/gradebook/v1p2/assessmentResults?fields=sourcedId,score

If the consumer requests that data be selected using 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:

  • CodeMajor value is 'failure';
  • Severity value is 'error';
  • CodeMinor value is 'invalid_selection_field'.

3.3 Security Framework

This Section is NORMATIVE.

The information in this section is taken from the IMS Security Framework [Security]: that document describes the security approaches to be adopted in all IMS specifications.

3.3.1 Transport Security

As the service will be exposing personal data related to students and their grades, it is important that only authorized users have access to that data. Further, data exchanges should be encrypted to ensure that packet sniffing cannot be used to read the data in transit.

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 and/or TLS 1.3 is REQUIRED and SSL MUST NOT be used.

3.3.2 Authorization

The use of OAuth 2.0 Client Credentials with the Bearer Token obtained using the mechanism described in [RFC6749] (Section 4.4) is REQUIRED. Details of this are given in the IMS Security Framework [Security].

Authorization will use the OAuth 2.0 Client Credentials Grant mechanism. In this mechanism the client can request an access token using only its client credentials (using the consumer key and secret information) when the client is requesting access to the protected resources under its control, or those of another resource owner that have been previously arranged with the authorization server. In this approach the client issues a client authentication request and receives in response an access token. Issuing of an access token is defined in Section 5 of [RFC6749].

The request for an access token, including three scopes (scopename1, scopename2 and scopenamex) takes the form of (this uses TLS):

POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&scope=scopename1%20scopename2%20scopenamex

The inclusion of scopes is REQUIRED and the set of scopes available for this service are defined in the following subsection. The authorization encoding is produced using the consumer key and secret. Success results in the granting of the access token with a response of:

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache

{
    "access_token" : "2YotnFZFEjr1zCsicMWpAA",
    "token_type" : "bearer",
    "expires_in" : 3600,
    "scope" : "scopename1 scopename2 scopenamex"
}

The recommended default value for the "expires_in" is 3600s. The authorization server MUST provide the scopes which are made available (either all or a subset of the scopes supplied in the request).

The client utilizes the access token to authenticate with the resource using the HTTP "Authorization" request header field [RFC2617] with an authentication scheme defined by the specification of the access token type used, such as [RFC6750]. An example of the use of the bearer token is:

GET /resource/1 HTTP/1.1
Host: provider.example.com
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

NOTE: This exchange assumes that TLS is used to secure the link.

3.3.3 Scopes

The set of scopes available in this service are listed in the following Tables.

3.3.3.1 "https://purl.imsglobal.org/spec/or/v1p2/scope/assessment.createput" Scope

Access to all of the write assessment operations that permit the creation of a new single object in which the 'sourcedId' is supplied. The set of service operations covered by this scope are listed in the Table below.

Service Operations for the "https://purl.imsglobal.org/spec/or/v1p2/scope/assessment.createput" Scope.
Operation HTTP Verb Endpoint
putAssessmentLineItem PUT /assessmentLineItems/{sourcedId}
putAssessmentResult PUT /assessmentResults/{sourcedId}
3.3.3.2 "https://purl.imsglobal.org/spec/or/v1p2/scope/assessment.delete" Scope

Access to the set of assessment operations that permit an object to be deleted. The set of service operations covered by this scope are listed in the Table below.

Service Operations for the "https://purl.imsglobal.org/spec/or/v1p2/scope/assessment.delete" Scope.
Operation HTTP Verb Endpoint
deleteAssessmentLineItem DELETE /assessmentLineItems/{sourcedId}
deleteAssessmentResult DELETE /assessmentResults/{sourcedId}
3.3.3.3 "https://purl.imsglobal.org/spec/or/v1p2/scope/assessment.readonly" Scope

Access to ALL of the assessment read operations. The set of service operations covered by this scope are listed in the Table below.

Service Operations for the "https://purl.imsglobal.org/spec/or/v1p2/scope/assessment.readonly" Scope.
Operation HTTP Verb Endpoint
getAllAssessmentLineItems GET /assessmentLineItems
getAllAssessmentResults GET /assessmentResults
getAssessmentLineItem GET /assessmentLineItems/{sourcedId}
getAssessmentResult GET /assessmentResults/{sourcedId}

3.4 JSON Payloads

This Section is NOT NORMATIVE.

3.4.1 "deleteAssessmentLineItem" Request Payload

There is no payload for this request.

3.4.2 "deleteAssessmentLineItem" Response Payloads

3.4.2.1 Response Payloads for the HTTP Codes (204)

There is no payload for these responses i.e. only a HTTP response header is returned.

3.4.2.2 Response Payloads for the HTTP Codes (default, 401, 403, 404, 422, 429, 500)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "default, 401, 403, 404, 422, 429, 500" response messages for a "deleteAssessmentLineItem" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "default, 401, 403, 404, 422, 429, 500" response messages for a "deleteAssessmentLineItem" operation.
{
    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
    "imsx_severity" : "status"|"warning"|"error",
    "imsx_description" : "..String..",
    "imsx_CodeMinor" : {
        "imsx_codeMinorField" : [
            {
                "imsx_codeMinorFieldName" : "..NormalizedString..",
                "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"invaliddata"|
                				"unauthorisedrequest"|"internal_server_error"|"server_busy"|"deletefailure"|
                				"unknownobject"|"forbidden"
            },
            {...},
            {...}
        ]
    }
}

3.4.3 "deleteAssessmentResult" Request Payload

There is no payload for this request.

3.4.4 "deleteAssessmentResult" Response Payloads

3.4.4.1 Response Payloads for the HTTP Codes (204)

There is no payload for these responses i.e. only a HTTP response header is returned.

3.4.4.2 Response Payloads for the HTTP Codes (default, 401, 403, 404, 422, 429, 500)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "default, 401, 403, 404, 422, 429, 500" response messages for a "deleteAssessmentResult" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "default, 401, 403, 404, 422, 429, 500" response messages for a "deleteAssessmentResult" operation.
{
    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
    "imsx_severity" : "status"|"warning"|"error",
    "imsx_description" : "..String..",
    "imsx_CodeMinor" : {
        "imsx_codeMinorField" : [
            {
                "imsx_codeMinorFieldName" : "..NormalizedString..",
                "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"invaliddata"|
                				"unauthorisedrequest"|"internal_server_error"|"server_busy"|"deletefailure"|
                				"unknownobject"|"forbidden"
            },
            {...},
            {...}
        ]
    }
}

3.4.5 "getAllAssessmentLineItems" Request Payload

There is no payload for this request.

3.4.6 "getAllAssessmentLineItems" Response Payloads

3.4.6.1 Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "200" response messages for a "getAllAssessmentLineItems" operation.
Property Name Multiplicity JSON Data-type Description
    assessmentLineItems [0..*] Array [ Object ] The collection of assessment lineItem instances. The order is not significant. The corresponding query constraints may result in no instances being returned.
            sourcedId [1..1] String The sourcedId of the object. All objects MUST be identified by a Source Identifier. This is a GUID System ID for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields) they use to SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. The form of the extension is dependent on the binding technology being used.
                    extensions [0..*] Set of Proprietary Properties The form of the extension is dependent on the binding technology being used. This specification is silent on what implementers may consider to be appropriate extensions.
            title [1..1] String The title, human readable, for the assessment lineItem. This should allow the assessment lineItem to be distinguished from its peer assessment lineItems.
            description [0..1] String A human readable description of the usage of the assessment lineItem.
            class [0..1] Object The GUID of the class to which the assessment lineItem has been assigned. Note that an assessment LineItem MAY be assigned tio a class.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced i.e. a 'class'.
            parentAssessmentLineItem [0..1] Object The GUID of the parent assessment lineItem. This enables the assessment lineItems to be chained together in a parent/child hierarchy.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            scoreScale [0..1] Object The GUID of the score scale to be used for the lineItem. This attribute was added in the OR 1.2 release.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            resultValueMin [0..1] Float The minimum value (numeric) that can be assigned to the score attribute in a result. The score scale mapping should be used to map to other scores.
            resultValueMax [0..1] Float The maximum value (numeric) that can be assigned to the score attribute in a result. The score scale mapping should be used to map to other scores.
            learningObjectiveSet [0..*] Array [ Object ] The set of identifiers for the learning objectives to which this assessment is aligned. Any number groups of learning objectives can be assigned.
                    source [1..1] Union(SourceExtEnum) The source responsible for creating the learning objective identifiers. The permitted values are from an extensible vocabulary.
                    learningObjectiveIds [1..*] Array [ String ] The set of unique identifiers for the associated learning objectives. If these are CASE identifiers they MUST be valid UUIDs.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "200" response messages for a "getAllAssessmentLineItems" operation.
{
    "assessmentLineItems" : [
        {
            "sourcedId" : "..String..",
            "status" : "active"|"tobedeleted",
            "dateLastModified" : "..Date/Time..",
            "metadata" : {
                "..permitted extension point.." : "..user defined value.."
            },
            "title" : "..NormalizedString..",
            "description" : "..String..",
            "class" : {
                "href" : "..URI..",
                "sourcedId" : "..String..",
                "type" : "class"
            },
            "parentAssessmentLineItem" : {
                "href" : "..URI..",
                "sourcedId" : "..String..",
                "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
                		"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
            },
            "scoreScale" : {
                "href" : "..URI..",
                "sourcedId" : "..String..",
                "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
                		"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
            },
            "resultValueMin" : ..Number(Float)..,
            "resultValueMax" : ..Number(Float)..,
            "learningObjectiveSet" : [
                {
                    "source" : "..select from Union..",
                    "learningObjectiveIds" : [ "..NormalizedString..", ..., "..NormalizedString.." ]
                },
                {...},
                {...}
            ]
        },
        {...},
        {...}
    ]
}
3.4.6.2 Response Payloads for the HTTP Codes (default, 400, 401, 403, 422, 429, 500)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "default, 400, 401, 403, 422, 429, 500" response messages for a "getAllAssessmentLineItems" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "default, 400, 401, 403, 422, 429, 500" response messages for a "getAllAssessmentLineItems" operation.
{
    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
    "imsx_severity" : "status"|"warning"|"error",
    "imsx_description" : "..String..",
    "imsx_CodeMinor" : {
        "imsx_codeMinorField" : [
            {
                "imsx_codeMinorFieldName" : "..NormalizedString..",
                "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"invaliddata"|
                	"unauthorisedrequest"|"internal_server_error"|"server_busy"|"deletefailure"|"unknownobject"|"forbidden"
            },
            {...},
            {...}
        ]
    }
}

3.4.7 "getAllAssessmentResults" Request Payload

There is no payload for this request.

"getAllAssessmentResults" Response Payloads

Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "200" response messages for a "getAllAssessmentResults" operation.
Property Name Multiplicity JSON Data-type Description
    assessmentResults [0..*] Array [ Object ] The collection of assessment result instances. The order is not significant. The corresponding query constraints may result in no instances being returned.
            sourcedId [1..1] String The sourcedId of the object. All objects MUST be identified by a Source Identifier. This is a GUID System ID for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields) they use to SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. The form of the extension is dependent on the binding technology being used.
                    extensions [0..*] Set of Proprietary Properties The form of the extension is dependent on the binding technology being used. This specification is silent on what implementers may consider to be appropriate extensions.
            assessmentLineItem [1..1] Object The GUID of the assessment lineItem to which the assessment result is aligned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            student [1..1] Object The GUID of the student for whom the assessment result is assigned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            score [1..1] Float The score for the result. If a scoreScale is assigned then the value must align with the scale.
            textScore [0..1] String An optional non-numeric score value. If a scoreScale is assigned then the value must align with the scale.
            scoreDate [1..1] String (Format: date) The date at which the score is assigned. The format is YYYY-MM-DD as defined in [ISO 8601].
            scoreScale [0..1] Object The GUID of the scoreScale against which the result is aligned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            scorePercentile [0..1] Float The percentile rank of a score is the percentage of scores in its frequency distribution that are equal to or lower than it.
            scoreStatus [1..1] Enumeration The status of the score. The value is from an enumerated vocabulary.
            comment [0..1] String A human readable comment about the score.
            learningObjectiveSet [0..*] Array [ Object ] The set of identifiers for the learning objectives to which this result is aligned. Any number groups of learning objectives can be assigned.
                    source [1..1] Union(SourceExtEnum) The source responsible for creating the learning objective identifiers. The permitted values are from an extensible vocabulary.
                    learningObjectiveResults [1..*] Array [ Object ] The set of unique identifiers for the associated learning objectives (these may have alignment with a mastery score). If these are CASE identifiers they MUST be valid UUIDs.
                            learningObjectiveId [1..1] String The unique identifier for the associated learning objective. If this is a CASE identifier it MUST be a valid UUID.
                            score [0..1] Float The optional mastery score supplied as a numeric value.
                            textScore [0..1] String The optional mastery score supplied in a non-numeric form.
            inProgress [0..1] Enumeration This is used to indicate that the associated work activity has been assigned and student's work product is not yet expected to have been submitted.
            incomplete [0..1] Enumeration This is used to indicate that the student's work product has been submitted but it is deemed incomplete by the teacher.
            late [0..1] Enumeration This is used to indicate that the student's work product is either past due or it has been submitted past the due date. The score on this result may be impacted as as result of this flag.
            missing [0..1] Enumeration This is used to indicate that the student's work product as not been submitted.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "200" response messages for a "getAllAssessmentResults" operation.
{
    "assessmentResults" : [
        {
            "sourcedId" : "..String..",
            "status" : "active"|"tobedeleted",
            "dateLastModified" : "..Date/Time..",
            "metadata" : {
                "..permitted extension point.." : "..user defined value.."
            },
            "assessmentLineItem" : {
                "href" : "..URI..",
                "sourcedId" : "..String..",
                "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
                	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
            },
            "student" : {
                "href" : "..URI..",
                "sourcedId" : "..String..",
                "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
                	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
            },
            "score" : ..Number(Float)..,
            "textScore" : "..NormalizedString..",
            "scoreDate" : "..String(Date)..",
            "scoreScale" : {
                "href" : "..URI..",
                "sourcedId" : "..String..",
                "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
                	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
            },
            "scorePercentile" : ..Number(Float)..,
            "scoreStatus" : "exempt"|"fully graded"|"not submitted"|"partially graded"|"submitted"|"late"|
            	"incomplete"|"missing"|"withdrawal"|"in progress",
            "comment" : "..String..",
            "learningObjectiveSet" : [
                {
                    "source" : "..select from Union..",
                    "learningObjectiveResults" : [
                        {
                            "learningObjectiveId" : "..NormalizedString..",
                            "score" : ..Number(Float)..,
                            "textScore" : "..NormalizedString.."
                        },
                        {...},
                        {...}
                    ]
                },
                {...},
                {...}
            ],
            "inProgress" : "true"|"false",
            "incomplete" : "true"|"false",
            "late" : "true"|"false",
            "missing" : "true"|"false"
        },
        {...},
        {...}
    ]
}

Response Payloads for the HTTP Codes (default, 400, 401, 403, 422, 429, 500)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "default, 400, 401, 403, 422, 429, 500" response messages for a "getAllAssessmentResults" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "default, 400, 401, 403, 422, 429, 500" response messages for a "getAllAssessmentResults" operation.
{
    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
    "imsx_severity" : "status"|"warning"|"error",
    "imsx_description" : "..String..",
    "imsx_CodeMinor" : {
        "imsx_codeMinorField" : [
            {
                "imsx_codeMinorFieldName" : "..NormalizedString..",
                "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"invaliddata"|
                	"unauthorisedrequest"|"internal_server_error"|"server_busy"|"deletefailure"|"unknownobject"|"forbidden"
            },
            {...},
            {...}
        ]
    }
}

3.4.8 "getAssessmentLineItem" Request Payload

There is no payload for this request.

"getAssessmentLineItem" Response Payloads

Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "200" response messages for a "getAssessmentLineItem" operation.
Property Name Multiplicity JSON Data-type Description
    assessmentLineItem [1..1] Object The instance of the single assessment lineItem for a message payload. There must be a data payload otherwise an error report payload for the record not being located should be returned.
            sourcedId [1..1] String The sourcedId of the object. All objects MUST be identified by a Source Identifier. This is a GUID System ID for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields) they use to SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. The form of the extension is dependent on the binding technology being used.
                    extensions [0..*] Set of Proprietary Properties The form of the extension is dependent on the binding technology being used. This specification is silent on what implementers may consider to be appropriate extensions.
            title [1..1] String The title, human readable, for the assessment lineItem. This should allow the assessment lineItem to be distinguished from its peer assessment lineItems.
            description [0..1] String A human readable description of the usage of the assessment lineItem.
            class [0..1] Object The GUID of the class to which the assessment lineItem has been assigned. Note that an assessment LineItem MAY be assigned tio a class.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced i.e. a 'class'.
            parentAssessmentLineItem [0..1] Object The GUID of the parent assessment lineItem. This enables the assessment lineItems to be chained together in a parent/child hierarchy.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            scoreScale [0..1] Object The GUID of the score scale to be used for the lineItem. This attribute was added in the OR 1.2 release.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            resultValueMin [0..1] Float The minimum value (numeric) that can be assigned to the score attribute in a result. The score scale mapping should be used to map to other scores.
            resultValueMax [0..1] Float The maximum value (numeric) that can be assigned to the score attribute in a result. The score scale mapping should be used to map to other scores.
            learningObjectiveSet [0..*] Array [ Object ] The set of identifiers for the learning objectives to which this assessment is aligned. Any number groups of learning objectives can be assigned.
                    source [1..1] Union(SourceExtEnum) The source responsible for creating the learning objective identifiers. The permitted values are from an extensible vocabulary.
                    learningObjectiveIds [1..*] Array [ String ] The set of unique identifiers for the associated learning objectives. If these are CASE identifiers they MUST be valid UUIDs.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "200" response messages for a "getAssessmentLineItem" operation.
{
    "assessmentLineItem" : {
        "sourcedId" : "..String..",
        "status" : "active"|"tobedeleted",
        "dateLastModified" : "..Date/Time..",
        "metadata" : {
            "..permitted extension point.." : "..user defined value.."
        },
        "title" : "..NormalizedString..",
        "description" : "..String..",
        "class" : {
                "href" : "..URI..",
                "sourcedId" : "..String..",
                "type" : "class"
        },
        "parentAssessmentLineItem" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "scoreScale" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "resultValueMin" : ..Number(Float)..,
        "resultValueMax" : ..Number(Float)..,
        "learningObjectiveSet" : [
            {
                "source" : "..select from Union..",
                "learningObjectiveIds" : [ "..NormalizedString..", ..., "..NormalizedString.." ]
            },
            {...},
            {...}
        ]
    }
}

Response Payloads for the HTTP Codes (default, 400, 401, 403, 404, 422, 429, 500)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "default, 400, 401, 403, 404, 422, 429, 500" response messages for a "getAssessmentLineItem" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "default, 400, 401, 403, 404, 422, 429, 500" response messages for a "getAssessmentLineItem" operation.
{
    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
    "imsx_severity" : "status"|"warning"|"error",
    "imsx_description" : "..String..",
    "imsx_CodeMinor" : {
        "imsx_codeMinorField" : [
            {
                "imsx_codeMinorFieldName" : "..NormalizedString..",
                "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"invaliddata"|
                	"unauthorisedrequest"|"internal_server_error"|"server_busy"|"deletefailure"|"unknownobject"|"forbidden"
            },
            {...},
            {...}
        ]
    }
}

3.4.9 "getAssessmentResult" Request Payload

There is no payload for this request.

"getAssessmentResult" Response Payloads

Response Payloads for the HTTP Codes (200)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "200" response messages for a "getAssessmentResult" operation.
Property Name Multiplicity JSON Data-type Description
    assessmentResult [1..1] Object The instance of the single assessment result for a message payload. There must be a data payload otherwise an error report payload for the record not being located should be returned.
            sourcedId [1..1] String The sourcedId of the object. All objects MUST be identified by a Source Identifier. This is a GUID System ID for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields) they use to SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. The form of the extension is dependent on the binding technology being used.
                    extensions [0..*] Set of Proprietary Properties The form of the extension is dependent on the binding technology being used. This specification is silent on what implementers may consider to be appropriate extensions.
            assessmentLineItem [1..1] Object The GUID of the assessment lineItem to which the assessment result is aligned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            student [1..1] Object The GUID of the student for whom the assessment result is assigned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            score [1..1] Float The score for the result. If a scoreScale is assigned then the value must align with the scale.
            textScore [0..1] String An optional non-numeric score value. If a scoreScale is assigned then the value must align with the scale. This attribute was added in OR 1.2.
            scoreDate [1..1] String (Format: date) The date at which the score is assigned. The format is YYYY-MM-DD as defined in [ISO 8601].
            scoreScale [0..1] Object The GUID of the scoreScale against which the result is aligned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            scorePercentile [0..1] Float The percentile rank of a score is the percentage of scores in its frequency distribution that are equal to or lower than it.
            scoreStatus [1..1] Enumeration The status of the score. The value is from an enumerated vocabulary.
            comment [0..1] String A human readable comment about the score.
            learningObjectiveSet [0..*] Array [ Object ] The set of identifiers for the learning objectives to which this result is aligned. Any number groups of learning objectives can be assigned.
                    source [1..1] Union(SourceExtEnum) The source responsible for creating the learning objective identifiers. The permitted values are from an extensible vocabulary.
                    learningObjectiveResults [1..*] Array [ Object ] The set of unique identifiers for the associated learning objectives (these may have alignment with a mastery score). If these are CASE identifiers they MUST be valid UUIDs.
                            learningObjectiveId [1..1] String The unique identifier for the associated learning objective. If this is a CASE identifier it MUST be a valid UUID.
                            score [0..1] Float The optional mastery score supplied as a numeric value.
                            textScore [0..1] String The optional mastery score supplied in a non-numeric form.
            inProgress [0..1] Enumeration This is used to indicate that the associated work activity has been assigned and student's work product is not yet expected to have been submitted.
            incomplete [0..1] Enumeration This is used to indicate that the student's work product has been submitted but it is deemed incomplete by the teacher.
            late [0..1] Enumeration This is used to indicate that the student's work product is either past due or it has been submitted past the due date. The score on this result may be impacted as as result of this flag.
            missing [0..1] Enumeration This is used to indicate that the student's work product as not been submitted.

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "200" response messages for a "getAssessmentResult" operation.
{
    "assessmentResult" : {
        "sourcedId" : "..String..",
        "status" : "active"|"tobedeleted",
        "dateLastModified" : "..Date/Time..",
        "metadata" : {
            "..permitted extension point.." : "..user defined value.."
        },
        "assessmentLineItem" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "student" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "score" : ..Number(Float)..,
        "textScore" : "..NormalizedString..",
        "scoreDate" : "..String(Date)..",
        "scoreScale" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "scorePercentile" : ..Number(Float)..,
        "scoreStatus" : "exempt"|"fully graded"|"not submitted"|"partially graded"|"submitted"|"late"|"incomplete"
        	|"missing"|"withdrawal"|"in progress",
        "comment" : "..String..",
        "learningObjectiveSet" : [
                {
                    "source" : "..select from Union..",
                    "learningObjectiveResults" : [
                        {
                            "learningObjectiveId" : "..NormalizedString..",
                            "score" : ..Number(Float)..,
                            "textScore" : "..NormalizedString.."
                        },
                        {...},
                        {...}
                    ]
                },
                {...},
                {...}
        ],
        "inProgress" : "true"|"false",
        "incomplete" : "true"|"false",
        "late" : "true"|"false",
        "missing" : "true"|"false"
    }
}

Response Payloads for the HTTP Codes (default, 400, 401, 403, 404, 422, 429, 500)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "default, 400, 401, 403, 404, 422, 429, 500" response messages for a "getAssessmentResult" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "default, 400, 401, 403, 404, 422, 429, 500" response messages for a "getAssessmentResult" operation.
{
    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
    "imsx_severity" : "status"|"warning"|"error",
    "imsx_description" : "..String..",
    "imsx_CodeMinor" : {
        "imsx_codeMinorField" : [
            {
                "imsx_codeMinorFieldName" : "..NormalizedString..",
                "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"invaliddata"|
                	"unauthorisedrequest"|"internal_server_error"|"server_busy"|"deletefailure"|"unknownobject"|"forbidden"
            },
            {...},
            {...}
        ]
    }
}

3.4.10 "putAssessmentLineItem" Request Payload

A tabular description of the request payload is shown in the Table below.

Tabular representation of the JSON payload for the request message for a "putAssessmentLineItem" operation.
Property Name Multiplicity JSON Data-type Description
    assessmentLineItem [1..1] Object The instance of the single assessment lineItem for a message payload. There must be a data payload otherwise an error report payload for the record not being located should be returned.
            sourcedId [1..1] String The sourcedId of the object. All objects MUST be identified by a Source Identifier. This is a GUID System ID for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields) they use to SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. The form of the extension is dependent on the binding technology being used.
                    extensions [0..*] Set of Proprietary Properties The form of the extension is dependent on the binding technology being used. This specification is silent on what implementers may consider to be appropriate extensions.
            title [1..1] String The title, human readable, for the assessment lineItem. This should allow the assessment lineItem to be distinguished from its peer assessment lineItems.
            description [0..1] String A human readable description of the usage of the assessment lineItem.
            class [0..1] Object The GUID of the class to which the lineItem has been assigned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced i.e. a 'class'.
            parentAssessmentLineItem [0..1] Object The GUID of the parent assessment lineItem. This enables the assessment lineItems to be chained together in a parent/child hierarchy.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            scoreScale [0..1] Object The GUID of the score scale to be used for the lineItem. This attribute was added in the OR 1.2 release.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            resultValueMin [0..1] Float The minimum value (numeric) that can be assigned to the score attribute in a result. The score scale mapping should be used to map to other scores.
            resultValueMax [0..1] Float The maximum value (numeric) that can be assigned to the score attribute in a result. The score scale mapping should be used to map to other scores.
            learningObjectiveSet [0..*] Array [ Object ] The set of identifiers for the learning objectives to which this assessment is aligned. Any number groups of learning objectives can be assigned.
                    source [1..1] Union(SourceExtEnum) The source responsible for creating the learning objective identifiers. The permitted values are from an extensible vocabulary.
                    learningObjectiveIds [1..*] Array [ String ] The set of unique identifiers for the associated learning objectives. If these are CASE identifiers they MUST be valid UUIDs.

An example of the request payload is shown in the code block below.

JSON payload example for the request message for a "putAssessmentLineItem" operation.
{
    "assessmentLineItem" : {
        "sourcedId" : "..String..",
        "status" : "active"|"tobedeleted",
        "dateLastModified" : "..Date/Time..",
        "metadata" : {
            "..permitted extension point.." : "..user defined value.."
        },
        "title" : "..NormalizedString..",
        "description" : "..String..",
        "class" : {
                "href" : "..URI..",
                "sourcedId" : "..String..",
                "type" : "class"
        },
        "parentAssessmentLineItem" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "scoreScale" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "resultValueMin" : ..Number(Float)..,
        "resultValueMax" : ..Number(Float)..,
        "learningObjectiveSet" : [
            {
                "source" : "..select from Union..",
                "learningObjectiveIds" : [ "..NormalizedString..", ..., "..NormalizedString.." ]
            },
            {...},
            {...}
        ]
    }
}

3.4.11 "putAssessmentLineItem" Response Payloads

3.4.11.1 Response Payloads for the HTTP Codes (201)

There is no payload for these responses i.e. only a HTTP response header is returned.

3.4.11.2 Response Payloads for the HTTP Codes (default, 401, 403, 404, 422, 429, 500)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "default, 401, 403, 404, 422, 429, 500" response messages for a "putAssessmentLineItem" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "default, 401, 403, 404, 422, 429, 500" response messages for a "putAssessmentLineItem" operation.
{
    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
    "imsx_severity" : "status"|"warning"|"error",
    "imsx_description" : "..String..",
    "imsx_CodeMinor" : {
        "imsx_codeMinorField" : [
            {
                "imsx_codeMinorFieldName" : "..NormalizedString..",
                "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"invaliddata"|
                	"unauthorisedrequest"|"internal_server_error"|"server_busy"|"deletefailure"|"unknownobject"|"forbidden"
            },
            {...},
            {...}
        ]
    }
}

3.4.12 "putAssessmentResult" Request Payload

A tabular description of the request payload is shown in the Table below.

Tabular representation of the JSON payload for the request message for a "putAssessmentResult" operation.
Property Name Multiplicity JSON Data-type Description
    assessmentResult [1..1] Object The instance of the single assessment result for a message payload. There must be a data payload otherwise an error report payload for the record not being located should be returned.
            sourcedId [1..1] String The sourcedId of the object. All objects MUST be identified by a Source Identifier. This is a GUID System ID for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields) they use to SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.
            status [1..1] Enumeration All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.
            dateLastModified [1..1] String (Format: date-time) All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.
            metadata [0..1] Object All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. The form of the extension is dependent on the binding technology being used.
                    extensions [0..*] Set of Proprietary Properties The form of the extension is dependent on the binding technology being used. This specification is silent on what implementers may consider to be appropriate extensions.
            assessmentLineItem [1..1] Object The GUID of the assessment lineItem to which the assessment result is aligned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            student [1..1] Object The GUID of the student for whom the assessment result is assigned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            score [1..1] Float The score for the result. If a scoreScale is assigned then the value must align with the scale.
            textScore [0..1] String An optional non-numeric score value. If a scoreScale is assigned then the value must align with the scale. This attribute was added in OR 1.2.
            scoreDate [1..1] String (Format: date) The date at which the score is assigned. The format is YYYY-MM-DD as defined in [ISO 8601].
            scoreScale [0..1] Object The GUID of the scoreScale against which the result is aligned.
                    href [1..1] String (Format: uri) The URI for the type of object being referenced.
                    sourcedId [1..1] String The globally unique identifier of the object being referenced.
                    type [1..1] Enumeration The type of object being referenced. This is an enumerated vocabulary.
            scorePercentile [0..1] Float The percentile rank of a score is the percentage of scores in its frequency distribution that are equal to or lower than it.
            scoreStatus [1..1] Enumeration The status of the score. The value is from an enumerated vocabulary.
            comment [0..1] String A human readable comment about the score.
            learningObjectiveSet [0..*] Array [ Object ] The set of identifiers for the learning objectives to which this result is aligned. Any number groups of learning objectives can be assigned.
                    source [1..1] Union(SourceExtEnum) The source responsible for creating the learning objective identifiers. The permitted values are from an extensible vocabulary.
                    learningObjectiveResults [1..*] Array [ Object ] The set of unique identifiers for the associated learning objectives (these may have alignment with a mastery score). If these are CASE identifiers they MUST be valid UUIDs.
                            learningObjectiveId [1..1] String The unique identifier for the associated learning objective. If this is a CASE identifier it MUST be a valid UUID.
                            score [0..1] Float The optional mastery score supplied as a numeric value.
                            textScore [0..1] String The optional mastery score supplied in a non-numeric form.
            inProgress [0..1] Enumeration This is used to indicate that the associated work activity has been assigned and student's work product is not yet expected to have been submitted.
            incomplete [0..1] Enumeration This is used to indicate that the student's work product has been submitted but it is deemed incomplete by the teacher.
            late [0..1] Enumeration This is used to indicate that the student's work product is either past due or it has been submitted past the due date. The score on this result may be impacted as as result of this flag.
            missing [0..1] Enumeration This is used to indicate that the student's work product as not been submitted.

An example of the request payload is shown in the code block below.

JSON payload example for the request message for a "putAssessmentResult" operation.
{
    "assessmentResult" : {
        "sourcedId" : "..String..",
        "status" : "active"|"tobedeleted",
        "dateLastModified" : "..Date/Time..",
        "metadata" : {
            "..permitted extension point.." : "..user defined value.."
        },
        "assessmentLineItem" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "student" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "score" : ..Number(Float)..,
        "textScore" : "..NormalizedString..",
        "scoreDate" : "..String(Date)..",
        "scoreScale" : {
            "href" : "..URI..",
            "sourcedId" : "..String..",
            "type" : "academicSession"|"category"|"class"|"course"|"demographics"|"enrollment"|"lineItem"|"org"|
            	"resource"|"result"|"student"|"teacher"|"user"|"term"|"gradingPeriod"|"scoreScale"|"school"
        },
        "scorePercentile" : ..Number(Float)..,
        "scoreStatus" : "exempt"|"fully graded"|"not submitted"|"partially graded"|"submitted"|"late"|
        	"incomplete"|"missing"|"withdrawal"|"in progress",
        "comment" : "..String..",
        "learningObjectiveSet" : [
                {
                    "source" : "..select from Union..",
                    "learningObjectiveResults" : [
                        {
                            "learningObjectiveId" : "..NormalizedString..",
                            "score" : ..Number(Float)..,
                            "textScore" : "..NormalizedString.."
                        },
                        {...},
                        {...}
                    ]
                },
                {...},
                {...}
        ],
        "inProgress" : "true"|"false",
        "incomplete" : "true"|"false",
        "late" : "true"|"false",
        "missing" : "true"|"false"
    }
}

"putAssessmentResult" Response Payloads

Response Payloads for the HTTP Codes (201)

There is no payload for these responses i.e. only a HTTP response header is returned.

Response Payloads for the HTTP Codes (default, 401, 403, 404, 422, 429, 500)

A tabular description of the response payload is shown in the Table below.

Tabular representation of the JSON payload for "default, 401, 403, 404, 422, 429, 500" response messages for a "putAssessmentResult" operation.
Property Name Multiplicity JSON Data-type Description
    imsx_codeMajor [1..1] Enumeration The code major value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes. The permitted vocabulary for the values for the CodeMajor field.
    imsx_severity [1..1] Enumeration The severity value (from the corresponding enumerated vocabulary). See Appendix B for further information on the interpretation of this set of codes.
    imsx_description [0..1] String A human readable description supplied by the entity creating the status code information.
    imsx_CodeMinor [0..1] Object The set of reported code minor status codes. See Appendix B for further information on the interpretation of this set of codes.
            imsx_codeMinorField [1..*] Array [ Object ] Each reported code minor status code.
                    imsx_codeMinorFieldName [1..1] String This should contain the identity of the system that has produced the code minor status code report. In most cases this will be the target service provider denoted as 'TargetEndSystem'.
                    imsx_codeMinorFieldValue [1..1] Enumeration The code minor status code (this is a value from the corresponding enumerated vocabulary).

An example of the response JSON payload is shown in the code block below. The JSON Schema file that can be used to validate this payload is given in Appendix B.

JSON payload example for "default, 401, 403, 404, 422, 429, 500" response messages for a "putAssessmentResult" operation.
{
    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
    "imsx_severity" : "status"|"warning"|"error",
    "imsx_description" : "..String..",
    "imsx_CodeMinor" : {
        "imsx_codeMinorField" : [
            {
                "imsx_codeMinorFieldName" : "..NormalizedString..",
                "imsx_codeMinorFieldValue" : "fullsuccess"|"invalid_filter_field"|"invalid_selection_field"|"invaliddata"|
                	"unauthorisedrequest"|"internal_server_error"|"server_busy"|"deletefailure"|"unknownobject"|"forbidden"
            },
            {...},
            {...}
        ]
    }
}

3.5 Extending and Profiling the Binding

3.5.1 Extending the Binding

Proprietary extensions of the service are based upon two approaches:

  • The extension of the data models being manipulated by the current set of operations;
  • The inclusion of new operations to support new proprietary functionality.

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.

3.5.1.1 Proprietary 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 [OR-IG-12].

3.5.1.2 Proprietary Data Elements

It is recognized that implementers may wish to extend the specification. The preferred mechanism for doing this is for implementers to use an extension space within the OneRoster data model, and then set their parsers to read those extension attributes. Extensions are ONLY permitted using the 'metadata' attribute within the 'Base' class.

These extensions take the form of name/value pairs. The name is the label of the extension field, and the value is the value of the extension. For example, if wanting to show the extension of field "classification", with value "private" that was added/provided by "ims", the name/value pair is: "ims.classification" : "private".

It is RECOMMENDED that where extensions are used, whenever possible the name/value pairs are based upon vocabulary controlled files. This eliminates a proliferation of free text equivalencies from entering the data e.g. "Florida" vs "FL", vs "Florida, USA". In such cases either the attribute, or the value (or both) MUST be a URI that references the attribute and/or value from an appropriate vocabulary file. For example:

"http://www.nbrs.org" : "FL"

Within the OpenAPI files, uncontrolled data extensions are explicitly prohibited by the JSON Schema definition.

3.5.1.3 Proprietary Vocabulary Terms

In this version the ability to extend some of the enumerated vocabularies has been added: currently, ONLY the 'ScoreStatusEnum' and 'SourceEnum'' vocabularies MAY be extended. Each proprietary term must start with the characters 'ext:'. An example is adding the two proprietary scoreStatus value of 'ext:pending' to the 'ScoreStatusEnum' vocabulary.

3.5.2 Profiling the Binding

This Service can be profiled. In general, Profiling is used to:

  • Refine which Interfaces are used and which operations are supported for each Interface;
  • Refine the data models by increasing the constraints on the base definitions.

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.

4. Implementation Guide

4.1 Relationship to Other IMS Specifications

To be completed in a later version of this Document.

4.2 Realizing the Use-cases

To be completed in a later version of this Document.

4.3 REST-based Best Practices

To be completed in a later version of this Document.

4.4 Integrating with CSV-based Exchange

To be completed in a later version of this Document.

5. Conformance and Certification

5.1 Conformance Testing Process

The process for conformance testing implementations of Assessment Results Management Profile includes the following:

  • Go to the IMS Conformance Test Suite for the Assessment Results Management Profile. Conformance Test Suite links are available in the 1EdTech OneRoster/Learning Information Services Alliance and the relevant link details are given in Sections 5.2 Service Provider and 5.3 Consumer certification) of this document;
  • Follow the onscreen instructions to run the tests;
  • Once the test has been successfully run, submit a print out of the test results along with the following information to conformance@imsglobal.org:
    1. Your Name
    2. Your Organization
    3. Your Product Name and Version
    4. Date the Product was tested
    5. Whether you are a Service/Data Provider or a Service/Data Consumer.

All Tests for the appropriate operational modes must be passed successfully to be considered IMS compliant.

5.1.1 Requirements for Assessment Result Management Profile v1.0 Conformance

All tests must be passed successfully to be considered 1EdTech Assessment Result Management Profile compliant.

5.1.2 Conformance Mark

After you have submitted your successful conformance information to conformance@imsglobal.org, and received confirmation and a registration number from 1EdTech you may then apply the appropriate conformance mark. The 1EdTech conformance chart will list your conformance details. If you have any questions, please feel free to contact us at any point.

Membership in the OneRoster/Learning Information Services Alliance is the only way to achieve official conformance to the Assessment Result Management Profile standard. Products without a 1EdTech conformance Registration Number are not considered to be compliant by 1EdTech.

5.2 Service Provider Compliance

For service provider conformance the endpoints listed in the Tables below MUST be supported reflecting support for 'pull' (where the consumer reads the data from the provider) and push' (where the provider writes the endpoints into the consumer) modes.

The endpoints that MUST be supported by a compliant service provider when data is pulled from the provider.
Service Call Endpoint HTTP Verb Mode
getAllAssessmentLineItems /assessmentLineItems GET Resp
getAssessmentLineItem /assessmentLineItems/{id} GET Resp
getAllAssessmentResults /assessmentResults GET Resp
getAssessmentResult /assessmentResults/{id} GET Resp

Support for ANY of the other endpoints and service modes is OPTIONAL. For a 'GET' request a service provider must supply all of the required data fields for the action and may supply any of the optional data fields.

The endpoints that MUST be supported by a compliant provider when data is pushed by the consumer.
Service Call Endpoint HTTP Verb Mode
putAssessmentLineItem /assessmentLineItems/{id} PUT Init
putAssessmentResult /assessmentResults/{id} PUT Init

Support for ANY of the other endpoints and service modes is OPTIONAL.

5.3 Service Consumer Compliance

For service consumer conformance the endpoints listed in the Tables below MUST be supported reflecting support for 'pull' (where the consumer reads the data from the provider) and push' (where the consumer writes the data into the provider) modes.

The endpoints that MUST be supported by a compliant service consumer when data is pulled from the provider.
Service Call Endpoint HTTP Verb Mode
getAllAssessmentLineItems /assessmentLineItems GET Init
getAllAssessmentResults /assessmentResults GET Init

Support for ANY of the other endpoints and service modes is OPTIONAL. For a 'GET' request a service provider must supply all of the required data fields for the action and may supply any of the optional data fields.

The endpoints that MUST be supported by a compliant service consumer when data is pushed to the provider.
Service Call Endpoint HTTP Verb Mode
putAssessmentLineItem /assessmentLineItems/{id} PUT Resp
putAssessmentResult /assessmentResults/{id} PUT Resp

Support for ANY of the other endpoints and service modes is OPTIONAL.

5.4 Service Certification

5.4.1 Service Provider Certification

The functional capabilities of such systems are:

  • They MUST support the assessment results management profile set of endpoints;
  • All of either the pull or the push modes required endpoints MUST be supported;
  • Any of the optional endpoints MAY be supported (from both the pull and push modes);
  • They MUST supply all of the required data fields;
  • They MAY supply any of the optional data fields;
  • They MAY provide extension data fields;
  • They MUST support the endpoint payload pagination mechanism for all responses that provide a collection in the payload;
  • They MUST support the endpoint payload filtering mechanism for all responses that provide a collection in the payload;
  • They MUST support the endpoint payload sorting mechanism for all responses that provide a collection in the payload;
  • They MUST support the endpoint payload field selection mechanism for all responses that provide a collection or a singleton in the payload;
  • They MUST support the OAuth 2.0 Bearer Token authentication mechanism;
  • The OpenAPI file that describes the functionality of the available ARP-GS services MUST be published at the endpoint base URL. This MUST be a valid OpenAPI 3.0 JSON file at the URL: "...hostname..."/ims/oneroster/gradebook/v1p2/discovery/assessmentresultv1p0service_openapi3_v1p0.json.

Systems that wish to undertake conformance testing as a Service Provider should use the conformance test system located at: https://???tbd..

5.4.2 Service Consumer Certification

The functional capabilities of such systems are:

  • They MUST support the assessment results management profile set of endpoints;
  • All of either the pull or the push modes required endpoints MUST be supported;
  • Any of the optional endpoints MAY be supported (from both the pull and push modes);
  • They MUST support all of the required data fields;
  • They MAY support any of the optional data fields;
  • They MAY process extension data fields;
  • They MUST support the endpoint payload pagination mechanism for all requests that provide a collection in the response payload;
  • They MUST support the endpoint payload filtering mechanism for all requests that provide a collection in the response payload;
  • They MUST support the endpoint payload sorting mechanism for all requests that provide a collection in the response payload;
  • They MUST support the endpoint payload field selection mechanism for all requests that provide a collection or a singleton in the response payload;
  • They MUST support the OAuth 2.0 Bearer Token authentication mechanism.

Systems that wish to undertake conformance testing as a Service Consumer should use the conformance test system located at: >https://???tbd..

5.4.3 Comparison of the Certifications

A comparison of the available certifications for the defined OneRoster endpoints is shown in the Table below. The key for this Table is:

  • 'C' denotes a service consumer;
  • 'P' denotes a service provider;
  • 'Init' denotes that the end-system issues the request (a shaded box denotes that support for the endpoint is required for that mode);
  • 'Resp' denotes that the end-system responds to the request (a shaded box denotes that support for the endpoint is required for that mode)-
  • '-' denotes that the endpoint is not available to that operational mode.
Comparison of the certifications available with respect to the defined endpoints.
Service Call Endpoint HTTP Verb Consumer Provider
getAllAssessmentLineItems /assessmentLineItems GET Init
(Pull)
Resp
(Pull)
getAssessmentLineItem /assessmentLineItems/{id} GET Init
(Pull)
Resp
(Pull)
putAssessmentLineItem /assessmentLineItems/{id} PUT Resp
(Push)
Init
(Push)
deleteAssessmentLineItem /assessmentLineItems/{id} DELETE Resp
(Push)
Init
(Push)
getAllAssessmentResults /assessmentResults GET Init
(Pull)
Resp
(Pull)
getAssessmentResult /assessmentResults/{id} GET Init
(Pull)
Resp
(Pull)
putAssessmentResult /assessmentResults/{id} PUT Resp
(Push)
Init
(Push)
deleteAssessmentResult /assessmentResults/{id} DELETE Resp
(Push)
Init
(Push)

A. OpenAPI Listings

This Section is NORMATIVE.

A.1 Listing of the OpenAPI (JSON) File

A.1.1 OpenAPI 2.0 JSON Listing

The OpenAPI 2 (JSON) listing (based upon [OAS14]) is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/assessmentresultv1p0service_openapi2_v1p0.json.

A.1.2 OpenAPI 3.0 JSON Listing

The OpenAPI 3 (JSON) listing (based upon [OAS17]) is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/assessmentresultv1p0service_openapi3_v1p0.json.

A.2 Listing of the OpenAPI (YAML) File

A.2.1 OpenAPI 2.0 YAML Listing

The OpenAPI 2 (YAML) listing (based upon [OAS14]) is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/assessmentresultv1p0service_openapi2_v1p0.yaml.

A.2.2 OpenAPI 3.0 YAML Listing

The OpenAPI 3 (YAML) listing (based upon [OAS17]) is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/openapi/assessmentresultv1p0service_openapi3_v1p0.yaml.

B. JSON Schema Listings

This Section is NORMATIVE.

B.1 JSON Schema for the "deleteAssessmentLineItem" Operation Request Payload Validation

No request payload is sent for this delete request and so there is no JSON Schema listing.

B.2 JSON Schema for the "deleteAssessmentLineItem" Operation Response Payload Validation for HTTP Codes (204)

No payload is returned for this HTTP code and so there is no JSON Schema listing.

B.3 JSON Schema for the "deleteAssessmentLineItem" Operation Response Payload Validation for HTTP Codes (default,401,403,404,422,429,500)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-deleteassessmentlineitem-default-401-403-404-422-429-500-responsepayload-schemav1p0.json

B.4 JSON Schema for the "deleteAssessmentResult" Operation Request Payload Validation

No request payload is sent for this delete request and so there is no JSON Schema listing.

B.5 JSON Schema for the "deleteAssessmentResult" Operation Response Payload Validation for HTTP Codes (204)

No payload is returned for this HTTP code and so there is no JSON Schema listing.

B.6 JSON Schema for the "deleteAssessmentResult" Operation Response Payload Validation for HTTP Codes (default,401,403,404,422,429,500)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-deleteassessmentresult-default-401-403-404-422-429-500-responsepayload-schemav1p0.json

B.7 JSON Schema for the "getAssessmentLineItem" Operation Request Payload Validation

No request payload is sent for this get request and so there is no JSON Schema listing.

B.8 JSON Schema for the "getAssessmentLineItem" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-getassessmentlineitem-200-responsepayload-schemav1p0.json

B.9 JSON Schema for the "getAssessmentLineItem" Operation Response Payload Validation for HTTP Codes (default,400,401,403,404,422,429,500)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-getassessmentresult-default-400-401-403-404-422-429-500-responsepayload-schemav1p0.json

B.10 JSON Schema for the "getAssessmentResult" Operation Request Payload Validation

No request payload is sent for this get request and so there is no JSON Schema listing.

B.11 JSON Schema for the "getAssessmentResult" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-getassessmentresult-200-responsepayload-schemav1p0.json

B.12 JSON Schema for the "getAssessmentResult" Operation Response Payload Validation for HTTP Codes (default,400,401,403,404,422,429,500)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-getassessmentresult-default-400-401-403-404-422-429-500-responsepayload-schemav1p0.json

B.13 JSON Schema for the "getAllAssessmentLineItems" Operation Request Payload Validation

No request payload is sent for this get request and so there is no JSON Schema listing.

B.14 JSON Schema for the "getAllAssessmentLineItems" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-getallassessmentlineitems-200-responsepayload-schemav1p0.json

B.15 JSON Schema for the "getAllAssessmentLineItems" Operation Response Payload Validation for HTTP Codes (default,400,401,403,422,429,500)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-getallassessmentlineitems-default-400-401-403-422-429-500-responsepayload-schemav1p0.json

B.16 JSON Schema for the "getAllAssessmentResults" Operation Request Payload Validation

No request payload is sent for this get request and so there is no JSON Schema listing.

B.17 JSON Schema for the "getAllAssessmentResults" Operation Response Payload Validation for HTTP Codes (200)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-getallassessmentresults-200-responsepayload-schemav1p0.json

B.18 JSON Schema for the "getAllAssessmentResults" Operation Response Payload Validation for HTTP Codes (default,400,401,403,422,429,500)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-getallassessmentresults-default-400-401-403-422-429-500-responsepayload-schemav1p0.json

B.19 JSON Schema for the "putAssessmentLineItem" Operation Request Payload Validation

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-putassessmentlineitem-requestpayload-schemav1p0.json

B.20 JSON Schema for the "putAssessmentLineItem" Operation Response Payload Validation for HTTP Codes (201)

No payload is returned for this HTTP code and so there is no JSON Schema listing.

B.21 JSON Schema for the "putAssessmentLineItem" Operation Response Payload Validation for HTTP Codes (default,401,403,404,422,429,500)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-putassessmentlineitem-default-401-403-404-422-429-500-responsepayload-schemav1p0.json

B.22 JSON Schema for the "putAssessmentResult" Operation Request Payload Validation

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-putassessmentresult-requestpayload-schemav1p0.json

B.23 JSON Schema for the "putAssessmentResult" Operation Response Payload Validation for HTTP Codes (201)

No payload is returned for this HTTP code and so there is no JSON Schema listing.

B.24 JSON Schema for the "putAssessmentResult" Operation Response Payload Validation for HTTP Codes (default,401,403,404,422,429,500)

The JSON Schema listing is available at: https://purl.imsglobal.org/spec/or/v1p2/schema/jsd/onerostergradebookservicev1p2-putassessmentresult-default-401-403-404-422-429-500-responsepayload-schemav1p0.json

C. Summary of the Conformance Tests for a Consumer

This section is non-normative.

The set of tests that will be used to determine if an implementation of the consumer functionality is compliant are summarised in Table B1. The features supplied in Table B1 are:

  • ID - the unique identifier assigned to the test;
  • Mode - set as either 'R' to denote that this test MUST be passed, 'O' to denote this test MAY be passed and '–' to denote the test is not applicable. R(P) and O(P) denote MUST support and MAY support respectively for the Assessment Results Push endpoints.
  • Description - a brief summary of the objective of the test.
Table C.1 - A summary of the set of tests to be applied to a consumer undergoing certification.
ID Mode Description
AR-1.1 R OAuth2: Send request with valid access token.
AR-2.1 R Confirm Correct Endpoint Request Format: Get All AssessmentLineItems.
AR-2.2 R Confirm Correct Endpoint Request Format: Get All AssessmentResults.
AR-2.3 O Confirm Correct Endpoint Request Format: Get AssessmentLineItem By Id.
AR-2.4 O Confirm Correct Endpoint Request Format: Get AssessmentResult By Id.
AR-3.1 R(P) Confirm Correct Endpoint Request Format: Put AssessmentLineItem.
AR-3.2 R(P) Confirm Correct Endpoint Request Format:Put AssessmentResult.
AR-3.3 O(P) Confirm Correct Endpoint Request Format: Delete AssessmentLineItem.
AR-3.4 O(P) Confirm Correct Endpoint Request Format: Delete AssessmentResult.
More tests to be added in a later version of this Document.

D. Summary of the Conformance Tests for a Service Provider

This section is non-normative.

The set of tests that will be used to determine if an implementation of the service provider functionality is compliant are summarised in the Table D1. The features supplied in Tables are:

  • ID - the unique identifier assigned to the test;
  • Mode - set as either 'R' to denote that this test MUST be passed, 'O' to denote this test MAY be passed and '–' to denote the test is not applicable;
  • Description - a brief summary of the objective of the test.

All of the tests are applied using OAuth 2.0 (Client Credentials) for support is REQUIRED.

Table D1 - A summary of the set of tests to be applied to a service provider supporting the service undergoing certification.
ID Mode Description
AR-GALLLI-101 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload.
AR-GALLLI-201 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &sort=sourcedId query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-202 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &sort=sourcedId&orderBy=asc query parameters. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-203 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &sort=sourcedId&orderBy=desc query parameters. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-301 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &filter (with the equal test on a sourcedId) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-302 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &filter (with the not equal test on a sourcedId) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-303 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &filter (with the greater than test on a sourcedId) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-304 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/lassessmentLineItems' endpoint works correctly using the &filter (with the greater than or equals test on a sourcedId) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-305 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &filter (with the less than test on a sourcedId) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-306 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &filter (with the less than or equals test on a sourcedId) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-307 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &filter (with the contains test on a title) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-308 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &filter (with the AND predicate test on a sourcedId) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLLI-309 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems' endpoint works correctly using the &filter (with the OR predicate test on a sourcedId) query parameter. The test system issues the getAllAssessmentLineItems request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
More tests (AR-GALLLI-***) to be added in a later release of this document.
AR-GONELI-101 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentLineItems/{id}' endpoint works correctly. The test system issues the getAssessmentLineItem request and expects to receive a fully populated JSON payload.
More tests (AR-GONELI-***) to be added in a later release of this document.
AR-GALLRS-101 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentResults' endpoint works correctly. The test system issues the getAllAssessmentResults request and expects to receive a fully populated JSON payload.
AR-GALLRS-201 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentResults' endpoint works correctly using the &sort=sourcedId query parameter. The test system issues the getAllAssessmentResults request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLRS-202 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentResults' endpoint works correctly using the &sort=sourcedId&orderBy=asc query parameters. The test system issues the getAllAssessmentResults request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
AR-GALLRS-203 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentResults' endpoint works correctly using the &sort=sourcedId&orderBy=desc query parameters. The test system issues the getAllAssessmentResults request and expects to receive a fully populated JSON payload. This query parameter must be supported for this service.
More tests (AR-GALLRS-***) to be added in a later release of this document.
AR-GONERS-101 R To confirm the service provider's '.../ims/oneroster/gradebook/v1p2/assessmentResults/{id}' endpoint works correctly. The test system issues the getAssessmentResult request and expects to receive a fully populated JSON payload.
More tests (AR-GONERS-***) to be added in a later release of this document.

E. Data Model Details

This section is non-normative.

This is a subset of teh full data model that can is available in the OR 1.2 Gradebook Service Model [ORGBK-SM-12].

E.1 AssessmentLineItem Class Description

The data model for the "AssessmentLineItem" class is shown in the Figure below and the accompanying definition in the Table below.

UML diagram of the AssessmentLineItem class.
Figure 9 AssessmentLineItem class definitions.
Description of the "AssessmentLineItem" class.
Descriptor Definition
Class Name AssessmentLineItem
Class Type Container [ Sequence ]
Parents The set of parent classes are:
  • AssessmentLineItemSet
  • SingleAssessmentLineItem
Derived Classes There are no derived classes.
Super Classes The set of classes from which this class is derived:
Characteristics There are no characteristics.
Children The set of children attributes are: The set of directly inherited children attributes are:
Link Data The set of attributes that are used to provide links to other data objects are:
Description This is the container for the definition of an assessment lineItem. An assessment lineItem is a collection of results for a set of students who are completing an assignment.

E.1.1 "title" Attribute Description

The description of the "title" attribute for the "AssessmentLineItem" class is given in the Table below.

Description of the "title" attribute for the "AssessmentLineItem" class.
Descriptor Definition
Attribute Name title
Data Type NormalizedString (Primitive-type)
Value Space A set of characters.
Scope Local ("-")
Multiplicity [1]
Description The title, human readable, for the assessment lineItem. This should allow the assessment lineItem to be distinguished from its peer assessment lineItems.

E.1.2 "description" Attribute Description

The description of the "description" attribute for the "AssessmentLineItem" class is given in the Table below.

Description of the "description" attribute for the "AssessmentLineItem" class.
Descriptor Definition
Attribute Name description
Data Type String (Primitive-type)
Value Space A set of characters.
Scope Local ("-")
Multiplicity [0..1]
Description A human readable description of the usage of the assessment lineItem.

E.1.3 "class" Attribute Description

The description of the "class" attribute for the "AssessmentLineItem" class is given in the Table below.

Description of the "class" attribute for the "AssessmentLineItem" class.
Descriptor Definition
Attribute Name class
Data Type ClassGUIDRef
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0..1]
Description The GUID of the class to which the assessment lineItem has been assigned. Note that an assessment LineItem MAY be assigned tio a class.

E.1.4 "parentAssessmentLineItem" Attribute Description

The description of the "parentAssessmentLineItem" attribute for the "AssessmentLineItem" class is given the Table below.

Description of the "parentAssessmentLineItem" attribute for the "AssessmentLineItem" class.
Descriptor Definition
Attribute Name parentAssessmentLineItem
Data Type AssessmentLineItemGUIDRef
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0..1]
Description The GUID of the parent assessment lineItem. This enables the assessment lineItems to be chained together in a parent/child hierarchy.

E.1.5 "scoreScale" Attribute Description

The description of the "scoreScale" attribute for the "AssessmentLineItem" class is given in the Table below.

Description of the "scoreScale" attribute for the "AssessmentLineItem" class.
Descriptor Definition
Attribute Name scoreScale
Data Type ScoreScaleGUIDRef
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0..1]
Description The GUID of the score scale to be used for the lineItem. This attribute was added in the OR 1.2 release.

E.1.6 "resultValueMin" Attribute Description

The description of the "resultValueMin" attribute for the "AssessmentLineItem" class is given in Table below.

Description of the "resultValueMin" attribute for the "AssessmentLineItem" class.
Descriptor Definition
Attribute Name resultValueMin
Data Type Float (Primitive-type)
Value Space Floating number.
Scope Local ("-")
Multiplicity [0..1]
Description The minimum value (numeric) that can be assigned to the score attribute in a result. The score scale mapping should be used to map to other scores.

E.1.7 "resultValueMax" Attribute Description

The description of the "resultValueMax" attribute for the "AssessmentLineItem" class is given in the Table below.

Description of the "resultValueMax" attribute for the "AssessmentLineItem" class.
Descriptor Definition
Attribute Name resultValueMax
Data Type Float (Primitive-type)
Value Space Float number.
Scope Local ("-")
Multiplicity [0..1]
Description The maximum value (numeric) that can be assigned to the score attribute in a result. The score scale mapping should be used to map to other scores.

E.1.8 "learningObjectiveSet" Attribute Description

The description of the "learningObjectiveSet" attribute for the "AssessmentLineItem" class is given in the Table below.

Description of the "learningObjectiveSet" attribute for the "AssessmentLineItem" class.
Descriptor Definition
Attribute Name learningObjectiveSet
Data Type LearningObjectiveSet
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0.. unbounded]
Description The set of identifiers for the learning objectives to which this assessment is aligned. Any number groups of learning objectives can be assigned.

E.2 AssessmentResult Class Description

The data model for the "AssessmentResult" class is shown in the Figure below and the accompanying definition in the Table below.

UML diagram of the AssessmentResult class.
Figure 10 AssessmentResult class definitions.
Description of the "AssessmentResult" class.
Descriptor Definition
Class Name AssessmentResult
Class Type Container [ Sequence ]
Parents The set of parent classes are:
  • AssessmentResultSet
  • SingleAssessmentResult
Derived Classes There are no derived classes.
Super Classes The set of classes from which this class is derived:
Characteristics There are no characteristics.
Children The set of children attributes are: The set of directly inherited children attributes are:
Link Data The set of attributes that are used to provide links to other data objects are:
Description This is the container for the AssessmentResult record. An assessment result consists of the assigned score plus the context for that score.

E.2.1 "assessmentLineItem" Attribute Description

The description of the "assessmentLineItem" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "assessmentLineItem" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name assessmentLineItem
Data Type AssessmentLineItemGUIDRef
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [1]
Description The GUID of the assessment lineItem to which the assessment result is aligned.

E.2.2 "student" Attribute Description

The description of the "student" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "student" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name student
Data Type UserGUIDRef
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [1]
Description The GUID of the student for whom the assessment result is assigned.

E.2.3 "score" Attribute Description

The description of the "score" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "score" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name score
Data Type Float (Primitive-type)
Value Space A floating point number.
Scope Local ("-")
Multiplicity [0..1]
Description The score for the result. If a scoreScale is assigned then the value must align with the scale.

E.2.4 "textScore" Attribute Description

The description of the "textScore" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "textScore" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name textScore
Data Type NormalizedString (Primitive-type)
Value Space A character string.
Scope Local ("-")
Multiplicity [0..1]
Description An optional non-numeric score value. If a scoreScale is assigned then the value must align with the scale.

E.2.5 "scoreDate" Attribute Description

The description of the "scoreDate" attribute for the "AssessmentResult" class is given in Table 6.1.5.5.

Description of the "scoreDate" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name scoreDate
Data Type Date (Primitive-type)
Value Space Date in [ISO8601] format.
Scope Local ("-")
Multiplicity [1]
Description The date at which the score is assigned or there is an update to the result e.g. change in the 'scoreStatus'. The format is YYYY-MM-DD.

E.2.6 "scoreScale" Attribute Description

The description of the "scoreScale" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "scoreScale" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name scoreScale
Data Type ScoreScaleGUIDRef
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0..1]
Description The GUID of the scoreScale against which the result is aligned.

E.2.7 "scorePercentile" Attribute Description

The description of the "scorePercentile" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "scorePercentile" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name scorePercentile
Data Type Float (Primitive-type)
Value Space A floating point number.
Scope Local ("-")
Multiplicity [0..1]
Description The percentile rank of a score is the percentage of scores in its frequency distribution that are equal to or lower than it.

E.2.8 "scoreStatus" Attribute Description

The description of the "scoreStatus" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "scoreStatus" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name scoreStatus
Data Type ScoreStatusExtEnum
Value Space Container [ Union ]
Scope Local ("-")
Multiplicity [1]
Description The status of the score. The value is from an extensible enumerated vocabulary.

E.2.9 "comment" Attribute Description

The description of the "comment" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "comment" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name comment
Data Type String (Primitive-type)
Value Space A set of characters.
Scope Local ("-")
Multiplicity [0..1]
Description A human readable comment about the score.

E.2.10 "learningObjectiveSet" Attribute Description

The description of the "learningObjectiveSet" attribute for the "AssessmentResult" class is given in Table below.

Description of the "learningObjectiveSet" attribute for the "AssessmentResult" class.
Descriptor Definition
Attribute Name learningObjectiveSet
Data Type LearningObjectiveScoreSet
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0.. unbounded]
Description The set of identifiers for the learning objectives to which this result is aligned. Any number groups of learning objectives can be assigned.

E.2.11 "inProgress" Attribute Description

The description of the "inProgress" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "inProgress" attribute for the "AssessmentResult" class.
Attribute Name inProgress
Data Type BooleanTrueFalseEnum
Value Space Enumerated value set of: { true | false }
Scope Local ("-")
Multiplicity [0..1]
Description This is used to indicate that the associated work activity has been assigned and student's work product is not yet expected to have been submitted.

E.2.12 "incomplete" Attribute Description

The description of the "incomplete" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "incomplete" attribute for the "AssessmentResult" class.
Attribute Name incomplete
Data Type BooleanTrueFalseEnum
Value Space Enumerated value set of: { true | false }
Scope Local ("-")
Multiplicity [0..1]
Description This is used to indicate that the student's work product has been submitted but it is deemed incomplete by the teacher.

E.2.13 "late" Attribute Description

The description of the "late" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "late" attribute for the "AssessmentResult" class.
Attribute Name late
Data Type BooleanTrueFalseEnum
Value Space Enumerated value set of: { true | false }
Scope Local ("-")
Multiplicity [0..1]
Description This is used to indicate that the student's work product is either past due or it has been submitted past the due date. The score on this result may be impacted as as result of this flag.

E.2.14 "missing" Attribute Description

The description of the "missing" attribute for the "AssessmentResult" class is given in the Table below.

Description of the "missing" attribute for the "AssessmentResult" class.
Attribute Name missing
Data Type BooleanTrueFalseEnum
Value Space Enumerated value set of: { true | false }
Scope Local ("-")
Multiplicity [0..1]
Description This is used to indicate that the student's work product as not been submitted.

E.3 Base Class Description

The data model for the "Base" class is shown in Figure 6.1.7 and the accompanying definition in the Table below.

UML diagram of the Base class.
Figure 11 Base class definitions.
Description of the "Base" class.
Descriptor Definition
Class Name Base
Class Type Container [ Sequence ]
Parents There are no parent classes.
Derived Classes The set of derived classes are:
Super Classes This class is not derived from another class.
Characteristics There are no characteristics.
Children The set of children attributes are:
Description This is the container for the set of common attributes that are available to all of the first class data structures.

E.3.1 "sourcedId" Attribute Description

The description of the "sourcedId" attribute for the "Base" class is given in the Table below.

Description of the "sourcedId" attribute for the "Base" class.
Descriptor Definition
Attribute Name sourcedId
Data Type GUID
Value Space Container [ DerivedType ]
Scope Local ("-")
Multiplicity [1]
Description The sourcedId of the object. All objects MUST be identified by a Source Identifier. This is a GUID System ID for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields) they use to SourcedId. The sourcedId of an object is considered an addressable property of an entity and as such will not be treated as Personally Identifiable Information (PII) by certified products. Therefore, as a part of certification, vendors will be required to declare that they will notify customers via documentation or other formal and documented agreement that sourcedIds should never contain PII in general, but particularly users. This means that if a customer includes a student name in an enrollment.sourcedId, it will not fall to any certified product to protect the enrollment.sourcedId as PII, or even the userSourcedId field in the enrollment record.

E.3.2 "status" Attribute Description

The description of the "status" attribute for the "Base" class is given in the Table below.

Description of the "status" attribute for the "Base" class.
Descriptor Definition
Attribute Name status
Data Type BaseStatusEnum
Value Space Enumerated value set of: { active | tobedeleted }
Scope Local ("-")
Multiplicity [1]
Description All objects MUST BE either 'active' or 'tobedeleted'. Something which is flagged 'tobedeleted' is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. In v1.1 the enumeration value of 'inactive' was removed and so for backwards compatibility all such marked objects should be interpreted as 'tobedeleted'.

E.3.3 "dateLastModified" Attribute Description

The description of the "dateLastModified" attribute for the "Base" class is given in the Table below.

Description of the "dateLastModified" attribute for the "Base" class.
Descriptor Definition
Attribute Name dateLastModified
Data Type DateTime (Primitive-type)
Value Space Using [[ISO8601].
Scope Local ("-")
Multiplicity [1]
Description All objects MUST be annotated with the dateTime upon which they were last modified. This enables requesters to query for just the latest objects. DateTimes MUST be expressed in W3C profile of [ISO 8601] and MUST contain the UTC timezone.

E.3.4 "metadata" Attribute Description

The description of the "metadata" attribute for the "Base" class is given in the Table below.

Description of the "metadata" attribute for the "Base" class.
Descriptor Definition
Attribute Name metadata
Data Type Metadata
Value Space Container [ Sequence ]
Scope Local ("-")
Multiplicity [0..1]
Description All objects CAN be extended using the Metadata class. This specification is silent on what implementers may consider to be appropriate extensions. The form of the extension is dependent on the binding technology being used.

F. Revision History

This section is non-normative.

F.1 Version History

Version No. Release Date Comments
1EdTech Final Release 1.0 6th June 2022 The first formal release of the Final Release version of this document.

G. References

G.1 Normative references

[OAS14]
OpenAPI Specification (version 2). OpenAPI Initiative (Linux Foundation). September 2014. URL: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md
[OAS17]
OpenAPI Specification (version 3). OpenAPI Initiative (Linux Foundation). July 2017. URL: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md
[OR-CC-12]
1EdTech OneRoster 1.2 Conformance & Certification Final Release 1.0. 1EdTech Consortium Inc. June 2022. URL: https://www.imsglobal.org/ims-oneroster-v1p2-final-certificationv1p0.html
[OR-CSV-12]
OneRoster 1.2 CSV Binding. Colin Smythe; Matthew Richards; Joshua McGhee. IMS Global Learning Consortium, Inc. July, 2020. URL: https://www.imsglobal.org/sites/default/files/spec/oneroster/v1p2/ims-oneroster-v1p2-final-csvbindv1p0.html
[OR-IG-12]
1EdTech OneRoster 1.2 Implementation Guide Final Release 1.0. 1EdTech Consortium Inc. June 2022. URL: https://www.imsglobal.org/ims-oneroster-v1p2-final-impguidev1p0.html
[ORGBK-JSON-12]
1EdTech OneRoster 1.2 Gradebook Services REST/JSON Binding Final Release 1.0. 1EdTech Consortium Inc. June 2022. URL: https://www.imsglobal.org/ims-oneroster-gradebook-v1p2-final-restbindv1p0.html
[ORGBK-SM-12]
1EdTech OneRoster 1.2 Gradebook Services Final Release 1.0. 1EdTech Consortium Inc. June 2022. URL: https://www.imsglobal.org/ims-oneroster-gradebook-v1p2-final-infomodelv1p0.html
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC2617]
HTTP Authentication: Basic and Digest Access Authentication. J. Franks; P. Hallam-Baker; J. Hostetler; S. Lawrence; P. Leach; A. Luotonen; L. Stewart. IETF. June 1999. Draft Standard. URL: https://www.rfc-editor.org/rfc/rfc2617
[RFC6749]
The OAuth 2.0 Authorization Framework. D. Hardt, Ed.. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6749
[RFC6750]
The OAuth 2.0 Authorization Framework: Bearer Token Usage. M. Jones; D. Hardt. IETF. October 2012. Proposed Standard. URL: https://www.rfc-editor.org/rfc/rfc6750
[Security]
1EdTech Security Framework 1.1. IMS Global Inc. July 2021. URL: https://www.imsglobal.org/spec/security/v1p1/
[UNICODE]
The Unicode Standard. Unicode Consortium. URL: https://www.unicode.org/versions/latest/

G.2 Informative references

[ISO8601]
Representation of dates and times. ISO 8601:2004.. International Organization for Standardization (ISO). 2004. ISO 8601:2004. URL: http://www.iso.org/iso/catalogue_detail?csnumber=40874

H. List of Contributors

The following individuals contributed to the development of this document:

Name Organization Role
Eric AdamsInstructure
Barry BrahierInfinite Campus
Tom ClarkPearson
Linda FengUnicon
Viktor HaagDesire2Learn
Richard HeimLearningMate
Tom IngramEscambia County School District
Oxana JurosevicInstructure
Jong KimPearson
Andrew KuritzkyEdmentum
David MayesGwinnett County Schools
Joshua McGhee1EdTechEditor
Phil Nicholls1EdTech
Padraig O'hiceadhaHMH
James PerreaultFLVS
Patrick PorterHouston ISD
Matt RichardsInfinite CampusCo-Chair
Wendy RiedyMicrosoft
Kurt RompotPearson
Upendra PenegalapatiPearson
Gabrielle SandersonIlluminate Education
Colin Smythe1EdTechEditor
Konrad StimelingStride
Aditya SubramaniamSchoology
Matt VellaSchoology
TJ VeringMicrosoft
Mark WallsGwinnett County Schools

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: 1EdTech Assessment Results Profile for Gradebook Service 1.0

Date: September 19th, 2022

Specification Images: