IMS OneRoster: CSV Binding 1.2 (IMS Candidate Final Public)

IMS OneRoster: CSV Binding

IMS Candidate Final Public
Version 1.2
IMS Candidate Final Public
Date Issued: July 1st, 2021
Status: This document is for review and adoption by the IMS membership.
This version: https://www.imsglobal.org/spec/or/v1p2/csv/
Latest version: https://www.imsglobal.org/spec/or/latest/csv/
Errata: https://www.imsglobal.org/spec/or/v1p2/errata/

IPR and Distribution Notice

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

IMS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain 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.

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

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

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

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

Public contributions, comments and questions can be posted here: http://www.imsglobal.org/forums/ims-glc-public-forums-and-resources.

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

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

Abstract

The IMS OneRoster® (OR) standard addresses the exchange of student data (primarily about people, courses, enrollments and grades) between different educational systems for the specific needs of K-12. The primary use-cases are: the exchange of data between a Student Information System (SIS) and Learning Management System (LMS), and the rostering of learning tools. In OR 1.2, the service has been split into three core services:

The underlying OneRoster specification is available in:

  • OR 1.2 Rostering Service Model [ORROS-SM] - to enable the exchange of information about the rostering of people in classes;
  • OR 1.2 Resources Service Model [ORRES-SM] - to enable the exchange of information about the set of resources that SHOULD be made available to users, courses and classes;
  • OR 1.2 Gradebook Service Model [ORGBK-SM] - to enable the exchange of information about results which may be aligned as lineItems and categories which are collections of lineItems.

The standard includes a REST-based binding to make it quicker and easier to implement the exchange of information about people, membership, courses and gradebooks. In addition to the REST binding description, a format for CSV file based exchange has also been defined: THIS DOCUMENT.

CSV files are typically exchanged between the school and the vendor to populate the roster information needed to gain access to learning tools, portals and learning environments. This specification defines how the relevant information is to be stored in a set of CSV files. This set of CSV files is exchanged as a zip file (it also contains a 'manifest.csv' file that describes the associated data CSV files). This specificatiions DOES NOT define how the zip file is moved from system to system.

1. Introduction

This Section is NORMATIVE.

1.1 Scope and Context

This document contains the description of how the OneRoster data model is exchanged in a set of CSV files. This binding addresses the format and content of the CSV files: it does NOT define how the CSV files are exchanged between end systems. The other documents that should be used with this CSV binding are:

  • OneRoster 1.2 Implementation Guide [OR-IG] - the best practices to be adopted when processing OneRoster CSV files;
  • OneRoster 1.2 Conformance and Certification [OR-CC] - the process by which an implementation can achieve OneRoster 1.2 CSV certification.

1.2 Changes Between OR 1.1 and 1.2

The differences between versions 1.1 and 1.2 of the OR specification CSV binding are:

  • The following editorial changes have been made:-
    • For the purposes of easing internationalization of this specification, all references to CEDS have been removed from the data model descriptions. Usage of the appropriate vocabularies are discussed in the Implementation Guide [OR-IG] and any appropriate profiling documents;
  • The following CSV files have been added:-
    • 'userProfiles.csv'
    • 'roles.csv'
    • 'userResources.csv'
    • 'scoreScales.csv'
    • 'lineItemScales.csv'
    • 'resultScales.csv'
    • 'lineItemLearningObjectiveIds.csv'
    • 'resultearningObjectiveIds.csv'
  • The following changes have been made to the 'manifest.csv' file:-
    • Rows for the eight new CSV files have been added
    • The 'oneroster.version' row is required to have a value of '1.2' when referring to an OR 1.2 compliant manifest
  • The following changes have been made to the 'categories.csv' file:-
    • The 'weight' column has been added
  • The following changes have been made to the 'demographics.csv' file:-
    • The enumerated vocabulary for the 'sex' column is now permitted to have new values of 'other and 'unspecified'
  • The following changes have been made to the 'lineItems.csv' file:-
    • The 'schoolSourcedId' column has been added
    • The 'gradingPeriodSourcedId' column has been renamed 'academicSessionSourcedId'
    • The 'resultValueMin' and 'resultValueMax' attributes have been made optional
  • The following changes have been made to the 'results.csv' file:-
    • The 'classSourcedId' and 'textScore' columns have been added
    • The permitted tokens in the 'scoreStatus' column has been expanded with new values of { late | incomplete | missing | withdrawal | in progress }
    • Use of the 'score' column has been made OPTIONAL.
  • The following changes have been made to the 'users.csv' file:-
    • The 'orgSourcedIds' column has been removed (org identification is now achieved via the 'roles.csv' file)
    • The 'role' column has been removed (role allocation is now achieved via the 'roles.csv' file)
    • The 'preferredGivenName', 'preferredMiddleName' and 'preferredFamilyName' columns have been added
    • The 'primaryOrgSourcedId' column has been added
    • The 'userMasterIdentifier' column has been added.

1.3 Conformance Statements

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

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

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

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

1.4 Structure of this Document

The structure of the rest of this document is:

An outline description of the stucture of the rest of this document.
2. CSV OVERVIEW An overview of the structure of the CSV binding for OneRoster.
3. CSV CSV FORMAT The detailed format for the data in the CSV files for OneRoster.
APPENDIX A – THE FILE DEPENDENCY MATRIX An explanation of the file dependencies when exchanging bulk processing based CSV files.
APPENDIX B – REVISION HISTORY History of the various published versions of this document. This includes details of the changes made with respect to the previously published version.
APPENDIX C – REFERENCES The details of the set of documents cited within this document.
APPENDIX D – LIST OF CONTRIBUTORS The people who were responsible for the creation of this document.

1.5 Acronyms

API
Application Programming Interface
BOM
Beginning of Message
CASE
Compentencies and Academic Standards Exchange
CEDS
Common Education Data Standards
CSV
Comma Separated Values
GUID
Globally Unique Identifier
IETF
Internet Engineering Task Force
LDAP
Lightweight Directory Access Protocol
LIS
Learning Information Services
LMS
Learning Management System
LOR
Learning Object Repository
LTI
Learning Tools Interoperability
RFC
Request For Comment
URN
Uniform Resource Name
UTF
Unicode Transformation Format
UUID
Universally Unique Identifier

2. CSV Overview

This Section is NORMATIVE.

2.1 Binding of the Data

Many districts currently provide student information to tool providers and LMS/LOR vendors as ‘.csv’ formatted files. For those districts that must continue to use CSV files to exchange roster information with vendors, the format defined in the Tables in Section 3 should be used: this format corresponds to the data models in the OneRoster 1.2 Rostering [ORROS-SM], Resources [ORRES-SM] and Gradebook [ORGBK-SM] documents. Districts can choose to upload class rosters/gradebooks by preparing up to twenty (20) files in CSV format outlined in this document. The rosters/gradebooks could be available for both import and export. A summary of the set of files is given in Table 2.1.

Table 2.1 A summary of the list of files that may be present as part of a OneRoster CSV-based data exchange.
CSV File Name Required Description
manifest.csv Yes A control file. The manifest contains the OR version (set as 1.2 for this release of the standard) and the list of files that are supplied in this data set.
academicSessions.csv No A data file. The 'academic sessions' data model content.
categories.csv No A data file. The 'categories' data model content.
classes.csv No A data file. The 'classes' data model content.
classResources.csv No A data file. The links between the 'classes' and 'resources' data model content.
courseResourses.csv No A data file. The links between the 'courses' and 'resources' data model content.
courses.csv No A data file. The 'courses' data model content.
demographics.csv No A data file. The 'demographics' data model content.
Data model revised in v1.2.
enrollments.csv No A data file. The 'enrollments' data model content.
lineItemLearningObjectiveIds.csv* No A data file. The 'learning objectives' mapping to 'lineItems' data model content.
A new file added in v1.2.
lineItems.csv No A data file. The 'lineItems' data model content.
Data model revised in v1.2.
lineItemScoreScales.csv* No A data file. The 'score scales' mapping to 'lineItems' data model content.
A new file added in v1.2.
orgs.csv No A data file. The 'orgs' data model content.
resources.csv No A data file. The 'resource' data model content.
resultLearningObjectiveIds.csv* No A data file. The 'learning objectives' mapping to 'results' data model content.
A new file added in v1.2.
results.csv No A data file. The 'results' data model content.
Data model revised in v1.2.
resultScoreScales.csv* No A data file. The 'score scales' mapping to 'results' data model content.
A new file added in v1.2.
roles.csv* No A data file. The mapping between roles, orgs and accounts data model content.
A new file added in v1.2.
scoreScales.csv* No A data file. The 'score scales' data model content.
A new file added in v1.2.
userProfiles.csv* No A data file. The userProfiles' data model content.
A new file added in v1.2.
userResources.csv* No A data file. The userResources' data model content.
A new file added in v1.2.
users.csv No A data file. The 'users' data model content.
Data model revised in v1.2.

KEY:

  • CSV File Name – the name of the CSV file;
  • Required – denotes whether or not the CSV file MUST be supplied (Yes or No);
  • Description – a statement of the content in the file;
  • '*' denotes files added in the V1.2 release.

When data is exchanged there will be 1-22 CSV files. An exchange MUST include the 'manifest.csv' file. The case of when only the 'manifest.csv' is supplied is used to denote that no updates occurred. At most, 22 CSV files exchanged i.e. there MUST NOT be more than one of each of the data CSV files. When the set of files are for bulk processing they must be semantically consistent i.e. every object referenced in a file must also be defined in either the same, or one of the other files in the zip package (see Appendix A for more details on this set of file dependencies).

2.2 Exchanging the CSV Files

For V1.2 the CSV files will be exchanged as a zip file. The encompassed files must be at the root level i.e. they MUST NOT be contained within an enclosing directory. There is NO constraint on the name of the zip file but it must have a file extension of ‘zip’. The compression MUST conform to [RFC1951].

2.3 Compatibility Between V1.0, V1.1 and V1.2

A system that imports both V1.0, V1.1 and V1.2 compliant data sets must differentiate using the following algorithm:

  • If a 'manifest.csv' file is present then the data set conforms to V1.1 and/or V1.2 (this must be assumed even if the rest of the file set conforms to OneRoster 1.0 definitions and the appropriate error messages must be produced but the subsequent processing is implementation dependent). The manifest file contains the list of CSV files that MUST also accompany the manifest file. If the set of supplied files differs from the list of files in the manifest then an import error should be reported and the system is permitted to process the data as defined by the implementation;
  • If a 'manifest.csv' file is NOT present then, under normal operations, the data set conforms to V1.0. Seven data files MUST be supplied i.e. one file for each of the data models (there MUST NOT be any of the new CSV data files introduced in V1.1/V1.2). If a file is missing then an error should be reported and the system is permitted to process the data as defined by the implementation. In the case where the 'manifest.csv' file is missing but the file set conforms to OneRoster 1.1/1.2 then the appropriate error message should be produced and the subsequent processing is implementation dependent.

2.4 Bulk/Delta Behavior Constraints

The existence and management of a record is controlled via the bulk and delta processing options. A record can be in four possible states:

  • 'No Record' – the record has not been created or it did exist but the system has deleted the record and it cannot be recovered with the previously assigned sourcedId;
  • 'Record[-]' – the record has been created and assigned a sourcedId but it has not yet been activated;
  • 'Record[Active]' – the record status has been set to 'active';
  • 'Record[ToBeDeleted]' – the record status has been set of 'tobedeleted'.

For each state there are four possible types of transition events:

  • B[-] – a bulk transfer has occurred and an existing record (one with a sourcedId) does not appear in those files;
  • B[S] – a bulk transfer has occurred and the record occurs in the new file set;
  • D[A] – a delta transfer has occurred and the record status is set as 'active';
  • D[D] – a delta transfer has occurred and the record status is set as 'tobedeleted'.

The 'System Deletes the Record' transition is only possible when the record is in the state of 'Record[ToBeDeleted]'. For this transition the system deletes the record (the length of time between this deletion action and the record being set as 'tobedeleted' is implementation dependent).

The state diagram for the creation and management of a record in a service provider is shown in Figure 1.

State diagram for the CSV bulk/delta modes interaction.
Figure 1 – State diagram for the management of records using bulk/delta processing at the service provider.

A OneRoster Service Consumer could issue a 'HTTP GET' request for the record in each of these four states. When such a read request is made the request will result in the following payloads:

  • 'No Record' – in the case of a single record request a 404 response will be returned;
  • 'Record[-]' – the record will be returned with an empty 'status' field and an empty 'dateLastModified' field;
  • 'Record[Active]' – the record will be returned with a 'status' field value of 'active' and the 'dateLastModified' field set to the time the record was last changed;
  • 'Record[ToBeDeleted]' – the record will be returned with a 'status' field value of 'tobedeleted' and the 'dateLastModified' field set to the time the record was last changed.

3. CSV Format

This Section is NORMATIVE.

The file format for each of the data files is a Comma Separated Values (CSV) format as specified in [RFC4180] with the extra restriction that carriage-returns are not permitted within a field. Fields containing commas and double-quotes must be enclosed in double-quotes. If double-quotes are used to enclose a field, then a double-quote appearing inside the field must be escaped by preceding it with another double-quote.

The CSV files must be UTF-8 encoded [RFC3629]. Importing processors must tolerate BOM (Byte Order Mark) prefixes and ignore them. In a UTF-8 encoded file with a BOM, the BOM will appear as the 3-byte sequence ‘EF BB BF’ at the beginning of the file. If present, the CSV header will begin at the 4th byte of the file; if not present, the CSV header will begin at the 1st byte of the file.

Other key points are:

  • All header names and content values within the CSV file are case-sensitive. Incorrect case will result in conformance failure and should be logged as a detected error;
  • The Header row for each file is required;
  • The Header fields for a file must be supplied in the same order as defined in the tables below. If metadata extension fields are used, then they must be added to the right of the defined data fields in the specification, as the last set of columns. This ensures that the sequence of the defined data fields remains fixed irrespective of the presence or not of metadata fields;
  • Header field names must be uniquely named within a file;
  • Files that contain no data rows are NOT permitted;
  • For ALL fields that are optional and which have a defined enumeration token set, then the value of NULL/blank (i.e. a blank value "") is permitted to denote that NO data is supplied;
  • The support of ALL string-based data-types requires that a maximum length of at least 255 must be supported by implementations. If string lengths of greater than 255 are used then system may lose some part of the string without failing conformance.

When mapping from the data model [ORROS-SM], [ORRES-SM], [ORGBK-SM] to the equivalent column headers the following special rules have been applied:

  • When referencing an object in the data model (using the data-type GUIDRef) the name has been extended using SourcedId e.g. 'org' to 'orgSourcedId';
  • When referring to a set of objects in the data model maps to a comma separated list, enclosed in quotation marks, under the corresponding column header (as per [RFC4180]);
  • The references to resources in the Class and Course data models have NOT been mapped (instead the two CSV files 'classResources.csv' and 'courseResources.csv' are used).

CSV import/export is envisaged to work in one of two ways, bulk and delta:

  • In BULK processing, the CSV files MUST NOT contain values in the "dateLastModified" and "status" fields. That is to say, for each row, there will be no data for either of these fields. Importing Systems MUST view this incoming data as the reference version of all data. That is to say, if records that were previously imported do not appear in this bulk csv file, then the importing system should internally mark those records as 'tobedeleted' with the 'dateLastModified' value set to the time of the bulk files import processing. If said records subsequently appear in a future bulk file, then those records should be updated and made active. When a set of Bulk files are created they must be semantically complete i.e. every object referenced by another object MUST also be defined in the corresponding source CSV file and included with the 'manifest.csv' file;
  • In DELTA processing, the incoming CSV file MUST contain values in the "dateLastModified" and "status" fields. That is to say, each row in the CSV file should include data describing that (the row) data was last modified and its status. Importing systems must view this incoming delta file as changes to the reference data, and should make the appropriate changes, deletions and insertions of the new data.

The key to the CSV description tables listed in Subsections 3.2 to 3.20 is:

  • Field Header – the name for the Column Header;
  • Required – denotes if data must be present. The meanings for this field are:-
    • 'Yes' for fields which are always required
    • 'Yes for Delta' for fields which must be populated for Delta processing, and which must be blank for Bulk processing
    • 'No' for fields which do not require to have values;
  • Format – the data-type for the data:-
    • 'GUID' denotes some form of globally unique identifier (this must be less than 256 characters). This is not restricted to the 128 bit UUID format but MUST contain ONLY the characters '0-1 | a-Z | A-Z | . | - | _ | / | @' (the '|' character is being used as a separator in the expression)
    • 'GUID Reference' denotes the GUID of an object defined in some other CSV data file (this is limited to the same set of characters as per a 'GUID')
    • 'UUID Reference' denotes the UUID of the referenced object (this must be a valid 128 bit UUID)
    • 'List of GUID Reference' denotes a comma-delimited list of GUID References of objects defined in another CSV data file
    • 'ID' denotes an identifier defined outside of the OneRoster specification, e.g. identifiers generated by vendors for their resources in the Resources dataset
    • 'String' denotes a sequence of characters that should follow the description. Generally this is aimed to be human-readable e.g. "Science Lesson"
    • 'List of Strings' denotes a sequence of Strings. The individual strings within the list must not contain commas, and the list is a comma separated list e.g. "1,2,3". If a List of Strings contains more than one element, then it must be double-quote encapsulated
    • 'Enumeration' denotes a fixed set of values that will be referred to in the description. In the case of fields which are not required, an empty field denotes no value
    • 'Enumeration List' denotes a list of Enumerations. The list is comma separated e.g. "teacher,student,aide"
    • 'Float' denotes a floating point number
    • 'DateTime' denotes a timestamp format. DateTimes MUST be expressed in W3C profile of ISO 8601 [ISO8601] and MUST contain the UTC timezone e.g. "2012-04-23T18:25:43.511Z"
    • 'Date' denotes a date format. Dates MUST be expressed using ISO 8601 format [ISO8601], more commonly formatted as "YYYY-MM-DD" e.g. "2002-04-23"
    • 'Year' denotes a date format of year only. Years MUST be expressed using ISO 8601 format [ISO8601], more commonly formatted as "YYYY" e.g. "2002";
  • Example/Description – an example of the expected data, and a brief statement of the nature of the content.

3.1 'manifest.csv'

NOTE: The manifest file will consist of just two columns with the headers ‘propertyName’ and ‘value’. Each row will contain a single property/value pair. The list of supported property/value pairs is described in Table 3.1.

Table 3.1 - Format for the contents of the 'manifest.csv' file.
Property Name
(One per row)
Required Format Value Description
manifest.version Yes String The version of the manifest. For an initial value this must be “1.0”.
oneroster.version Yes String The OneRoster version supported by this file set. This must be “1.2” for implementations of this version of the specification.
file.academicSessions Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.categories Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.classes Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.classResources Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.courses Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.courseResources Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.demographics Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.enrollments Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.lineItemLearningObjectiveIds* Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.lineItems Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.lineItemScoreScales* Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.orgs Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.resources Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.resultLearningObjectiveIds* Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.results Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.resultScoreScales* Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.roles* Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.scoreScales* Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.userProfiles* Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.userResources* Yes Enumeration Permitted values of: { absent | bulk | delta }.
file.users Yes Enumeration Permitted values of: { absent | bulk | delta }.
source.systemName No String The name for the system producing the set of files.
source.systemCode No String Identification code for the system producing the set of files.

The '*' denotes the rows that have been added in OR 1.2. In the enumerations in Table 3.1 the interpretations for each permitted value are:

  • 'absent' – the CSV file is not supplied;
  • 'bulk' – the CSV file contains only bulk data;
  • 'delta' – the CSV file contains only delta data.

These processing mode hints should be consistent with the data held within the accompanying CSV files but in cases of conflict the values in the data CSV files must take precedence.

3.2 'academicSessions.csv'

This file represents the AcademicSessions dataset from the OneRoster Rostering specification.

The academicSessions.csv file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the category.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title Yes String Name or title of the academic session.
type Yes Enumeration Permitted values of: { gradingPeriod | semester | schoolYear | term }
This vocabulary may be extended.
startDate Yes Date Inclusive end date for the academic session. ISO 8601 format [ISO8601].
endDate Yes Date Exclusive end date for the academic session. ISO 8601 format [ISO8601].
parentSourcedId No GUID Reference. SourcedId of the parent of this academic session.
schoolYear Yes Year The school year for which the academic session contributes. This year should be that in which the school year ends (Format is: YYYY).

The dependencies of this file on other files when supporting bulk processing are:

  • Other academicSessions could be referenced in the SAME file through the 'parentSourcedId' attribute. Therefore, for semantic consistency there are NO dependencies on OTHER files.

3.3 'categories.csv'

This file represents the Categories dataset from the OneRoster Gradebook specification.

The categories.csv file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the category.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title Yes String The title assigned to the set of lineItems to denote its nature e.g. homework, essays, etc.
weight No Integer Total weight of this grading category in calculation of course final score. This is a Percent value only, e.g. 80%.
This is a new column added in version 1.2.

There are NO dependencies of this file on other files when supporting bulk processing.

3.4 'classes.csv'

This file represents the Classes dataset from the OneRoster Rostering specification.

The classes.csv file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the class.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title Yes String Name of this class.
grades No List of Strings Grade(s) for which the class is attended. The permitted vocabulary should be agreed as part of the definition of the usage of this specification.
courseSourcedId Yes GUID Reference SourcedId of the course of which this class is an instance.
classCode No String Human readable code used to help identify this class.
classType Yes Enumeration The permitted values are: { homeroom | scheduled }
This vocabulary may be extended.
location No String Human readable description of where the class is physically located.
schoolSourcedId Yes GUID Reference. SourcedId of the Org that teaches this class of OrgType 'school'.
termSourcedIds Yes List of GUID References. SourcedIds of the terms (the academicSessions) in which the class is taught.
subjects No List of Strings Subject name(s) in human readable form. If the 'subjectCodes' attribute is present then the subjects and subjectCodes lists must have the same length and have order significance.
The permitted vocabulary should be agreed as part of the definition of the usage of this specification.
If the value of the "Course Title" contains commas, then those commas must be removed.
subjectCodes No List of Strings Subject codes(s) in machine readable form. If more than one subject code is needed, use double quotes, and separate with commas (per [RFC4180]). If the 'subjects' attribute is present the two lists must have the same length and have order significance. The permitted vocabulary should be agreed as part of the definition of the usage of this specification.
periods No List of Strings The time slots in the day that the class will be given. If more than one period is needed, use double quotes, and separate with commas (per [RFC4180]). Examples: 1; “1,3,5”

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated terms (academicSessions) using the ‘termSourcedIds’ attribute. This produces a dependency on the academicSessions.csv;
  • This requires a reference to the associated course (course) using the ‘courseSourcedId’ attribute. This produces a dependency on the courses.csv;
  • This requires a reference to the associated school (org) using the ‘schoolSourcedId’ attribute. This produces a dependency on the orgs.csv.

3.5 'classResources.csv'

This file represents the links between the Resources and Classes datasets from the OneRoster Rostering and Resources specification.

The classResources.csv file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the classResource relationship.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title No String Name of the related class.
classSourcedId Yes GUID Reference. SourcedId of the reference Class.
resourceSourcedId Yes GUID Reference. SourcedId of the Resource associated with the Class.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated class (class) using the 'classSourcedId' attribute. This produces a dependency on the classes.csv. This dependency on the class leads to the corresponding dependencies on the academicSessions.csv, courses.csv and orgs.csv files;
  • This requires a reference to the associated resource (resource) using the ‘resourceSourcedId’ attribute. This produces a dependency on the resources.csv.

3.6 'courseResources.csv'

This file represents the links between the Resources and Courses datasets from the OneRoster Rostering and Resources specification.

The 'courseResources.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the courseResourse relationship.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title No String Name of the related class.
courseSourcedId Yes GUID Reference. SourcedId of the reference Course.
resourceSourcedId Yes GUID Reference. SourcedId of the Resource associated with the Course.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated course (course) using the 'courseSourcedId' attribute. This produces a dependency on the courses.csv. This dependency on the course leads to the corresponding dependencies on the academicSessions.csv and orgs.csv files;
  • This requires a reference to the associated resource (resource) using the ‘resourceSourcedId’ attribute. This produces a dependency on the resources.csv.

3.7 'courses.csv'

This file represents the Courses dataset from the OneRoster Rostering specification.

The courses.csv file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the course.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
schoolYearSourcedId No GUID Reference. SourcedId of the associated AcademicSession with type of 'schoolYear'.
title Yes String Name of this course.
courseCode No String Human readable code used to help identify this course.
grades No List of Strings Grade(s) for which the class is attended. The permitted vocabulary should be agreed as part of the definition of the usage of this specification.
orgSourcedId Yes GUID Reference. SourcedId of an org to which this course belongs.
subjects No List of Strings Subject name(s) in human readable form. If the 'subjectCodes' attribute is present then the subjects and subjectCodes lists must have the same length and have order significance.
The permitted vocabulary should be agreed as part of the definition of the usage of this specification.
If the value of the "Course Title" contains commas, then those commas must be removed.
subjectCodes No List of Strings Subject codes(s) in machine readable form. If more than one subject code is needed, use double quotes, and separate with commas (per [RFC4180]). If the 'subjects' attribute is present the two lists must have the same length and have order significance. The permitted vocabulary should be agreed as part of the definition of the usage of this specification.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated school year (academicSession) using the ‘schoolYearSourcedId’ attribute. This produces a dependency on the academicSessions.csv;
  • This requires a reference to the associated orgaization (org) using the ‘orgSourcedId’ attribute. This produces a dependency on the orgs.csv.

3.8 'demographics.csv'

This file represents the Demographics dataset from the OneRoster Rostering specification.

The 'demographics.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the demographics. This MUST be the 'sourcedId' of the User whose demographics are being described.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
birthDate No Date The date of birth. ISO 861 format: 'YYYY-MM-DD'.
sex No Enumeration Permitted values are: { male | female | unspecified | other }.
The terms 'unspecified' and 'other' added in Version 1.2.
This vocabulary may be extended.
americanIndianOrAlaskaNative No Boolean Permitted values are: { true | false }
asian No Boolean Permitted values are: { true | false }
blackOrAfricanAmerican No Boolean Permitted values are: { true | false }
nativeHawaiianOrOtherPacificIslander No Boolean Permitted values are: { true | false }
white No Boolean Permitted values are: { true | false }
demographicRaceTwoOrMoreRaces No Boolean Permitted values are: { true | false }
hispanicOrLatinoEthnicity No Boolean Permitted values are: { true | false }
countryOfBirthCode No String Country where the user was born. The permitted vocabulary should be agreed as part of the definition of the usage of this specification.
stateOfBirthAbbreviation No String State where the user was born. The permitted vocabulary should be agreed as part of the definition of the usage of this specification.
cityOfBirth No String City where the user was born.
publicSchoolResidenceStatus No String An indication of the location of the users legal residence relative to (within or outside) the boundaries of the public school attended and its administrative unit. The permitted vocabulary should be agreed as part of the definition of the usage of this specification.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated user using the 'sourcedId' attribute. This produces a dependency on the users.csv. This creates a corresponding dependency on the orgs.csv, roles.csv and userProfiles.csv files.

3.9 'enrollments.csv'

This file represents the Enrollments dataset from the OneRoster Rostering specification.

The enrollments.csv file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the enrolment.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
classSourcedId Yes GUID Reference SourcedId of the Class.
schoolSourcedId Yes GUID Reference SourcedId of an Org with type ‘school’.
userSourcedId Yes GUID Reference SourcedId of the User.
role Yes Enumeration Permitted values are: { administrator | aide | guardian | parent | proctor | relative | student | teacher }.
This vocabulary may be extended.
primary No Boolean Permitted values are: { true | false }. Applicable only to teachers. Only one teacher should be designated as the primary teacher for a class in the period defined by the begin/end dates.
beginDate No Date The start date for the enrollment (inclusive). This date must align with the associated academic session (term) identified in the class.
endDate No Date The end date for the enrollment (exclusive). This date must align with the associated academic session (term) identified for the class.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated class (class) using the 'classSourcedId' attribute. This produces a dependency on the classes.csv. This creates a corresponding dependency on the academicSessions.csv and courses.csv files. The courses dependency creates a further set of dependencies on the on the academicSessions.csv and orgs.csv files;
  • This requires a reference to the associated school (org) using the 'schoolSourcedId' attribute. This produces a dependency on the orgs.csv;
  • This requires a reference to the associated user (user) using the 'userSourcedId' attribute. This produces a dependency on the users.csv. This creates a corresponding dependency on the orgs.csv, roles.csv and userProfiles.csv files.

3.10 'lineItemLearningObjectiveIds.csv'

A new file added in version 1.2.

This file represents the mapping between LineItems and the corresponding Learning Objectives in the OneRoster Gradebook specification.

The 'lineItemLearningObjectiveIds.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the lineItem learning objective relationship.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
lineItemSourcedId Yes GUID Reference SourcedId of the parent LineItem for this learning objective.
source Yes Enumeration. The type of learning objective identifiers. Enumeration of: { case | unknown }. 'case' is used to denote an IMS CASE identifier.
This vocabulary may be extended.
learningObjectiveId Yes String Unique identifier for the associated learning objective. If an IMS CASE identifier then it MUST be a valid UUID URN.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated lineItem using the 'lineItemSourcedId' attribute. This produces a dependency on the lineItems.csv. This dependency leads to the corresponding dependencies on the categories.csv, academicSessions.csv, classes.csv, courses.csv and orgs.csv files.

3.11 'lineItems.csv'

This file represents the LineItems dataset from the OneRoster Gradebook specification.

The 'lineItems.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the lineItem.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title Yes String The title assigned to the lineItem.
description No String Short description of the role of the lineItem.
assignDate Yes Date Date the associated activity was assigned.
dueDate Yes Date Date the associated activity is due to be completed.
classSourcedId Yes GUID Reference SourcedId of the Class.
categorySourcedId Yes GUID Reference SourcedId of the Category.
academicSessionSourcedId Yes GUID Reference SourcedId of the academicSession to which the lineItem is based.
resultValueMin No Float The minimum value permitted for the score (inclusive) e.g. 0.0.
resultValueMax No Float The maximum value permitted for the score (inclusive) e.g. 100.0.
schoolSourcedId Yes GUID Reference SourcedId of the School.
This is a new column added in version 1.2.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated class (class) using the 'classSourcedId' attribute. This produces a dependency on the classes.csv. This creates a corresponding dependency on the academicSessions.csv and courses.csv files. The courses dependency creates a further set of dependencies on the on the academicSessions.csv and orgs.csv files;
  • This requires a reference to the associated category (category) using the 'categorySourcedId' attribute. This produces a dependency on the categories.csv;
  • This requires a reference to the associated grading period (academicSession) using the 'gradingPeriodSourcedId' attribute. This creates a dependency on the academicSessions.csv file.

3.12 'lineItemScoreScales.csv'

A new file added in version 1.2.

This file represents the mapping between the LineItems and ScoreScales datasets from the OneRoster Gradebook specification.

The 'lineItemScoreScales.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the lineItem scoreScale.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title No String Name of the related scoreScale.
lineItemSourcedId Yes GUID Reference. SourcedId of the reference LineItem.
scoreScaleSourcedId Yes GUID Reference. SourcedId of the reference ScoreScale.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated lineItem using the 'lineItemSourcedId' attribute. This produces a dependency on the lineItems.csv. This dependency leads to the corresponding dependencies on the categories.csv, academicSessions.csv, courses.csv and orgs.csv files;
  • This requires a reference to the associated scoreScale using the ‘scoreScaleSourcedId’ attribute. This produces a dependency on the scoreScales.csv. This dependency leads to the corresponding dependencies on the academicSessions.csv, classes.csv, courses.csv and orgs.csv files.

3.13 'orgs.csv'

This file represents the Orgs dataset from the OneRoster Rostering specification.

The 'orgs.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the org.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
name Yes String Name of the organization.
type Yes Enumeration Permitted values are: { department | school | district | local | state | national }
This vocabulary may be extended.
identifier No String Human readable identifier for this org e.g. NCES ID.
parentSourcedId No GUID Reference. SourcedId of an Org representing the Parent organization.

The dependencies of this file on other files when supporting bulk processing are:

  • Other orgs could be referenced in the SAME file through the ‘parentSourcedId’ attribute. Therefore, for semantic consistency there are NO dependencies on OTHER files.

3.14 'resources.csv'

This file represents the Resources dataset from the OneRoster Resources specification.

The 'resources.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the resource.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
vendorResourceId Yes ID Unique ID of this resource as allocated by the vendor. It is unique in the context of resource identifiers allocated by the vendor.
title No String Name of this resource.
roles No Enumeration List A comma separated list with permitted values are: { administrator | aide | guardian | parent | proctor | relative | student | teacher }
This vocabulary may be extended.
importance No Enumeration Permitted values are: { primary | secondary }.
vendorId No ID Identifier of the vendor responsible for this resource. This unique ID will be assigned by IMS during the OneRoster conformance process.
applicationId No ID Identifier of the application associated with this resource. This identifier is assigned by the creator/vendor of the resource.

There are NO dependencies of this file on other files when supporting bulk processing.

3.15 'resultLearningObjectiveIds.csv'

A new file added in version 1.2.

This file represents the mapping between Results and the corresponding Learning Objectives in the OneRoster Gradebook specification.

The 'resultLearningObjectiveIds.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the result learning objective relationship.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
resultSourcedId Yes GUID Reference SourcedId of the parent Result for this learning objective.
source Yes Enumeration The type of learning objective identifiers. Enumeration of: { case | unknown }. 'case' is used to denote an IMS CASE identifier.
This vocabulary may be extended.
learningObjectiveId Yes String Unique identifier for the associated learning objective. If a CASE identifier then it MUST be a valid UUID URN.
score No Float The optional mastery score supplied as a numeric value.
textScore No String The optional mastery score supplied as a string.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated lineItem using the 'resultSourcedId' attribute. This leads to the corresponding dependencies on the users.csv, classes.csv, lineItems.csv, categories.csv, academicSessions.csv, courses.csv and orgs.csv files.

3.16 'results.csv'

This file represents the Results dataset from the OneRoster Gradebook specification.

The 'results.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the result.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
lineItemSourcedId Yes GUID Reference Unique identifier of the lineItem.
studentSourcedId Yes GUID Reference Unique identifier of the student (user). References a record that is/was created in the users.csv file with type of 'student'.
scoreStatus Yes Enumeration Permitted values are: { exempt | fully graded | not submitted | partially graded | submitted | late | incomplete | missing | withdrawal | in progress }
This vocabulary may be extended.
score No Float A floating point number (the range should be consistent with that defined in the associated lineItem resultValueMin and resultValueMax fields).
scoreDate Yes Date The date the result was submitted and/or the 'scoreStatus' was changed.
comment No String Human readable comment about the result.
textScore No String An optional non-numeric score value. If a scoreScale is assigned then the value must align with the scale.
This is a new column added in version 1.2.
classSourcedId No GUID Reference Unique identifier of the class. References a record that is/was created in the classes.csv file.
This is a new column added in version 1.2.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated lineItem using the 'lineItemSourcedId' attribute. This produces a dependency on the lineItems.csv. This creates a corresponding dependency on the academicSessions.csv, classes.csv, courses.csv, orgs.csv and categories.csv files;
  • This requires a reference to the associated student (user) using the 'studentSourcedId' attribute. This produces a dependency on the users.csv. This creates a corresponding dependency on the orgs.csv, roles.csv and userProfiles.csv files.

3.17 'resultScoreScales.csv'

A new file added in version 1.2.

This file represents the mapping between the Results and ScoreScales datasets from the OneRoster Gradebook specification.

The 'resultScoreScales.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the resultScoreScale.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title No String Name of the related scoreScale.
resultSourcedId Yes GUID Reference. SourcedId of the reference Result.
scoreScaleSourcedId Yes GUID Reference. SourcedId of the reference ScoreScale.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated lineItem using the 'resultSourcedId' attribute. This produces a dependency on the results.csv. This leads to the corresponding dependencies on the users.csv, classes.csv, lineItems, categories.csv, academicSessions.csv, courses.csv and orgs.csv files;
  • This requires a reference to the associated scoreScale using the ‘scoreScaleSourcedId’ attribute. This produces a dependency on the scoreScales.csv. This leads to the corresponding dependencies on the academicSessions.csv, classes.csv, courses.csv and orgs.csv files.

3.18 'roles.csv'

A new file added in version 1.2.

The set of roles for a user in an org. A user can have 1-many roles in 1-many orgs. This is defined as a set of 1-1 mappings.

The 'roles.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the role.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
userSourcedId Yes GUID Reference The user whose role is being defined.
roleType Yes Enumeration Determines if this is the primary role. Only one role per orgnaization can be 'primary'. Permitted values are: { primary | secondary }
role Yes Enumeration The type of role. Permitted values are: { administrator | aide | guardian | parent | proctor | relative | student | teacher }
This vocabulary may be extended.
beginDate No Date The start date on which the role became active (inclusive).
endDate No Date The end date on which the role ceased to be active (exclusive).
orgSourcedId Yes GUID Reference SourcedId of the Org within which the User has the assigned role.
userProfileSourcedId No GUID Reference SourcedId of the UserProfile for the User.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated user using the 'userSourcedId' attribute. This produces a dependency on the users.csv. This also produces a dependency on the orgs.csv;
  • This requires a reference to the associated org using the 'orgSourcedId' attribute. This produces a dependency on the orgs.csv;
  • If a value for the 'userProfileSourcedId' attribute is supplied, a link to the associated userProfile is established. This produces a dependency on the userProfiles.csv.

3.19 'scoreScales.csv'

A new file added in version 1.2.

This file represents the ScoreScales dataset from the OneRoster Gradebook specification. This is a new CSV file added in OR 1.2.

The 'scoreScales.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the scoreScale.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
title Yes String A human readable title for the score scale.
type Yes String The type of score scaling e.g. percent.
orgSourcedId Yes GUID Reference The org for which the score scale is used.
courseSourcedId Yes GUID Reference The course for which the score scale is used.
classSourcedId Yes GUID Reference The class for which the score scale is used.
scoreScaleValue Yes List of Strings A specific mapping of values between two score scales. The left hand side (LHS) value is the reference point. These values are enclosed in ‘{}’ with a colon used to separate the values. If more than one score scale mapping is needed, use double quotes, and separate with commas (per [RFC4180]).
Examples: {Pass:50} and "{A+:100},{A:94},{A-:90}", {A:7-10}, {60-69:B}, etc.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated user using the 'orgSourcedId' attribute. This produces a dependency on the orgs.csv;
  • This requires a reference to the associated user using the 'courseSourcedId' attribute. This produces a dependency on the courses.csv. The courses dependency creates a further set of dependencies on the on the academicSessions.csv and orgs.csv files;
  • This requires a reference to the associated user using the 'classSourcedId' attribute. This produces a dependency on the classes.csv. This creates a corresponding dependency on the academicSessions.csv and courses.csv files. The courses dependency creates a further set of dependencies on the on the academicSessions.csv and orgs.csv files.

3.20 'userProfiles.csv'

A new file added in version 1.2.

This information is used to enable authentication/authorization/access management of the various systems/tools/apps/etc. available to the user.

The accounts.csv file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the userProfile.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
userSourcedId Yes GUID Unique ID for the corresponding user.
profileType Yes String The type of user profile. This should be a human readable label that has some significance in the context of the related system, app, tool, etc.
vendorId Yes String The unique identifier for the vendor of the system, tool, app, etc. which requires the use of this user profile.
applicationId No String The unique identifier for the vendor of the system, tool, app, etc. which requires the use of this account.
description No String A human readable description of the use of the account. This should not contain any security information for access to the account.
credentialType Yes String The type of credentials for the user profile. This should be indicative of when this credential should be used.
username Yes String The username for this profile.
password No String The password for the user. This may or may not be an encrypted string. If encrypted, the processing system must be aware of the encryption method.

The extension mechansim should be used to support the exchange of the appropriate credentials and other details required for the profile.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated user using the 'userSourcedId' attribute. This produces a dependency on the users.csv. This also produces a dependency on the orgs.csv.

3.21 'userResources.csv'

A new file added in version 1.2.

This file represents the links between the Resources and Users datasets from the OneRoster Rostering and Resources specification.

The 'userResources.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the userResourse relationship.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
userSourcedId Yes GUID Reference. SourcedId of the user who will have access to this resource.
orgSourcedId No GUID Reference. SourcedId of the reference Organization.
classSourcedId No GUID Reference. SourcedId of the reference Class.
resourceSourcedId Yes GUID Reference. SourcedId of the Resource associated with the User.

The dependencies of this file on other files when supporting bulk processing are:

  • This requires a reference to the associated user using the 'userSourcedId' attribute. This produces a dependency on the users.csv. This also produces a dependency on the orgs.csv;
  • There may be a reference to the associated organization (org) using the ‘orgSourcedId’ attribute. This produces a dependency on the orgs.csv;
  • There may be a reference to the associated class (class) using the 'classSourcedId' attribute. This produces a dependency on the classes.csv. This dependency on the class leads to the corresponding dependencies on the academicSessions.csv, courses.csv and orgs.csv files;
  • This requires a reference to the associated resource (resource) using the ‘resourceSourcedId’ attribute. This produces a dependency on the resources.csv.

3.22 'users.csv'

This file represents the Users dataset from the OneRoster Rostering specification.

Several columns have been deleted and new ones added in this release.

The 'users.csv' file format and contents.
Column Field Header Required Format Description
sourcedId Yes GUID Unique ID for the user.
status Yes for Delta Enumeration Permitted values for Delta mode: { active | tobedeleted }.
This MUST NOT be used for the Bulk mode.
dateLastModified Yes for Delta DateTime The date that this record was last modified. ISO 8601 format [ISO8601].
This MUST NOT be used for the Bulk mode.
enabledUser Yes Boolean Permitted values are: { true | false }. 'false' denotes that the user is an active record but system access is curtailed according to the local administration rules.
username Yes String User name.
userIds No List of Strings External machine-readable ID (e.g. LDAP id, LTI id) for this user. The ID must be accompanied by a type to indicate the nature of the Identifier. The Type and ID values are enclosed in ‘{}’ with a colon used to separate the values. If more than one userId is needed, use double quotes, and separate with commas (per [RFC4180]).
Examples: {LDAP:Id} and "{LDAP:Id},{LTI:Id},{Fed:Id}"
givenName Yes String User's first name.
familyName Yes String User's surname.
middleName No String User's middle name(s). If more than one then they are separated by a space.
identifier No String Identifier for the user with a human readable meaning.
email No String Email address for the User.
sms No String SMS address for the User.
phone No String Phone number for the User.
agentSourcedIds No List of GUID References SourcedIds of the Users to which this user has a relationship. If multiple IDs are required then use double quotes and separate with commas.
Note: In most cases this will be for indicating parental relationships.
grades No String Grade(s) for which a user with role 'student' is enrolled. The permitted vocabulary should be agreed as part of the definition of the usage of this specification.
password No String The password for the user. This may or may not be an encrypted string. If encrypted the processing system must be aware of the encryption method.
userMasterIdentifier No String The master identifier that could be used to provide globally unique identification of the user across all of the tools, systems, apps, etc. available/accessed by the user.
This is a new column added in version 1.2.
resourceSourcedIds No List of GUID References The list of sourcedIds for the resources that are to be made available to this user.
This is a new column added in version 1.2.
preferredGivenName No String The given name by which the User prefers to be known.
This is a new column added in version 1.2.
preferredMiddleName No String The middle names by which the User prefers to be known.
This is a new column added in version 1.2.
preferredFamilyName No String The family name by which the User prefers to be known.
This is a new column added in version 1.2.
primaryOrgSourcedId No GUID Reference The sourcedId of the primary 'org' for the 'user'. In OR 1.2 a user can have one or more 'roles' in one or more 'org's and so identification of the primary 'org' is now required.
This is a new column added in version 1.2.

The dependencies of this file on other files when supporting bulk processing are:

  • This produces an implicit dependency on the roles.csv file. This creates a dependency on the orgs.csv file;
  • This produces an implicit optional dependency on the userProfiles.csv file. This creates a dependency on the orgs.csv file;
  • There may be reference to agents (users) in the SAME file through the 'agentsSourcedIds' attribute but this creates no new file dependencies;
  • There may be reference to the associated resources (resource) using the ‘resourceSourcedIds’ attribute. This produces a dependency on the resources.csv.

4. Extending & Profiling the CSV Binding

This Section is NON-NORMATIVE.

4.1 Extending the CSV Binding

4.1.1 Proprietary Data Elements

It is recognized that implementers may wish to extend the specification. The preferred mechanism for doing this is for implementers to use an extension space within the OneRoster data model, and then set their CSV parsers to read those extension attributes. Extensions are ONLY permitted by adding 'metadata' named columns to the end of the set of columns already defined in the specification.

An example of creating such an extension is given in the accompanying Implementation Guide document [OR-IG].

4.1.2 Proprietary Vocabulary Terms

In this version the ability to extend some of the enumerated vocabularies has been added: currently, ONLY the 'classType' (classes.csv), 'role' (enrollments.csv and roles.csv), 'roles' (resources.csv), 'scoreStatus' (results.csv), 'SessionTypeEnum', 'sex' (demographics.csv), 'source' (lineItemLearningObjectiveIds.csv and resultLearningObjectiveIds.csv) and 'type' (academicSession.csv and orgs.csv) vocabularies MAY be extended. Each proprietary term must start with the characters 'ext:'.

An example of creating such an extension is given in the accompanying Implementation Guide document [OR-IG].

4.2 Profiling the CSV Binding

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

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

Valid Profiles must be restrictive i.e. optional features can be removed or constraints increased but new features must not be added. A Profile of this service is made by annotating the UML supplied with the documentation for the specification.

It is strongly recommended that a profile of this specification is undertaken either by, or with the close support, of IMS Global. However, no matter who is responsible for creating the profile artefacts (documents, OpenAPI files, XSDs, etc.), it is strongly recommended that the IMS specification tools are used. This will ensure that the artefacts are consistent with the base specifications and that useful support documentation is automatically produced e.g. creation of a document that summarises the differences between the base specification and the profile. Organizations wishing to produce a profile of this specification should contact Lisa Mattson (IMS Global Chief Operations Officer) at: lmattson@imsglobal.org.

A. File Dependencies Matrix

This section is non-normative.

This Section is NON-NORMATIVE.

Table A1 is the dependency matrix for the CSV files. This shows the set of CSV files that MUST be supplied for BULK exchange; this dependency is created because the set of supplied CSV files must be semantically complete and the data model defines certain fields must be present within a CSV file. To read the matrix select the CSV file of interest in the left hand column. The entries along that row indicate if some other CSV file is required (R) or may be required (O) if an associated optional field has been included in the source CSV file.

The color coding for Table A1 is:-

  • Green - denotes a source file that has NO dependencies on the other CSV files (the manifest will include a single data file i.e. either 'categories.csv' or 'resources.csv')
  • Yellow - denotes a source file that has a dependency only on itself i.e. another row in the same CSV file (the manifest will include a single data file i.e. of either 'academicSessions.csv' or 'orgs.csv')
  • Orange - denotes a source file that has a dependency on some other file that itself is self contained i.e. a CSV file that is color-coded Green or Yellow. 'courses.csv' has a dependency on the Yellow and/or Green coded files
  • Pink - denotes a source file that a dependency on some other file that itself has other dependencies. Pink coded files are 'classes.csv', 'classResources.csv', 'courseResources.csv', 'demographics.csv', 'roles.csv', 'userProfiles.csv' and 'users.csv'
  • Red - denotes a source file that as a further depth of dependency when compared to the files that are color coded Pink. Red coded files are 'enrollments.csv', 'lineItems.csv', 'lineItemScoreScales.csv', 'results.csv', 'resultScoreScales.csv', and 'scoreScales.csv'.
Table A1 - CSV files dependencies matrix.
File Names Rostering Resources Gradebook
academic
Sessions
classes courses demographics enrollments orgs roles user
Profiles
users resources class
Resources
course
Resources
user
Resources
categories line
Items
results score
Scales
result
Score
Scales
line
Item
Score
Scales
result
Learning
Objective
Ids
line
Item
Learning
Objective
Ids
academicSessions O(P)
classes [C] R(T), O[S] R R(S), R[S]
courses [S] O(SY) R
demographics R[U] R[U] O[U] R
enrollments R[C], O(SY) R R[C] R(S), R(U) R[U] O[U] R
orgs O(P)
roles R O R
userProfiles R[U] R
users [U] R R O O(A) O
File Names academic
Sessions
classes courses demographics enrollments orgs roles user
Profiles
users resources class
Resources
course
Resources
user
Resources
categories line
Items
results score
Scales
result
Score
Scales
line
Item
Score
Scales
result
Learning
Objective
Ids
line
Item
Learning
Objective
Ids
resources
classResources R[C] R R[C] R[C] R
courseResources O[S] R R[S] R
userResources O[C] O O R R
File Names academic
Sessions
classes courses demographics enrollments orgs roles user
Profiles
users resources class
Resources
course
Resources
user
Resources
categories line
Items
results score
Scales
result
Score
Scales
line
Item
Score
Scales
result
Learning
Objective
Ids
line
Item
Learning
Objective
Ids
categories
lineItems [L] R(GP), R[C] R R[C] R[C] R
results [R] R[L], O(SY) R[L] R[L] R[L] R[U] O[U] R(S) R[L] R
scoreScales [X] R[C], O[S] R R, R[C] R, R[C], R[S]
resultScoreScales R[X], R[R] R[X], R[R] R[X], R[R] R[X], R[R] R[R] O[R] R[R] R[R] R[R] R R
lineItemScoreScales R[X], R[L] R[X], R[L] R[X], R[L] R[X], R[L] R[L] R R
resultLearningObjectiveIds R[R] R[R] R[R] R[R] R[R] O[R] R[R] R[R] R[R] R
lineItemLearningObjectiveIds R[L] R[L] R[L] R[L] R[L] R

The key conclusions are:

  • No CSV file is dependent on the 'classResoures.csv', 'courseResources.csv', 'demographics.csv', 'enrollments.csv', 'lineItemScoreScales.csv', 'results.csv', 'resultScoreScales.csv', 'lineItemLearningObjectiveIds.csv', 'resultLearningObjectiveIds.csv' and 'userResources.csv'files
  • The Gradebooks-oriented CSV file-set ('categories.csv', 'lineItems.csv', 'results.csv', 'lineItemLearningObjectiveIds.csv', 'resultLearningObjectiveIds.csv', 'scoreScales.csv', 'lineItemScoreScales.csv' and 'resultScoreScales.csv' files) IS dependent on several of the Rostering CSV files
  • The Rostering-oriented CSV file-set must consist of 'academicsessions.csv', 'classes.csv', 'courses.csv', 'enrollments.csv', 'orgs.csv', 'roles.csv' and 'users.csv'.

NOTE: An implementation may impose further constraints on the set of files required for semantic consistency i.e. more files may need to be supplied than the strict minimum.

B. Revision History

This section is non-normative.

B.1 Version History

Publication history and revision details for this specification.
Version No. Release Date Comments
Final Release v1.0 3rd June 2015 The first formal release of the Final Release version of this document.
Final Release v1.1 17th April, 2017 The second formal release of this document. The conformance requirements, for both CSV and REST, have been made considerably more demanding and specific.
Candidate Final Public Release v1.2 1st July, 2021 The third formal release of this document. A number of new data model features have been added to the operational modes of Rostering, Resources and Gradebook. Support for eight new CSV files has been included, namely:
  • Rostering based - 'roles.csv' and 'userProfiles.csv'
  • Resources based - 'userResources.csv'
  • Gradebook based - 'scoreScales.csv', 'resultScoreScales.csv', 'lineItemScoreScales', 'lineItemLearningObjectiveIds.csv' and 'resultLearningObjectiveIds.csv'.

B.2 Changes in this Version

The changes made for this Final Release 1.2 document are:

  • The following editorial changes have been made:-
    • For the purposes of easing internationalization of this specification, all references to CEDS have been removed from the data model descriptions. Usage of the appropriate vocabularies are discussed in the Implementation Guide [OR-IG] and any appropriate profiling documents.
  • The following CSV files have been added:-
    • 'userProfiles.csv'
    • 'roles.csv'
    • 'userResources.csv'
    • 'scoreScales.csv'
    • 'lineItemScoreScales.csv'
    • 'resultScoreScales.csv'
    • 'lineItemLearningObjectiveIds.csv'
    • 'resultLearningObjectiveIds.csv'.
  • The following changes have been made to the 'manifest.csv' file:-
    • Rows for the eight new CSV files have been added
    • The 'oneroster.version' row is required to have a value of '1.2' when referring to an OR 1.2 compliant manifest
  • The following changes have been made to the 'categories.csv' file:-
    • The 'weight' column has been added.
  • The following changes have been made to the 'demographics.csv' file:-
    • The enumerated vocabulary for the 'sex' column is now permitted to have new values of 'other and 'unspecified'.
  • The following changes have been made to the 'lineItems.csv' file:-
    • The 'schoolSourcedId' column has been added
    • The 'resultValueMin' and 'resultValueMax' attributes have been made optional
    • The 'gradingPeriodSourcedId' column has been renamed 'academicSessionSourcedId'.
  • The following changes have been made to the 'results.csv' file:-
    • The 'classSourcedId' and 'textScore' columns have been added
    • The permitted tokens in the 'scoreStatus' column has been expanded with new values of { late | incomplete | missing | withdrawal | in progress }.
  • The following changes have been made to the 'users.csv' file:-
    • The 'orgSourcedIds' column has been removed (org identification is now achieved via the 'roles.csv' file)
    • The 'role' column has been removed (role allocation is now achieved via the 'roles.csv' file)
    • The 'preferredGivenName', 'preferredMiddleName' and 'preferredFamilyName' columns have been added
    • The 'primaryOrgSourcedId' column has been added
    • The 'userMasterIdentifier' column has been added.

C. References

C.1 Normative references

[ISO8601]
Representation of dates and times. ISO 8601:2004.. International Organization for Standardization (ISO). 2004. ISO 8601:2004. URL: http://www.iso.org/iso/catalogue_detail?csnumber=40874
[OR-CC]
OneRoster 1.2 Conformance and Certification. IMS Global Learning Consortium, Inc. July, 2021. URL: https://www.imsglobal.org/spec/oneroster/v1p2/cert/
[OR-IG]
OneRoster 1.2 Implementation Guide. IMS Global Learning Consortium, Inc. July, 2021. URL: https://www.imsglobal.org/spec/oneroster/v1p2/impl/
[ORGBK-SM]
OneRoster 1.2 Gradebook Services. IMS Global Learning Consortium, Inc. July, 2021. URL: https://www.imsglobal.org/spec/oneroster/v1p2/gradebook/info
[ORRES-SM]
OneRoster 1.2 Resource Services. IMS Global Learning Consortium, Inc. July, 2021. URL: https://www.imsglobal.org/spec/oneroster/v1p2/resource/info
[ORROS-SM]
OneRoster 1.2 Rostering Services. IMS Global Learning Consortium, Inc. July, 2021. URL: https://www.imsglobal.org/spec/oneroster/v1p2/rostering/info
[RFC1951]
DEFLATE Compressed Data Format Specification version 1.3. P. Deutsch. IETF. May 1996. Informational. URL: https://www.rfc-editor.org/rfc/rfc1951
[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC3629]
UTF-8, a transformation format of ISO 10646. F. Yergeau. IETF. November 2003. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3629
[RFC4180]
Common Format and MIME Type for Comma-Separated Values (CSV) Files. Y. Shafranovich. IETF. October 2005. Informational. URL: https://www.rfc-editor.org/rfc/rfc4180

D. List of Contributors

The following individuals contributed to the development of this document:

Name Organization Role
William BakerPearson
Arthur BarstowMcGraw-Hill
Hank DavidsonPearson
Vijay DhanarajClasslink
David GappaSafari Montage
Linda FengUnicon
Viktor HaagD2L
Richard HeimLearning Mate
Tom IngramEscambia County School District
Oxana JurosevicInstructure
Mike KaastraD2L
Jong KimPearson
Lisa MattsonIMS Global
David MayesGwinnett County Schools
Joshua McGheeIMS Globaleditor
Phil NichollsIMS Global
Padraig O'hiceadhaHMH
Upendra PenegalapatiPearson
George PerreaultClasslink
James PerreaultFLVS
Patrick PorterHouston ISD
Matt RichardsInfinite Campuscochair
Kurt RompotPearson
Marc SheftelPearson
Colin SmytheIMS Globaleditor
Konrad StimelingK12
Matt VellaSchoology
TJ VeringMicrosoft
Mark WallsGwinnett County Schools
Stanley WattsClasslink
Mike ZackersonInstructure

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 OneRoster: CSV Binding 1.2

Date: July 1st, 2021