OneRoster File Format

This article describes how to create and format CSV files for School Passport using the OneRoster standard.

In this article

Import with SFTP and REST API’s

Requirements to files

File templates

academicSessions.csv

orgs.csv

classes.csv

courses.csv

users.csv

enrollments.csv

demographics.csv

OneRoster is an open, standards-based way to share classes and roster information between systems. The OneRoster standard has been developed by IMS Global Learning Consortium® to facilitate the exchange of roster information and grades between an educational organization and a software vendor.

OneRoster is the standard specification for the secure sharing of class rosters and related data between the Student Information System (SIS) and any other system, typically a content application or learning management system (LMS). The OneRoster standard supports spreadsheet-style (CSV) export-import as well as direct system exchanges using REST API.

Import with SFTP and REST API’s

School data also can be imported via REST API, which means that you can sync objects from SISes that provide OneRoster. Using this sync method, you can connect directly to your SIS using the REST-based OneRoster 1.1 API provided by the SIS and synchronize data directly instead of using CSV file upload.

The following GG4L-integrated SIS Vendors support data synchronization via REST-based OneRoster 1.1 API: ClassLink, Infinite Campus, Skyward, and Aeries.

Requirements to files

OneRoster CSV files should contain only active student data. For example, the students.csv file should contain only currently enrolled students. Ingestion of historical or archived data is not supported. For more information about OneRoster file requirements, see IMS OneRoster®: Specification.

• Use the comma-separated values format (CSV) for all uploads to the SFTP server.
• CSV files should contain field values separated by commas, with line breaks between rows. Double quotes around fields are optional, except when the field value includes a comma, where they are required.
• Use UTF-8 encoding. If you are updating a CSV file import, then remember to confirm the UTF-8 encoding to avoid generating unwanted special characters in your file. If you save your file after forgetting to confirm its UTF-8 encoding, then your data will be corrupted when you upload it as a new spreadsheet.
• File names and field headers must be identical to those listed in the specification. 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. A name convention for the metadata headers is the following: metadata.[metadataFieldName]
  
  For details, on how to map metadata fields, see Attribute Mapping.
• Each CSV file must contain all required fields provided in tables.

File templates

All five specific files are required to ensure your OneRoster CSVs are optimized, each with their corresponding column headers and data. The demographics.csv is strictly optional, and not required.

academicSessions.csv

Required. Contains all periods of time during which courses and/or classes are scheduled during the school year.

For details, refer to the OneRoster specification.

Column header	Required
sourcedId	Yes
title	Yes
type	Yes
startDate	Yes
endDate	Yes
status	No
dateLastModified	No
metadata	No
parent	No
children	No
schoolYear	No

orgs.csv

Required. Contains all organizations that are parts of the district, such as departments, schools, districts, and states. School Passport works only works with schools. All other types of organizations other than schools are ignored.

For details, refer to the OneRoster specification.

Column header	Required
sourcedId	Yes
name	Yes
type	Yes
status	No
dateLastModified	No
metadata	No
identifier	No
parent	No
children	No

classes.csv

Required. Contains all classes (sections) within the current school year that should exist in the School Passport or need to be shared with the Ed-Tech Vendor. A class is an instance of a course where students and teachers are enrolled. A class is typically held within a term. 

For details, refer to the OneRoster specification.

Column header	Required
sourcedId	Yes
title	Yes
classType	Yes
schoolSourcedId	Yes
termsSourcedId	Yes
classCode	No
course	No
dateLastModified	No
grades	No
location	No
metadata	No
periods	No
resources	No
status	No
subjectCodes	No
subjects	No

courses.csv

Required. Contains the course offerings. These are sometimes referred to as “class templates” and are not assigned to teachers or students.

For details, refer to the OneRoster specification.

Column header	Required
sourcedId	Yes
title	Yes
orgSourcedId	Yes
status	No
dateLastModified	No
schoolYearSourcedId	No
courseCode	No
subjects	No
subjectCodes	No

users.csv

Required. Contains information about all students, teachers, administrators, and parents related to a district.

Users within the file are typically linked to other users. For example, a student may have parents. The "agents" attribute allows for building relationships between the users. Note that these relationships are typically built from the student’s point of view - so a student will link to his/her parents (via the agent attribute). The reverse view MUST also be modeled. For example, a parent user role MUST have an agent that is of a student role.

For details, refer to the OneRoster specification.

Column header	Required
sourcedId	Yes
orgSourcedId	Yes
username	Yes
givenName	Yes
familyName	Yes
status	No
dateLastModified	No
role	No
userIds	No
identifier	No
email	No
sms	No
phone	No
agents	No

enrollments.csv

Required. Contains the full set of student and teacher class enrollments for a school year that should exist within the School Passport or need to be shared with the Ed-Tech vendors. Each individual student and teacher must have a separate record in the enrollments.csv for each scheduled class. 

For details, refer to the OneRoster specification.

Column header	Required
sourcedId	Yes
status	Yes
schoolSourcedId	Yes
classSourcedId	Yes
userSourcedId	Yes
dateLastModified	No
metadata	No
role	No
primary	No
beginDate	No
endDate	No

demographics.csv

Optional. Contains additional users information such as birthdate, sex, and ethnicity.

Demographic information is taken from the Common Educational Data Standards from the US government.

For details, refer to the OneRoster specification.

Column header	Required
sourcedId	Yes
title	Yes
metadata	Yes
birthDate	Yes
sex	Yes
americanIndianOrAlaskaNative	Yes
asian	Yes
blackOrAfricanAmerican	Yes
nativeHawaiianOrOtherPacificIslander	Yes
white	Yes
demographicRaceTwoOrMoreRaces	Yes
hispanicOrLatinoEthnicity	Yes
countryOfBirthCode	Yes
stateOfBirthAbbreviation	Yes
cityOfBirth	Yes
publicSchoolResidenceStatus	Yes
status	No
dateLastModified	No