Basic Roster File Format

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

In this article

Import with SFTP

Requirements to files

File templates

schools.csv

students.csv

teachers.csv

sections.csv

enrollments.csv

admins.csv

staff.csv

Alongside supporting CSV file export in OneRoster file format, most Student Information Systems (SIS) also support data export in Clever-like data format, which is called GG4L Basic Roster data standard. Therefore, the best way to generate CSV files in Basic Roster format is by generating them within SIS. Typing data manually or changing data once it’s exported can lead to unexpected file formatting errors, which can prevent your data from being processed in School Passport.

The following GG4L-integrated SIS data-consuming Vendors, that support data sharing via Basic Roster: Lightspeed Systems, SchoolsBuddy, POSSIP, Rank One Sport, IXL - Learning, GG4L Compass, SFTP, and EdPay.

Import with SFTP

The import of Basic Roster files is supported through the secure SFTP protocol, ensuring encryption of data both during the import process and while in transit.  Import via SFTP is recommended for districts that will be doing frequent data imports or has an SIS that enables/supports automatic SFTP transfers. Also, it allows you to schedule automatic file processing. Basic RosterCSV files can be uploaded on the SFTP server separately or compressed to the zip archive.

To obtain SFTP credentials for a specific Vendor, you can find instructions under the Supported Apps category within the vendor-specific article. 

Requirements to files

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

Use the following specifications for all CSV files:

• CSV stands for comma-separated values, a file format (.csv) for spreadsheets. You can use CSV files to import data from your SIS.
• File names and field headers must be identical to those listed in the specification.
• For headers, case-sensitive matching is not required.
• All files must be present for upload to be processed. For example, a directory with only students.csv will not be processed.
• 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.
• 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.

Download Basic Roster templates

For details on Clever file format, refer to the Basic Roster specification.

File templates

To ensure your OneRoster CSVs are optimized, all five specific files are required, each with their corresponding column headers and data. 

You can download the BasicRoster CSV file templates to provide a structured format for organizing and preparing your data for seamless integration with

schools .csv

Required. Contains a list of schools within the districts.

Column header	Required
School_id	Yes
School_name	Yes
School_number	Yes
State_id	No
Low_grade	No
Hight_grade	No
Principal	No
Principal_email	No
School_address	No
School_city	No
School_zip	No
School_phone	No

students.csv

Required. Contains a list of students and their parents/guardians. To add multiple parent/guardian contacts to one student, you may create multiple rows for a single student with different contact information.

Column header	Required
School_id	Yes
Student_id	Yes
Last_name	Yes
First_name	Yes
Student_number	No
State_id	No
Middle_name	No
Grade	No
Gender	No
Greduation_year	No
DOB	No
Contact_relationship	No
Contact_type	No
Contact_name	No
Contact_email	No
Contact_sis_id	No

teachers.csv

Required. Contains a list of the district`s teaching staff.

Column header	Required
School_id	Yes
Teacher_id	Yes
Last_name	Yes
First_name	Yes
Teacher_number	No
State_teacher_id	No
Teacher_email	No
Middle_name	No
Title	No
Username	No

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

Column header	Required
School_id	Yes
Section_id	Yes
Teacher_id	Yes
Name	No
Section_number	No
Grade	No
Course_name	No
Course_number	No
Course_description	No
Period	No
Subject	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.

Column header	Required
School_id	Yes
Section_id	Yes
Student_id	Yes

admins.csv

Deprecated. Contains school administrators, such as principals, librarians, and technical coordinators, not included in class rosters. Each administrator should have a row for each school they manage.

Column header	Required
School_id	Yes
Staff_id	Yes
Admin_email	Yes
First_name	Yes
Last_name	Yes
Admin_title	No
Username	No
Password	No

staff.csv