IMS Candidate Final

IMS Global Logo

IMS Extended Transcript Service REST/JSON Binding Version 1.0

IMS Candidate Final
Version 1.0

Date Issued: September 8, 2017
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 © 2017 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 Extended Transcript Service REST/JSON Binding v1.0

Revision: September 8, 2017

toc | top

Table of Contents

1. Introduction

1.1 Overview of the Extended Transcript 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 "getSetOfExtendedTranscripts" 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 Core Security with HMAC-SHA2

5.2 OAuth 2 Bearer Token Authorization

6. JSON Payloads

6.1 "getSetOfExtendedTranscripts" Request Payload

6.2 "getSetOfExtendedTranscripts" 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 "/extendedTranscripts " 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 "Course.Type" Definition

7.5.8 "Degree.Type" Definition

7.5.9 "Evidence.Type" Definition

7.5.10 "ExtendedTranscript.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 "RecordStatus.Type" Definition

7.5.17 "TranscriptEntity.Type" Definition

7.5.18 "TranscriptEntityLink.Type" Definition

7.5.19 "TranscriptEntitySet.Type" Definition

7.5.20 "URL.Type" Definition

7.5.21 "imsx_CodeMinor.Type" Definition

7.5.22 "imsx_CodeMinorField.Type" Definition

7.5.23 "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 Extended Transcript Service OpenAPI JSON Definition Listing

B2 Extended Transcript 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.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 "/extendedTranscripts " 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 'Course.Type' Complex Type.

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

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

Table 7.5.10 - OpenAPI JSON Schema description for the 'ExtendedTranscript.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 'RecordStatus.Type' Complex Type.

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

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

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

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

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

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

Table 7.5.23 - 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 "getSetOfExtendedTranscripts" operation.

toc | top

1. Introduction

1.1 Overview of the Extended Transcript Service

The IMS Extended Transcript 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 Extended Transcript (eT) 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 Extended Transcript supports interoperability in that eT Providers and Consumers can consistently send and receive transcripts among conformant entities. The IMS Extended Transcript 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 eTs.

The eT digitized information can be consumed by other schools, institutions, employers, and any other entities that are conformant as eT consumers. In this machine readable format, eT 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 Extended Transcript Service Model [eT, 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

[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/.
[eT, 17a] IMS Extended Transcript (eT) 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., September 8, 2017, http://www.imsglobal.org/et/.

toc | top

2. Serialization

2.1 JSON-LD Serialization

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

The canonical JSON-LD context IRI defined for the ExtendedTranscript class is https://purl.imsglobal.org/ctx/extended-transcript/v1p0.

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
getSetOfExtendedTranscripts /extendedTranscripts 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/extended-transcript/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 "getSetOfExtendedTranscripts" 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 "getSetOfExtendedTranscripts" 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 extended transcript is requested.

3.4 HTTP Code Handling

In the cases where a request cannot be serviced as expected the service provider will return 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
/extendedTranscripts GET
  • 200 - this is the response when the request has been completed successfully. Records for all of the specified extended transcripts were returned. The payload is defined by the structure PackageSet.Type.
  • 400 - partial success of the request. At least one of the requested extended transcripts 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 extended transcript is requested.

toc | top

5. Security Framework

5.1 Core Security with HMAC-SHA2

Servers MUST support the HMAC-SHA2 (256) signing method with OAuth data passed in the HTTP request. This includes changing the values for the OAuth parameters: 'oauth_signature_method', 'oauth_signature' and 'oauth_body_hash'.

5.2 OAuth 2 Bearer Token Authorization

Extended Transcripts requires the use of OAuth 2.0 Bearer Tokens with the Bearer Token obtained using the mechanism described in [RFC 6749] (https://tools.ietf.org/html/rfc6749#section-4.4). Support for TLS 1.2 is required.

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

The request for an access token takes the form of:

        
POST /token HTTP/1.1
Host: server.example.com
Authorization: Basic czZCaGRSa3F0MzpnWDFmQmF0M2JW
Content-Type: application/x-www-form-urlencoded
grant_type=client_credentials
        
The authorization encoding is produced using the consumer key and secret. Success results in the granting of the access token with a response of:
        
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"access_token" : "2YotnFZFEjr1zCsicMWpAA",
"token_type" : "bearer",
"expires_in" : 3600,
}
        

The recommended default value for the 'expires_in' is 3600s.

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

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

toc | top

6. JSON Payloads

6.1 "getSetOfExtendedTranscripts" Request Payload

There is no payload for this request.

6.2 "getSetOfExtendedTranscripts" 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 "getSetOfExtendedTranscripts" operation.
    {
        "results" : [
            {
                "personID" : "..String..",
                "extendedTranscript" : {
                    "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.."
                        },
                        {...},
                        {...}
                    ],
                    "transcriptEntities" : {
                        "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" : ...tbc(Multiple Enum)...,
                                        "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" : ...tbc(Multiple Enum)...,
                                        "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" : ...tbc(Multiple Enum)...,
                                        "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" : ...tbc(Multiple Enum)...,
                                        "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" : ...tbc(Multiple Enum)...,
                                        "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" : ...tbc(Multiple Enum)...,
                                        "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" : ...tbc(Multiple Enum)...,
                                        "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.."
                },
                "statusInfo" : {
                    "imsx_codeMajor" : "success"|"processing"|"failure"|"unsupported",
                    "imsx_severity" : "status"|"warning"|"error",
                    "imsx_description" : "..String..",
                    "imsx_codeMinor" : {
                        "imsx_codeMinorField" : [
                            {
                                "imsx_codeMinorFieldName" : "..NormalizedString..",
                                "imsx_codeMinorFieldValue" : "fullsuccess"|"server_busy"|"invaliddata"|"unauthorisedrequest"|"internal_server_error"|"forbidden"|"targetreadfailure"
                            },
                            {...},
                            {...}
                        ]
                    }
                }
            },
            {...},
            {...}
        ]
    }
                        

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 Extended Transcript Service
Specification Version 1.0
Description The Extended Transcript Service provides enables the exchange of data about users and their achievements between a Extended Transcript 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/extended-transcript/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 Extended Transcript Packages as a whole. The set of endpoints assigned to this tag are: The set of endpoints assigned to this tag are:

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 "/extendedTranscripts " Path

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

Table 7.4.1 - The Set of HTTP Verbs Permitted on the '/extendedTranscripts ' Path.
HTTP Verb: GET
Operation ID getSetOfExtendedTranscripts
Summary The REST "read" request message for the "getSetOfExtendedTranscripts()" API call.
Tags PackagesManager
Description This is a request to the Service Provider to provide a set of Extended Transcripts that corresponds to the IDs given in the personIDs parameter. For each requested transcript 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 extended transcripts were returned.
default PackageSet.Type No description supplied.
400 PackageSet.Type Partial success of the request. At least one of the requested extended transcripts 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
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{1..*} ! 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/TranscriptEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "assessmentMethod" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "scoringMethod" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "hasGroupParticipation" : {
                        "description" : "Model Primitive Datatype = Boolean",
                        "type" : "boolean"
                    },
                    "assessor" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "assessmentEvaluation" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "assessmentOutput" : {
                        "description" : "Model Primitive Datatype = String",
                        "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 transcript entities contained within this transcript.
Diagram To be supplied in a later release of this document
Model id{1..1} ! type{1..1} ! associationType{0..*} ! ...tbc...entityId{1..1} ! { Namespace Extension }
Source
    "Association.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string",
                "default" : "Relationship"
            },
            "associationType" : {
                "type" : "string",
                "enum" : [ "exactMatchOf","precedes","isChildOf","isParentOf","hasSkillLevel","replacedBy","isPartOf","exemplar","isRelatedTo","isPeerOf" ]
            },
            "entityType" : {
                "type" : "string",
                "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
            },
            "entityId" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            }
        },
        "required" : [ "id","type","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 transcript entities that are not semantically compatible with other transcript entity classes.
Diagram To be supplied in a later release of this document
Model None
Source
    "Basic.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/TranscriptEntity.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
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{1..*} ! alternativeLabel{0..1} ! { Namespace Extension }, level{0..1} ! areaOfStudy{0..1}
Source
    "Certificate.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/TranscriptEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "level" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "areaOfStudy" : {
                        "description" : "Model Primitive Datatype = String",
                        "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
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{1..*} ! 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/TranscriptEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "category" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "scoringMethod" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "role" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "startDate" : {
                        "description" : "Model Primitive Datatype = DateTime",
                        "type" : "string",
                        "format" : "date-time"
                    },
                    "endDate" : {
                        "description" : "Model Primitive Datatype = DateTime",
                        "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
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{1..*} ! alternativeLabel{0..1} ! { Namespace Extension }, humanCodingScheme{0..1} ! CFDocumentURI{0..1}
Source
    "Competency.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/TranscriptEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "humanCodingScheme" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "CFDocumentURI" : {
                        "description" : "Model Primitive Datatype = AnyURI",
                        "type" : "string",
                        "format" : "uri"
                    }
                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.7 "Course.Type" Definition

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

Table 7.5.7 - 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
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{1..*} ! alternativeLabel{0..1} ! { Namespace Extension }, courseCode{0..1} ! startDate{0..1} ! endDate{0..1}
Source
    "Course.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/TranscriptEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "courseCode" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "startDate" : {
                        "description" : "Model Primitive Datatype = DateTime",
                        "type" : "string",
                        "format" : "date-time"
                    },
                    "endDate" : {
                        "description" : "Model Primitive Datatype = DateTime",
                        "type" : "string",
                        "format" : "date-time"
                    }
                },
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.8 "Degree.Type" Definition

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

Table 7.5.8 - 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
Model id{1..1} ! type{1..1} ! name{1..1} ! description{0..1} ! defaultCredits{0..1} ! defaultPoints{0..1} ! sourcedId{0..1} ! associations{1..*} ! alternativeLabel{0..1} ! { Namespace Extension }, programName{1..1} ! programSpecialization{0..1} ! level{0..1} ! areaOfStudy{0..1}
Source
    "Degree.Type" : {
        "description" : "...",
        "type" : "object",
        "allOf" : [
            {
                "$ref" : "#/definitions/TranscriptEntity.Type"
            },
            {
                "type" : "object",
                "properties" : {
                    "programName" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "programSpecialization" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "level" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    },
                    "areaOfStudy" : {
                        "description" : "Model Primitive Datatype = String",
                        "type" : "string"
                    }
                },
                "required" : [ "programName" ],
                "additionalProperties" : false
            }
        ]
    },
                        

7.5.9 "Evidence.Type" Definition

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

Table 7.5.9 - 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",
                "type" : "string"
            },
            "url" : {
                "$ref" : "#/definitions/URL.Type"
            }
        },
        "required" : [ "name","url" ],
        "additionalProperties" : true
    },
                        

7.5.10 "ExtendedTranscript.Type" Definition

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

Table 7.5.10 - OpenAPI JSON Schema description for the "ExtendedTranscript.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{1..*} ! transcriptEntities{1..1} ! { Namespace Extension }
Source
    "ExtendedTranscript.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string",
                "default" : "ExtendedTranscript"
            },
            "createdAt" : {
                "description" : "Model Primitive Datatype = DateTime",
                "type" : "string",
                "format" : "date-time"
            },
            "issuer" : {
                "$ref" : "#/definitions/Issuer.Type"
            },
            "overviewUrl" : {
                "$ref" : "#/definitions/URL.Type"
            },
            "person" : {
                "$ref" : "#/definitions/Person.Type"
            },
            "records" : {
                "type" : "array",
                "minItems" : 1,
                "items" : {
                    "$ref" : "#/definitions/Record.Type"
                }
            },
            "transcriptEntities" : {
                "$ref" : "#/definitions/TranscriptEntitySet.Type"
            }
        },
        "required" : [ "id","type","createdAt","records","transcriptEntities" ],
        "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 extended transcript
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",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string",
                "default" : "Issuer"
            },
            "name" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "URL" : {
                "description" : "Model Primitive Datatype = AnyURI",
                "type" : "string",
                "format" : "uri"
            },
            "address" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "phone" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "logo" : {
                "description" : "Model Primitive Datatype = AnyURI",
                "type" : "string",
                "format" : "uri"
            },
            "issuingPersonFullName" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "issuingPersonTitle" : {
                "description" : "Model Primitive Datatype = String",
                "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 Extended Transcripts (no transcript will be returned if the requested transcript was not found), the ID of the person to whom the transcript applies, and a status code.
Diagram To be supplied in a later release of this document
Model personID{1..1} ! extendedTranscript{0..1} ! statusInfo{1..1}
Source
    "Package.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "personID" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "extendedTranscript" : {
                "$ref" : "#/definitions/ExtendedTranscript.Type"
            },
            "statusInfo" : {
                "$ref" : "#/definitions/imsx_StatusInfo.Type"
            }
        },
        "required" : [ "personID","statusInfo" ],
        "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" : {
                "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 transcript.
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",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string",
                "default" : "Person"
            },
            "fullName" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "givenName" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "familyName" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "email" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "phone" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "mobile" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "studentId" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "birthDate" : {
                "description" : "Model Primitive Datatype = Date",
                "type" : "string",
                "format" : "date"
            },
            "sourcedId" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "url" : {
                "description" : "Model Primitive Datatype = AnyURI",
                "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 transcript 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",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string",
                "default" : "Record"
            },
            "recordOf" : {
                "$ref" : "#/definitions/TranscriptEntityLink.Type"
            },
            "date" : {
                "description" : "Model Primitive Datatype = DateTime",
                "type" : "string",
                "format" : "date-time"
            },
            "term" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "result" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "credits" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "points" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "assertions" : {
                "description" : "Model Primitive Datatype = AnyURI",
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "type" : "string",
                    "format" : "uri"
                }
            },
            "status" : {
                "$ref" : "#/definitions/RecordStatus.Type"
            },
            "evidence" : {
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Evidence.Type"
                }
            }
        },
        "required" : [ "id","type","recordOf","date" ],
        "additionalProperties" : true
    },
                        

7.5.16 "RecordStatus.Type" Definition

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

Table 7.5.16 - 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",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string",
                "default" : "RecordStatus"
            },
            "completed" : {
                "description" : "Model Primitive Datatype = Boolean",
                "type" : "boolean"
            },
            "notes" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            }
        },
        "required" : [ "id","type" ],
        "additionalProperties" : true
    },
                        

7.5.17 "TranscriptEntity.Type" Definition

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

Table 7.5.17 - OpenAPI JSON Schema description for the "TranscriptEntity.Type" Complex Type.
Annotations A transcript entity, such as degree or course, provides context for defining an achievement, performance, or outcome record. Each type of transcript 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{1..*} ! alternativeLabel{0..1} ! { Namespace Extension }
Source
    "TranscriptEntity.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "type" : {
                "type" : "string",
                "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
            },
            "name" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "description" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "defaultCredits" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "defaultPoints" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "sourcedId" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            },
            "associations" : {
                "type" : "array",
                "minItems" : 1,
                "items" : {
                    "$ref" : "#/definitions/Association.Type"
                }
            },
            "alternativeLabel" : {
                "description" : "Model Primitive Datatype = String",
                "type" : "string"
            }
        },
        "required" : [ "id","type","name","associations" ],
        "additionalProperties" : true
    },
                        

7.5.18 "TranscriptEntityLink.Type" Definition

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

Table 7.5.18 - OpenAPI JSON Schema description for the "TranscriptEntityLink.Type" Complex Type.
Annotations A reference to a transcript entity contained within this transcript.
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
    "TranscriptEntityLink.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string",
                "default" : "TranscriptEntityLink"
            },
            "entityType" : {
                "type" : "string",
                "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
            },
            "entityId" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string"
            }
        },
        "required" : [ "id","type","entityType","entityId" ],
        "additionalProperties" : true
    },
                        

7.5.19 "TranscriptEntitySet.Type" Definition

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

Table 7.5.19 - OpenAPI JSON Schema description for the "TranscriptEntitySet.Type" Complex Type.
Annotations A collection of transcript entities, partitioned by entity types. Note that all transcript entities referenced within a transcript 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
    "TranscriptEntitySet.Type" : {
        "description" : "...",
        "type" : "object",
        "properties" : {
            "id" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string"
            },
            "type" : {
                "description" : "Model Primitive Datatype = NormalizedString",
                "type" : "string",
                "default" : "TranscriptEntitySet"
            },
            "assessments" : {
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Assessment.Type"
                }
            },
            "certificates" : {
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Certificate.Type"
                }
            },
            "coCurriculars" : {
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/CoCurricular.Type"
                }
            },
            "competencies" : {
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Competency.Type"
                }
            },
            "courses" : {
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Course.Type"
                }
            },
            "degrees" : {
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Degree.Type"
                }
            },
            "basicEntities" : {
                "type" : "array",
                "minItems" : 0,
                "items" : {
                    "$ref" : "#/definitions/Basic.Type"
                }
            }
        },
        "required" : [ "id","type" ],
        "additionalProperties" : true
    },
                        

7.5.20 "URL.Type" Definition

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

Table 7.5.20 - OpenAPI JSON Schema description for the "URL.Type" Complex Type.
Annotations
Diagram To be supplied in a later release of this document
Model N/A
Source
    "URL.Type" : {
        "description" : "...",
        "type" : "string",
        "format" : "uri"
    },
                        

7.5.21 "imsx_CodeMinor.Type" Definition

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

Table 7.5.21 - 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" : {
                "type" : "array",
                "minItems" : 1,
                "items" : {
                    "$ref" : "#/definitions/imsx_CodeMinorField.Type"
                }
            }
        },
        "required" : [ "imsx_codeMinorField" ],
        "additionalProperties" : false
    },
                        

7.5.22 "imsx_CodeMinorField.Type" Definition

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

Table 7.5.22 - 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",
                "type" : "string"
            },
            "imsx_codeMinorFieldValue" : {
                "type" : "string",
                "enum" : [ "fullsuccess","server_busy","invaliddata","unauthorisedrequest","internal_server_error","forbidden","targetreadfailure" ]
            }
        },
        "required" : [ "imsx_codeMinorFieldName","imsx_codeMinorFieldValue" ],
        "additionalProperties" : false
    },
                        

7.5.23 "imsx_StatusInfo.Type" Definition

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

Table 7.5.23 - 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" : {
                "type" : "string",
                "enum" : [ "success","processing","failure","unsupported" ]
            },
            "imsx_severity" : {
                "type" : "string",
                "enum" : [ "status","warning","error" ]
            },
            "imsx_description" : {
                "description" : "Model Primitive Datatype = String",
                "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 [eT, 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 Extended Transcript 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);
    • Empty - the associated instance must be empty;
    • 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);
    • 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 Error Codes and Handling for each Endpoint Table Explanation

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

Table A1.3 The key to the descriptions of the list of error 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.
Error Codes and Handling The list of error codes that may be returned by the service provider. A description of the cause of the error code is supplied along with a link to the definition of the associated JSON payload structure that contains the detailed error information.

toc | top

A2 OpenAPI Descriptions Explanations

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 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 informationfor 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 paylaod 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.
Model The set of child elements. This is an ordered list of elements (as per the sequence in the complexType) 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 OpenAPI documentation for the description of the permitted contents for this declaration.

toc | top

Appendix B OpenAPI Listings

B1 Extended Transcript 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" : "Extended Transcript Service OpenAPI (JSON) Definition",
        "description" : "The Extended Transcript Service provides enables the exchange of data about users and their achievements between a Extended Transcript 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/extended-transcript/v1p0",
    "schemes" : [ "http","https" ],
    "tags" : [
        {
            "name" : "PackagesManager",
            "description" : "The set of service operations that manage access to the Extended Transcript 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" : {
        "/extendedTranscripts	" : {
            "get" : {
                "operationId" : "getSetOfExtendedTranscripts",
                "summary" : "The REST read request message for the getSetOfExtendedTranscripts() API call.",
                "tags" : [ "PackagesManager" ],
                "description" : "This is a request to the Service Provider to provide a set of Extended Transcripts that corresponds to the IDs given in the personIDs parameter. For each requested transcript 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 extended transcript is requested.",
                        "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 extended transcripts 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 extended transcripts 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/TranscriptEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "assessmentMethod" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "scoringMethod" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "hasGroupParticipation" : {
                            "description" : "Model Primitive Datatype = Boolean",
                            "type" : "boolean"
                        },
                        "assessor" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "assessmentEvaluation" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "assessmentOutput" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        }
                    },
                    "additionalProperties" : false
                }
            ]
        },
        "Association.Type" : {
            "description" : "Establish a relationship between two transcript entities contained within this transcript. ",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string",
                    "default" : "Relationship"
                },
                "associationType" : {
                    "type" : "string",
                    "enum" : [ "exactMatchOf","precedes","isChildOf","isParentOf","hasSkillLevel","replacedBy","isPartOf","exemplar","isRelatedTo","isPeerOf" ]
                },
                "entityType" : {
                    "type" : "string",
                    "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
                },
                "entityId" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                }
            },
            "required" : [ "id","type","entityType","entityId" ],
            "additionalProperties" : true
        },
        "Basic.Type" : {
            "description" : "Provides support for representing transcript entities that are not semantically compatible with other transcript entity classes.	",
            "type" : "object",
            "allOf" : [
                {
                    "$ref" : "#/definitions/TranscriptEntity.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/TranscriptEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "level" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "areaOfStudy" : {
                            "description" : "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/TranscriptEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "category" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "scoringMethod" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "role" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "startDate" : {
                            "description" : "Model Primitive Datatype = DateTime",
                            "type" : "string",
                            "format" : "date-time"
                        },
                        "endDate" : {
                            "description" : "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/TranscriptEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "humanCodingScheme" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "CFDocumentURI" : {
                            "description" : "Model Primitive Datatype = AnyURI",
                            "type" : "string",
                            "format" : "uri"
                        }
                    },
                    "additionalProperties" : false
                }
            ]
        },
        "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/TranscriptEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "courseCode" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "startDate" : {
                            "description" : "Model Primitive Datatype = DateTime",
                            "type" : "string",
                            "format" : "date-time"
                        },
                        "endDate" : {
                            "description" : "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/TranscriptEntity.Type"
                },
                {
                    "type" : "object",
                    "properties" : {
                        "programName" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "programSpecialization" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "level" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        },
                        "areaOfStudy" : {
                            "description" : "Model Primitive Datatype = String",
                            "type" : "string"
                        }
                    },
                    "required" : [ "programName" ],
                    "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",
                    "type" : "string"
                },
                "url" : {
                    "$ref" : "#/definitions/URL.Type"
                }
            },
            "required" : [ "name","url" ],
            "additionalProperties" : true
        },
        "ExtendedTranscript.Type" : {
            "description" : "Collection of Records for a single person declared by a single Issuer.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string",
                    "default" : "ExtendedTranscript"
                },
                "createdAt" : {
                    "description" : "Model Primitive Datatype = DateTime",
                    "type" : "string",
                    "format" : "date-time"
                },
                "issuer" : {
                    "$ref" : "#/definitions/Issuer.Type"
                },
                "overviewUrl" : {
                    "$ref" : "#/definitions/URL.Type"
                },
                "person" : {
                    "$ref" : "#/definitions/Person.Type"
                },
                "records" : {
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/Record.Type"
                    }
                },
                "transcriptEntities" : {
                    "$ref" : "#/definitions/TranscriptEntitySet.Type"
                }
            },
            "required" : [ "id","type","createdAt","records","transcriptEntities" ],
            "additionalProperties" : true
        },
        "Issuer.Type" : {
            "description" : "The issuing organization of this extended transcript",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string",
                    "default" : "Issuer"
                },
                "name" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "URL" : {
                    "description" : "Model Primitive Datatype = AnyURI",
                    "type" : "string",
                    "format" : "uri"
                },
                "address" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "phone" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "logo" : {
                    "description" : "Model Primitive Datatype = AnyURI",
                    "type" : "string",
                    "format" : "uri"
                },
                "issuingPersonFullName" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "issuingPersonTitle" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                }
            },
            "required" : [ "id","type","name","URL" ],
            "additionalProperties" : true
        },
        "Package.Type" : {
            "description" : "A Package contains zero or one Extended Transcripts (no transcript will be returned if the requested transcript was not found), the ID of the person to whom the transcript applies, and a status code.",
            "type" : "object",
            "properties" : {
                "personID" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "extendedTranscript" : {
                    "$ref" : "#/definitions/ExtendedTranscript.Type"
                },
                "statusInfo" : {
                    "$ref" : "#/definitions/imsx_StatusInfo.Type"
                }
            },
            "required" : [ "personID","statusInfo" ],
            "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" : {
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/Package.Type"
                    }
                }
            },
            "required" : [ "results" ],
            "additionalProperties" : false
        },
        "Person.Type" : {
            "description" : "Individual who is the subject of the transcript.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string",
                    "default" : "Person"
                },
                "fullName" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "givenName" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "familyName" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "email" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "phone" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "mobile" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "studentId" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "birthDate" : {
                    "description" : "Model Primitive Datatype = Date",
                    "type" : "string",
                    "format" : "date"
                },
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "url" : {
                    "description" : "Model Primitive Datatype = AnyURI",
                    "type" : "string",
                    "format" : "uri"
                }
            },
            "required" : [ "id","type","fullName","givenName","familyName" ],
            "additionalProperties" : true
        },
        "Record.Type" : {
            "description" : "Person's status and relevant metadata regarding a specific transcript entity, as recognized by the issuer. May include associated results, assertions, and evidence.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string",
                    "default" : "Record"
                },
                "recordOf" : {
                    "$ref" : "#/definitions/TranscriptEntityLink.Type"
                },
                "date" : {
                    "description" : "Model Primitive Datatype = DateTime",
                    "type" : "string",
                    "format" : "date-time"
                },
                "term" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "result" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "credits" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "points" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "assertions" : {
                    "description" : "Model Primitive Datatype = AnyURI",
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "type" : "string",
                        "format" : "uri"
                    }
                },
                "status" : {
                    "$ref" : "#/definitions/RecordStatus.Type"
                },
                "evidence" : {
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Evidence.Type"
                    }
                }
            },
            "required" : [ "id","type","recordOf","date" ],
            "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",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string",
                    "default" : "RecordStatus"
                },
                "completed" : {
                    "description" : "Model Primitive Datatype = Boolean",
                    "type" : "boolean"
                },
                "notes" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                }
            },
            "required" : [ "id","type" ],
            "additionalProperties" : true
        },
        "TranscriptEntity.Type" : {
            "description" : "A transcript entity, such as degree or course, provides context for defining an achievement, performance, or outcome record.  Each type of transcript 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",
                    "type" : "string"
                },
                "type" : {
                    "type" : "string",
                    "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
                },
                "name" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "description" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "defaultCredits" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "defaultPoints" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "sourcedId" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "associations" : {
                    "type" : "array",
                    "minItems" : 1,
                    "items" : {
                        "$ref" : "#/definitions/Association.Type"
                    }
                },
                "alternativeLabel" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                }
            },
            "required" : [ "id","type","name","associations" ],
            "additionalProperties" : true
        },
        "TranscriptEntityLink.Type" : {
            "description" : "A reference to a transcript entity contained within this transcript.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string",
                    "default" : "TranscriptEntityLink"
                },
                "entityType" : {
                    "type" : "string",
                    "enum" : [ "Basic","Competency","Course","Degree","Certificate","Assessment","CoCurricular" ]
                },
                "entityId" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string"
                }
            },
            "required" : [ "id","type","entityType","entityId" ],
            "additionalProperties" : true
        },
        "TranscriptEntitySet.Type" : {
            "description" : "A collection of transcript entities, partitioned by entity types. Note that all transcript entities referenced within a transcript must be included in this collection.",
            "type" : "object",
            "properties" : {
                "id" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string"
                },
                "type" : {
                    "description" : "Model Primitive Datatype = NormalizedString",
                    "type" : "string",
                    "default" : "TranscriptEntitySet"
                },
                "assessments" : {
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Assessment.Type"
                    }
                },
                "certificates" : {
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Certificate.Type"
                    }
                },
                "coCurriculars" : {
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/CoCurricular.Type"
                    }
                },
                "competencies" : {
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Competency.Type"
                    }
                },
                "courses" : {
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Course.Type"
                    }
                },
                "degrees" : {
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Degree.Type"
                    }
                },
                "basicEntities" : {
                    "type" : "array",
                    "minItems" : 0,
                    "items" : {
                        "$ref" : "#/definitions/Basic.Type"
                    }
                }
            },
            "required" : [ "id","type" ],
            "additionalProperties" : true
        },
        "URL.Type" : {
            "description" : "...tbd (Class description)...",
            "type" : "string",
            "format" : "uri"
        },
        "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" : {
                    "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",
                    "type" : "string"
                },
                "imsx_codeMinorFieldValue" : {
                    "type" : "string",
                    "enum" : [ "fullsuccess","server_busy","invaliddata","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" : {
                    "type" : "string",
                    "enum" : [ "success","processing","failure","unsupported" ]
                },
                "imsx_severity" : {
                    "type" : "string",
                    "enum" : [ "status","warning","error" ]
                },
                "imsx_description" : {
                    "description" : "Model Primitive Datatype = String",
                    "type" : "string"
                },
                "imsx_codeMinor" : {
                    "$ref" : "#/definitions/imsx_CodeMinor.Type"
                }
            },
            "required" : [ "imsx_codeMajor","imsx_severity" ],
            "additionalProperties" : false
        }
    },
    "consumes" : [ "application/json" ],
    "produces" : [ "application/json" ]
}
        

B2 Extended Transcript 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: Extended Transcript Service OpenAPI (YAML) Definition
    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/extended-transcript/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 Extended Transcript 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: 
    /extendedTranscripts	:
        get:
            operationId: getSetOfExtendedTranscripts
            summary: The REST read request message for the getSetOfExtendedTranscripts() API call.
            tags: 
                - PackagesManager
            description: |
                This is a request to the Service Provider to provide a set of Extended Transcripts that corresponds to the IDs given in the personIDs parameter. For each requested transcript 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 extended transcript is requested.
                  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 extended transcripts 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 extended transcripts 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/TranscriptEntity.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 transcript entities contained within this transcript. 
        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: 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 transcript entity. (E.g., "Basic", "Certificate", "CoCurricular", etc.)
                type: string
                enum: 
                    - Basic
                    - Competency
                    - Course
                    - Degree
                    - Certificate
                    - Assessment
                    - CoCurricular
            entityId: 
                description: The id of the associated transcript entity. Model Primitive Datatype = String
                type: string
        additionalProperties: true
    Basic.Type:
        description: |
            Provides support for representing transcript entities that are not semantically compatible with other transcript entity classes.	
        type: object
        allOf: 
            - $ref: "#/definitions/TranscriptEntity.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/TranscriptEntity.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/TranscriptEntity.Type"
            - type: object
              properties: 
                category: 
                    description: Area of cocurricular activity, as defined by thte 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/TranscriptEntity.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
    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/TranscriptEntity.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/TranscriptEntity.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
              required: 
                - programName
              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: Title for the actual evidentice artifact.. Model Primitive Datatype = String
                type: string
            url: 
                description: |
                    Reference to the actual evidence artifact..
                $ref: "#/definitions/URL.Type"
        additionalProperties: true
    ExtendedTranscript.Type:
        description: |
            Collection of Records for a single person declared by a single Issuer.
        type: object
        required: 
            - id
            - type
            - createdAt
            - records
            - transcriptEntities
        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: ExtendedTranscript
            createdAt: 
                description: Date and time this transcript was produced Model Primitive Datatype = DateTime
                type: string
                format: date-time
            issuer: 
                description: |
                    The issuer of this extended transcript.
                $ref: "#/definitions/Issuer.Type"
            overviewUrl: 
                description: |
                    URL to access the issuer's documentation for the extended transcript. This may include a general description of the transcript, along with any policies around the issuance and interpretation of the transcript.
                $ref: "#/definitions/URL.Type"
            person: 
                description: |
                    The person to whom this transcript is issued.
                $ref: "#/definitions/Person.Type"
            records: 
                description: |
                    The Records of this transcript.
                type: array
                minItems: 1
                items: 
                    $ref: "#/definitions/Record.Type"
            transcriptEntities: 
                description: |
                    Collection of all the transcript entities contained within this transcript.
                $ref: "#/definitions/TranscriptEntitySet.Type"
        additionalProperties: true
    Issuer.Type:
        description: |
            The issuing organization of this extended transcript
        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 transcript. Model Primitive Datatype = AnyURI
                type: string
                format: uri
            issuingPersonFullName: 
                description: The name of the person who has the authority to issue the Extended Transcript. Model Primitive Datatype = String
                type: string
            issuingPersonTitle: 
                description: The role, title or position of the person who has the authority to issue the Extended Transcript. Model Primitive Datatype = String
                type: string
        additionalProperties: true
    Package.Type:
        description: |
            A Package contains zero or one Extended Transcripts (no transcript will be returned if the requested transcript was not found), the ID of the person to whom the transcript applies, and a status code.
        type: object
        required: 
            - personID
            - statusInfo
        properties: 
            personID: 
                description: The ID of a person for which an extended transcript is requested.
 Model Primitive Datatype = String
                type: string
            extendedTranscript: 
                description: |
                    The Extended Transcript instance of this Package. 
                $ref: "#/definitions/ExtendedTranscript.Type"
            statusInfo: 
                description: |
                    A status code representing the result of processing the request.
                $ref: "#/definitions/imsx_StatusInfo.Type"
        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 transcript.
        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 transcript 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: 
                description: |
                    Reference to a TranscriptEntity
                $ref: "#/definitions/TranscriptEntityLink.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: 
                description: |
                    State or condition of the record defined by completed and notes properties.
                $ref: "#/definitions/RecordStatus.Type"
            evidence: 
                description: |
                    Evidence for the record.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Evidence.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
    TranscriptEntity.Type:
        description: |
            A transcript entity, such as degree or course, provides context for defining an achievement, performance, or outcome record.  Each type of transcript entity has a set of required and optional fields that provide structure for defining entities of that type.
        type: object
        required: 
            - id
            - type
            - name
            - associations
        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.. 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 transcript entity.
                type: array
                minItems: 1
                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
    TranscriptEntityLink.Type:
        description: |
            A reference to a transcript entity contained within this transcript.
        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 transcript entity. (E.g., "Basic", "Certificate", "CoCurricular", etc.)
                type: string
                enum: 
                    - Basic
                    - Competency
                    - Course
                    - Degree
                    - Certificate
                    - Assessment
                    - CoCurricular
            entityId: 
                description: The id of the associated transcript entity. Model Primitive Datatype = NormalizedString
                type: string
        additionalProperties: true
    TranscriptEntitySet.Type:
        description: |
            A collection of transcript entities, partitioned by entity types. Note that all transcript entities referenced within a transcript 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 transcript entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Assessment.Type"
            certificates: 
                description: |
                    Collection of all certificate transcript entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Certificate.Type"
            coCurriculars: 
                description: |
                    Collection of all co-curricular transcript entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/CoCurricular.Type"
            competencies: 
                description: |
                    Collection of all competency transcript entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Competency.Type"
            courses: 
                description: |
                    Collection of all course transcript entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Course.Type"
            degrees: 
                description: |
                    Collection of all degree transcript entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Degree.Type"
            basicEntities: 
                description: |
                    Collection of all basic transcript entities.
                type: array
                minItems: 0
                items: 
                    $ref: "#/definitions/Basic.Type"
        additionalProperties: true
    URL.Type:
        description: |
            ...not supplied...
        type: string
        format: uri
    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: 
                    - fullsuccess
                    - server_busy
                    - invaliddata
                    - 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
                    - processing
                    - failure
                    - unsupported
            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: 
                description: |
                    The set of reported code minor status codes.
                $ref: "#/definitions/imsx_CodeMinor.Type"
        additionalProperties: false
        

toc | top

About this Document

Title: IMS Extended Transcript 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: September 8, 2017
Status: IMS Candidate Final
Summary: The IMS Extended Transcript Service is used to exchange information about users and their achievements. This standard defines a data model for extended transcripts. It also describes how this data can be exchanged using service calls. This document contains the REST/JSON Binding description for the Extended Transcript 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 September 8, 2017 Candidate Final version of the Extended Transcript 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 Extended Transcript Service REST/JSON Binding v1.0

Date: September 8, 2017

toc | top