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-12] - the best practices to be adopted when processing OneRoster CSV files;
• OneRoster 1.2 Conformance and Certification [OR-CC-12] - 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-12] 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 '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', 'textScore', 'inProgress', 'incomplete', 'late' and 'missing' columns have been added
  • 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
  • The 'pronouns' 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:

1.5 Acronyms

API

Application Programming Interface

BOM

Beginning of Message

CASE

Competencies 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

PII

Personal Identifiable Information

RFC

Request For Comment

SIS

Student Information System

URN

Uniform Resource Name

UTF

Unicode Transformation Format

UUID

Universally Unique Identifier

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-12], Resources [ORRES-SM-12] and Gradebook [ORGBK-SM-12] 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.

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.

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

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 data-set from the OneRoster Rostering specification.

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 data-set from the OneRoster Gradebook specification.

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

3.4 'classes.csv'

This file represents the Classes data-set from the OneRoster Rostering specification.

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 data-sets from the OneRoster Rostering and Resources specification.

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 data-sets from the OneRoster Rostering and Resources specification.

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 data-set from the OneRoster Rostering 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 organization (org) using the ‘orgSourcedId’ attribute. This produces a dependency on the orgs.csv.

3.8 'demographics.csv'

This file represents the Demographics data-set from the OneRoster Rostering 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 data-set from the OneRoster Rostering specification.

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 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 data-set from the OneRoster Gradebook specification.

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.
• This requires a reference to the associated school via the 'schoolSourcedId' attribute. This creates a dependency on the orgs.csv file.

3.12 'lineItemScoreScales.csv'

A new file added in version 1.2.

This file represents the mapping between the LineItems and ScoreScales data-sets from the OneRoster Gradebook specification.

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 data-set from the OneRoster Rostering specification.

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 data-set from the OneRoster Resources specification.

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 dependencies of this file on other files when supporting bulk processing are:

• This requires a reference to the associated result 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 data-set from the OneRoster Gradebook specification.

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 data-sets from the OneRoster Gradebook specification.

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 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 data-set from the OneRoster Gradebook specification. This is a new CSV file added in OR 1.2.

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 extension mechanism 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 data-sets from the OneRoster Rostering and Resources specification.

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 data-set from the OneRoster Rostering specification.

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

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 a reference to the primary org for the user. 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.1 Extending the CSV Binding

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 1EdTech. However, no matter who is responsible for creating the profile artifacts (documents, OpenAPI files, XSDs, etc.), it is strongly recommended that the 1EdTech specification tools are used. This will ensure that the artifacts 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 the 1EdTech Vice President of Operations at: operations@1edtech.org.