IMS Final Release

 

IMS OneRoster™ Specification

Version 1.0 Final

Date Issued:            3 June 2015

Latest version:         http://www.imsglobal.org/lis/

 

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 © 2015 IMS Global Learning Consortium. All Rights Reserved.

Use of this specification to develop products or services is governed by the license with IMS found on the IMS website: http://www.imsglobal.org/license.html.

Permission is granted to all parties to use excerpts from this document as needed in producing requests for proposals.

The limited permissions granted above are perpetual and will not be revoked by IMS or its successors or assigns.

THIS SPECIFICATION IS BEING OFFERED WITHOUT ANY WARRANTY WHATSOEVER, AND IN PARTICULAR, ANY WARRANTY OF NONINFRINGEMENT IS EXPRESSLY DISCLAIMED. ANY USE OF THIS SPECIFICATION SHALL BE MADE ENTIRELY AT THE IMPLEMENTER'S OWN RISK, AND NEITHER THE CONSORTIUM, NOR ANY OF ITS MEMBERS OR SUBMITTERS, SHALL HAVE ANY LIABILITY WHATSOEVER TO ANY IMPLEMENTER OR THIRD PARTY FOR ANY DAMAGES OF ANY NATURE WHATSOEVER, DIRECTLY OR INDIRECTLY, ARISING FROM THE USE OF THIS SPECIFICATION.

For comments and feedback, join the discussion in our public forums

 

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

Trademark Information: http://www.imsglobal.org/copyright.html
Document Name:  IMS OneRoster Specification
Revision: 3 June 2015

 

1.               Introduction

Learning Information Services (LIS) is a standard which is maintained by IMS Global. The standard addresses the exchange of student data (about people, courses, enrollments and grades) between different educational systems. The standard was created by IMS members who typically represent the learning and student information systems used in higher education.

An assessment of LIS was undertaken by IMS Members representing the interests of the K12 sector. They found LIS to broadly meet their needs when it came to student enrollment scenarios, but desired extra functionality when it came to the transport of grades and gradebooks.

The group wanted to use functionality of LIS, but make it simpler to use. This was done by addressing documentation. In LIS, there are eleven documents which describe the eleven LIS services and the information model that underpins them. There are then more documents which describe XML schemas, WSDL files, conformance tests and more. Most of these documents are generated from the computer UML models of LIS, and then augmented with highly technical commentary.

Further simplification was achieved in the data model.  In full LIS, to specify a name currently needs two vocabularies to describe a name and its elements. The author does not believe that the creators of LIS set out to deliberately create an overcomplicated standard. The problem that LIS solves is inherently complicated (specifically in HE). There is perhaps an argument that LIS has been subject to a wide proliferation of ‘alternative scenarios’ into the core specification itself. The author argues also that the highly “optional” nature of the LIS data model has not helped.

Given those concerns, the LIS group created the CORE PROFILE of LIS, which limited implementers to building a subset of the services and operations. The core profile means that developers need only consider the read and delete operations for the person, group, membership and course section services. Conformance to the core profile can be tested, and all of the LIS conformant products to date are to the core profile.

The LIS group also created the FINAL GRADE profile of LIS, and this is a statement of the operations that developers need to build in order to move final grades for course sections between systems. Conformance to this profile can be tested, but to date, no developers have submitted software for formal testing.

This document describes work to be undertaken in order to:

  • Widen the functionality around grade transfer (for K12)
  • Simplify (‘narrow’) the Data Model for LIS to make it more appropriate to K12.

This work is to be carried out in the context of a RESTful binding.

1.1.         References

[LTI, 10]                IMS Learning Tools Interoperability (LTI) v1.0, IMS Global, May 2010.

[LIS, 13]                IMS Learning Information Services, IMS Global, July 2013.

 

2.               Specific Requirements for LIS in K12

The following are the requirements for the LIS profile for K12.

This table of requirements has been updated since the previous version of this document. Requirements removed from the previous version are shown in StrikeThrough. New requirements from the previous version are shown under the “NEW REQUIREMENTS” line. When updating this document to a new version, delete any strikethrough requirements, and move all new requirements above the “NEW REQUIREMENTS” line. Add strikethrough to any now deprecated requirements.

 

ID#

Requirement

1

Support for a term object, with fields: ID, Title, Start Date, End Date

2

Support for  a username field in Person

3

Support for a “Category” in relation to a line item.

4

Category fields: ID, Title, Weight, Drop Lowest, Calculated By [vocabulary controlled]

5

Support for a Grade Comment in Result

6

Support for an “Assignment” in relation to a Line Item

7

Assignment Fields: ID, Title, Description, Due Date, Category [see 3], Term [see 1], Grading Scale [result value]

8

RESTful Binding (HTTP Verbs, ‘normal’ RESTful URL patterns

9

JSON or JSON-LD Binding

10

Solution also possible in SOAP / WSDL

11

Decide if there are multiple data types per file / message, or just one data type per file / message

12

Simple Data Types: School, Course, Class, Teacher, Student, Term

13

Simple Data Type: School = School ID and School Name

14

Simple Data Type: Student = Student ID and Student Name

15

Simple Data Type: Course = Course ID and Course Name

16

Simple Data Type: Class = Class ID and Class Name

17

Simple Data Type: Teacher = Teacher ID and Teacher Name

18

A school has multiple courses; a course has multiple classes; users take multiple classes and classes are made up of multiple users. Teachers teach in many Schools, Learners Learn in many Schools, A school has many teachers, a school has many learners

19

There must be a notion of data and transactions security (authorization and encryption), which uses two-legged oAuth, as LTI does

--

NEW REQUIREMENTS FL Meeting 21.11.2014

20

Assignment Field: Date Assigned

21

Define a structure for multiple levels or organization (school, district, state, country)

22

Add a notion of “grade” – e.g. Elementary, Middle, High

23

Class Field: Grade

24

Course Field: Grade

25

Add a notion of a Grading Period, which is a unit of time, in which a lineitem has been assessed

26

Assignment Field: Grading Period

27

Modify the vocabulary for Result Status: Not Submitted, Submitted, Partially Graded, Fully Graded, Exempt

28

Remove Result Value from Result (Grade)

29

Class Field: Subject(s)

30

Course Field: Subject(s)

31

User Field: Student ID#, Teacher ID# - a human readable identifier for users

32

User Field: Contact Information – Email, SMS, Phone

33

User Field: Parent Information, User Type {check LIS}

34

Add API entry point to get all classes for student

35

All classes: Add a version id, or a date, so that requesters can access just the records that have changed, Add a status (“active or inactive”).

36

Add support for an extensions mechanism, allowing new fields to be passed in the JSON.

 

NEW REQUIREMENTS: 12.01.2015

37

Add endpoints: classes for teacher, students for class in school, teachers for class in school

38

Make explicit the relationships between objects

39

Add term information to class

40

Add a mechanism for adding metadata to classes

41

Add LTI User ID field to user  LTI User ID field to be renamed (07.04.2015)

 

NEW REQUIREMENTS: 26.01.2015

42

Add Demographics to User

43

Break out enrolments into own object

Table 2.1: Requirements for LIS in K12.

3.               Design

3.1.         Restful Bindings - Data Types [R9]

3.1.1.         Introduction [R18]

The basic data model is shown below, with the following scenario: A school teaches over a number of terms. A school teaches a number of courses, employs a number of teachers, and educates a number of students.

A class is an instance of a course which is taught in a particular term. A course can consist of a number of classes. A class is assessed via a number of line items (columns in a gradebook), and a line item can be categorized. Students taking a class are assessed by grading; a lineitem will have zero or more results, but potentially only one result per student.

This section shows how the following relationships were derived from the base classes in LIS; a JSON binding is also provided.

Figure 3.1: Basic Data Model

Note: to avoid confusion, if no context is given, then the word “Grade” means the education level of a class or course (e.g. “1st Grade, 9th Grade etc.). Result is the word used to mean educational achievement (e.g. a Grade A, or 78%). The assessment of assignments (represented by a line item) would yield results.

3.1.2.         The Base Class [R35, R40]

All classes in the REST binding descend from the base class. This class defines that all objects must share some common properties:

Figure 3.2: Base Class with Status Enumeration

·         SourcedId: All Objects MUST be identifiable via a Sourced Id. This is a GUID System ID for an object. This is the GUID that SYSTEMS will refer to when making API calls, or when needing to identify an object. It is RECOMMENDED that systems are able to map whichever local ids (e.g. database key fields) they use to SourcedIds.

·         Status: All objects MUST BE either “active”, “inactive” or “tobedeleted”.  Something which is flagged “tobedeleted” is to be considered safe to delete. Systems can delete records that are flagged as such if they wish, but they are not under any compulsion to do so. An “inactive” record is one which is simply not active, but it should not be considered safe to delete.

·         DateLastModified: All objects MUST be annotated with the date upon which they were last modified. This enables requesters to query for just the latest objects. Dates MUST be expressed in W3C profile of ISO 8601 and expressed in the UTC timezone (which is common on most servers anyway).

·         Metadata: All objects CAN be annotated with Metadata. This spec is silent on what implementers may consider to be appropriate metadata.

Data Model

 

Data Element Name

Multiplicity

Example / Notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

“boarding”: “false”

Table 3.1: Data Elements for Base Class

Dates:

Dates MUST be expressed using ISO 8601 format: http://tools.ietf.org/html/rfc3339. This is JavaScript’s prevailing data format:

YYYY-MM-DDTHH:MM:SS.mmmZ

An example of which:

2012-04-23T18:25:43.511Z

The Z denotes the UTC timezone.

For brevity, the UML diagrams will only show the SourcedId field. The JSON bindings will include all of the base class fields.

Metadata:

Metadata is represented in attribute/value pairs.  The attribute is the name of the metadata field, and the value is the value of the metadata, For example, if wanting to show the metadata of field X, with value “IMS”, the attribute/value pair is: “X:IMS”.

It is RECOMMENDED that where metadata is used, it is drawn from vocabulary controlled files. This eliminates a proliferation of free text equivalencies from entering the data (e.g. “Florida” vs “FL”, vs “Florida, USA”. In such cases either the attribute, or the value (or both) MUST be a URI which references the attribute and/or value from an appropriate vocabulary file.

Appendix one shows a list of metadata fields and vocabularies that have been suggested by members.

Example in JSON (showing an ncesId for a fictitious private female only boarding school that is also an IMS associate member):

 

{

   “metadata” : {

     “ncesId”: “8892928234”

     “classification” : “private”

     “gender” : “female”

     “boarding” : “true”

   “http://www.imsglobal.org/memberLevel”:

   “http://www.imsglobal.org/memberLevel/associate”

   }

}

Note that in the examples that follow for the other classes, metadata is only included where plausible terms have been identified.

3.1.3.         ORG [R21, R40]

ORG is defined here as a structure for holding organizational information. An ORG might be a school, or it might be a local, statewide, or national entity. ORGs will typically have a parent ORG (up to the national level), and children, allowing a hierarchy to be established.

School is defined here as the place where the learning happens. Most commonly this is the data that describes a bricks and mortar building, or, in the case of a virtual school, the virtual school organization. For enrollment and result reporting purposes, little information about this organization is required. Later versions of the specification could add further information, such as an address, for example.

A common example of a local organization is a school district.

Note that although School is a type of org, the default entry point for requests in most places will be a school. The API (see below) provides many school based entry points, whilst still allowing for more generic reading of ORGs, for those applications that need to.

The closest analogue in LIS is the “org” field which is found in various objects such as CourseSection.

Figure 3.3: LIS ORG Data Model

ORG is derived from LIS Org:

Figure 3.4: Proposed ORG Data Model

Suggested Optional Metadata for Schools:
Classification, Gender, Boarding, NCES ID (See Appendix A1)

Data Model

 

Data Element Name

Multiplicity

Example / Notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

“Classification”: “Public”

name

1

IMS High

type

1

school

identifier

0..1

Human readable identifier for this org (e.g. NCES ID).

parent

0..1

(link to parent (If applicable))

children

0..*

(link to children (if applicable))

Table 3.2 Data Elements for Organizations

JSON Representation

NOTE: In order to make all examples look clearer, commas have been omitted from the end of lines.

{

   “org”: {

     “sourcedId” : “<sourcedId of this org>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this ORG was last modified>”

     “name” : “<name of the org>”

     “type” : “school | local | state | national”

     “identifier” : “<human readable identifier for this organization>”

     “metadata” : {

        “ncesId”: “0808120938”

     }

     “parent” : {

        “href” : “<href to the parent org>”

        “sourcedId” : “<sourcedid of the parent org>”

        “type” : “org”

     },

     “children” : [

     {

        “href” : “<href of the first child org>”

        “sourcedId” : “<sourcedid of the first child org>”

        “type” : “org”

     },

     …

     {

        “href” : “<href of the n’th child org>”

        “sourcedId” : “<sourcedid of the n’th child org>”

        “type” : “org”

     }

     ]

}

}

The JSON representation of an array of schools is as follows:

{

   “orgs”: [

   {

     “sourcedId”: “<sourcedid of first school>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this school was last modified>”          

     “identifier”: “0808120938”

     “name” : “<name of first school>”

     “type” : “school”

     “parent” : {

        “href” : “<href to the parent org>”

        “sourcedId” : “<sourcedid of the parent org>”

        “type” : “org”

     }

   },

   ….

   {

     “sourcedId”: “<sourcedid of n’th school>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this school was last modified>”

     “identifier”: “0808120938”

     “name” : “<name of n’th school>”

     “type” : “school”

     “parent” : {

        “href” : “<href to the parent org>”

        “sourcedId” : “<sourcedid of the parent org>”

        “type” : “org”

     }

 

}]

}

3.1.4.         AcademicSessions [R1, R12, R25]

AcademicSessions represent durations of time. Typically they are used to describe terms, grading periods, and other durations, (e.g. school years).

Term is used to describe a period of time during which learning will take place. Other words for term could be in common use around the world (e.g. Semester). The important thing is that Term is a unit of time, often many weeks long, into which courses are scheduled.

Grading Period is used to represent another unit of time, that within which line items are assessed. A term may have many grading periods, a grading period belongs to a single term. A class may be assessed over several grade periods (represented by a line item being connected to a grading period).

LIS does not have a Term object, but version 2.0.1 of LIS notes that creating a term object is desirable. Current LIS best practice is to use the Group object (perhaps with an extension). It is proposed that a new object is created specifically to handle academic sessions. The parent / child attributes of academic sessions allow terms to be connected to their grading periods and vis versa.

Figure 3.5: Proposed Term Data Model

Data Model

 

Data Element Name

Multiplicity

Example / Notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

“comment” : “grading period 1”

title

1

Spring Term

startDate

1

2012-01-01

endDate

1

2012-04-30

type

1

”term” | “gradingPeriod” | “schoolYear | semester”

parent

0..1

(link to parent (if applicable))

children

0..*

(link to children (if applicable))

Table 3.3: Data Elements for Academic Sessions

JSON Representation

 

{

   “academicSession”: {

     “sourcedId” : “<sourcedid of this academicSession (term)>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this object was last modified>”

     “title” : “<name of the academicSession (term)>”

     “startDate” : “<acaemicSession (term) start date>”

     “endDate” : “<academicSession (term) end date>”

     “type” : “term”

     “parent” : {

        “href” : “<href of the parent for this academic session>”

        “sourcedId” : “<sourcedId of the  parent for this academic session>”

        “type” : “academicSession”

     }

     “children” : [{

        “href” : “<href of 1st child for this academic session>”

        “sourcedId” : “<sourcedId of the 1st child for this academic session>”

        “type” : “academicSession”

     },

     {…}

     ]

  }

}

The JSON representation of a Grading Period uses the same structure, but also carries the relationship to the term it belongs to:

 

{

   “academicSession”: {

     “sourcedId” : “<sourcedid>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this object was last modified>”

     “title” : “<name of the academicSession (grading period)>”

     “startDate” : “<academicSession (grading period) start date>”

     “endDate” : “<academicSession (grading period) end date>”

     “type” : “gradingPeriod”

     “parent” : {

        “href” : “<href of the parent for this academic session>”

        “sourcedId” : “<sourcedId of the  parent for this academic session>”

        “type” : “academicSession”

     }

    }

}

3.1.5.         Enrollments [R43]

An enrollment is the name given to that fact that an individual will be taking part in a course or class. In the vast majority of cases, users will be students learning in a class, or teachers teaching the class. Other roles are possible too. LIS uses the membership construct to model enrollments:

Figure 3.6: Membership Data Model from LIS

It is proposed that the enrollment object takes a subset of these elements:

Figure 3.7: Enrollment Data model

Data Model

Data Element Name

Multiplicity

Example / Notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

“comment” : “primary choice”

userSourcedId

1

89898982

classSourcedId

1

117819812

schoolSourcedId

1

828928928

role

1

“teacher”

primary

0..1

Applicable only to teachers. Only one teacher should be designated as the primary teacher for a class.

Table 3.4: Enrollment Data model

 

JSON Representation

NOTE: The abstract data model requires the sourcedIds of the user, school and class for the enrolment. In the JSON these need to be specified as links. This means a full href as well as a sourcedId, as per below.

 

{

   “enrollment” : {

     “sourcedId” : “<sourced id of this enrollment>”

     “status” : “<status of this enrollment>”

     “dateLastModified”: “<date this enrollment was last modified>”

     “role” : “teacher | student | parent | guardian | relative | aide | administrator”

     “primary” : true | false

     “user” : {

         “href” : “<href of the user for this enrollment>”

        “sourcedId” : “<sourcedId of the user for this enrollment>”

        “type” : “user”

     }

     “class” : {

        “href” : “<href of the class for this enrollment>”

        “sourcedId” : “<sourcedId of the class for this enrollment>”

        “type” : “class”

     }

     “school” : {      

        “href” : “<href of the school for this enrollment>”

        “sourcedId” : “<sourcedId of the school for this enrollment>”

        “type” : “org”

     }

   }

}

 

3.1.6.         Course [R15, R22, R24, R29]

A Course is a course of study onto which a student may be enrolled. It typically has a curriculum and may be taught to different students by different teachers. It is likely that several classes of a single course may be taught in a term. (For example, a school runs Grade 9 English in the spring term. There are four classes, each with a different 30 students, taught by 4 different teachers. However the curriculum for each of those four classes is the same – the course curriculum).

LIS uses a hierarchy of course objects to represent courses. The most appropriate here is Course Template. 

Figure 3.8: LIS Course Template Data Model

Note that Course Template is outside of the core profile of LIS.

It is proposed that the Course object take a subset of the elements from Course Template, adding Grade and Subject, as follows:

Figure 3.9: Proposed Course Data Model

Suggested Optional Metadata:
Frequency/Duration (See Appendix One)

Data Model

 

Data Element Name

Multiplicity

Example / Notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

“core academic course” : “yes”

title

1

Basic Chemistry

schoolYear

0..1

(link to academicSession, if applicable)

courseCode

1

CHEM101

grade

0..1

9

subjects

0..*

“chemistry”

org

0..1

(Link to org, if applicable)

Table 3.5: Data Elements for Courses

JSON Representation

 

{

   “course” : {

     “sourcedId”: “<sourcedId of the course>”

     “status” : “active | inactive | tobedeleted”

“dateLastModified” : “<date this object was last modified>”
“metadata” : {

 

        “duration” : “<how long this course takes to teach>”

     }

     “title” : “<title of the course>”

     “schoolYear” : {

        “href”: “<href of the academicSession (school year) related to this course>”

        “sourcedId”: “<sourcedId of the academicSession (school year) related to this course>”

        “type” : “academicSession”

     }

     “courseCode” : “<course code for the course>”

     “grade” : “<the grade for this course>”

     “subjects” : [“1st subject”,”2nd subject”..”n’th subject” ]

     “org” : {

        “href”: “<href of the org related to this course>”

        “sourcedId”: “<sourcedId of the org related to this course>”

        “type” : “org”

     }

   }

}

3.1.7.         Class [R16, R21, R23, R30, R38, R39]

A class is an instance of a course, onto which students and teachers are enrolled. A class is typically held within a term.

LIS uses the both the course offering and the course section to describe the notion of a class.  Course Offering locates a course template in time (i.e. by assigning an academic session to it), whilst the course section breaks the offering up into its constituent parts (e.g. labs, tutorials and lectures). It is proposed that Class typically be drawn from the fields in Course Section, as this is the object that represents the actual scheduled learning:

Figure 3.10: LIS CourseSection Data Model

It is proposed that the Class object take a subset of these elements, adding Grade: and Subject

Figure 3.11: Proposed Class Data Model

Data Model

 

Data Element Name

Multiplicity

Example  / notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

“comment”: “9am to 11am”

title

1

Basic Chemistry

classCode

0..1

Chem101-Mr Rogers

classType

0..1

scheduled

location

0..1

“room 19”

grade

0..1

9

subjects

0..*

“chemistry”

course

0..1

(Link to course)

school

1

(Link to school)

terms

0..*

(links to academicSessions (terms))

Table 3.6: Data Elements for Classes

JSON Representation

{

   “class” : {

     “sourcedId”: “<sourcedId of this class >”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this class was last modified>”

     “title” : “<name of this class>”

     “classCode” : “<human readable code for this class>”

     “classType” : “homeroom | scheduled”

     “location” : “<physical location of this class”>

     “grade” : “<grade of this class>”

     “subjects” : [<“1st subject ”,”2nd subject”..”nth subject”>]

     “course” : {

        “href”: “<href of the course that this is a class of>”

        “sourcedId”: “<sourcedId of the course that this is a class of>”

        “type” : “course”

     }

     “school” : {

        “href”: “<href of the school that this is a class of>”

        “sourcedId”: “<sourcedId of the school that this is a class of>”

        “type” : “org”

     }

     “terms” : [{

        “href”: “<href of the first term that this class is in>”

        “sourcedId”: “<sourcedId of the first term that this class is in>”

        “type” : “academicSession”

     }, {

     …

     }]

 

     }

}

 

3.1.8.         Teachers and Students [R2, R14, R17, R31, R32, R33, R38, R41, R42]

Teachers and Students are human beings that are teaching or studying in a class respectively. LIS represents these with Person. For the case of binding, it is proposed that a single User class is used to represent both teachers and students, and that a role element be used to distinguish a user’s natural role. In the rest binding to follow, it is possible to select teachers and students within a school, course or class. In LIS, users have an “institution role” set within the person record to identify their (primary) role.

Note that this requirement is expanded to introduce other types of human: parents, guardians, relatives and aides.

Humans may have relationships with other humans. For example, a student may have parents. The “agents” attribute allows for relationships between humans to be expressed. Note that these are typically from the point of view of the student – so a student will link to its parents (via the agent attribute). The reverse view MUST also be modeled, so for example, a user of role “parent” MUST have agents which are of type “student”.
Note: teachers MUST NOT be declared as agents of students – the teaching relationship is covered via enrollments.

Figure 3.12: LIS Person Data Model

It is proposed that the User object take a subset of these elements:

Figure 3.13: Proposed User Data Model with Role Enumeration

Demographics

Demographics information is taken from the Common Educational Data Standards from the US government. (http://ceds.ed.gov). Demographics are OPTIONAL. See Appendix One for the demographic terms and data types for those terms.

Data Model

 

Data Element Name

Multiplicity

Example  / notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

 

username

1

pjn@imsglobal.org

userId

0..1

This is an external user id that should be used for this user, if for some reason the sourcedId cannot be used. This might be an active directory id, an LTI id, or some other machine readable identifier that is used for this person.

givenName

1

Phil

familyName

1

Nicholls

role

1

teacher

identifier

0..1

9898-PJN

email

0..1

pjn@imsglobal.org

sms

0..1

+44 07759 555 922

phone

0..1

+44 07759 555 922

agents

0..*

<links to other people>

orgs

1..*

<links to orgs> (in most cases, this is a single link to a school, but could be to a district or national org). People might also be linked to multiple organizations.

demographics

0..1

<link to demographics>

Table 3.7: Data Elements for Users

JSON Representation

{

   “user” : {

     “sourcedId” : “<sourcedid of this user>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this user was last modified>”

     “username” : “<username to use for this user>”

     “userId” : “<active directory / lti user id / some other id >”

     “givenName” : “<this user’s given name>”

     “familyName : “<this user’s family name>”

     “role” : “teacher | student | parent | guardian | relative | aide | administrator”

     “identifier” : “<human readable ID, such as student id>”

     “email” : “<email address for this user>”

     “sms” : “<sms number for this user>”

     “phone” : “<phone number for this user>”

     “agents” : [

        {

           “href” : “href of the first agent (e.g. parent) for this user”

           “sourcedId” : “sourcedid of the first agent for this user”

           “type” : “user”

        },

        …

        {

           “href”: “href of the n’th agent for this user”

           “sourcedId” : “sourcedid of the n’th agent for this user”

           “type” : “user”

        }

     ]

     “demographics” : {

        “href” :”<href of the demographics data for this user>”

        “sourcedId” :”<sourcedid of the demographics data for this user>”

        “type” : “demographics”

     }

     “orgs” : [{

        “href”: “<href of the 1st org that this user is attached to>”

        “sourcedId”: “<sourcedId of the 1st org that this user is attached to>”

        “type” : “org”

     } …

     {

        “href”: “<href of the nth org that this user is attached to>”

        “sourcedId”: “<sourcedId of the nth org that this user is attached to>”

        “type” : “org”

     }]

 

}

}

 

3.1.9.         Demographics Data [R42]

Demographics information is taken from the Common Educational Data Standards from the US government. (http://ceds.ed.gov). Demographics are OPTIONAL.

Note that demographics data is held in its own service, and that access to this service is considered privileged. Not all consumer keys will be able to request demographics data.

Demographic Data is modeled in LIS, but the sort of demographic data required by K12 is very different to that modeled in LIS. For this reason, new structures have been created.

The sourcedId of the demographics MUST be the same as the sourcedId of the user to which it refers.

Figure 3.14: Data Elements for Demographics

 

Data Model
 

Demographic Term

Multiplicity

Data Type

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

birthdate

0..1

Date

sex

0..1

Vocabulary (“Male” | “Female” )

americanIndianOrAlaskaNative

0..1

Vocabulary (“Yes” | “No” )

asian

0..1

Vocabulary (“Yes” | “No” )

blackOrAfricanAmerican

0..1

Vocabulary (“Yes” | “No” )

nativeHawaiianOrOtherPacificIslander

0..1

Vocabulary (“Yes” | “No” )

white

0..1

Vocabulary (“Yes” | “No”)

demographicRaceTwoOrMoreRaces

0..1

Vocabulary (“Yes” | “No”)

hispanicOrLatinoEthnicity

0..1

Vocabulary (“Yes” | “No” )

countryOfBirthCode

0..1

Vocabulary – https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20002

stateOfBirthAbbreviation

0..1

Vocabulary – https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20837

cityOfBirth

0..1

String

publicSchoolResidenceStatus

0..1

Vocabulary - https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20863

Table 3.8: Data Elements for Demographics

 

 

JSON Representation:

{

     “demographics” : {

        “sourcedId” : “<sourcedid of this demographics record (same as user referenced)>”

        “status” : “active | inactive | tobedeleted”

        “dateLastModified” : “<date these demographics were last modified>”

        “birthdate” : “<value>” (e.g. 1980-01-01)

        “sex” : “<value>” (e.g. Male)

        “americanIndianOrAlaskaNative” : “<value>” (e.g. No)

        “asian” : “<value>” (e.g. No)

        “blackOrAfricanAmerican” : “<value>” (e.g. Yes)

        “nativeHawaiianOrOtherPacificIslander: “<value>”

        “white” : “<value>”

        “demographicRaceTwoOrMoreRaces” : “<value>”

        “hispanicOrLatinoEthnicity” : “<value>”

        “countryOfBirthCode” : “<value>” (e.g. US)

        “stateOfBirthAbbreviation” : “<value>” (e.g. NY)

        “cityOfBirth” : “<value>” (e.g. New York)

        “publicSchoolResidenceStatus : “<value>” (e.g. 01652)

     }

}

3.1.10.      Line Item Categories [R3, R4]

A Category is the name given to a grouping of line items. (Line Items being equivalent to assignments which students will complete). Examples of categories include “homework”, “quizzes” or “essays”. LIS has no equivalent of category.

It is proposed that the Category object be defined as follows:

Figure 3.15: Proposed Category Data Model

Data Model

 

Data Element Name

Multiplicity

Example  / notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

 

title

1

Homework

Table 3.9: Data Elements for Categories

JSON Representation

{

   “category” : {

     “sourcedId” : “<sourcedId of this category>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this object was last modified>”

     “title” : “<title of this category>”

}

}

3.1.11.      Line Items [R6, R7, R20]

Line Items are assignments in LIS, they make up the column headings in a gradebook, and many students will each complete line items as they are assessed. LIS already describes a lineitem as follows:


Figure 3.16: LIS Line Item Data Model

It is proposed that the Line Item object take a subset of these elements, and adds a few more which are relevant to K12.

Figure 3.17: Proposed Line Item (assignment) Data Model

The resultValue takes from the LIS resultValue, which describes the assessment scheme that can be used for a particular line item. ResultValues in LIS take two forms – a simple score with a minimum and a maximum, or a set of scale values (“A”, “B+” etc.). In the interest of simplicity, it is proposed that only the former is used:

Figure 3.18: LIS Result Value Data Model

Data Model

 

Data Element Name

Multiplicity

Example  / notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

 

title

1

Maths Test 1

description

0..1

Simple addition test

assignDate

1

2012-01-01T18:25:43.511Z

dueDate

1

2012-01-05T18:25:43.511Z

class

1

<link to class>

category

1

<link to category>

gradingPeriod

1

<link to grading period>

resultValue

1

“min” : “0.0”, “max” : “100.0”

Table 3.10: Data Elements for Line Items

JSON Representation

{

   “lineitem” : {

     “sourcedId” : “<sourcedId of this lineitem>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this object was last modified>”

     “title” : “<title of this lineitem>”

     “description” : “<description of this lineitem>”

     “assignDate” : “<date that this lineitem was assigned>”

     “dueDate” : “<date that this lineitem is due>”

     “category” : {

        “href” : “<href to this category>”

        “sourcedId” : “<sourcedId of this category>”

        “type” : “category”

     }

     “class” : {

        “href” : “<href to the class this line item is for>”

        “sourcedId” : “<sourcedId of the class this line item is for>”

        “type” : “class”

     }

     “gradingPeriod” : {

        “href” : “<href to this grading period>”

        “sourcedId” : “<sourcedid of this grading period>”

        “type” : “academicSession”

     }

     “resultValue” : {

        “min” : “<floating point value of the minimum possible score>”

        “max”: “<floating point value of the maximum possible score>”

     }

}

}

3.1.12.      Results [R5. R27, R28]

Results represent individual scores for line items:

Figure 3.19: LIS Result Data Model

It is proposed that the Result object takes a subset of these elements:

Figure 3.20: Proposed Result Data Model

Data Model

 

Data Element Name

Multiplicity

Example  / notes

sourcedId

1

9877728989-ABF-0001

status

1

active

dateLastModified

1

2012-04-23T18:25:43.511Z

metadata

0..1

 

lineItem

1

<link to line item>

student

1

<link to student>

score

1

67.0

resultStatus

1

fully graded

date

1

2012-01-05T18:25:43.511Z

comment

0..1

“excellent”

Table 3.11: Data Elements for Results

 

JSON Representation

 {

   “result” : {

     “sourcedId” : “<sourcedid of this grade>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this result was last modified>”

     “lineitem” : {

        “href” : “<href to this lineitem>”

        “sourcedId” : “<sourcedId of this lineitem>”

        “type” : “lineitem”

     }

     “student” : {

        “href” : “<href to this student>”

        “sourcedId” : “<sourcedId of this student>”

        “type” : “user”

     }

     “score” : “<score of this grade>”

     “resultstatus” : “not submitted | submitted | partially graded | fully graded | exempt”

     “date” : “<date that this grade was assigned>”

     “comment” : “<a comment to accompany the score>”

 

}

}

 

 

 

3.2.         RESTful bindings [R8, R11, R19, R34, R37] - Interface

This section describes the RESTful binding of the data model.

3.2.1.         API Root URL and Version

The API Root URL MUST be /learningdata.

To allow further versions of the specification to exist in a controlled manner, the initial version number MUST be /v1.

Example: https://imsglobal.org/learningdata/v1/*

Responses to Requests which are sent to this root URL MUST include:

  • A list of URLs to the endpoints supported under the root URL.
  • A link the developer documentation (for example, the online version of the specification, a link to online API documentation).

3.2.2.         Endpoints

Table 2 shows the permitted HTTP verbs for each endpoint / resource type. For Version 1, only READ MUST be supported. The other HTTP verbs will feature in later versions of the specification.

At a minimum the endpoints for each data type MUST be implemented. Several convenience endpoints are also introduced (for example, calls to get all students in a class, or calls to get all students). This is to avoid the need for users of the service to be forced to specify search terms simply to get back data for what are envisaged to be common use cases.

 

Service Call

Endpoint

GET

(read)

getOrgs

/orgs

Return collection of Orgs

getOrg

/orgs/{id}

Return Specific Org

getSchools

/schools

Return collection of schools

getSchool

/schools/{id}

Return specific school

getAcademicSessions

/academicSessions

Return collection of all academic sessions

getAcademicSession

/academicSessions/{id}

Return specific Academic Session

getTerms

/terms

Return collection of terms

getTerm

/terms/{id}

Return specific term

getGradingPeriods

/gradingPeriods

Return collection of grading periods

getGradingPeriod

/gradingPeriods/{id}

Return specific Grading Period

getCourses

/courses

Return collection of courses

getCourse

/courses/{id}

Return specific course

getClasses

/classes

Return collection of classes

getClass

/classes/{id}

Return specific class

getUsers

/users

Return collection of users

getUser

/users/{id}

Return specific user

getDemographics

/demographics

Return collection of demographics

getDemographic

/demographics/{id}

Return specific demographics

getEnrollments

/enrollments

Return collection of all enrollments

getEnrollment

/enrollments/{id}

Return specific enrollment

getTeachers

/teachers

Return collection of teachers

getTeacher

/teachers/{id}

Return specific teacher

getStudents

/students

Return collection of students

getStudent

/students/{id}

Return specific student

getCategories

/categories

Return collection of grading categories

getCategory

/categories/{id}

Return specific grading category.

getCoursesForSchool

/schools/{id}/courses

Return collection of courses taught by this school

getClassesForSchool

/schools/{id}/classes

Return collection of classes taught by this school

getEnrollmentsForClassInSchools

/schools/{id}/classes/{id}/enrollments

Return collection of all enrollments into this class

getStudentsForClassInSchool

/schools/{id}/classes/{id}/students

Return collection of students taking this class in this school.

getTeachersForClassInSchool

/schools/{id}/classes/{id}/teachers

Return collection of teachers taking this class in this school.

getEnrollmentsForSchools

/schools/{id}/enrollments

Return collection of all enrollments for this school

getStudentsForSchool

/schools/{id}/students

Return collection of students attending this school

getTeachersForSchool

/schools/{id}/teachers

Return collection of teachers teaching at this school

getTermsForSchool

/schools/{id}/terms

Return the collection of terms that are used by this school.

getClassesForTerm

/terms/{id}/classes

Return the collection of classes that are taught in this term.

getGradingPeriodsForTerm

/terms/{id}/gradingPeriods

Return the collection of Grading Periods that are part of this term.

getClassesForCourse

/courses/{id}/classes

Return the collection of classes that are teaching this course.

getClassesForStudent

/students/{id}/classes

Return the collection of classes that this student is taking.

getClassesForTeacher

/teachers/{id}/classes

Return the collection of classes that this teacher is teaching

getStudentsForClass

/classes/{id}/students

Return the collection of students that are taking this class.

getTeachersForClass

/classes/{id}/teachers

Return the collection of teachers that are teaching this class.

getResultsForClass

/classes/{class_id}/results

Return the collection of results (assessed grades) for this class.

getLineItemsForClass

/classes/{id}/lineitems

Return the collection of line items (Columns) in the gradebook for this class.

getResultsForLineItemForClass

/classes/{class_id}/lineitems/{li_id}/results

Return the collection of results (assessed grades), for this specific lineitem (Column) for this class.

getResultsForStudentsForClass

/classes/{class_id}/students/{student_id}/results

Return the collection of results (assessed grades), for this specific student, attending this class.

 

Table 3.12: HTTP Endpoints

Note: /schools/* is a shorthand convenience to avoid the requester needing to search for orgs of type school.

3.2.3.         Binding of Resource Data

JSON MUST be used to bind the resource data. Section 3.1 shows the data models that are required to be bound.

Parsers MUST be capable of parsing the JSON data shown in the UML and example bindings. Parsers MAY ignore any other JSON fields that they encounter, UNLESS those fields are in the extension space (see later).

3.2.4.         Pagination

It is expected that Student Information Systems may well contain massive amounts of data, and as such there is a real danger of data overload if entire collections are requested. To avoid this, implementations MUST adopt a pagination mechanism.

Pagination is controlled via two parameters that are appended to the request.

  • Limit – the number of results to return
  • Offset – the index of the first record to return. (zero indexed)

The default value for limit MUST be 100.

The default value for offset MUST be 0.

Example: return the first 10 resources in a collection of students:

GET https://imsglobal.org/learningdata/v1/students?limit=10

Example: return the second 10 resources in a collection of students:

GET https://imsglobal.org/learningdata/v1/students?limit=10&offset=10

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

It is RECOMMENDED that implementers pass back next, previous, first and last links in the HTTP Link Header.

Example:

503 student resources exist in the collection. Pagination is on the second page, in units of 10.

Link:

<https://imsglobal.org/learningdata/v1/students?limit=10&offset=20>; rel=”next”,

<https://imsglobal.org/learningdata/v1/students?limit=3&offset=500>; rel=”last”,

<https://imsglobal.org/learningdata/v1/students?limit=10&offset=0>; rel=”first”,

<https://imsglobal.org/learningdata/v1/students?limit=10&offset=0>; rel=”prev”

3.2.5.         Sorting

It MUST be possible for collections to be returned in a sorted order. It MUST be possible to sort the collection based on any data element in the core description of the resource. Sort requests MUST make use of the reserved word sort. (?sort=), and optionally the reserved word orderBy.

  • data_field MUST be used in the request to ask for the collection to be sorted on data field.
  • orderBy MUST be used in the request to ask for the collection to be ordered ascending (asc) or descending (desc).
  • Example:

To ask for a list of students sorted into ascending familyName order:

GET https://imsglobal.org/learningdata/v1/students?sort=familyName&orderBy=asc

3.2.6.         Filtering

It MUST be possible to filter collections for elements matching a certain criteria.

It MUST be possible to filter collections based on any data element in the core description of the resource.

Filter requests MUST consist of the form ?filter=<data field><predicate><value> <logical>

The data fields that can be used are those that are present in the class definition being filtered. So for example in “courses”, it MUST be possible to filter on: sourcedId, status, dateLastModified, title, grade and subjects.

Predicates MUST be chosen from the following predicates:

 

Predicate

Representation

Equals

=

Not Equal

!=

Greater Than

Greater Than or Equal

>=

Lesser Than

Lesser Than or Equal

<=

Contains

contains

Values MUST be enclosed within single quotes

Logical parameters allow more complex queries to be created. For version 1, it is RECOMMENDED that logical operations are limited to “AND” and “OR”.

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

<NestedObject>.<Property>

Note then when querying on metadata, the property is loosely typed.

Example:

To find a student with an Identifier of ND5848416:

https://imsglobal.org/learningdata/v1/students?filter=identifier='ND5848416'

encoded: https://imsglobal.org/learningdata/v1/students?filter=identifier%3D%27ND5848416%27

To ask for all schools with ncesid of 200:

GET https://imsglobal.org/learningdata/v1/schools?filter=metadata.ncesId=’200’

encoded: https://imsglobal.org/learningdata/v1/schools?filter=metadata.ncesId%3D%27200%27

Filter queries MUST be URL encoded.

Example:

To ask for a list of students with the familyName Jones:

Query: familyName=’jones’

GET https://imsglobal.org/learningdata/v1/students?filter=familyName%3D%27jones%27

To ask for a list of students whose familyName is jones and who were last modified after the 1st of January 2015:

Query: familyName=’jones’ AND dateLastModified>‘2015-01-01’

GET https://imsglobal.org/learningdata/v1/students?filter=familyName%3D%27jones%27%20AND%20dateLastModified%3E%272015%3D01-01%27

To ask for a list of all classes taught by teacher 123 which were last modified after the 1st of January 2015:

Query: dateLastModified>’2015-01-01’

GET https://imsglobal.org/learningdata/v1/teachers/123/classes?filter=dateLastModified%3E%272015%3D01-01%27

3.2.7.         Field Selection

It MUST be possible for requesters to select the range of fields to be returned. By default, all mandatory and optional fields from the core description of the resource MUST be returned. If any fields are specified in the request then the implementation MUST return those fields AND ONLY those fields. Any Field or fields from the Full Data Model MAY be requested. Any field or fields from the Data Model MAY be requested.

Field selection request MUST make use of the reserved word fields. The value of fields is a comma delimited list of the fields to return.

Example:

To ask for a list of students retuning only the given name and family name:

GET https://imsglobal.org/learningdata/v1/students?fields=givenName,familyName

3.2.8.         Error Handling

Implementations MUST be able to report the existence of errors that arise when processing the request. Error reporting MUST make use of the following HTTP response codes:

Error Code

Description

Notes

200

OK – It was possible to read the collection / resource

 

201

OK – New resource has been created

Reserved for version 1.X

204

OK – The resource was deleted successfully

Reserved for version 1.X

400

Bad Request – the Request was invalid and cannot be served.

 

401

Unauthorized – the Request requires authorization

 

404

Not Found – there is no resource behind the URI.

 

422

Entity cannot be processed – used where the server cannot validate an incoming entity.

Reserved for version 1.X

500

Internal Server Error

Avoid – use only if there is catastrophic error and there is not a more appropriate code.

Table 3.13: HTTP response error codes

It is RECOMMENDED that implementations also provide more information about errors to requesters in the form of a dedicated error payload. As more than one error can potentially occur, the payload should be ready to report an array of potential errors:

The error payload follows the prevailing LIS practice of specifying a CodeMajor, Severity, CodeMinor and description.

The LIS specifications list a great number of error payloads. For this specification, a subset is used:

CodeMajor: Enumeration: SUCCESS, FAILURE.

Severity: Enumeration: STATUS, ERROR, WARNING

CodeMinor: Enumeration: FULL SUCCESS, UNKNOWN OBJECT, INVALID DATA, UNAUTHORIZED

Description: A text string providing a human readable description of the error that happened.

Table 4 shows how these errors can be applied to the HTTP response codes:

 

Error Code

CodeMajor

Severity

Code Minor

200

SUCCESS

STATUS

FULL SUCCESS

400

FAILURE

ERROR

INVALID DATA

401

FAILURE

ERROR

UNAUTHORIZED

404

FAILURE

ERROR

UNKNOWN OBJECT

500

FAILURE

ERROR

 

Table 3.14: Error Payloads from LIS

In JSON:

{

   “errors”: [

   {

     “codeMajor”: “FAILURE”

     “severity” : “ERROR”

     “codeMinor”: “INVALIDDATA”,

     “description”: “the field ‘user_age’ does not exist”

}

   ]

}

It is RECOMMENDED that for successful requests, no error payload is returned, the HTTP status code should be enough. (This may be revised in version 1.X)

3.2.9.         Security [R19]

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

  • All Requests and Responses MUST be sent using Transaction Layer Security (TLS). Exchange of the signed certificates for endpoints between clients and servers is beyond the scope of this specification. Implementers of clients and servers are advised to look at the various 3rd party certificate signing services in order to obtain signed certificates.

In the interest of simplicity, and to get implementations up and running as fast as possible, version 1 of this specification uses the same 2-legged oAuth authorization approach as does IMS Learning Tools Interoperability™ (LTI).

OAuth signing is a security mechanism designed to protect POST and GET requests.

The OAuth 1.0 specification specifies how to construct a base message string and then sign that string using a secret. The signature is then sent as part of the GET request and is validated by the Implementation using OAuth. The website http://www.oauth.net contains the specification for OAuth 1.0 and sample libraries for implementing OAuth signing. For more information, implementers are directed to consult the oAuth documentation. For simplicity, an outline of the algorithm is presented below:

A service MUST issue a public oAuth consumer key and a private oAuth consumer secret to any clients that are authorized to use the service. Naturally each client will receive a different consumer key and consumer secret from each other client. Clients MUST:

  • Append the oAuth parameters from table 5 to the request Authorization HTTP header field.
  • Append the oAuth signature, which is a hash of the entire request string, and the oAuth parameters (except signature), encrypted via the oauth_consmer_secret, to the Authorization HTTP header field.

The following table lists the oAuth values which SHOUD be sent to the server:

 

Parameter

Description

Example

oauth_consumer_key

The public consumer key for the requester.

“Psydev-GW-001.shef.ac.uk”

oauth_signature_method

The type of encryption used

“HMAC-SHA1”

oauth_timestamp

The timestamp of the message, unix long milliseconds from 1st Jan 1970.

“1244843520”

oauth_nonce

Number to user once – used to avoid replay attacks, and should be unique per request. Servers should store the nonces for 90 minutes to ensure that they are not reused.

“1244843520435893000”

oauth_version

The version of oAuth to use.

“1.0”

oauth_signature

The signature of the request itself (without the extra oAuth parameters), encrypted using the oauth_consumer_secret.

“X78kljkljsdc%jksdcnj”

oauth_callback

Not Used – but may be required by library.

“about:blank”

Table 3.15: oAuth parameters

Servers MUST support the HMAC-SHA1 signing method with OAuth data passed as GET data.

NOTE that this security profile requires the client and server to have synchronized clocks.  The use of a configurable time interval can adjust for slightly-off clocks, but setting the interval too large is discouraged.

A service implementation MUST do the following to determine if a request is authorized:

  • Check that the timestamp is ok (ideally to within the specified time interval). If not ok, reject the request as unauthorized (with a suitable error description).
  • Check that the nonce has not been used before within the specified time interval. If it has, reject the request as unauthorized. If the nonce has not been used before, store it, so that it cannot be used again. It is RECOMMENDED that nonces are stored for 90 minutes.
  • Retrieve the value of the oAuth consumer secret by looking it up using the oAuth consumer key.
  • Create a hash of the request using HMACsha1, using the retrieved oAuth consumer secret.
  • If the calculated hash does not match the signature, the request is unauthorized.

Clients MUST NOT send the oAuth consumer secret in the request.

Creating the signature requires a precise algorithm to be followed from the oAuth specification. This algorithm is outlined below (see https://dev.twitter.com/oauth/overview/creating-signatures for more information). The signature is created from a hash of three different data values:

  • The HTTP Verb
  • The Url of the request
  • The parameters of the request (including the oAuth parameters).

To collect the parameters:

  1. Percent Encode every key and value to be signed.
  2. Sort the list of parameters alphabetically.
  3. For each key/value pair:
    Append the encoded key to the output sting.
    Append the ‘=’ character to the output string.
    Append the encoded value to the output string.
    If more key/value pairs remain, append a ‘&’ character to the output string

To create the signature base string:

  1. convert the HTTP method to uppercase and set the output string equal to this value.
  2. Append the ‘&’ character to the output String.
  3. Percent encode the URL and append it to the output String
  4. Append the ‘&’ character to the output String
  5. Percent encode the parameter String and append it to the output String.

This final signature base string is then encrypted using the consumer secret.

(for more information see the oAuth documentation).

3.2.10.      Serialization Format [R9]

For version 1, JSON data MUST be supported as the binding. Clients MAY ask for other bindings, but implementers are not obliged to provide them, and a 4XX response is valid. It is RECOMMENDED therefore to use the HTTP header field; Accept, with a value of “application/json”.

Implementers MUST use the HTTP header field: Content-Type, with a value of “application/json”, to inform requesters that results will be returned in JSON.

3.2.11.      Extensions [R36]

It is recognized that implementers may wish to extend the specification. The preferred mechanism for doing this is for implementers to use an extension space within the JSON, and then set their parsers to read those extension attributes. It is RECOMMENDED that the extension space elements are declared as follows:

 

ext_<implementer_specific>_<name_of_extension>

For example:

 

{

   “course” : {

     “sourcedId”: “<sourcedId of the course>”

     “status” : “active | inactive | tobedeleted”

     “dateLastModified” : “<date this object was last modified>”

     “title” : “<title of the course>”

     “courseNumber” : “<course code for the course>”

     “grade” : “<the grade for this course>”

     “subject” : “<subject of this course>”

“ext_psydev_course_rating” : “3”

   }

}

3.3.         SOAP bindings – Data Models [R10]

To bind this specification’s data model to SOAP means to look at the existing LIS data model. Where necessary this model needs to be extended.

3.3.1.         Org / School

As noted, the closest match to school in LIS is the org structure which is found in many of the main LIS classes.

ORG is not a top level object in and of itself.

There are two potential solutions here:

  1. Create a top level service which describes ORGs, and then map a school into an ORG.
  2. Use the Group structure to represent an ORG.

It is recommended that a top level service is created, although this would have a serious impact on the rest of the LIS were it for ORGS (the most correct way).

3.3.2.         Term and Grading Period

Terms are missing from LIS 2.0.1, but best practice suggests to use the GROUP construct to represent a term. This specification recommends that this best practice is followed. Course objects MUST use the Sourced ID of the group representing the term in their academicSession attribute.

The following fields in Group are mandatory when representing a term using the Group Structure:

  • SourcedId
  • GroupType (typeValue=”TERM” | typeValue=”GRADING_PERIOD”)
  • Org
  • Description
  • TimeFrame (begin, end)
  • Relationship

The following extensions are used:

  • Status (active or inactive)
  • DateLastModified (date)

Note that a TERM has many GRADING_PERIODs, therefore in the group structure, it is important to ensure that the relationships are set correctly.

3.3.3.         Course

The closest match to the K12 definition of a course is LIS’s Course Template Structure.

The following fields in Course Template are mandatory:

  • SourcedId
  • title
  • course number

The following extensions are added

  • Grade (String)
  • Subject (String)
  • Status (active or inactive)
  • DateLastModified (date)

3.3.4.         Class

Class is best represented by a course section in LIS, but there is no direct link between a course section and a course template. To this end, implementations will need to create a minimal course offering to link the section to the template.

The following fields in Course Section are mandatory:

  • SourcedId
  • title
  • parentOfferingId

The following extensions are added

  • Grade (String)
  • Subject (String)
  • Status (active or inactive)
  • DateLastModified (date)

The following fields in Course Offering are mandatory:

  • SourcedId
  • Title
  • parentTemplateId

3.3.5.         Teachers and Students

Teachers and students are represented via the Person class in LIS.

The following fields in Person are mandatory:

  • SourcedId
  • Name (type=FULL)
    • NamePart (type=GIVEN)
    • NamePart (type=FAMILY)
  • Agents ( 1 or more)
    • AgentType (type=PARENT or GUARDIAN or RELATIVE or AIDE)
    • AgentId
    • AgentDomain
    • AgentDescription
  • Contact Info (1 or more)
    • ContactInfoType (type= TELEPHONE or SMS or EMAIL_PRIMARY)
    • ContactInfoValue
  • Roles
    • Enterprise Roles (EnterpriseRolesType=StudentInformationSystem)
      • InstitutionRoleValue (type=STUDENT or FACULTY)
      • UserId (UserIdValue=<username>)

With the extensions:

  • Identifier (Type=String)
  • Status (active or inactive)
  • DateLastModified (date)
  • LTI User Id (string)
  • Demographics (CEDS added as sets of attribute / value pairs

3.3.6.         Line Item Category

Line Item categories do not exist in LIS, and a new service will be required. This MUST be a simple CRUD service to create, read update and delete line item categories. The data model fields are:

Figure 3.21: Proposed Category Data Model

The interface for the line item category service is as follows:

Figure 3.22: Proposed Category Service interface

3.3.7.         Line Item

Line Items are directly represented in LIS. The following fields are mandatory:

  • SourcedId
  • description
  • resultValue (Value Range only, declared inline).

The following extensions are added:

  • dueDate (type=date)
  • TermId (type=GUID)
  • GradingPeriodId(type=GUID)
  • Status (active or inactive)
  • DateLastModified (date)

3.3.8.         Result

The following fields in Result are mandatory when representing a term using the Result Structure:

  • SourcedId
  • ResultStatus
  • LineItemSourcedId
  • PersonSourcedId
  • resultScore
  • date

The following field is added as an extension:

  • Comment (type = string)
  • Status (active or inactive)
  • DateLastModified (date)

The Result Status vocabulary is changed to use the new values from this specification: Not Submitted, Submitted, Partially Graded, Fully Graded, Exempt.

3.4.         SOAP Bindings – Interface [R10]

 

Service Call

LIS Operations

(read)

getOrgs

 

getOrg

 

getSchools

 

getSchool

 

getTerms

discoverGroupIds (GroupType=TERM)

readGroups

getTerm

readGroup

getGradingPeriods

discoverGroupIds (GroupType=GRADING_PERIOD)

readGroups

getGradingPeriod

readGroups

getCourses

ReadAllCourseTemplateIds

ReadCourseTemplates

getCourse

ReadCourseTemplate

getClasses

ReadAllCourseSectionIds

ReadCourseSections

getClass

ReadCourseSection

getUsers

ReadAllPersonIds

ReadPersons

getUser

ReadPerson

getTeachers

DiscoverPersonIds(institutionrole=Faculty)

ReadPersons

getTeacher

ReadPerson

getStudents

DiscoverPersonIds(institutionrole=Student)

ReadPersons

getStudent

ReadPerson

getCategories

ReadAllCategoryIds

ReadCategory (many times)

getCategory

ReadCategory

getCoursesForSchool

DiscoverCourseTemplateIds(org.name=<name of school>)

ReadCourseTemplates

getClassesForSchool

DiscoverCourseSectionIds(org.name=<name of school>)

ReadCourseSections

getStudentsForClassInSchool

DiscoverCourseSectionIds(org.name=<name of school>)

For correct sourced id of course section:

discoverMembershipIds (id, type=CourseSection, role=Learner)

readMemberships

For each membership, extract person id

readPersons(person ids)

getTeachersForClassInSchool

DiscoverCourseSectionIds(org.name=<name of school>)

For correct sourced id of course section:

discoverMembershipIds (id, type=CourseSection, role=Instructor)

readMemberships

For each membership, extract person id

readPersons(person ids)

getStudentsForSchool

 

getTeachersForSchool

 

getTermsForSchool

 

getClassesForTerm

discoverCourseSectionIds(academicSession=<term id>)

readCourseSections

gerGradingPeriodsForTerm

For the target Group of type TERM, read the relationships.

For each relationship, ReadGroup, and discard any groups that are not of GroupType GRADING_PERIOD.

 

getClassesForCourse

discoverCourseOfferingIds(parentTemplateId=<course id>)

readCourseOfferings

For each CourseOfferingId:

discoverCourseSectionIds(parentOfferingId=<CourseOfferingId>

readCourseSections

getClassesForStudent

readMembershipIdsForPerson

readMemberships

For each Membership with context of course section, extract course section Id

ReadCourseSections(course_section_ids)

getClassesForTeacher

readMembershipIdsForPerson

readMemberships

For each Membership with context of course section, extract course section Id

ReadCourseSections(course_section_ids)

getStudentsForClass

discoverMembershipIds (id, type=CourseSection, role=Learner)

readMemberships

For each membership, extract person id

readPersons(person ids)

getTeachersForClass

discoverMembershipIds (id, type=CourseSection, role=Instructor)

readMemberships

For each membership, extract person id

readPersons(person ids)

getResultsForClass

ReadResultIdsForCourseSection

ReadResults

getLineItemsForClass

ReadLineItemIdsForCourseSection

ReadLineItems

getResultsForLineItemForClass

ReadResultIdsForLineItem

ReadResults

getResultsForStudentsForClass

discoverMembershipIds (id, type=CourseSection, personId, type=Person)

readResults()

Table 3.15: LIS Service Mappings

4.               Best Practices

This section describes best practice for implementers and users of this specification.

 

LTI User Id: The user class has a number of identifier fields. In keeping with IMS specifications, the preferred practice is for the sourced id field to be used wherever possible, across all systems. That is to say, the SIS should provide a sourced id for a user to the LMS. The LMS should provide that same sourced id for that user to any tools that it launches via LTI, rather than supplying some other identifier. This should be true across all orgs and roles.

However, it is known that at present this isn’t current practice, so other identifiers have been added to the user class to enable migration to best practice. The “userId” field is intended as a bridging piece in which any other machine readable id can be stored for a given user. This might be an LTI id, or it might be an active directory or LDAP identifier. If LMSs cannot use the sourcedIds for the user when making external calls, then this field can be used instead.

Also included is a field called “Identifier”. This is purely for humans to use when referring to a particular user for whatever reason. It is not a machine readable field and should not be processed as anything other than a human readable string.

 

School and District identifiers. These Identifiers are purely for humans to use when referring to a particular instance. These fields are not designed to be machine readable, and should not be processed as anything other than a human readable string.

NCES Identifiers: In the USA, the National Center for Educational Statistics issues identifiers for schools and districts which are to be used when reporting to the NCES. It is considered best practice to use these identifiers in the appropriate orgs to which they belong. For example, a high school record should include the NCES ID for that high school in the human readable “Identifier” field.

NON US Jurisdictions should agree on a suitable identifier for their region.

 

Course and Class Codes: These codes are intended as human readable identifiers for courses and classes. These fields should not be relied upon to be machine readable, although it could well be the case that they are. There is no best practice for deciding upon what a good coding scheme is for creating these codes, but they should at least be internally consistent.

 

Homerooms. Homerooms can be supported in the data model by assigning the “homeroom” value from the vocabulary in the class type data field. So far, there are only two values in the vocabulary, although others may be added later. It is safe to assume that a class which is not marked as a homeroom would be a scheduled class; best practice is to be explicit and assign classes as scheduled (even in scenarios where homerooms do not exist, or do not have a presence on a VLE).

 

Demographics: Each user returns a link to the demographics object for that user. The demographics service may then be queried to provide the full demographics information. It has been done this way to prevent a lot of demographics data being thrown around in every single user request (as demographics information should be considered privileged information). Implementers of the demographics service should carefully consider the consumer keys in incoming requests for demographics data, and not be afraid to return “unauthorized” errors for some requesters. It is possible (and expected) that certain consumer keys will not be able to request demographics information, whilst still being able to request user, course and class data (for example).

A1: Recommended Vocabularies for Metadata

IMS recommends that the following vocabularies and terms are used in metadata:

Schools:

National Center For Educational Statistics School ID (http://nces.ed.gov)

Classification: “private” | “public” | “charter”

Gender: “male” | “female” | “mixed”

Boarding: “true” | “false”

LocalId: The local identifier within the source system for this record

Districts:

National Center For Educational Statistics District ID (http://nces.ed.gov).

Courses:

SchoolYear: a string showing the school year in which the course is taught. This is the form of a hyphenated string: e.g. 2014-2105.

Duration: A string showing the duration of the course. (e.g. one year, two terms etc.).

Classes:

(none?)

Users:

Demographics:

The demographics information for users is taken from the common educational data standards, published and maintained at ceds.gov.edu. The following table shows the permitted data types and their value spaces:

 

Demographic Term

Data Type

Birthdate

Date

Sex

Vocabulary (“Male” | “Female” )

American Indian or Alaska Native

Vocabulary (“Yes” | “No” )

Asian

Vocabulary (“Yes” | “No” )

Black or African American

Vocabulary (“Yes” | “No” )

Native Hawaiian or Other Pacific Islander

Vocabulary (“Yes” | “No” )

White

Vocabulary (“Yes” | “No”)

Demographic Race Two or More Races

Vocabulary (“Yes” | “No”)

Hispanic or Latino Ethnicity

Vocabulary (“Yes” | “No” )

Country of Birth Code

Vocabulary – https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20002

State of Birth Abbreviation

Vocabulary – https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20837

City of Birth

String

Public School Residence Status

Vocabulary - https://ceds.ed.gov/CEDSElementDetails.aspx?TermxTopicId=20863

Table A.1: Permitted User Demographic Data Types and Their Value Spaces.

 

About This Document

Title:                                      IMS OneRoster Specification

Editor:                                  Phil Nicholls (IMS Global)

Version:                                1.0

Version Date:                      3 June 2015

Status:                                   Final

Summary:                            This document outlines a vision for a K12 focused Learning Information Services, built upon ‘technical simplicity’.

Purpose:                               This document is made available for public comment and feedback.

Document Location:          http://www.imsglobal.org/lis

 

 

List of Contributors

The following individuals contributed to the development of this document:

 

Name                                     Organization

David Gappa                        Safari Montage

Tom Ingram                         Escambia County School District

Mike Kaastra                       Desire2Learn

Andrew Kuritzky                 HMH

Lisa Mattson                        IMS Global

David Mayes                        Gwinnett County Schools

Andy Miller                           Learning.com

Phil Nicholls                          IMS Global (UK)

Padraig O’hiceadha            HMH

Upendra Penegalapati        Pearson

George Perreault                  Orange County Public Schools

James Perreault                    FLVS

Patrick Porter                        Houston ISD       

Wendy Riedy                       Sungard K12

Kurt Rompot                        Pearson

Aditya Subramaniam         Schoology

Mark Walls                           Gwinnett County Schools

Stanley Watts                       Classlink

Mike Zackerson                   Instructure

 

Revision History

Version No.

Release Date

Comments

v1.0 Public Draft

 12 February 2015

The first release of the OneRoster Specification.

v1.0 Final

3 June 2015

Final Release of the OneRoster Specification.

 

 IMS Global Learning Consortium, Inc. ("IMS Global") is publishing the information contained in this IMS OneRoster Specification ("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 OneRoster Specification v1.0

Date: 3 June