IMS Candidate Final

IMS Global Logo

IMS Comprehensive Learner Record Service REST/JSON Binding Version 1.0

IMS Candidate Final
Version 1.0

Date Issued: July 6th, 2018
Latest version: http://www.imsglobal.org/et/

IPR and Distribution Notices

Recipients of this document are requested to submit, with their comments, notification of any relevant patent claims or other intellectual property rights of which they may be aware that might be infringed by any implementation of the specification set forth in this document, and to provide supporting documentation.

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on IMS's procedures with respect to rights in IMS specifications can be found at the IMS Intellectual Property Rights web page: http://www.imsglobal.org/ipr/imsipr_policyFinal.pdf.

Copyright © 2018 IMS Global Learning Consortium. All Rights Reserved.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/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: www.imsglobal.org/forums/ims-glc-public-forums-and-resources.

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

Document Name: IMS Comprehensive Learner Record Service REST/JSON Binding v1.0

Revision: July 6th, 2018

toc | top

Table of Contents

1. Introduction

1.1 Overview of the Comprehensive Learner Record Service

1.2 Scope and Context

1.3 Structure of this Document

1.4 Nomenclature

1.5 References

2. Serialization

2.1 JSON-LD Serialization

3. The REST Endpoints

3.1 Mapping of the Service Operations to the REST Endpoints

3.2 API Root URL and Versioning

3.3 Predefined Endpoint Query Parameters

3.3.1 "getCLRs" Endpoint Query Parameters

3.3.1.1 "personIDs" Query Parameter

3.4 HTTP Code Handling

4. Using the Endpoint Parameters

4.1 The 'PersonIDs' Parameter

5. Security Framework

5.1 OAuth 2 Client Credentials resource access

6. JSON Payloads

6.1 "getCLRs" Request Payload

6.2 "getCLRs" Response Payload

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

7. Service OpenAPI Description

7.1 General Information

7.2 Tags Information

7.3 Security Information

7.4 Paths Information

7.4.1 "clr" Path

7.5 Definitions Information

7.5.1 "Assessment.Type" Definition

7.5.2 "Association.Type" Definition

7.5.3 "Basic.Type" Definition

7.5.4 "Certificate.Type" Definition

7.5.5 "CoCurricular.Type" Definition

7.5.6 "Competency.Type" Definition

7.5.7 "ComprehensiveLearnerRecord.Type" Definition

7.5.8 "Course.Type" Definition

7.5.9 "Degree.Type" Definition

7.5.10 "Evidence.Type" Definition

7.5.11 "Issuer.Type" Definition

7.5.12 "Package.Type" Definition

7.5.13 "PackageSet.Type" Definition

7.5.14 "Person.Type" Definition

7.5.15 "Record.Type" Definition

7.5.16 "RecordEntity.Type" Definition

7.5.17 "RecordEntityLink.Type" Definition

7.5.18 "RecordEntitySet.Type" Definition

7.5.19 "RecordStatus.Type" Definition

7.5.20 "imsx_CodeMinor.Type" Definition

7.5.21 "imsx_CodeMinorField.Type" Definition

7.5.22 "imsx_StatusInfo.Type" Definition

8. Extending and Profiling the Service

8.1 Extending the Service

8.1.1 Proprietary operations

8.1.2 Proprietary data elements

8.2 Profiling the Service

Appendix A REST/JSON Modelling Terms

A1 REST Endpoint Description Explanations

A1.1 REST Endpoint Mapping Table Explanation

A1.2 Query Parameter Table Explanation

A1.3 Error Codes and Handling for each Endpoint Table Explanation

A2 OpenAPI Descriptions Explanations

A2.1 OpenAPI General Information Table Explanation

A2.2 OpenAPI Tags Table Explanation

A2.3 OpenAPI Security Table Explanation

A2.4 OpenAPI Paths Table Explanation

A2.5 OpenAPI Definitions Table Explanation

Appendix B OpenAPI Listings

B1 Comprehensive Learner Record Service OpenAPI JSON Definition Listing

B2 Comprehensive Learner Record Service OpenAPI YAML Definition Listing

About this Document

List of Contributors

Revision History

toc | top

List of Tables

Table 3.1 - The Set of REST Endpoint URL-leaf Values.

Table 3.3.1.1 - The definition of the "personIDs" query parameter for the "getCLRs" operation.

Table 3.4 - The List of HTTP Codes and Handling for each Endpoint.

Table 7.1 - The Set of General Information Defined in the OpenAPI Description.

Table 7.2 - The Set of Tags Defined in the OpenAPI Description.

Table 7.4.1 - The Set of HTTP Verbs Permitted on the "clr" Path.

Table 7.5.1 - OpenAPI JSON Schema description for the 'Assessment.Type' Complex Type.

Table 7.5.2 - OpenAPI JSON Schema description for the 'Association.Type' Complex Type.

Table 7.5.3 - OpenAPI JSON Schema description for the 'Basic.Type' Complex Type.

Table 7.5.4 - OpenAPI JSON Schema description for the 'Certificate.Type' Complex Type.

Table 7.5.5 - OpenAPI JSON Schema description for the 'CoCurricular.Type' Complex Type.

Table 7.5.6 - OpenAPI JSON Schema description for the 'Competency.Type' Complex Type.

Table 7.5.7 - OpenAPI JSON Schema description for the 'ComprehensiveLearnerRecord.Type' Complex Type.

Table 7.5.8 - OpenAPI JSON Schema description for the 'Course.Type' Complex Type.

Table 7.5.9 - OpenAPI JSON Schema description for the 'Degree.Type' Complex Type.

Table 7.5.10 - OpenAPI JSON Schema description for the 'Evidence.Type' Complex Type.

Table 7.5.11 - OpenAPI JSON Schema description for the 'Issuer.Type' Complex Type.

Table 7.5.12 - OpenAPI JSON Schema description for the 'Package.Type' Complex Type.

Table 7.5.13 - OpenAPI JSON Schema description for the 'PackageSet.Type' Complex Type.

Table 7.5.14 - OpenAPI JSON Schema description for the 'Person.Type' Complex Type.

Table 7.5.15 - OpenAPI JSON Schema description for the 'Record.Type' Complex Type.

Table 7.5.16 - OpenAPI JSON Schema description for the 'RecordEntity.Type' Complex Type.

Table 7.5.17 - OpenAPI JSON Schema description for the 'RecordEntityLink.Type' Complex Type.

Table 7.5.18 - OpenAPI JSON Schema description for the 'RecordEntitySet.Type' Complex Type.

Table 7.5.19 - OpenAPI JSON Schema description for the 'RecordStatus.Type' Complex Type.

Table 7.5.20 - OpenAPI JSON Schema description for the 'imsx_CodeMinor.Type' Complex Type.

Table 7.5.21 - OpenAPI JSON Schema description for the 'imsx_CodeMinorField.Type' Complex Type.

Table 7.5.22 - OpenAPI JSON Schema description for the 'imsx_StatusInfo.Type' Complex Type.

Table A1.1 The key to the descriptions of the mapping between a service calls and its REST endpoint URL-leaf

Table A1.2 The key to the descriptions of the data attribute/characteristic tables

Table A1.3 The key to the descriptions of the list of error codes and handling for each endpoint

Table A2.1 The key to the tabular description of the OpenAPI general information

Table A2.2 The key to the tabular description of the OpenAPI tags information

Table A2.3 The key to the tabular description of the OpenAPI security information.

Table A2.4 The key to the tabular description of the OpenAPI paths information for an HTTP Verb

Table A2.5 The key to the tabular description of the OpenAPI definitions information

toc | top

List of Code Blocks

Code 6.2.1 - JSON payload example for "200, default, 400, 401, 403, 429, 500" response messages for a "getCLRs" operation.

toc | top

1. Introduction

1.1 Overview of the Comprehensive Learner Record Service

The IMS Comprehensive Learner Record service is used to organize and communicate learner achievement records in a standardized format. This standard defines an information model for institutional academic record issuers, learners' whose records are represented, and the learner records themselves. It also describes how this data can be requested as single documents or sets of documents using a set of service calls. This document contains effective practice recommendations when adopting the specification.

1.2 Scope and Context

The IMS Comprehensive Learner Record (CLR) Specification has been designed to create, transmit, and render an individual's set of achievements from one issuer, in a digital, machine-readable format. The specification allows for global adoption and supports shared tools within the IMS Global community.

The Comprehensive Learner Record supports interoperability in that CLR Providers and Consumers can consistently send and receive records among conformant entities. The IMS Comprehensive Learner Record specification describes an information model, service definition, and implementation guide to allow institutions, suppliers, and others to 'extend' the traditional transcript with records and types of information that are typically not found in a traditional transcript, such as competency attainment and co-curricular activities, and to define and facilitate an institution's learner achievements record store for collection of CLRs.

The CLR digitized information can be consumed by other schools, institutions, employers, and any other entities that are conformant as CLR consumers. In this machine readable format, CLR data enables granular and expansive discoverability of learning achievements that was not previously possible.

1.3 Structure of this Document

The structure of the rest of this document is:

2. Serialization ...tbc...
3. The REST Endpoints An explanation of the relationship between the logical service operations (as defined in the Comprehensive Learner Record Service Model [CLR, 17a]) and how these are realised as the corresponding set of REST endpoints (including the set of query parameters that are permitted);
4. Using the Endpoint Parameters A detailed explanation of how the permitted set of query parameters should be used to control the volume and type of information that will be supplied by the service provider;
5. Security Framework The underlying security framework within which this REST/JSON binding is designed to operate. This includes the details about authentication and how the payload integrity may be protected;
6. JSON Payloads Examples of the set of JSON payloads that are sent by the consumer (the request) and returned by the service provider (response). These examples are focused on the expected structure of a request/response and do not include actual payloads;
7. Service OpenAPI Description A detailed explanation of the structure of the OpenAPI files that are produced as part of the specification documentation. The associated JSON and YAML files are supplied in Appendix B;
8. Extending and Profiling the Service An explanation of how the service can be extended, using the permitted points of extension and/or profiled. Profiling is the process by which the specification is tailored to a specific set of market/domain requirements;
Appendix A REST/JSON Modelling Terms An overview of the model driven approach, the concepts and the terms used by IMS to create the service model REST/JSON binding definitions (based upon a profile of UML) and the accompanying documentation (including this binding);
Appendix B 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 specification.

1.4 Nomenclature

JSON JavaScript Object Notation
JSON-LD A JSON-based Serialization for Linked Data
REST Representation State Transfer
UML Unified Modelling Language
URL Uniform Resource Locator

1.5 References

[CLR, 17a] IMS Comprehensive Learner Record (CLR) 1.0 Service Model Candidate Final Document, Bryan Smith, Learning Objects (USA), Chris Houston Capella University (USA), Markus Gylling, IMS Global (Sweden), IMS Global Learning Consortium Inc., July 6th, 2018, http://www.imsglobal.org/et/.
[JSON-LD, 14a] JSON-LD 1.0, Manu Sporny, Digital Bazaar, Dave Longley, Digital Bazaar, Gregg Kellogg, Kellogg Associates, Markus Lanthaler, Graz University of Technology, Niklas Lindstrom, W3C, 16 January, 2014, https://www.w3.org/TR/json-ld/.
[SECURITY FRAMEWORK, 18a] IMS Security Framework, Smythe, Colin, IMS Global, 27 March, 2018, https://imsglobal.org/spec/security/v1p0/.

toc | top

2. Serialization

2.1 JSON-LD Serialization

The ComprehensiveLearnerRecord class defined by this specification uses the JSON-LD [JSON-LD, 14a] serialization.

The canonical JSON-LD context IRI defined for the ComprehensiveLearnerRecord class is https://purl.imsglobal.org/spec/clr/v1p0/context/.

For informaton about extensibility and restrictions of the JSON-LD serialization, refer to proprietary data elements.

toc | top

3. The REST Endpoints

3.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 Table 3.1. The syntax and semantics for this mapping are described in Appendix A1.1.

Table 3.1 - The Set of REST Endpoint URL-leaf Values.
Service Call REST Endpoint HTTP Verb
getCLRs clr GET

3.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/clr/v1p0".

3.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 Appendix A1.2.

3.3.1 "getCLRs" Endpoint Query Parameters

3.3.1.1 "personIDs" Query Parameter

The description of the "personIDs" query parameter is presented in Table 3.3.1.1

Table 3.3.1.1 - The definition of the "personIDs" query parameter for the "getCLRs" operation.
Descriptor Definition
Parameter Name personIDs
Data Type String (Primitive-type)
Value Space See Appendix A1.2.
Multiplicity [1..*]
Description Array of IDs for users for which an comprehensive learner record is requested. The ampersand character is used as the separator character for array entries where each entry is a key and value pair, i.e. ?personIDs=123&personIDs=456.

3.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 Table 3.4. The syntax and semantics for this tabular description are described in Appendix A1.3.

Table 3.4 - The List of HTTP Codes and Handling for each Endpoint.
REST Endpoint HTTP Verb HTTP Codes and Handling
clr GET
  • 200 - this is the response when the request has been completed successfully. Records for all of the specified comprehensive learner records were returned. The payload is defined by the structure PackageSet.Type.
  • 400 - partial success of the request. At least one of the requested comprehensive learner records could not be supplied. This is accompanied by the 'codeMajor/severity' values of 'failure/error' The payload is defined by the structure PackageSet.Type.
  • 401 - the request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. The payload is defined by the structure PackageSet.Type.
  • 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'. The payload is defined by the structure PackageSet.Type.
  • 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'. The payload is defined by the structure PackageSet.Type.
  • 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'. The payload is defined by the structure PackageSet.Type.

toc | top

4. Using the Endpoint Parameters

4.1 The 'PersonIDs' Parameter

The personIDs parameter is an array (with 1..n entries) of IDs for users for which an comprehensive learner record is requested. When a single record is requested, the query parameter has the syntax ?personIDs=123. When multiple records are requested, the ampersand character is used as the separator between key and value pairs, i.e. ?personIDs=123&personIDs=456.

toc | top

5. Security Framework

5.1 OAuth 2 Client Credentials resource access

The CLR security model uses OAuth 2 client credentials based resource access. CLR Providers and Consumers must adhere to the security protocol as defined in [SECURITY FRAMEWORK, 18a], section 4 (Securing Web Services), with the additional constraint that JSON Web Tokens (as defined in section 4.2 in [SECURITY FRAMEWORK, 18a]) MUST be treated as opaque strings by CLR consumers.

A Scope MUST be supplied during the token request and token response messages exchanges. The only permitted scope in this version of this specification is https://purl.imsglobal.org/spec/clr/v1p0/scope/clr.readonly.

Providers MUST fall back gracefully if they encounter any additional unrecognized scopes in the request.

NOTE: It is anticipated that a future draft of this specification will be updated to include support for Authorization Code grants. Cf. https://github.com/IMSGlobal/security-framework/issues/30.

Overview graph of the CLR security model

toc | top

6. JSON Payloads

6.1 "getCLRs" Request Payload

There is no payload for this request.

6.2 "getCLRs" Response Payloads

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

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

Code 6.2.1 - JSON payload example for "200, default, 400, 401, 403, 429, 500" response messages for a "getCLRs" operation.
    {
        "results" : [
            {
                "personID" : "..String..",
                "comprehensiveLearnerRecord" : {
                    "id" : "..NormalizedString..",
                    "type" : "..NormalizedString..",
                    "createdAt" : "..Date/Time..",
                    "issuer" : {
                        "id" : "..NormalizedString..",
                        "type" : "..NormalizedString..",
                        "name" : "..String..",
                        "url" : "..URI..",
                        "address" : "..String..",
                        "phone" : "..String..",
                        "logo" : "..URI..",
                        "issuingPersonFullName" : "..String..",
                        "issuingPersonTitle" : "..String..",
                        "..permitted extension point.." : "..user defined value.."
                    },
                    "overviewUrl" : "..URI..",
                    "person" : {
                        "id" : "..NormalizedString..",
                        "type" : "..NormalizedString..",
                        "fullName" : "..String..",
                        "givenName" : "..String..",
                        "familyName" : "..String..",
                        "email" : "..String..",
                        "phone" : "..String..",
                        "mobile" : "..String..",
                        "studentId" : "..String..",
                        "birthDate" : "..String(Date)..",
                        "sourcedId" : "..String..",
                        "url" : "..URI..",
                        "..permitted extension point.." : "..user defined value.."
                    },
                    "records" : [
                        {
                            "id" : "..NormalizedString..",
                            "type" : "..NormalizedString..",
                            "recordOf" : {
                                "id" : "..NormalizedString..",
                                "type" : "..NormalizedString..",
                                "entityType" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                "entityId" : "..NormalizedString..",
                                "..permitted extension point.." : "..user defined value.."
                            },
                            "date" : "..Date/Time..",
                            "term" : "..String..",
                            "result" : "..String..",
                            "credits" : "..String..",
                            "points" : "..String..",
                            "assertions" : [ "..URI..", ..., "..URI.." ],
                            "status" : {
                                "id" : "..NormalizedString..",
                                "type" : "..NormalizedString..",
                                "completed" : "..Boolean..",
                                "notes" : "..String..",
                                "..permitted extension point.." : "..user defined value.."
                            },
                            "evidence" : [
                                {
                                    "name" : "..String..",
                                    "url" : "..URI..",
                                    "..permitted extension point.." : "..user defined value.."
                                },
                                {...},
                                {...}
                            ],
                            "..permitted extension point.." : "..user defined value.."
                        },
                        {...},
                        {...}
                    ],
                    "recordEntities" : {
                        "id" : "..NormalizedString..",
                        "type" : "..NormalizedString..",
                        "assessments" : [
                            {
                                "id" : "..String..",
                                "type" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                "name" : "..String..",
                                "description" : "..String..",
                                "defaultCredits" : "..String..",
                                "defaultPoints" : "..String..",
                                "sourcedId" : "..String..",
                                "associations" : [
                                    {
                                        "id" : "..NormalizedString..",
                                        "type" : "..NormalizedString..",
                                        "associationType" : "exactMatchOf"|"precedes"|"isChildOf"|"isParentOf"|"hasSkillLevel"|"replacedBy"|"isPartOf"|"exemplar"|"isRelatedTo"|"isPeerOf",
                                        "entityType" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                        "entityId" : "..String..",
                                        "..permitted extension point.." : "..user defined value.."
                                    },
                                    {...},
                                    {...}
                                ],
                                "alternativeLabel" : "..String..",
                                "..permitted extension point.." : "..user defined value..",
                                "assessmentMethod" : "..String..",
                                "scoringMethod" : "..String..",
                                "hasGroupParticipation" : "..Boolean..",
                                "assessor" : "..String..",
                                "assessmentEvaluation" : "..String..",
                                "assessmentOutput" : "..String.."
                            },
                            {...},
                            {...}
                        ],
                        "certificates" : [
                            {
                                "id" : "..String..",
                                "type" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                "name" : "..String..",
                                "description" : "..String..",
                                "defaultCredits" : "..String..",
                                "defaultPoints" : "..String..",
                                "sourcedId" : "..String..",
                                "associations" : [
                                    {
                                        "id" : "..NormalizedString..",
                                        "type" : "..NormalizedString..",
                                        "associationType" : "exactMatchOf"|"precedes"|"isChildOf"|"isParentOf"|"hasSkillLevel"|"replacedBy"|"isPartOf"|"exemplar"|"isRelatedTo"|"isPeerOf",
                                        "entityType" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                        "entityId" : "..String..",
                                        "..permitted extension point.." : "..user defined value.."
                                    },
                                    {...},
                                    {...}
                                ],
                                "alternativeLabel" : "..String..",
                                "..permitted extension point.." : "..user defined value..",
                                "level" : "..String..",
                                "areaOfStudy" : "..String.."
                            },
                            {...},
                            {...}
                        ],
                        "coCurriculars" : [
                            {
                                "id" : "..String..",
                                "type" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                "name" : "..String..",
                                "description" : "..String..",
                                "defaultCredits" : "..String..",
                                "defaultPoints" : "..String..",
                                "sourcedId" : "..String..",
                                "associations" : [
                                    {
                                        "id" : "..NormalizedString..",
                                        "type" : "..NormalizedString..",
                                        "associationType" : "exactMatchOf"|"precedes"|"isChildOf"|"isParentOf"|"hasSkillLevel"|"replacedBy"|"isPartOf"|"exemplar"|"isRelatedTo"|"isPeerOf",
                                        "entityType" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                        "entityId" : "..String..",
                                        "..permitted extension point.." : "..user defined value.."
                                    },
                                    {...},
                                    {...}
                                ],
                                "alternativeLabel" : "..String..",
                                "..permitted extension point.." : "..user defined value..",
                                "category" : "..String..",
                                "scoringMethod" : "..String..",
                                "role" : "..String..",
                                "startDate" : "..Date/Time..",
                                "endDate" : "..Date/Time.."
                            },
                            {...},
                            {...}
                        ],
                        "competencies" : [
                            {
                                "id" : "..String..",
                                "type" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                "name" : "..String..",
                                "description" : "..String..",
                                "defaultCredits" : "..String..",
                                "defaultPoints" : "..String..",
                                "sourcedId" : "..String..",
                                "associations" : [
                                    {
                                        "id" : "..NormalizedString..",
                                        "type" : "..NormalizedString..",
                                        "associationType" : "exactMatchOf"|"precedes"|"isChildOf"|"isParentOf"|"hasSkillLevel"|"replacedBy"|"isPartOf"|"exemplar"|"isRelatedTo"|"isPeerOf",
                                        "entityType" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                        "entityId" : "..String..",
                                        "..permitted extension point.." : "..user defined value.."
                                    },
                                    {...},
                                    {...}
                                ],
                                "alternativeLabel" : "..String..",
                                "..permitted extension point.." : "..user defined value..",
                                "humanCodingScheme" : "..String..",
                                "CFDocumentURI" : "..URI.."
                            },
                            {...},
                            {...}
                        ],
                        "courses" : [
                            {
                                "id" : "..String..",
                                "type" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                "name" : "..String..",
                                "description" : "..String..",
                                "defaultCredits" : "..String..",
                                "defaultPoints" : "..String..",
                                "sourcedId" : "..String..",
                                "associations" : [
                                    {
                                        "id" : "..NormalizedString..",
                                        "type" : "..NormalizedString..",
                                        "associationType" : "exactMatchOf"|"precedes"|"isChildOf"|"isParentOf"|"hasSkillLevel"|"replacedBy"|"isPartOf"|"exemplar"|"isRelatedTo"|"isPeerOf",
                                        "entityType" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                        "entityId" : "..String..",
                                        "..permitted extension point.." : "..user defined value.."
                                    },
                                    {...},
                                    {...}
                                ],
                                "alternativeLabel" : "..String..",
                                "..permitted extension point.." : "..user defined value..",
                                "courseCode" : "..String..",
                                "startDate" : "..Date/Time..",
                                "endDate" : "..Date/Time.."
                            },
                            {...},
                            {...}
                        ],
                        "degrees" : [
                            {
                                "id" : "..String..",
                                "type" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                "name" : "..String..",
                                "description" : "..String..",
                                "defaultCredits" : "..String..",
                                "defaultPoints" : "..String..",
                                "sourcedId" : "..String..",
                                "associations" : [
                                    {
                                        "id" : "..NormalizedString..",
                                        "type" : "..NormalizedString..",
                                        "associationType" : "exactMatchOf"|"precedes"|"isChildOf"|"isParentOf"|"hasSkillLevel"|"replacedBy"|"isPartOf"|"exemplar"|"isRelatedTo"|"isPeerOf",
                                        "entityType" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                        "entityId" : "..String..",
                                        "..permitted extension point.." : "..user defined value.."
                                    },
                                    {...},
                                    {...}
                                ],
                                "alternativeLabel" : "..String..",
                                "..permitted extension point.." : "..user defined value..",
                                "programName" : "..String..",
                                "programSpecialization" : "..String..",
                                "level" : "..String..",
                                "areaOfStudy" : "..String.."
                            },
                            {...},
                            {...}
                        ],
                        "basicEntities" : [
                            {
                                "id" : "..String..",
                                "type" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                "name" : "..String..",
                                "description" : "..String..",
                                "defaultCredits" : "..String..",
                                "defaultPoints" : "..String..",
                                "sourcedId" : "..String..",
                                "associations" : [
                                    {
                                        "id" : "..NormalizedString..",
                                        "type" : "..NormalizedString..",
                                        "associationType" : "exactMatchOf"|"precedes"|"isChildOf"|"isParentOf"|"hasSkillLevel"|"replacedBy"|"isPartOf"|"exemplar"|"isRelatedTo"|"isPeerOf",
                                        "entityType" : "Basic"|"Competency"|"Course"|"Degree"|"Certificate"|"Assessment"|"CoCurricular",
                                        "entityId" : "..String..",
                                        "..permitted extension point.." : "..user defined value.."
                                    },
                                    {...},
                                    {...}
                                ],
                                "alternativeLabel" : "..String..",
                                "..permitted extension point.." : "..user defined value.."
                            },
                            {...},
                            {...}
                        ],
                        "..permitted extension point.." : "..user defined value.."
                    },
                    "..permitted extension point.." : "..user defined value.."
                },
                "status" : "unsupported"|"internal_error"|"not_found"|"forbidden"|"server_busy"|"success"
            },
            {...},
            {...}
        ]
    }
                        

toc | top

7. Service OpenAPI Description

7.1 General Information

The set of General Information defined in the OpenAPI description, and realised in both the JSON and YAML instances, is listed in Table 7.1. The syntax and semantics for this information are described in Appendix A2.1.

Table 7.1 - The Set of General Information Defined in the OpenAPI Description.
Swagger Version 2.0
Specification Title Comprehensive Learner Record Service
Specification Version 1.0
Description The Comprehensive Learner Record Service enables the exchange of data about users and their achievements between a Comprehensive Learner Record Service Provider and the consumers of the associated data. This service has been described using the IMS Model Driven Specification development approach, this being the Platform Specific Model (PSM) of the service.
Terms of Service 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 API DEFINITION 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 IMPLEMENTERS 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 API DEFINITION.
Contact Lisa Mattson (COO), IMS Global (http://www.imsglobal.org). Email: lmattson@imsglobal.org.
License IMS Global - https://www.imsglobal.org/license.html
Host www.imsglobal.org
Base Path /ims/clr/v1p0
Schemes http, https
Consumes application/json
Produces application/json

7.2 Tags Information

The set of Tags defined in the OpenAPI description, and realised in both the JSON and YAML instances, is listed in Table 7.2. The syntax and semantics for these Tags are described in Appendix A2.2.

Table 7.2 - The Set of Tags Defined in the OpenAPI Description.
Tag Name Description
PackagesManager The set of service operations that manage access to the Comprehensive Learner Record Packages as a whole. The set of endpoints assigned to this tag are: The set of endpoints assigned to this tag are:
  • [ GET ] - clr

7.3 Security Information

The OAuth 2 security mode is used for this service. Table 7.3 describes the OpenAPI information for the configuration of the OAuth 2.0. The syntax and semantics for this information are described in Appendix A2.3.

Table 7.3 - The Set of OAuth 2.0 Security Information Defined in the OpenAPI Description.
Security Label OAuth2Security
Type oauth2
Description The standard usage of OAuth 2.0 by IMS Global.
Flow application
Token URL http://www.imsglobal.org
Scopes user
Global Scope OAuth2Security : [ user ]

7.4 Paths Information

The following Tables describe the OpenAPI information for each of the Paths. The syntax and semantics for these Paths are described in Appendix A2.4.

7.4.1 "clr" Path

The following Table describes the OpenAPI information for the HTTP Verb "GET" on the "clr" Path.

Table 7.4.1 - The Set of HTTP Verbs Permitted on the 'clr' Path.
HTTP Verb: GET
Operation ID getCLRs
Summary The REST "read" request message for the "getCLRs()" API call.
Tags PackagesManager
Description This is a request to the Service Provider to provide a set of Comprehensive Learner Records that corresponds to the IDs given in the personIDs parameter. For each requested record that can not be found the 'unknownobject' status code must be reported.
Path Placeholders Path placeholders are not permitted.
Query Parameters
Name Type Multiplicity Default
personIDs String [1..*] -
Responses
Name Type Description
200 PackageSet.Type This is the response when the request has been completed successfully. Records for all of the specified comprehensive learner records were returned.
default PackageSet.Type No description supplied.
400 PackageSet.Type Partial success of the request. At least one of the requested comprehensive learner records could not be supplied. This is accompanied by the 'codeMajor/severity' values of 'failure/error'
401 PackageSet.Type The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'.
403 PackageSet.Type 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'.
429 PackageSet.Type 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 PackageSet.Type 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'.

7.5 Definitions Information

The following Tables describe the OpenAPI information for each of the JSON Schema Definitions. The syntax and semantics for these JSON Schema Definition descriptions are described in Appendix A2.5.

7.5.1 "Assessment.Type" Definition

The OpenAPI JSON Schema description for the "Assessment.Type" Complex Type is given in Table 7.5.1.

Table 7.5.1 - OpenAPI JSON Schema description for the "Assessment.Type" Complex Type.
Annotations Assessment of work or performance
Diagram To be supplied in a later release of this document
Type Hierarchy RecordEntity.Type
^---Assessment.Type
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{0..*} ! alternativeLabel{0..1} ! { Namespace Extension }, assessmentMethod{0..1} ! scoringMethod{0..1} ! hasGroupParticipation{0..1} ! assessor{0..1} ! assessmentEvaluation{0..1} ! assessmentOutput{0..1}
Source
    "Assessment.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/RecordEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "assessmentMethod" : {
                        "description" : "Model Primitive Datatype = String. An enumeration of assessment methods. See http://www.credreg.net/ctdl/terms#AssessmentMethod.",
                        "type" : "string"
                    },
                    "scoringMethod" : {
                        "description" : "Model Primitive Datatype = String. An enumeration of types of applicable scoring. See http://www.credreg.net/ctdl/terms#ScoringMethod.",
                        "type" : "string"
                    },
                    "hasGroupParticipation" : {
                        "description" : "Model Primitive Datatype = Boolean. True or False that completing the assessment activity being referenced requires two or more participants. See https://www.imsglobal.org/ims-badge-extensions-education",
                        "type" : "boolean"
                    },
                    "assessor" : {
                        "description" : "Model Primitive Datatype = String. Organization, person, or role that assessed the work",
                        "type" : "string"
                    },
                    "assessmentEvaluation" : {
                        "description" : "Model Primitive Datatype = String. Link to studies or other information about research or calculations of reliability and validity for the assessment or the scoring methods. See https://www.imsglobal.org/ims-badge-extensions-education",
                        "type" : "string"
                    },
                    "assessmentOutput" : {
                        "description" : "Model Primitive Datatype = String. Additional details about assessment type. Values for assessmentOutput are expected to be words or phrases that describe the key features of the evidence produced. See https://www.imsglobal.org/ims-badge-extensions-education",
                        "type" : "string"
                    }
                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.2 "Association.Type" Definition

The OpenAPI JSON Schema description for the "Association.Type" Complex Type is given in Table 7.5.2.

Table 7.5.2 - OpenAPI JSON Schema description for the "Association.Type" Complex Type.
Annotations Establish a relationship between two record entities contained within this record.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! associationType{1..1} ! ...tbc...entityId{1..1} ! { Namespace Extension }
Source
    "Association.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                "type" : "string",
                "default" : "Relationship"
            },
            "associationType" : {
                "description" : "The type of relationship. ('isParentOf', 'isChildOf', etc.)",
                "type" : "string",
                "enum" : [ "exactMatchOf","precedes","isChildOf","isParentOf","hasSkillLevel","replacedBy","isPartOf","exemplar","isRelatedTo","isPeerOf" ]
            },
            "entityType" : {
                "description" : "The type of the associated record entity. (E.g., 'Basic', 'Certificate', 'CoCurricular', etc.)",
                "type" : "string",
                "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
            },
            "entityId" : {
                "description" : "Model Primitive Datatype = String. The id of the associated record entity.",
                "type" : "string"
            }
        },
        "required" : [ "id","type","associationType","entityType","entityId" ],
        "additionalProperties" : true
    },
                        

7.5.3 "Basic.Type" Definition

The OpenAPI JSON Schema description for the "Basic.Type" Complex Type is given in Table 7.5.3.

Table 7.5.3 - OpenAPI JSON Schema description for the "Basic.Type" Complex Type.
Annotations Provides support for representing record entities that are not semantically compatible with other record entity classes.
Diagram To be supplied in a later release of this document
Type Hierarchy RecordEntity.Type
^---Basic.Type
Model None
Source
    "Basic.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/RecordEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {

                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.4 "Certificate.Type" Definition

The OpenAPI JSON Schema description for the "Certificate.Type" Complex Type is given in Table 7.5.4.

Table 7.5.4 - OpenAPI JSON Schema description for the "Certificate.Type" Complex Type.
Annotations A credential that designates requisite mastery of the knowledge and skills of an occupation, profession, or academic program. See http://www.credreg.net/ctdl/terms#Certificate
Diagram To be supplied in a later release of this document
Type Hierarchy RecordEntity.Type
^---Certificate.Type
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{0..*} ! alternativeLabel{0..1} ! { Namespace Extension }, level{0..1} ! areaOfStudy{0..1}
Source
    "Certificate.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/RecordEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "level" : {
                        "description" : "Model Primitive Datatype = String. Relative position of the certificate in relation to others.  Examples include Undergraduate, Master's, Associate, etc.",
                        "type" : "string"
                    },
                    "areaOfStudy" : {
                        "description" : "Model Primitive Datatype = String. Area of study or category associated with this certificate. Examples include Infomatics, Accounting, Human Resources Management.",
                        "type" : "string"
                    }
                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.5 "CoCurricular.Type" Definition

The OpenAPI JSON Schema description for the "CoCurricular.Type" Complex Type is given in Table 7.5.5.

Table 7.5.5 - OpenAPI JSON Schema description for the "CoCurricular.Type" Complex Type.
Annotations Activities, achievements, or learning attained in addition to the offical academic curriculum or study, though still asserted by the Issuer. Generally outside of the classroom or course setting. Examples include student government, sports, music, art, debate, photography and others.
Diagram To be supplied in a later release of this document
Type Hierarchy RecordEntity.Type
^---CoCurricular.Type
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{0..*} ! alternativeLabel{0..1} ! { Namespace Extension }, category{0..1} ! scoringMethod{0..1} ! role{0..1} ! startDate{0..1} ! endDate{0..1}
Source
    "CoCurricular.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/RecordEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "category" : {
                        "description" : "Model Primitive Datatype = String. Area of cocurricular activity, as defined by the Issuer. Examples include sports, community service, student government, arts, etc.",
                        "type" : "string"
                    },
                    "scoringMethod" : {
                        "description" : "Model Primitive Datatype = String. An enumeration of types of applicable scoring. See http://www.credreg.net/ctdl/terms#ScoringMethod.",
                        "type" : "string"
                    },
                    "role" : {
                        "description" : "Model Primitive Datatype = String. Role, position, or title of the Person in the cocurricular activity, achievement, or learning experience.  Examples include Student President, Intern, Captain, etc.",
                        "type" : "string"
                    },
                    "startDate" : {
                        "description" : "Model Primitive Datatype = DateTime. Starting date of the Person’s involvement in the cocurricular activity.",
                        "type" : "string",
                        "format" : "date-time"
                    },
                    "endDate" : {
                        "description" : "Model Primitive Datatype = DateTime. Ending date of the Person’s involvement in the cocurricular activity.",
                        "type" : "string",
                        "format" : "date-time"
                    }
                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.6 "Competency.Type" Definition

The OpenAPI JSON Schema description for the "Competency.Type" Complex Type is given in Table 7.5.6.

Table 7.5.6 - OpenAPI JSON Schema description for the "Competency.Type" Complex Type.
Annotations Measurable or observable knowledge, skills, and abilities necessary to successful performance of a person in a given context. See http://credreg.net/ctdl#Competency
Diagram To be supplied in a later release of this document
Type Hierarchy RecordEntity.Type
^---Competency.Type
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{0..*} ! alternativeLabel{0..1} ! { Namespace Extension }, humanCodingScheme{0..1} ! CFDocumentURI{0..1}
Source
    "Competency.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/RecordEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "humanCodingScheme" : {
                        "description" : "Model Primitive Datatype = String. Human-referenceable code designated by the competency publisher to identify this competency item among others. See IMS CASE #DataAttribute_CFPckgItem_humanCodingScheme",
                        "type" : "string"
                    },
                    "CFDocumentURI" : {
                        "description" : "Model Primitive Datatype = AnyURI. Provides IMS CASE interoperability. If this competency is a CFItem using the CASE standard, this identifier maps to the containing CFDocument.",
                        "type" : "string",
                        "format" : "uri"
                    }
                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.7 "ComprehensiveLearnerRecord.Type" Definition

The OpenAPI JSON Schema description for the "ComprehensiveLearnerRecord.Type" Complex Type is given in Table 7.5.7.

Table 7.5.7 - OpenAPI JSON Schema description for the "ComprehensiveLearnerRecord.Type" Complex Type.
Annotations Collection of Records for a single person declared by a single Issuer.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! createdAt{1..1} ! issuer{0..1} ! overviewUrl{0..1} ! person{0..1} ! records{0..*} ! recordEntities{1..1} ! { Namespace Extension }
Source
    "ComprehensiveLearnerRecord.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                "type" : "string",
                "default" : "ComprehensiveLearnerRecord"
            },
            "createdAt" : {
                "description" : "Model Primitive Datatype = DateTime. Date and time this record was produced",
                "type" : "string",
                "format" : "date-time"
            },
            "issuer" : {
                "$ref" : "#/definitions/Issuer.Type"
            },
            "overviewUrl" : {
                "description" : "Model Primitive Datatype = AnyURI. URL to access the issuer's documentation for the comprehensive learner record. This may include a general description of the record, along with any policies around the issuance and interpretation of the record.",
                "type" : "string",
                "format" : "uri"
            },
            "person" : {
                "$ref" : "#/definitions/Person.Type"
            },
            "records" : {
                "description" : "The Records of this learner record.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Record.Type"
                }
            },
            "recordEntities" : {
                "$ref" : "#/definitions/RecordEntitySet.Type"
            }
        },
        "required" : [ "id","type","createdAt","recordEntities" ],
        "additionalProperties" : true
    },
                        

7.5.8 "Course.Type" Definition

The OpenAPI JSON Schema description for the "Course.Type" Complex Type is given in Table 7.5.8.

Table 7.5.8 - OpenAPI JSON Schema description for the "Course.Type" Complex Type.
Annotations Description of an educational course which may be offered as distinct instances at different times and places, or through different media or modes of study. An educational course is a sequence of one or more educational events and/or creative works which aims to build knowledge, competence or ability of learners. See http://www.credreg.net/ctdl/terms#Course
Diagram To be supplied in a later release of this document
Type Hierarchy RecordEntity.Type
^---Course.Type
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{0..*} ! alternativeLabel{0..1} ! { Namespace Extension }, courseCode{0..1} ! startDate{0..1} ! endDate{0..1}
Source
    "Course.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/RecordEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "courseCode" : {
                        "description" : "Model Primitive Datatype = String. The identifier used for the course, typically in course catalogs and curricula. Example; 'PSY1000'",
                        "type" : "string"
                    },
                    "startDate" : {
                        "description" : "Model Primitive Datatype = DateTime. Date this course starts.",
                        "type" : "string",
                        "format" : "date-time"
                    },
                    "endDate" : {
                        "description" : "Model Primitive Datatype = DateTime. Date this course ends.",
                        "type" : "string",
                        "format" : "date-time"
                    }
                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.9 "Degree.Type" Definition

The OpenAPI JSON Schema description for the "Degree.Type" Complex Type is given in Table 7.5.9.

Table 7.5.9 - OpenAPI JSON Schema description for the "Degree.Type" Complex Type.
Annotations Academic credential conferred upon completion of a program or course of study, typically over multiple years at postsecondary education institutions. See http://www.credreg.net/ctdl/terms#Degree
Diagram To be supplied in a later release of this document
Type Hierarchy RecordEntity.Type
^---Degree.Type
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{0..*} ! alternativeLabel{0..1} ! { Namespace Extension }, programName{0..1} ! programSpecialization{0..1} ! level{0..1} ! areaOfStudy{0..1}
Source
    "Degree.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/RecordEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "programName" : {
                        "description" : "Model Primitive Datatype = String. Name of the program associated with this degree. Examples include, Master of Business Administration, or Bachelor of Science in Nursing.",
                        "type" : "string"
                    },
                    "programSpecialization" : {
                        "description" : "Model Primitive Datatype = String. Name of the specialization or focus of this degree. Examples include Entrepreneurship, General Business Administration, or Finance.",
                        "type" : "string"
                    },
                    "level" : {
                        "description" : "Model Primitive Datatype = String. Academic level associated with this degree. Examples include Master's, Doctoral, or Bachelor's.",
                        "type" : "string"
                    },
                    "areaOfStudy" : {
                        "description" : "Model Primitive Datatype = String. Area of study or category associated with this degree. Examples include Business, Education, Psychology, or Nursing.",
                        "type" : "string"
                    }
                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.10 "Evidence.Type" Definition

The OpenAPI JSON Schema description for the "Evidence.Type" Complex Type is given in Table 7.5.10.

Table 7.5.10 - OpenAPI JSON Schema description for the "Evidence.Type" Complex Type.
Annotations One or more artifacts that represent supporting evidence for the record. Examples include text, media, websites, etc.
Diagram To be supplied in a later release of this document
Model name{1..1} ! url{1..1} ! { Namespace Extension }
Source
    "Evidence.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "name" : {
                "description" : "Model Primitive Datatype = String. Name of the actual evidentice artifact.",
                "type" : "string"
            },
            "url" : {
                "description" : "Model Primitive Datatype = AnyURI. Reference to the actual evidence artifact.",
                "type" : "string",
                "format" : "uri"
            }
        },
        "required" : [ "name","url" ],
        "additionalProperties" : true
    },
                        

7.5.11 "Issuer.Type" Definition

The OpenAPI JSON Schema description for the "Issuer.Type" Complex Type is given in Table 7.5.11.

Table 7.5.11 - OpenAPI JSON Schema description for the "Issuer.Type" Complex Type.
Annotations The issuing organization of this comprehensive learner record
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! name{1..1} ! url{1..1} ! address{0..1} ! phone{0..1} ! logo{0..1} ! issuingPersonFullName{0..1} ! issuingPersonTitle{0..1} ! { Namespace Extension }
Source
    "Issuer.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                "type" : "string",
                "default" : "Issuer"
            },
            "name" : {
                "description" : "Model Primitive Datatype = String. Name of the issuing organization.",
                "type" : "string"
            },
            "url" : {
                "description" : "Model Primitive Datatype = AnyURI. Web resource that provides additional information about the Issuer.",
                "type" : "string",
                "format" : "uri"
            },
            "address" : {
                "description" : "Model Primitive Datatype = String. Mailing address or location for the issuing organization.",
                "type" : "string"
            },
            "phone" : {
                "description" : "Model Primitive Datatype = String. Phone number available for contacting the Issuer.",
                "type" : "string"
            },
            "logo" : {
                "description" : "Model Primitive Datatype = AnyURI. Issuer's logo. This is either a URL to a publicly-available image, or a data URI for embedding an image in the record.",
                "type" : "string",
                "format" : "uri"
            },
            "issuingPersonFullName" : {
                "description" : "Model Primitive Datatype = String. The name of the person who has the authority to issue the Comprehensive Learner Record.",
                "type" : "string"
            },
            "issuingPersonTitle" : {
                "description" : "Model Primitive Datatype = String. The role, title or position of the person who has the authority to issue the comprehensive learner record.",
                "type" : "string"
            }
        },
        "required" : [ "id","type","name","url" ],
        "additionalProperties" : true
    },
                        

7.5.12 "Package.Type" Definition

The OpenAPI JSON Schema description for the "Package.Type" Complex Type is given in Table 7.5.12.

Table 7.5.12 - OpenAPI JSON Schema description for the "Package.Type" Complex Type.
Annotations A Package contains zero or one Comprehensive Learner Records (no record will be returned if the requested record was not found), the ID of the person to whom the record applies, and a status code.
Diagram To be supplied in a later release of this document
Model personID{1..1} ! comprehensiveLearnerRecord{0..1} ! status{1..1}
Source
    "Package.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "personID" : {
                "description" : "Model Primitive Datatype = String. The ID of a person for which an comprehensive learner record is requested.",
                "type" : "string"
            },
            "comprehensiveLearnerRecord" : {
                "$ref" : "#/definitions/ComprehensiveLearnerRecord.Type"
            },
            "status" : {
                "description" : "A status code representing the result of processing the request.",
                "type" : "string",
                "enum" : [ "unsupported","internal_error","not_found","forbidden","server_busy","success" ]
            }
        },
        "required" : [ "personID","status" ],
        "additionalProperties" : false
    },
                        

7.5.13 "PackageSet.Type" Definition

The OpenAPI JSON Schema description for the "PackageSet.Type" Complex Type is given in Table 7.5.13.

Table 7.5.13 - OpenAPI JSON Schema description for the "PackageSet.Type" Complex Type.
Annotations A set of Package objects returned by the Service Provider that correspond to the persons identified via the personIDs parameter.
Diagram To be supplied in a later release of this document
Model results{1..*}
Source
    "PackageSet.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "results" : {
                "description" : "The set of Package objects.",
                "type" : "array",
                "minItems" : 1,
                "items" : {
                    "$ref" : "#/definitions/Package.Type"
                }
            }
        },
        "required" : [ "results" ],
        "additionalProperties" : false
    },
                        

7.5.14 "Person.Type" Definition

The OpenAPI JSON Schema description for the "Person.Type" Complex Type is given in Table 7.5.14.

Table 7.5.14 - OpenAPI JSON Schema description for the "Person.Type" Complex Type.
Annotations Individual who is the subject of the record.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! fullName{1..1} ! givenName{1..1} ! familyName{1..1} ! email{0..1} ! phone{0..1} ! mobile{0..1} ! studentId{0..1} ! birthDate{0..1} ! sourcedId{0..1} ! url{0..1} ! { Namespace Extension }
Source
    "Person.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                "type" : "string",
                "default" : "Person"
            },
            "fullName" : {
                "description" : "Model Primitive Datatype = String. Full name of the person. (Compatible with the LIS definition of Person.Name)",
                "type" : "string"
            },
            "givenName" : {
                "description" : "Model Primitive Datatype = String. Given name (first name) of the person.",
                "type" : "string"
            },
            "familyName" : {
                "description" : "Model Primitive Datatype = String. Family name (last name) of the person.",
                "type" : "string"
            },
            "email" : {
                "description" : "Model Primitive Datatype = String. Primary email address for the individual.",
                "type" : "string"
            },
            "phone" : {
                "description" : "Model Primitive Datatype = String. Primary phone number for the individual.",
                "type" : "string"
            },
            "mobile" : {
                "description" : "Model Primitive Datatype = String. Mobile phone number for the individual, if available. May be the same value as 'phone'.",
                "type" : "string"
            },
            "studentId" : {
                "description" : "Model Primitive Datatype = String. Institution's student identifier for the person. This is frequently issued through a Student Information System.",
                "type" : "string"
            },
            "birthDate" : {
                "description" : "Model Primitive Datatype = Date. Person's date of birth.",
                "type" : "string",
                "format" : "date"
            },
            "sourcedId" : {
                "description" : "Model Primitive Datatype = String. Person's unique 'sourcedId' value, which is used for providing interoperability with Learning Information Services (LIS).",
                "type" : "string"
            },
            "url" : {
                "description" : "Model Primitive Datatype = AnyURI. Web resource that uniquely represents or belongs to the individual. This may be a resource about the individual, hosting provided by the instution to the individual, or an web resource independently controlled by the individual.",
                "type" : "string",
                "format" : "uri"
            }
        },
        "required" : [ "id","type","fullName","givenName","familyName" ],
        "additionalProperties" : true
    },
                        

7.5.15 "Record.Type" Definition

The OpenAPI JSON Schema description for the "Record.Type" Complex Type is given in Table 7.5.15.

Table 7.5.15 - OpenAPI JSON Schema description for the "Record.Type" Complex Type.
Annotations Person's status and relevant metadata regarding a specific record entity, as recognized by the issuer. May include associated results, assertions, and evidence.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! recordOf{1..1} ! date{1..1} ! term{0..1} ! result{0..1} ! credits{0..1} ! points{0..1} ! assertions{0..*} ! status{0..1} ! evidence{0..*} ! { Namespace Extension }
Source
    "Record.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                "type" : "string",
                "default" : "Record"
            },
            "recordOf" : {
                "$ref" : "#/definitions/RecordEntityLink.Type"
            },
            "date" : {
                "description" : "Model Primitive Datatype = DateTime. Date that this achievement, performance, or activity occurred.",
                "type" : "string",
                "format" : "date-time"
            },
            "term" : {
                "description" : "Model Primitive Datatype = String. Academic term in which the achievement, performance, or activity occurred.",
                "type" : "string"
            },
            "result" : {
                "description" : "Model Primitive Datatype = String. Level, grade, or other outcome measurement associated with the record. (E.g., '92%', 'A-', 'Mastered')",
                "type" : "string"
            },
            "credits" : {
                "description" : "Model Primitive Datatype = String. Credit hours earned by the learner that is associated with this record.",
                "type" : "string"
            },
            "points" : {
                "description" : "Model Primitive Datatype = String. Associated points earned by the learner that is associated with this record.",
                "type" : "string"
            },
            "assertions" : {
                "description" : "Model Primitive Datatype = AnyURI. Collection of URLs to Open Badge assertions relevant to this record.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "type" : "string",
                    "format" : "uri"
                }
            },
            "status" : {
                "$ref" : "#/definitions/RecordStatus.Type"
            },
            "evidence" : {
                "description" : "Evidence for the record.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Evidence.Type"
                }
            }
        },
        "required" : [ "id","type","recordOf","date" ],
        "additionalProperties" : true
    },
                        

7.5.16 "RecordEntity.Type" Definition

The OpenAPI JSON Schema description for the "RecordEntity.Type" Complex Type is given in Table 7.5.16.

Table 7.5.16 - OpenAPI JSON Schema description for the "RecordEntity.Type" Complex Type.
Annotations A record entity, such as degree or course, provides context for defining an achievement, performance, or outcome record. Each type of record entity has a set of required and optional fields that provide structure for defining entities of that type.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{0..*} ! alternativeLabel{0..1} ! { Namespace Extension }
Source
    "RecordEntity.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = String. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Type of the associated object",
                "type" : "string",
                "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
            },
            "name" : {
                "description" : "Model Primitive Datatype = String. The name of the entity.",
                "type" : "string"
            },
            "description" : {
                "description" : "Model Primitive Datatype = String. The description of the entity.",
                "type" : "string"
            },
            "defaultCredits" : {
                "description" : "Model Primitive Datatype = String. Credit hours associated with this entity, or credit hours possible, for example '3.0'",
                "type" : "string"
            },
            "defaultPoints" : {
                "description" : "Model Primitive Datatype = String. Points associated with this entity, or points possible. Example; '6.0'.",
                "type" : "string"
            },
            "sourcedId" : {
                "description" : "Model Primitive Datatype = String. Reference to the source identifier of the entity, if sourced from LIS or another system or standard.",
                "type" : "string"
            },
            "associations" : {
                "description" : "Collection of relationships belonging to this record entity.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Association.Type"
                }
            },
            "alternativeLabel" : {
                "description" : "Model Primitive Datatype = String. Alternate 'term' for referring to this type of competency. Some organizations may want to refer to the competency achievements as outcomes, objectives, skills, etc. Semantically they are the same as Competencies, but diversity of terms is used. This allows flexibility for an organization to define their own terms to use instead of 'Competency.' See IMS CASE #DataAttribute_CFPckgItem_alternativeLabel",
                "type" : "string"
            }
        },
        "required" : [ "id","type","name" ],
        "additionalProperties" : true
    },
                        

7.5.17 "RecordEntityLink.Type" Definition

The OpenAPI JSON Schema description for the "RecordEntityLink.Type" Complex Type is given in Table 7.5.17.

Table 7.5.17 - OpenAPI JSON Schema description for the "RecordEntityLink.Type" Complex Type.
Annotations A reference to an entity contained within this record.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! entityType{1..1} ! entityId{1..1} ! { Namespace Extension }
Source
    "RecordEntityLink.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                "type" : "string",
                "default" : "TranscriptEntityLink"
            },
            "entityType" : {
                "description" : "The type of the associated record entity. (E.g., 'Basic', 'Certificate', 'CoCurricular', etc.)",
                "type" : "string",
                "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
            },
            "entityId" : {
                "description" : "Model Primitive Datatype = NormalizedString. The id of the associated record entity.",
                "type" : "string"
            }
        },
        "required" : [ "id","type","entityType","entityId" ],
        "additionalProperties" : true
    },
                        

7.5.18 "RecordEntitySet.Type" Definition

The OpenAPI JSON Schema description for the "RecordEntitySet.Type" Complex Type is given in Table 7.5.18.

Table 7.5.18 - OpenAPI JSON Schema description for the "RecordEntitySet.Type" Complex Type.
Annotations A collection of record entities, partitioned by entity types. Note that all record entities referenced within a CLR must be included in this collection.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! assessments{0..*} ! certificates{0..*} ! coCurriculars{0..*} ! competencies{0..*} ! courses{0..*} ! degrees{0..*} ! basicEntities{0..*} ! { Namespace Extension }
Source
    "RecordEntitySet.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                "type" : "string",
                "default" : "TranscriptEntitySet"
            },
            "assessments" : {
                "description" : "Collection of all assessment record entities.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Assessment.Type"
                }
            },
            "certificates" : {
                "description" : "Collection of all certificate record entities.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Certificate.Type"
                }
            },
            "coCurriculars" : {
                "description" : "Collection of all co-curricular record entities.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/CoCurricular.Type"
                }
            },
            "competencies" : {
                "description" : "Collection of all competency record entities.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Competency.Type"
                }
            },
            "courses" : {
                "description" : "Collection of all course record entities.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Course.Type"
                }
            },
            "degrees" : {
                "description" : "Collection of all degree record entities.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Degree.Type"
                }
            },
            "basicEntities" : {
                "description" : "Collection of all basic record entities.",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Basic.Type"
                }
            }
        },
        "required" : [ "id","type" ],
        "additionalProperties" : true
    },
                        

7.5.19 "RecordStatus.Type" Definition

The OpenAPI JSON Schema description for the "RecordStatus.Type" Complex Type is given in Table 7.5.19.

Table 7.5.19 - OpenAPI JSON Schema description for the "RecordStatus.Type" Complex Type.
Annotations State or condition of the record defined by completed and notes properties.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! completed{0..1} ! notes{0..1} ! { Namespace Extension }
Source
    "RecordStatus.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                "type" : "string",
                "default" : "RecordStatus"
            },
            "completed" : {
                "description" : "Model Primitive Datatype = Boolean. True if this record is fully achieved, otherwise false. If this property is absent, the record is considered completed.",
                "type" : "boolean"
            },
            "notes" : {
                "description" : "Model Primitive Datatype = String. Any explanatory notes about the status of the record.",
                "type" : "string"
            }
        },
        "required" : [ "id","type" ],
        "additionalProperties" : true
    },
                        

7.5.20 "imsx_CodeMinor.Type" Definition

The OpenAPI JSON Schema description for the "imsx_CodeMinor.Type" Complex Type is given in Table 7.5.20.

Table 7.5.20 - OpenAPI JSON Schema description for the "imsx_CodeMinor.Type" Complex Type.
Annotations This is the container for the set of code minor status codes reported in the responses from the Service Provider.
Diagram To be supplied in a later release of this document
Model imsx_codeMinorField{1..*}
Source
    "imsx_CodeMinor.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMinorField" : {
                "description" : "Each reported code minor status code.",
                "type" : "array",
                "minItems" : 1,
                "items" : {
                    "$ref" : "#/definitions/imsx_CodeMinorField.Type"
                }
            }
        },
        "required" : [ "imsx_codeMinorField" ],
        "additionalProperties" : false
    },
                        

7.5.21 "imsx_CodeMinorField.Type" Definition

The OpenAPI JSON Schema description for the "imsx_CodeMinorField.Type" Complex Type is given in Table 7.5.21.

Table 7.5.21 - OpenAPI JSON Schema description for the "imsx_CodeMinorField.Type" Complex Type.
Annotations This is the container for a single code minor status code.
Diagram To be supplied in a later release of this document
Model imsx_codeMinorFieldName{1..1}, imsx_codeMinorFieldValue{1..1}
Source
    "imsx_CodeMinorField.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMinorFieldName" : {
                "description" : "Model Primitive Datatype = NormalizedString. Tiis should contain the identity of the system that has produced the code minor status code report.",
                "type" : "string"
            },
            "imsx_codeMinorFieldValue" : {
                "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                "type" : "string",
                "enum" : [ "server_busy","unauthorisedrequest","internal_server_error","forbidden","targetreadfailure" ]
            }
        },
        "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
        "additionalProperties" : false
    },
                        

7.5.22 "imsx_StatusInfo.Type" Definition

The OpenAPI JSON Schema description for the "imsx_StatusInfo.Type" Complex Type is given in Table 7.5.22.

Table 7.5.22 - OpenAPI JSON Schema description for the "imsx_StatusInfo.Type" Complex Type.
Annotations This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider.
Diagram To be supplied in a later release of this document
Model imsx_codeMajor{1..1}, imsx_severity{1..1}, imsx_description{0..1}, imsx_codeMinor{0..1}
Source
    "imsx_StatusInfo.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "imsx_codeMajor" : {
                "description" : "The code major value (from the corresponding enumerated vocabulary).",
                "type" : "string",
                "enum" : [ "success","failure" ]
            },
            "imsx_severity" : {
                "description" : "The severity value (from the corresponding enumerated vocabulary).",
                "type" : "string",
                "enum" : [ "status","warning","error" ]
            },
            "imsx_description" : {
                "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
                "type" : "string"
            },
            "imsx_codeMinor" : {
                "$ref" : "#/definitions/imsx_CodeMinor.Type"
            }
        },
        "required" : [ "imsx_codeMajor","imsx_severity" ],
        "additionalProperties" : false
    },
                        

toc | top

8. Extending and Profiling the Service

8.1 Extending the Service

Proprietary extensions of the service are based upon two approaches:

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.

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

An example of creating such an extension is given in the accompanying Best Practices document [CLR, 17a].

8.1.2 Proprietary data elements

Extensions to the payload are allowed using the provisions provided for this by JSON-LD. The following restrictions apply regarding payload extensibility:

It is strongly recommended to define extensions in collaboration with IMS Global, and only after communicating with the IMS Comprehensive Learner Record working group.

8.2 Profiling the Service

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

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.

toc | top

Appendix A REST/JSON Modelling Terms

A1 REST Endpoint Description Explanations

A1.1 REST Endpoint Mapping Table Explanation

Table A1.1 provides the key to the descriptions of the mapping between a service calls and its REST endpoint URL-leaf.

Table A1.1 The key to the descriptions of the mapping between a service calls and its REST endpoint URL-leaf.
Category Definition and Usage
Service Call The name of the service call as defined in the associated Behavioral Model.
REST Endpoint The REST endpoint URL leaf that is used to complete the request URL. This value must be appended to the host server (defined by the implementation) and API Root URL and version (defined in the specification).
HTTP Verb The HTTP verb that must be used for the request message. This is enumerated as: GET, PUT, POST and DELETE. The rules of mapping are:
  • GET - request to read the identified resource from the service provider;
  • PUT - request to write the supplied resource on the service provider using the given resource identifier;
  • POST - request to write the supplied resource on the service provider and the service provider must assign the unique identifier;
  • DELETE - request to delete the identified resource.

toc | top

A1.2 Query Parameter Table Explanation

Table A1.2 provides the key to the descriptions of the query parameters that are permitted for an endpoint.

Table A1.2 The key to the descriptions of the data attribute/characteristic tables.
Category Definition and Usage
Parameter Name The name given to the query parameter being described.
Data Type This is the data-type of the parameter. The data-type can take many forms:
  • Enumeration - a list of the permitted values;
  • Primitive Data-types from:-
    • AnyTypeLax - the namespace data-type i.e. defining data from any context (this is used for allowing any form of extension);
    • AnyURI - the AnyURI data-type (absolute or relatve URI);
    • Base - the base data-type for defining a base URI/URL link reference;
    • Boolean - the boolean data-type (with permitted values of "true" and "false");
    • Date - the date data-type (using the [ISO 8601] format);
    • DateTime - the date/time data-type (using the [ISO 8601] format);
    • Decimal - the decimal data-type (a variable precision number that is either positive or negative);
    • Double - the double data-type (double precision floating point number - 64bit);
    • Duration - the duration data-type (using the [ISO 8601] format)
    • Empty - the associated instance must be empty;
    • Float - the float data-type (single precision floating point number - 32bit);
    • ID - the unique identifier data-type;
    • IDREF - the reference to a previously defined unique identifier data-type (ID);
    • IDREFS - a list, whitespace separated, of references to a previously defined unique identifier data-type (ID);
    • Int - the int data-type (this is derived from the "decimal" data-type);
    • Integer - the integer data-type (using the);
    • Language - the language data-type as defined in [RFC 3066];
    • Namespace - the namespace data-type i.e. defining data from a context other than that as the default for the data model (this is used for importing other data models);
    • NamespaceLax - the namespace data-type i.e. defining data from a context other than that as the default for the data model (this is used for importing other data models but being lax on the validation);
    • NonNegativeInteger - the non-negative integer data-type (this is derived from the "integer" data-type) i.e. an integer that is zero or higher;
    • NCName - the NCName data-type (derived from the Name data-type);
    • NormalizedString - the normalized string data type (strings with line feeds, carriage returns and tab characters removed);
    • PositiveInteger - the positive integer data-type (this is derived from the "nonNegativeinteger" data-type) i.e. an integer that is one or higher;
    • String - the normalized string data type;
    • Time - the time data-type (using the [ISO 8601] format).
Value Space The range of valid values for this parameter (including any default value). If the value space is unspecified, it is not known or is not important. This value space must be defined in terms of the associated data-type.
Multiplicity A property of the parameter indicating the number of values that may be assigned to the parameter (this occurs as a comma separated list). The values of this property are expressed as a range or shorthand for a range using the notation:
  • "0..1" [optional; restricted]
  • "0..*" [optional; unrestricted]
  • "1" [mandatory; restricted]
  • "1..*" [mandatory; unrestricted]
Description Contains descriptions relating to the query parameter and its values space.

toc | top

A1.3 HTTP Codes and Handling for each Endpoint Table Explanation

Table A1.3 provides the key to the descriptions of the list of HTTP codes and handling for each endpoint.

Table A1.3 The key to the descriptions of the list of HTTP codes and handling for each endpoint.
Category Definition and Usage
REST Endpoint The REST endpoint URL leaf that is used to complete the request URL. This value must be appended to the host server (defined by the implementation) and API Root URL and version (defined in the specification).
HTTP Verb The HTTP verb that must be used for the request message. This is enumerated as: GET, PUT, POST and DELETE. The rules of mapping are:
  • GET - request to read the identified resource from the service provider;
  • PUT - request to write the supplied resource on the service provider using the given resource identifier;
  • POST - request to write the supplied resource on the service provider and the service provider must assign the unique identifier;
  • DELETE - request to delete the identified resource.
HTTP Codes and Handling The list of HTTP codes that may be returned by the service provider. A description of the cause of the HTTP code is supplied along with a link to the definition of the associated JSON payload structure that contains the detailed status information.

toc | top

A2 OpenAPI Descriptions Explanations

These definitions are with respect to the OpenAPI version 2 specification [OAS, 14].

A2.1 OpenAPI General Information Table Explanation

Table A2.1 provides the key to the OpenAPI general information.

Table A2.1 The key to the tabular description of the OpenAPI general information.
Category Definition and Usage
Swagger Version The version of the OpenAPI/Swagger specification for this OpenAPI description (this must be set as 2.0).
Specification Title The title of the specification being described.
Specification Version The version of the specification being described.
Description A short, human readable description of the specification being described using OpenAPI.
Terms of Service The Terms of Service for the API.
Contact The contact information for the API. For the IMS OpenAPI released files this will be set as "Lisa Mattson (IMS COO)". When used for an implementation this should be changed to the actual contact person.
License The URL for the associated IMS License for the use of this OpenAPI description.
Host The host (name or ip) serving the API. For the IMS OpenAPI released files this will be set as "www.imsglobal.org". When used for an implementation this should be changed to the actual host.
Base Path The base path that MUST be used in the endpoint URLs (this is relative to the host).
Schemes The set of transfer protocols that are supported using this API. This is a comma separated list.
Consumes A list of MIME types the APIs can consume. This is a comma separated list.
Produces A list of MIME types the APIs can produce. This is a comma separated list.

toc | top

A2.2 OpenAPI Tags Table Explanation

Table A2.2 provides the key to the tabular description of the OpenAPI tags information.

Table A2.2 The key to the tabular description of the OpenAPI tags information.
Category Definition and Usage
Tag Name The title of the tag (this must be unique). The tags are derived from the set of Interfaces defined in the Behavioral Model.
Description A human readable description of the tag. This is the comment associated with the Interface in the Behavioral Model. The list of associated endpoints assigned to this tag are listed with links to the OpenAPI description of those endpoints.

toc | top

A2.3 OpenAPI Security Table Explanation

Table A2.3 provides the key to the tabular description of the OpenAPI security information.

Table A2.3 The key to the tabular description of the OpenAPI security information.
Category Definition and Usage
Security Label The label by which this mode is identified within the OpenAPI file.
Type The security mode supported. The permitted values are:
  • "basic" - use of basic authentication
  • "apikey" - use of an API key (in the header or as a query parameter)
  • "oauth2" - use of OAuth 2.0
Description A human readable description of the usage of this security scheme.
Flow The flow used by the OAuth2 security scheme. The permitted values are:
  • "implicit" - implicit grant type is used to obtain access tokens (see [RFC 6749] sub-section 4.2)
  • "password" - resource owner password credentials grant type (see [RFC 6749] sub-section 4.3)
  • "application" - client credentials grant type (see [RFC 6749] sub-section 4.4)
  • "accessCode" - authorization code grant type (see [RFC 6749] sub-section 4.1)
Token URL The token URL to be used for this flow. A value must be supplied for the "password", "application" and "accessMode" flows in OAuth 2
Scopes The set of labels by which the global scope will be identified.
Global Scope The default identification of the security mode to be applied to an endpoint.

toc | top

A2.4 OpenAPI Paths Table Explanation

Table A2.4 provides the key to the OpenAPI paths information for an HTTP Verb.

Table A2.4 The key to the tabular description of the OpenAPI paths information for an HTTP Verb.
Category Definition and Usage
Operation ID A unique identifier for the service operation. This is the name of the operation defined in the Behavioral Model.
Summary A human readable summary of the objective of the service operation.
Tags The tag which has been assigned to this operation. The tag is determined by the Interface under which the operation is defined in the Behavioral Model.
Description A human readable summary of the objective of the service operation. This is derived from the associated description of the operation supplied in the Behavioral Model.
Path Placeolders The set of placeholders, and their meaning, in the URL path that will be replaced by the appopriate values in the request calls.
Query Parameters The set of query parameters that are permitted on the request calls. For each query parameter the following information is supplied:
  • Name - the name of the parameter;
  • Type - the data type for the parameter;
  • Multiplicity - the permitted multiplicity of the parameter. This takes the form of:-
    • "0..1" [optional; restricted]
    • "0..*" [optional; unrestricted] - this will normally be achieved as a comma separated list
    • "1" [mandatory; restricted]
    • "1..*" [mandatory; unrestricted] - this will normally be achieved as a comma separated list
  • Default - the default value for the parameter.
Responses The set of query responses that are permitted for the request. For each response the following information is supplied:
  • Name - the name of the response (this is either a valid HTTP code or the value "default");
  • Type - the data type for the response paylaod (this is linked to the corresponding OpenAPI definition). If there is no payload then this will be denoted by "N/A";
  • Description - the description of the response including any specific status code values.

toc | top

A2.5 OpenAPI Definitions Table Explanation

Table A2.5 provides the key to the OpenAPI definitions information.

Table A2.5 The key to the tabular description of the OpenAPI definitions information.
Category Definition and Usage
Annotations The definition of the complex-type as supplied in the data model definition for the associated class.
Diagram A visual representation of the definition of the complex-type. These diagrams will be supplied in later versions of the specficiation.
Type Hierachy The identification of the superclass upon which this type is based (the superclass is shown on the top line). This indicates the source of the inherited set of JSON properties (this line is only displayed when there is a type hierarchy).
Model The set of child properties. This is an ordered list of properties (as per the implied or actual sequence in the object) and accompanied by their multiplicity. In the case where the type is an enumeration or primitiveType then the value is "N/A". The value may also be "Empty" to indicate that no children are permitted. In some situations the value may be "None" denoting that there are no children defined e.g. for a base class from which other classes are derived and which may have children as part of the extension.
Source The equivalent JSON Schema (OpenAPI dialect) code for the declaration of the complex-type. This is the full declaration. See the coresponding OpenAPI documentation [OAS, 14] for the description of the permitted contents for this declaration.

toc | top

Appendix B OpenAPI Listings

B1 Comprehensive Learner Record Service OpenAPI JSON Definition Listing

The OpenAPI (JSON) listing is shown below (the OpenAPI JSON is available at: http://www.imsglobal.org/openapi/et/etv1p0/imsetv1p0_openapiv1p0.json).

{
    "swagger" : "2.0",
    "info" : {
        "version" : "1.0",
        "title" : "Comprehensive Learner Record Service OpenAPI (JSON) Definition",
        "description" : "The Comprehensive Learner Record Service enables the exchange of data about users and their achievements between a Comprehensive Learner Record Service Provider and the consumers of the associated data. This service has been described using the IMS Model Driven Specification development approach, this being the Platform Specific Model (PSM) of the service.",
        "termsOfService" : "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 API DEFINITION 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 IMPLEMENTERS 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 API DEFINITION.",
        "contact" : {
            "name" : "Lisa Mattson (COO), IMS Global ",
            "url" : "http://www.imsglobal.org",
            "email" : "lmattson@imsglobal.org"
        },
        "license" : {
            "name" : "IMS Global",
            "url" : "https://www.imsglobal.org/license.html"
        }
    },
    "host" : "www.imsglobal.org",
    "basePath" : "/ims/clr/v1p0",
    "schemes" : [ "http","https" ],
    "tags" : [
        {
            "name" : "PackagesManager",
            "description" : "The set of service operations that manage access to the Comprehensive Learner Record Packages as a whole. The set of endpoints assigned to this tag are:"
        }
    ],
    "securityDefinitions" : {
        "OAuth2Security" : {
            "type" : "oauth2",
            "description" : "The standard usage of OAuth 2.0 by IMS Global",
            "flow" : "application",
            "tokenUrl" : "http://www.imsglobal.org",
            "scopes" : {
                "user" : "All Endpoints"
            }
        }
    },
    "security" : [
        { "OAuth2Security" : [ "user" ] }
    ],
    "paths" : {
        "clr" : {
            "get" : {
                "operationId" : "getCLRs",
                "summary" : "The REST read request message for the getCLRs() API call.",
                "tags" : [ "PackagesManager" ],
                "description" : "This is a request to the Service Provider to provide a set of Comprehensive Learner Records that corresponds to the IDs given in the personIDs parameter. For each requested record that can not be found the 'unknownobject' status code must be reported.",
                "parameters" : [
                    {
                        "name" : "personIDs",
                        "in" : "query",
                        "description" : "Array of IDs for users for which an comprehensive learner record is requested. The ampersand character is used as the separator character for array entries where each entry is a key and value pair, i.e.?personIDs=123&personIDs=456.",
                        "required" : true,
                        "type" : "array",
                        "items" : {
                            "type" : "string"
                        },
                        "collectionFormat" : "csv",
                        "allowEmptyValue" : false
                    }
                ],
                "responses" : {
                    "200" : {
                        "description" : "This is the response when the request has been completed successfully. Records for all of the specified comprehensive learner records were returned.",
                        "schema" : {
                            "$ref" : "#/definitions/PackageSet.Type"
                        }
                    },
                    "default" : {
                        "description" : "...tbd (Response description)...",
                        "schema" : {
                            "$ref" : "#/definitions/PackageSet.Type"
                        }
                    },
                    "400" : {
                        "description" : "Partial success of the request. At least one of the requested comprehensive learner records could not be supplied. This is accompanied by the 'codeMajor/severity' values of 'failure/error'",
                        "schema" : {
                            "$ref" : "#/definitions/PackageSet.Type"
                        }
                    },
                    "401" : {
                        "description" : "The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. ",
                        "schema" : {
                            "$ref" : "#/definitions/PackageSet.Type"
                        }
                    },
                    "403" : {
                        "description" : "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'. ",
                        "schema" : {
                            "$ref" : "#/definitions/PackageSet.Type"
                        }
                    },
                    "429" : {
                        "description" : "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'. ",
                        "schema" : {
                            "$ref" : "#/definitions/PackageSet.Type"
                        }
                    },
                    "500" : {
                        "description" : "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'.",
                        "schema" : {
                            "$ref" : "#/definitions/PackageSet.Type"
                        }
                    }
                }
            }
        }
    },
    "definitions" : {
        "Assessment.Type" : {
            "description" : "Assessment of work or performance",
            "type" : "object",
            "allOf" : [
                {
                    "$ref" : "#/definitions/RecordEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "assessmentMethod" : {
                            "description" : "Model Primitive Datatype = String. An enumeration of assessment methods. See http://www.credreg.net/ctdl/terms#AssessmentMethod.",
                            "type" : "string"
                        },
                        "scoringMethod" : {
                            "description" : "Model Primitive Datatype = String. An enumeration of types of applicable scoring. See http://www.credreg.net/ctdl/terms#ScoringMethod.",
                            "type" : "string"
                        },
                        "hasGroupParticipation" : {
                            "description" : "Model Primitive Datatype = Boolean. True or False that completing the assessment activity being referenced requires two or more participants. See https://www.imsglobal.org/ims-badge-extensions-education",
                            "type" : "boolean"
                        },
                        "assessor" : {
                            "description" : "Model Primitive Datatype = String. Organization, person, or role that assessed the work",
                            "type" : "string"
                        },
                        "assessmentEvaluation" : {
                            "description" : "Model Primitive Datatype = String. Link to studies or other information about research or calculations of reliability and validity for the assessment or the scoring methods. See https://www.imsglobal.org/ims-badge-extensions-education",
                            "type" : "string"
                        },
                        "assessmentOutput" : {
                            "description" : "Model Primitive Datatype = String. Additional details about assessment type. Values for assessmentOutput are expected to be words or phrases that describe the key features of the evidence produced. See https://www.imsglobal.org/ims-badge-extensions-education",
                            "type" : "string"
                        }
                    },
                    "additionalProperties" : false
                }
            ]
        },
        "Association.Type" : {
            "description" : "Establish a relationship between two record entities contained within this record. ",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                    "type" : "string",
                    "default" : "Relationship"
                },
                "associationType" : {
                    "description" : "The type of relationship. ('isParentOf', 'isChildOf', etc.)",
                    "type" : "string",
                    "enum" : [ "exactMatchOf","precedes","isChildOf","isParentOf","hasSkillLevel","replacedBy","isPartOf","exemplar","isRelatedTo","isPeerOf" ]
                },
                "entityType" : {
                    "description" : "The type of the associated record entity. (E.g., 'Basic', 'Certificate', 'CoCurricular', etc.)",
                    "type" : "string",
                    "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
                },
                "entityId" : {
                    "description" : "Model Primitive Datatype = String. The id of the associated record entity.",
                    "type" : "string"
                }
            },
            "required" : [ "id","type","associationType","entityType","entityId" ],
            "additionalProperties" : true
        },
        "Basic.Type" : {
            "description" : "Provides support for representing record entities that are not semantically compatible with other record entity classes.",
            "type" : "object",
            "allOf" : [
                {
                    "$ref" : "#/definitions/RecordEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {

                    },
                    "additionalProperties" : false
                }
            ]
        },
        "Certificate.Type" : {
            "description" : "A credential that designates requisite mastery of the knowledge and skills of an occupation, profession, or academic program. See http://www.credreg.net/ctdl/terms#Certificate",
            "type" : "object",
            "allOf" : [
                {
                    "$ref" : "#/definitions/RecordEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "level" : {
                            "description" : "Model Primitive Datatype = String. Relative position of the certificate in relation to others.  Examples include Undergraduate, Master's, Associate, etc.",
                            "type" : "string"
                        },
                        "areaOfStudy" : {
                            "description" : "Model Primitive Datatype = String. Area of study or category associated with this certificate. Examples include Infomatics, Accounting, Human Resources Management.",
                            "type" : "string"
                        }
                    },
                    "additionalProperties" : false
                }
            ]
        },
        "CoCurricular.Type" : {
            "description" : "Activities, achievements, or learning attained in addition to the offical academic curriculum or study, though still asserted by the Issuer.  Generally outside of the classroom or course setting.  Examples include student government, sports, music, art, debate, photography and others.  ",
            "type" : "object",
            "allOf" : [
                {
                    "$ref" : "#/definitions/RecordEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "category" : {
                            "description" : "Model Primitive Datatype = String. Area of cocurricular activity, as defined by the Issuer. Examples include sports, community service, student government, arts, etc.",
                            "type" : "string"
                        },
                        "scoringMethod" : {
                            "description" : "Model Primitive Datatype = String. An enumeration of types of applicable scoring. See http://www.credreg.net/ctdl/terms#ScoringMethod.",
                            "type" : "string"
                        },
                        "role" : {
                            "description" : "Model Primitive Datatype = String. Role, position, or title of the Person in the cocurricular activity, achievement, or learning experience.  Examples include Student President, Intern, Captain, etc.",
                            "type" : "string"
                        },
                        "startDate" : {
                            "description" : "Model Primitive Datatype = DateTime. Starting date of the Person’s involvement in the cocurricular activity.",
                            "type" : "string",
                            "format" : "date-time"
                        },
                        "endDate" : {
                            "description" : "Model Primitive Datatype = DateTime. Ending date of the Person’s involvement in the cocurricular activity.",
                            "type" : "string",
                            "format" : "date-time"
                        }
                    },
                    "additionalProperties" : false
                }
            ]
        },
        "Competency.Type" : {
            "description" : "Measurable or observable knowledge, skills, and abilities necessary to successful performance of a person in a given context. See http://credreg.net/ctdl#Competency",
            "type" : "object",
            "allOf" : [
                {
                    "$ref" : "#/definitions/RecordEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "humanCodingScheme" : {
                            "description" : "Model Primitive Datatype = String. Human-referenceable code designated by the competency publisher to identify this competency item among others. See IMS CASE #DataAttribute_CFPckgItem_humanCodingScheme",
                            "type" : "string"
                        },
                        "CFDocumentURI" : {
                            "description" : "Model Primitive Datatype = AnyURI. Provides IMS CASE interoperability. If this competency is a CFItem using the CASE standard, this identifier maps to the containing CFDocument.",
                            "type" : "string",
                            "format" : "uri"
                        }
                    },
                    "additionalProperties" : false
                }
            ]
        },
        "ComprehensiveLearnerRecord.Type" : {
            "description" : "Collection of Records for a single person declared by a single Issuer.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                    "type" : "string",
                    "default" : "ComprehensiveLearnerRecord"
                },
                "createdAt" : {
                    "description" : "Model Primitive Datatype = DateTime. Date and time this record was produced",
                    "type" : "string",
                    "format" : "date-time"
                },
                "issuer" : {
                    "$ref" : "#/definitions/Issuer.Type"
                },
                "overviewUrl" : {
                    "description" : "Model Primitive Datatype = AnyURI. URL to access the issuer's documentation for the comprehensive learner record. This may include a general description of the record, along with any policies around the issuance and interpretation of the record.",
                    "type" : "string",
                    "format" : "uri"
                },
                "person" : {
                    "$ref" : "#/definitions/Person.Type"
                },
                "records" : {
                    "description" : "The Records of this learner record.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Record.Type"
                    }
                },
                "recordEntities" : {
                    "$ref" : "#/definitions/RecordEntitySet.Type"
                }
            },
            "required" : [ "id","type","createdAt","recordEntities" ],
            "additionalProperties" : true
        },
        "Course.Type" : {
            "description" : "Description of an educational course which may be offered as distinct instances at different times and places, or through different media or modes of study. An educational course is a sequence of one or more educational events and/or creative works which aims to build knowledge, competence or ability of learners. See http://www.credreg.net/ctdl/terms#Course",
            "type" : "object",
            "allOf" : [
                {
                    "$ref" : "#/definitions/RecordEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "courseCode" : {
                            "description" : "Model Primitive Datatype = String. The identifier used for the course, typically in course catalogs and curricula. Example; 'PSY1000'",
                            "type" : "string"
                        },
                        "startDate" : {
                            "description" : "Model Primitive Datatype = DateTime. Date this course starts.",
                            "type" : "string",
                            "format" : "date-time"
                        },
                        "endDate" : {
                            "description" : "Model Primitive Datatype = DateTime. Date this course ends.",
                            "type" : "string",
                            "format" : "date-time"
                        }
                    },
                    "additionalProperties" : false
                }
            ]
        },
        "Degree.Type" : {
            "description" : "Academic credential conferred upon completion of a program or course of study, typically over multiple years at postsecondary education institutions. See http://www.credreg.net/ctdl/terms#Degree",
            "type" : "object",
            "allOf" : [
                {
                    "$ref" : "#/definitions/RecordEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "programName" : {
                            "description" : "Model Primitive Datatype = String. Name of the program associated with this degree. Examples include, Master of Business Administration, or Bachelor of Science in Nursing.",
                            "type" : "string"
                        },
                        "programSpecialization" : {
                            "description" : "Model Primitive Datatype = String. Name of the specialization or focus of this degree. Examples include Entrepreneurship, General Business Administration, or Finance.",
                            "type" : "string"
                        },
                        "level" : {
                            "description" : "Model Primitive Datatype = String. Academic level associated with this degree. Examples include Master's, Doctoral, or Bachelor's.",
                            "type" : "string"
                        },
                        "areaOfStudy" : {
                            "description" : "Model Primitive Datatype = String. Area of study or category associated with this degree. Examples include Business, Education, Psychology, or Nursing.",
                            "type" : "string"
                        }
                    },
                    "additionalProperties" : false
                }
            ]
        },
        "Evidence.Type" : {
            "description" : "One or more artifacts that represent supporting evidence for the record. Examples include text, media, websites, etc.",
            "type" : "object",
            "properties" : {
                "name" : {
                    "description" : "Model Primitive Datatype = String. Name of the actual evidentice artifact.",
                    "type" : "string"
                },
                "url" : {
                    "description" : "Model Primitive Datatype = AnyURI. Reference to the actual evidence artifact.",
                    "type" : "string",
                    "format" : "uri"
                }
            },
            "required" : [ "name","url" ],
            "additionalProperties" : true
        },
        "Issuer.Type" : {
            "description" : "The issuing organization of this comprehensive learner record",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                    "type" : "string",
                    "default" : "Issuer"
                },
                "name" : {
                    "description" : "Model Primitive Datatype = String. Name of the issuing organization.",
                    "type" : "string"
                },
                "url" : {
                    "description" : "Model Primitive Datatype = AnyURI. Web resource that provides additional information about the Issuer.",
                    "type" : "string",
                    "format" : "uri"
                },
                "address" : {
                    "description" : "Model Primitive Datatype = String. Mailing address or location for the issuing organization.",
                    "type" : "string"
                },
                "phone" : {
                    "description" : "Model Primitive Datatype = String. Phone number available for contacting the Issuer.",
                    "type" : "string"
                },
                "logo" : {
                    "description" : "Model Primitive Datatype = AnyURI. Issuer's logo. This is either a URL to a publicly-available image, or a data URI for embedding an image in the record.",
                    "type" : "string",
                    "format" : "uri"
                },
                "issuingPersonFullName" : {
                    "description" : "Model Primitive Datatype = String. The name of the person who has the authority to issue the Comprehensive Learner Record.",
                    "type" : "string"
                },
                "issuingPersonTitle" : {
                    "description" : "Model Primitive Datatype = String. The role, title or position of the person who has the authority to issue the comprehensive learner record.",
                    "type" : "string"
                }
            },
            "required" : [ "id","type","name","url" ],
            "additionalProperties" : true
        },
        "Package.Type" : {
            "description" : "A Package contains zero or one Comprehensive Learner Records (no record will be returned if the requested record was not found), the ID of the person to whom the record applies, and a status code.",
            "type" : "object",
            "properties" : {
                "personID" : {
                    "description" : "Model Primitive Datatype = String. The ID of a person for which an comprehensive learner record is requested.",
                    "type" : "string"
                },
                "comprehensiveLearnerRecord" : {
                    "$ref" : "#/definitions/ComprehensiveLearnerRecord.Type"
                },
                "status" : {
                    "description" : "A status code representing the result of processing the request.",
                    "type" : "string",
                    "enum" : [ "unsupported","internal_error","not_found","forbidden","server_busy","success" ]
                }
            },
            "required" : [ "personID","status" ],
            "additionalProperties" : false
        },
        "PackageSet.Type" : {
            "description" : "A set of Package objects returned by the Service Provider that correspond to the persons identified via the personIDs parameter.",
            "type" : "object",
            "properties" : {
                "results" : {
                    "description" : "The set of Package objects.",
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/Package.Type"
                    }
                }
            },
            "required" : [ "results" ],
            "additionalProperties" : false
        },
        "Person.Type" : {
            "description" : "Individual who is the subject of the record.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                    "type" : "string",
                    "default" : "Person"
                },
                "fullName" : {
                    "description" : "Model Primitive Datatype = String. Full name of the person. (Compatible with the LIS definition of Person.Name)",
                    "type" : "string"
                },
                "givenName" : {
                    "description" : "Model Primitive Datatype = String. Given name (first name) of the person.",
                    "type" : "string"
                },
                "familyName" : {
                    "description" : "Model Primitive Datatype = String. Family name (last name) of the person.",
                    "type" : "string"
                },
                "email" : {
                    "description" : "Model Primitive Datatype = String. Primary email address for the individual.",
                    "type" : "string"
                },
                "phone" : {
                    "description" : "Model Primitive Datatype = String. Primary phone number for the individual.",
                    "type" : "string"
                },
                "mobile" : {
                    "description" : "Model Primitive Datatype = String. Mobile phone number for the individual, if available. May be the same value as 'phone'.",
                    "type" : "string"
                },
                "studentId" : {
                    "description" : "Model Primitive Datatype = String. Institution's student identifier for the person. This is frequently issued through a Student Information System.",
                    "type" : "string"
                },
                "birthDate" : {
                    "description" : "Model Primitive Datatype = Date. Person's date of birth.",
                    "type" : "string",
                    "format" : "date"
                },
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String. Person's unique 'sourcedId' value, which is used for providing interoperability with Learning Information Services (LIS).",
                    "type" : "string"
                },
                "url" : {
                    "description" : "Model Primitive Datatype = AnyURI. Web resource that uniquely represents or belongs to the individual. This may be a resource about the individual, hosting provided by the instution to the individual, or an web resource independently controlled by the individual.",
                    "type" : "string",
                    "format" : "uri"
                }
            },
            "required" : [ "id","type","fullName","givenName","familyName" ],
            "additionalProperties" : true
        },
        "Record.Type" : {
            "description" : "Person's status and relevant metadata regarding a specific record entity, as recognized by the issuer. May include associated results, assertions, and evidence.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                    "type" : "string",
                    "default" : "Record"
                },
                "recordOf" : {
                    "$ref" : "#/definitions/RecordEntityLink.Type"
                },
                "date" : {
                    "description" : "Model Primitive Datatype = DateTime. Date that this achievement, performance, or activity occurred.",
                    "type" : "string",
                    "format" : "date-time"
                },
                "term" : {
                    "description" : "Model Primitive Datatype = String. Academic term in which the achievement, performance, or activity occurred.",
                    "type" : "string"
                },
                "result" : {
                    "description" : "Model Primitive Datatype = String. Level, grade, or other outcome measurement associated with the record. (E.g., '92%', 'A-', 'Mastered')",
                    "type" : "string"
                },
                "credits" : {
                    "description" : "Model Primitive Datatype = String. Credit hours earned by the learner that is associated with this record.",
                    "type" : "string"
                },
                "points" : {
                    "description" : "Model Primitive Datatype = String. Associated points earned by the learner that is associated with this record.",
                    "type" : "string"
                },
                "assertions" : {
                    "description" : "Model Primitive Datatype = AnyURI. Collection of URLs to Open Badge assertions relevant to this record.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "type" : "string",
                        "format" : "uri"
                    }
                },
                "status" : {
                    "$ref" : "#/definitions/RecordStatus.Type"
                },
                "evidence" : {
                    "description" : "Evidence for the record.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Evidence.Type"
                    }
                }
            },
            "required" : [ "id","type","recordOf","date" ],
            "additionalProperties" : true
        },
        "RecordEntity.Type" : {
            "description" : "A record entity, such as degree or course, provides context for defining an achievement, performance, or outcome record.  Each type of record entity has a set of required and optional fields that provide structure for defining entities of that type.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = String. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Type of the associated object",
                    "type" : "string",
                    "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
                },
                "name" : {
                    "description" : "Model Primitive Datatype = String. The name of the entity.",
                    "type" : "string"
                },
                "description" : {
                    "description" : "Model Primitive Datatype = String. The description of the entity.",
                    "type" : "string"
                },
                "defaultCredits" : {
                    "description" : "Model Primitive Datatype = String. Credit hours associated with this entity, or credit hours possible, for example '3.0'",
                    "type" : "string"
                },
                "defaultPoints" : {
                    "description" : "Model Primitive Datatype = String. Points associated with this entity, or points possible. Example; '6.0'.",
                    "type" : "string"
                },
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String. Reference to the source identifier of the entity, if sourced from LIS or another system or standard.",
                    "type" : "string"
                },
                "associations" : {
                    "description" : "Collection of relationships belonging to this record entity.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Association.Type"
                    }
                },
                "alternativeLabel" : {
                    "description" : "Model Primitive Datatype = String. Alternate 'term' for referring to this type of competency. Some organizations may want to refer to the competency achievements as outcomes, objectives, skills, etc. Semantically they are the same as Competencies, but diversity of terms is used. This allows flexibility for an organization to define their own terms to use instead of 'Competency.' See IMS CASE #DataAttribute_CFPckgItem_alternativeLabel",
                    "type" : "string"
                }
            },
            "required" : [ "id","type","name" ],
            "additionalProperties" : true
        },
        "RecordEntityLink.Type" : {
            "description" : "A reference to an entity contained within this record.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                    "type" : "string",
                    "default" : "TranscriptEntityLink"
                },
                "entityType" : {
                    "description" : "The type of the associated record entity. (E.g., 'Basic', 'Certificate', 'CoCurricular', etc.)",
                    "type" : "string",
                    "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
                },
                "entityId" : {
                    "description" : "Model Primitive Datatype = NormalizedString. The id of the associated record entity.",
                    "type" : "string"
                }
            },
            "required" : [ "id","type","entityType","entityId" ],
            "additionalProperties" : true
        },
        "RecordEntitySet.Type" : {
            "description" : "A collection of record entities, partitioned by entity types. Note that all record entities referenced within a CLR must be included in this collection.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                    "type" : "string",
                    "default" : "TranscriptEntitySet"
                },
                "assessments" : {
                    "description" : "Collection of all assessment record entities.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Assessment.Type"
                    }
                },
                "certificates" : {
                    "description" : "Collection of all certificate record entities.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Certificate.Type"
                    }
                },
                "coCurriculars" : {
                    "description" : "Collection of all co-curricular record entities.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/CoCurricular.Type"
                    }
                },
                "competencies" : {
                    "description" : "Collection of all competency record entities.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Competency.Type"
                    }
                },
                "courses" : {
                    "description" : "Collection of all course record entities.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Course.Type"
                    }
                },
                "degrees" : {
                    "description" : "Collection of all degree record entities.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Degree.Type"
                    }
                },
                "basicEntities" : {
                    "description" : "Collection of all basic record entities.",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Basic.Type"
                    }
                }
            },
            "required" : [ "id","type" ],
            "additionalProperties" : true
        },
        "RecordStatus.Type" : {
            "description" : "State or condition of the record defined by completed and notes properties.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Unique identifier for the associated object",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Type of the associated object",
                    "type" : "string",
                    "default" : "RecordStatus"
                },
                "completed" : {
                    "description" : "Model Primitive Datatype = Boolean. True if this record is fully achieved, otherwise false. If this property is absent, the record is considered completed.",
                    "type" : "boolean"
                },
                "notes" : {
                    "description" : "Model Primitive Datatype = String. Any explanatory notes about the status of the record.",
                    "type" : "string"
                }
            },
            "required" : [ "id","type" ],
            "additionalProperties" : true
        },
        "imsx_CodeMinor.Type" : {
            "description" : "This is the container for the set of code minor status codes reported in the responses from the Service Provider.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorField" : {
                    "description" : "Each reported code minor status code.",
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/imsx_CodeMinorField.Type"
                    }
                }
            },
            "required" : [ "imsx_codeMinorField" ],
            "additionalProperties" : false
        },
        "imsx_CodeMinorField.Type" : {
            "description" : "This is the container for a single code minor status code.",
            "type" : "object",
            "properties" : {
                "imsx_codeMinorFieldName" : {
                    "description" : "Model Primitive Datatype = NormalizedString. Tiis should contain the identity of the system that has produced the code minor status code report.",
                    "type" : "string"
                },
                "imsx_codeMinorFieldValue" : {
                    "description" : "The code minor status code (this is a value from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "server_busy","unauthorisedrequest","internal_server_error","forbidden","targetreadfailure" ]
                }
            },
            "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
            "additionalProperties" : false
        },
        "imsx_StatusInfo.Type" : {
            "description" : "This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider.",
            "type" : "object",
            "properties" : {
                "imsx_codeMajor" : {
                    "description" : "The code major value (from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "success","failure" ]
                },
                "imsx_severity" : {
                    "description" : "The severity value (from the corresponding enumerated vocabulary).",
                    "type" : "string",
                    "enum" : [ "status","warning","error" ]
                },
                "imsx_description" : {
                    "description" : "Model Primitive Datatype = String. A human readable description supplied by the entity creating the status code information.",
                    "type" : "string"
                },
                "imsx_codeMinor" : {
                    "$ref" : "#/definitions/imsx_CodeMinor.Type"
                }
            },
            "required" : [ "imsx_codeMajor","imsx_severity" ],
            "additionalProperties" : false
        }
    },
    "consumes" : [ "application/json" ],
    "produces" : [ "application/json" ]
}
        

B2 Comprehensive Learner Record Service OpenAPI YAML Definition Listing

The OpenAPI (YAML) listing is shown below (the OpenAPI YAML is available at: http://www.imsglobal.org/openapi/et/etv1p0/imsetv1p0_openapiv1p0.yaml).

swagger: '2.0'

#####################################################################################
#                               API Information                                     #
#####################################################################################
info: 
    version: '1.0'
    title: Comprehensive Learner Record Service OpenAPI (YAML) Definition
    description: The Comprehensive Learner Record Service enables the exchange of data about users and their achievements between a Comprehensive Learner Record Service Provider and the consumers of the associated data. This service has been described using the IMS Model Driven Specification development approach, this being the Platform Specific Model (PSM) of the service.
    termsOfService: 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 API DEFINITION 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 IMPLEMENTERS 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 API DEFINITION.
    contact: 
        name: Lisa Mattson (COO), IMS Global
        url: http://www.imsglobal.org
        email: lmattson@imsglobal.org
    license: 
        name: IMS Global
        url: https://www.imsglobal.org/license.html

#####################################################################################
#                   Host, Base Path, Schemes and Content Types                      #
#####################################################################################
host: www.imsglobal.org
basePath: /ims/clr/v1p0
schemes: 
    - http
    - https
consumes: 
    - application/json
produces: 
    - application/json

#####################################################################################
#                                  Tags                                             #
#####################################################################################
tags: 
    - name: PackagesManager
      description: |
        The set of service operations that manage access to the Comprehensive Learner Record Packages as a whole. The set of endpoints assigned to this tag are:

#####################################################################################
#                                 Security                                          #
#####################################################################################
securityDefinitions:
    OAuth2Security:
        type: oauth2
        description: The standard usage of OAuth 2.0 by IMS Global.
        flow: application
        tokenUrl: http://www.imsglobal.org
        scopes: 
            user: All Endpoints

security:
    - OAuth2Security:
        - user

#####################################################################################
#                                   Paths                                           #
#####################################################################################
paths: 
    clr:
        get:
            operationId: getCLRs
            summary: The REST read request message for the getCLRs() API call.
            tags: 
                - PackagesManager
            description: |
                This is a request to the Service Provider to provide a set of Comprehensive Learner Records that corresponds to the IDs given in the personIDs parameter. For each requested record that can not be found the 'unknownobject' status code must be reported.
            parameters: 
                - name: personIDs
                  in: query
                  description: |
                      Array of IDs for users for which an comprehensive learner record is requested. The ampersand character is used as the separator character for array entries where each entry is a key and value pair, i.e.?personIDs=123&personIDs=456.
                  required: true
                  type: array
                  items: 
                      type: string
                  collectionFormat: csv
                  allowEmptyValue: false
            responses: 
                "200" : 
                    description: |
                        This is the response when the request has been completed successfully. Records for all of the specified comprehensive learner records were returned.
                    schema: 
                        $ref: "#/definitions/PackageSet.Type"
                "default" : 
                    description: |
                        ...tbd (Response description)...
                    schema: 
                        $ref: "#/definitions/PackageSet.Type"
                "400" : 
                    description: |
                        Partial success of the request. At least one of the requested comprehensive learner records could not be supplied. This is accompanied by the 'codeMajor/severity' values of 'failure/error'
                    schema: 
                        $ref: "#/definitions/PackageSet.Type"
                "401" : 
                    description: |
                        The request was not correctly authorised i.e. 'unauthorisedrequest'. This would be accompanied by the 'codeMajor/severity' values of 'failure/error'. 
                    schema: 
                        $ref: "#/definitions/PackageSet.Type"
                "403" : 
                    description: |
                        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'. 
                    schema: 
                        $ref: "#/definitions/PackageSet.Type"
                "429" : 
                    description: |
                        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'. 
                    schema: 
                        $ref: "#/definitions/PackageSet.Type"
                "500" : 
                    description: |
                        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'.
                    schema: 
                        $ref: "#/definitions/PackageSet.Type"


#####################################################################################
#                               Definitions                                         #
#####################################################################################
definitions: 
    Assessment.Type:
        description: |
            Assessment of work or performance
        type: object
        allOf: 
            - $ref: "#/definitions/RecordEntity.Type"
            - type: object
              properties: 
                assessmentMethod: 
                    description: An enumeration of assessment methods. See http://www.credreg.net/ctdl/terms#AssessmentMethod. Model Primitive Datatype = String.
                    type: string
                scoringMethod: 
                    description: An enumeration of types of applicable scoring. See http://www.credreg.net/ctdl/terms#ScoringMethod. Model Primitive Datatype = String.
                    type: string
                hasGroupParticipation: 
                    description: True or False that completing the assessment activity being referenced requires two or more participants. See https://www.imsglobal.org/ims-badge-extensions-education Model Primitive Datatype = Boolean.
                    type: boolean
                assessor: 
                    description: Organization, person, or role that assessed the work Model Primitive Datatype = String.
                    type: string
                assessmentEvaluation: 
                    description: Link to studies or other information about research or calculations of reliability and validity for the assessment or the scoring methods. See https://www.imsglobal.org/ims-badge-extensions-education Model Primitive Datatype = String.
                    type: string
                assessmentOutput: 
                    description: Additional details about assessment type. Values for assessmentOutput are expected to be words or phrases that describe the key features of the evidence produced. See https://www.imsglobal.org/ims-badge-extensions-education Model Primitive Datatype = String.
                    type: string
              additionalProperties: false
    Association.Type:
        description: |
            Establish a relationship between two record entities contained within this record. 
        type: object
        required: 
            - id
            - type
            - associationType
            - entityType
            - entityId
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = NormalizedString.
                type: string
            type: 
                description: Type of the associated object Model Primitive Datatype = NormalizedString.
                type: string
                default: Relationship
            associationType: 
                description: |
                    The type of relationship. ('isParentOf', 'isChildOf', etc.)
                type: string
                enum: 
                   - exactMatchOf
                   - precedes
                   - isChildOf
                   - isParentOf
                   - hasSkillLevel
                   - replacedBy
                   - isPartOf
                   - exemplar
                   - isRelatedTo
                   - isPeerOf
            entityType: 
                description: |
                    The type of the associated record entity. (E.g., 'Basic', 'Certificate', 'CoCurricular', etc.)
                type: string
                enum: 
                   - Basic
                   - Competency
                   - Course
                   - Degree
                   - Certificate
                   - Assessment
                   - CoCurricular
            entityId: 
                description: The id of the associated record entity. Model Primitive Datatype = String.
                type: string
        additionalProperties: true
    Basic.Type:
        description: |
            Provides support for representing record entities that are not semantically compatible with other record entity classes.
        type: object
        allOf: 
            - $ref: "#/definitions/RecordEntity.Type"
            - type: object
              properties: {}
              additionalProperties: false
    Certificate.Type:
        description: |
            A credential that designates requisite mastery of the knowledge and skills of an occupation, profession, or academic program. See http://www.credreg.net/ctdl/terms#Certificate
        type: object
        allOf: 
            - $ref: "#/definitions/RecordEntity.Type"
            - type: object
              properties: 
                level: 
                    description: Relative position of the certificate in relation to others.  Examples include Undergraduate, Master's, Associate, etc. Model Primitive Datatype = String.
                    type: string
                areaOfStudy: 
                    description: Area of study or category associated with this certificate. Examples include Infomatics, Accounting, Human Resources Management. Model Primitive Datatype = String.
                    type: string
              additionalProperties: false
    CoCurricular.Type:
        description: |
            Activities, achievements, or learning attained in addition to the offical academic curriculum or study, though still asserted by the Issuer.  Generally outside of the classroom or course setting.  Examples include student government, sports, music, art, debate, photography and others.  
        type: object
        allOf: 
            - $ref: "#/definitions/RecordEntity.Type"
            - type: object
              properties: 
                category: 
                    description: Area of cocurricular activity, as defined by the Issuer. Examples include sports, community service, student government, arts, etc. Model Primitive Datatype = String.
                    type: string
                scoringMethod: 
                    description: An enumeration of types of applicable scoring. See http://www.credreg.net/ctdl/terms#ScoringMethod. Model Primitive Datatype = String.
                    type: string
                role: 
                    description: Role, position, or title of the Person in the cocurricular activity, achievement, or learning experience.  Examples include Student President, Intern, Captain, etc. Model Primitive Datatype = String.
                    type: string
                startDate: 
                    description: Starting date of the Person’s involvement in the cocurricular activity. Model Primitive Datatype = DateTime.
                    type: string
                    format: date-time
                endDate: 
                    description: Ending date of the Person’s involvement in the cocurricular activity. Model Primitive Datatype = DateTime.
                    type: string
                    format: date-time
              additionalProperties: false
    Competency.Type:
        description: |
            Measurable or observable knowledge, skills, and abilities necessary to successful performance of a person in a given context. See http://credreg.net/ctdl#Competency
        type: object
        allOf: 
            - $ref: "#/definitions/RecordEntity.Type"
            - type: object
              properties: 
                humanCodingScheme: 
                    description: Human-referenceable code designated by the competency publisher to identify this competency item among others. See IMS CASE #DataAttribute_CFPckgItem_humanCodingScheme Model Primitive Datatype = String.
                    type: string
                CFDocumentURI: 
                    description: Provides IMS CASE interoperability. If this competency is a CFItem using the CASE standard, this identifier maps to the containing CFDocument. Model Primitive Datatype = AnyURI.
                    type: string
                    format: uri
              additionalProperties: false
    ComprehensiveLearnerRecord.Type:
        description: |
            Collection of Records for a single person declared by a single Issuer.
        type: object
        required: 
            - id
            - type
            - createdAt
            - recordEntities
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = NormalizedString.
                type: string
            type: 
                description: Type of the associated object Model Primitive Datatype = NormalizedString.
                type: string
                default: ComprehensiveLearnerRecord
            createdAt: 
                description: Date and time this record was produced Model Primitive Datatype = DateTime.
                type: string
                format: date-time
            issuer: 
                $ref: "#/definitions/Issuer.Type"
            overviewUrl: 
                description: URL to access the issuer's documentation for the comprehensive learner record. This may include a general description of the record, along with any policies around the issuance and interpretation of the record. Model Primitive Datatype = AnyURI.
                type: string
                format: uri
            person: 
                $ref: "#/definitions/Person.Type"
            records: 
                description: |
                    The Records of this learner record.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Record.Type"
            recordEntities: 
                $ref: "#/definitions/RecordEntitySet.Type"
        additionalProperties: true
    Course.Type:
        description: |
            Description of an educational course which may be offered as distinct instances at different times and places, or through different media or modes of study. An educational course is a sequence of one or more educational events and/or creative works which aims to build knowledge, competence or ability of learners. See http://www.credreg.net/ctdl/terms#Course
        type: object
        allOf: 
            - $ref: "#/definitions/RecordEntity.Type"
            - type: object
              properties: 
                courseCode: 
                    description: The identifier used for the course, typically in course catalogs and curricula. Example; 'PSY1000' Model Primitive Datatype = String.
                    type: string
                startDate: 
                    description: Date this course starts. Model Primitive Datatype = DateTime.
                    type: string
                    format: date-time
                endDate: 
                    description: Date this course ends. Model Primitive Datatype = DateTime.
                    type: string
                    format: date-time
              additionalProperties: false
    Degree.Type:
        description: |
            Academic credential conferred upon completion of a program or course of study, typically over multiple years at postsecondary education institutions. See http://www.credreg.net/ctdl/terms#Degree
        type: object
        allOf: 
            - $ref: "#/definitions/RecordEntity.Type"
            - type: object
              properties: 
                programName: 
                    description: Name of the program associated with this degree. Examples include, Master of Business Administration, or Bachelor of Science in Nursing. Model Primitive Datatype = String.
                    type: string
                programSpecialization: 
                    description: Name of the specialization or focus of this degree. Examples include Entrepreneurship, General Business Administration, or Finance. Model Primitive Datatype = String.
                    type: string
                level: 
                    description: Academic level associated with this degree. Examples include Master's, Doctoral, or Bachelor's. Model Primitive Datatype = String.
                    type: string
                areaOfStudy: 
                    description: Area of study or category associated with this degree. Examples include Business, Education, Psychology, or Nursing. Model Primitive Datatype = String.
                    type: string
              additionalProperties: false
    Evidence.Type:
        description: |
            One or more artifacts that represent supporting evidence for the record. Examples include text, media, websites, etc.
        type: object
        required: 
            - name
            - url
        properties: 
            name: 
                description: Name of the actual evidentice artifact. Model Primitive Datatype = String.
                type: string
            url: 
                description: Reference to the actual evidence artifact. Model Primitive Datatype = AnyURI.
                type: string
                format: uri
        additionalProperties: true
    Issuer.Type:
        description: |
            The issuing organization of this comprehensive learner record
        type: object
        required: 
            - id
            - type
            - name
            - url
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = NormalizedString.
                type: string
            type: 
                description: Type of the associated object Model Primitive Datatype = NormalizedString.
                type: string
                default: Issuer
            name: 
                description: Name of the issuing organization. Model Primitive Datatype = String.
                type: string
            url: 
                description: Web resource that provides additional information about the Issuer. Model Primitive Datatype = AnyURI.
                type: string
                format: uri
            address: 
                description: Mailing address or location for the issuing organization. Model Primitive Datatype = String.
                type: string
            phone: 
                description: Phone number available for contacting the Issuer. Model Primitive Datatype = String.
                type: string
            logo: 
                description: Issuer's logo. This is either a URL to a publicly-available image, or a data URI for embedding an image in the record. Model Primitive Datatype = AnyURI.
                type: string
                format: uri
            issuingPersonFullName: 
                description: The name of the person who has the authority to issue the Comprehensive Learner Record. Model Primitive Datatype = String.
                type: string
            issuingPersonTitle: 
                description: The role, title or position of the person who has the authority to issue the comprehensive learner record. Model Primitive Datatype = String.
                type: string
        additionalProperties: true
    Package.Type:
        description: |
            A Package contains zero or one Comprehensive Learner Records (no record will be returned if the requested record was not found), the ID of the person to whom the record applies, and a status code.
        type: object
        required: 
            - personID
            - status
        properties: 
            personID: 
                description: The ID of a person for which an comprehensive learner record is requested. Model Primitive Datatype = String.
                type: string
            comprehensiveLearnerRecord: 
                $ref: "#/definitions/ComprehensiveLearnerRecord.Type"
            status: 
                description: |
                    A status code representing the result of processing the request.
                type: string
                enum: 
                   - unsupported
                   - internal_error
                   - not_found
                   - forbidden
                   - server_busy
                   - success
        additionalProperties: false
    PackageSet.Type:
        description: |
            A set of Package objects returned by the Service Provider that correspond to the persons identified via the personIDs parameter.
        type: object
        required: 
            - results
        properties: 
            results: 
                description: |
                    The set of Package objects.
                type: array
                minItems: 1
                items: 
                    $ref: "#/definitions/Package.Type"
        additionalProperties: false
    Person.Type:
        description: |
            Individual who is the subject of the record.
        type: object
        required: 
            - id
            - type
            - fullName
            - givenName
            - familyName
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = NormalizedString.
                type: string
            type: 
                description: Type of the associated object Model Primitive Datatype = NormalizedString.
                type: string
                default: Person
            fullName: 
                description: Full name of the person. (Compatible with the LIS definition of Person.Name) Model Primitive Datatype = String.
                type: string
            givenName: 
                description: Given name (first name) of the person. Model Primitive Datatype = String.
                type: string
            familyName: 
                description: Family name (last name) of the person. Model Primitive Datatype = String.
                type: string
            email: 
                description: Primary email address for the individual. Model Primitive Datatype = String.
                type: string
            phone: 
                description: Primary phone number for the individual. Model Primitive Datatype = String.
                type: string
            mobile: 
                description: Mobile phone number for the individual, if available. May be the same value as 'phone'. Model Primitive Datatype = String.
                type: string
            studentId: 
                description: Institution's student identifier for the person. This is frequently issued through a Student Information System. Model Primitive Datatype = String.
                type: string
            birthDate: 
                description: Person's date of birth. Model Primitive Datatype = Date.
                type: string
                format: date
            sourcedId: 
                description: Person's unique 'sourcedId' value, which is used for providing interoperability with Learning Information Services (LIS). Model Primitive Datatype = String.
                type: string
            url: 
                description: Web resource that uniquely represents or belongs to the individual. This may be a resource about the individual, hosting provided by the instution to the individual, or an web resource independently controlled by the individual. Model Primitive Datatype = AnyURI.
                type: string
                format: uri
        additionalProperties: true
    Record.Type:
        description: |
            Person's status and relevant metadata regarding a specific record entity, as recognized by the issuer. May include associated results, assertions, and evidence.
        type: object
        required: 
            - id
            - type
            - recordOf
            - date
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = NormalizedString.
                type: string
            type: 
                description: Type of the associated object Model Primitive Datatype = NormalizedString.
                type: string
                default: Record
            recordOf: 
                $ref: "#/definitions/RecordEntityLink.Type"
            date: 
                description: Date that this achievement, performance, or activity occurred. Model Primitive Datatype = DateTime.
                type: string
                format: date-time
            term: 
                description: Academic term in which the achievement, performance, or activity occurred. Model Primitive Datatype = String.
                type: string
            result: 
                description: Level, grade, or other outcome measurement associated with the record. (E.g., '92%', 'A-', 'Mastered') Model Primitive Datatype = String.
                type: string
            credits: 
                description: Credit hours earned by the learner that is associated with this record. Model Primitive Datatype = String.
                type: string
            points: 
                description: Associated points earned by the learner that is associated with this record. Model Primitive Datatype = String.
                type: string
            assertions: 
                description: Collection of URLs to Open Badge assertions relevant to this record. Model Primitive Datatype = AnyURI.
                type: array
                minItems: 0
                items: 
                    type: string
                    format: uri
            status: 
                $ref: "#/definitions/RecordStatus.Type"
            evidence: 
                description: |
                    Evidence for the record.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Evidence.Type"
        additionalProperties: true
    RecordEntity.Type:
        description: |
            A record entity, such as degree or course, provides context for defining an achievement, performance, or outcome record.  Each type of record entity has a set of required and optional fields that provide structure for defining entities of that type.
        type: object
        required: 
            - id
            - type
            - name
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = String.
                type: string
            type: 
                description: |
                    Type of the associated object
                type: string
                enum: 
                   - Basic
                   - Competency
                   - Course
                   - Degree
                   - Certificate
                   - Assessment
                   - CoCurricular
            name: 
                description: The name of the entity. Model Primitive Datatype = String.
                type: string
            description: 
                description: The description of the entity. Model Primitive Datatype = String.
                type: string
            defaultCredits: 
                description: Credit hours associated with this entity, or credit hours possible, for example '3.0' Model Primitive Datatype = String.
                type: string
            defaultPoints: 
                description: Points associated with this entity, or points possible. Example; '6.0'. Model Primitive Datatype = String.
                type: string
            sourcedId: 
                description: Reference to the source identifier of the entity, if sourced from LIS or another system or standard. Model Primitive Datatype = String.
                type: string
            associations: 
                description: |
                    Collection of relationships belonging to this record entity.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Association.Type"
            alternativeLabel: 
                description: Alternate 'term' for referring to this type of competency. Some organizations may want to refer to the competency achievements as outcomes, objectives, skills, etc. Semantically they are the same as Competencies, but diversity of terms is used. This allows flexibility for an organization to define their own terms to use instead of 'Competency.' See IMS CASE #DataAttribute_CFPckgItem_alternativeLabel Model Primitive Datatype = String.
                type: string
        additionalProperties: true
    RecordEntityLink.Type:
        description: |
            A reference to an entity contained within this record.
        type: object
        required: 
            - id
            - type
            - entityType
            - entityId
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = NormalizedString.
                type: string
            type: 
                description: Type of the associated object Model Primitive Datatype = NormalizedString.
                type: string
                default: TranscriptEntityLink
            entityType: 
                description: |
                    The type of the associated record entity. (E.g., 'Basic', 'Certificate', 'CoCurricular', etc.)
                type: string
                enum: 
                   - Basic
                   - Competency
                   - Course
                   - Degree
                   - Certificate
                   - Assessment
                   - CoCurricular
            entityId: 
                description: The id of the associated record entity. Model Primitive Datatype = NormalizedString.
                type: string
        additionalProperties: true
    RecordEntitySet.Type:
        description: |
            A collection of record entities, partitioned by entity types. Note that all record entities referenced within a CLR must be included in this collection.
        type: object
        required: 
            - id
            - type
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = NormalizedString.
                type: string
            type: 
                description: Type of the associated object Model Primitive Datatype = NormalizedString.
                type: string
                default: TranscriptEntitySet
            assessments: 
                description: |
                    Collection of all assessment record entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Assessment.Type"
            certificates: 
                description: |
                    Collection of all certificate record entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Certificate.Type"
            coCurriculars: 
                description: |
                    Collection of all co-curricular record entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/CoCurricular.Type"
            competencies: 
                description: |
                    Collection of all competency record entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Competency.Type"
            courses: 
                description: |
                    Collection of all course record entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Course.Type"
            degrees: 
                description: |
                    Collection of all degree record entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Degree.Type"
            basicEntities: 
                description: |
                    Collection of all basic record entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Basic.Type"
        additionalProperties: true
    RecordStatus.Type:
        description: |
            State or condition of the record defined by completed and notes properties.
        type: object
        required: 
            - id
            - type
        properties: 
            id: 
                description: Unique identifier for the associated object Model Primitive Datatype = NormalizedString.
                type: string
            type: 
                description: Type of the associated object Model Primitive Datatype = NormalizedString.
                type: string
                default: RecordStatus
            completed: 
                description: True if this record is fully achieved, otherwise false. If this property is absent, the record is considered completed. Model Primitive Datatype = Boolean.
                type: boolean
            notes: 
                description: Any explanatory notes about the status of the record. Model Primitive Datatype = String.
                type: string
        additionalProperties: true
    imsx_CodeMinor.Type:
        description: |
            This is the container for the set of code minor status codes reported in the responses from the Service Provider.
        type: object
        required: 
            - imsx_codeMinorField
        properties: 
            imsx_codeMinorField: 
                description: |
                    Each reported code minor status code.
                type: array
                minItems: 1
                items: 
                    $ref: "#/definitions/imsx_CodeMinorField.Type"
        additionalProperties: false
    imsx_CodeMinorField.Type:
        description: |
            This is the container for a single code minor status code.
        type: object
        required: 
            - imsx_codeMinorFieldName
            - imsx_codeMinorFieldValue
        properties: 
            imsx_codeMinorFieldName: 
                description: Tiis should contain the identity of the system that has produced the code minor status code report. Model Primitive Datatype = NormalizedString.
                type: string
            imsx_codeMinorFieldValue: 
                description: |
                    The code minor status code (this is a value from the corresponding enumerated vocabulary).
                type: string
                enum: 
                   - server_busy
                   - unauthorisedrequest
                   - internal_server_error
                   - forbidden
                   - targetreadfailure
        additionalProperties: false
    imsx_StatusInfo.Type:
        description: |
            This is the container for the status code and associated information returned within the HTTP messages received from the Service Provider.
        type: object
        required: 
            - imsx_codeMajor
            - imsx_severity
        properties: 
            imsx_codeMajor: 
                description: |
                    The code major value (from the corresponding enumerated vocabulary).
                type: string
                enum: 
                   - success
                   - failure
            imsx_severity: 
                description: |
                    The severity value (from the corresponding enumerated vocabulary).
                type: string
                enum: 
                   - status
                   - warning
                   - error
            imsx_description: 
                description: A human readable description supplied by the entity creating the status code information. Model Primitive Datatype = String.
                type: string
            imsx_codeMinor: 
                $ref: "#/definitions/imsx_CodeMinor.Type"
        additionalProperties: false
        

toc | top

About this Document

Title: IMS Comprehensive Learner Record Service REST/JSON Binding v1.0
Editors: Bryan Smith, Learning Objects (USA)
Chris Houston, Capella University (USA)
Markus Gylling, IMS Global (Sweden)

Co-chairs: Deb Everhart, Learning Objects (USA)
Jeff Grann, Capella University (USA)

Version: 1.0
Version Date: July 6th, 2018
Status: IMS Candidate Final
Summary: The IMS Comprehensive Learner Record Service is used to exchange information about users and their achievements. This standard defines a data model for comprehensive learner records. It also describes how this data can be exchanged using service calls. This document contains the REST/JSON Binding description for the Comprehensive Learner Record Service.

Revision Information: First release of this specification.
Purpose: For adoption and implemenation by the Competency Framework and Competency Based Education Task Forces.
Document Location: IMS Competency Framework and Competency Based Education Task Forces Forums

toc | top

List of Contributors

The following individuals contributed to the development of this document:

Insiya Bream UMUC (USA)
Kenny Burnham Parchment (USA)
Andrea Deau University of Wisconsin-Extension (USA)
Deb Everhart Learning Objects (USA)
Steve Gance WA Comm & Tech Colleges (USA)
Jeff Grann Cappella University (USA)
Paul Gray Learning Objects (USA)
Bob Grogan eLumen (USA)
Markus Gylling IMS Global (USA)
Chris Houston Capella University (USA)
Mark Leuba IMS Global (USA)
Phillip Long University of Texas at Austin (USA)
Nate Otto Concentric Sky (USA)
Joellen Shendy UMUC (USA)
Bryan Smith Learning Objects (USA)
Chris Tatem University of Maryland University College (USA)

toc | top

Revision History

Version No. Release Date Comments
Candidate Final July 6th, 2018 Candidate Final version of the Comprehensive Learner Record specification.

toc | top

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: IMS Comprehensive Learner Record Service REST/JSON Binding v1.0

Date: July 6th, 2018

toc | top