Roster Data
File format guidelines
The file should always include a header row with the columns matching specified Field names.
Column values should be comma-separated and enclosed in double-quotes (at minimum all string values should be double-quoted).
All the Required fields must be provided. Other values may be left blank or the column may be omitted altogether.
Filenames can include a base suffix to distinguish them from other files of the same type (e.g. users_103.csv or users_20220301.csv). However, the filename should always begin with the name of the entity it contains and have a .csv suffix.
Organization
Filename: orgs.csv
Spec: doc
| Field | Required | Format | Description/Guidance |
|---|---|---|---|
| sourcedId | Yes | GUID | Should be unique for this type |
| status | No | Enumeration | Used in delta mode only. Allows values: active, tobedeleted |
| dateLastModified | No | DateTime | Used in delta mode only. Format: YYYY-MM-DD |
| name | Yes | String | Common name of school/district |
| type | Yes | Enumeration | Allowed values: school, district |
| identifier | No | String | NCES ID for the school/district. |
| parentSourcedId | No | GUID Reference. | SourcedId of the Parent org. |
| metadata.address1 | No | String | Building street address |
| metadata.address2 | No | String | Building street address |
| metadata.city | No | String | Building city |
| metadata.state | No | String | Building state |
| metadata.postCode | No | String | Building ZIP code |
| metadata.phoneNumber | No | String | Building phone number |
| metadata.attendanceType | No | String | Allowed values: daily, period |
| metadata.attendanceReporting | No | String | Allowed values: negative, positive |
| metadata.attendancePeriod | No | String | The homeroom period for the school. |
| metadata.scheduleType | No | String | Type of class scheduled used in the school. |
| metadata.scheduleBasis | No | String | Allowed values: semester, trimester |
Academic Session
Filename: academicsessions.csv
Spec: doc
| Field | Required | Format | Description/Guidance |
|---|---|---|---|
| sourcedId | Yes | GUID | SourcedId of this academicSession. |
| status | Yes for Delta | Enumeration | |
| dateLastModified | Yes for Delta | DateTime | |
| title | Yes | String | Name or title of the academic session. |
| type | Yes | Enumeration | schoolYear |
| startDate | Yes | Date | Inclusive start date for the academic session. |
| endDate | Yes | Date | Exclusive end date for the academic session. |
| 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). |
Course
Filename: courses.csv
Spec: doc
| Field | Required | Format | Description/Guidance |
|---|---|---|---|
| sourcedId | Yes | GUID | Key. Must be unique. |
| status | Yes for Delta | Enumeration | |
| dateLastModified | Yes for Delta | DateTime | |
| schoolYearSourcedId | No | GUID Reference. | SourcedId of ype of "schoolYear" (e.g. 2022) |
| title | Yes | String | Name of the course. |
| courseCode | No | String | Human readable course code. |
| grades | No | List of Strings | Grade(s) for which the class is attended. The permitted vocabulary is from CEDS (Version 5) for the 'Entry Grade Level' element https://ceds.ed.gov/CEDSElementDetails.aspx?TermId=7100 |
| orgSourcedId | Yes | GUID Reference. | |
| subjects | No | List of Strings | |
| subjectCodes | No | String |
Class
Filename: classes.csv
Spec: doc
| Field | Required | Format | Description/Guidance |
|---|---|---|---|
| sourcedId | Yes | GUID | Unique ID for the class. SourcedId is used in other files and must be unique across all classes. |
| status | Yes for Delta | Enumeration | |
| dateLastModified | Yes for Delta | DateTime | |
| title | Yes | String | Name of this class. |
| grades | No | List of Strings | Grade(s) for which the class is attended. The permitted vocabulary is from CEDS (Version 5) and the 'Entry Grade Level' element https://ceds.ed.gov/CEDSElementDetails.aspx?TermId=7100 |
| 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 | See section 4.13.1 [OneRoster, 20a] for the enumeration list. |
| 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. | SourcedId of the terms (the academicSessions) in which the class is taught. |
| subjects | No | List of Strings | |
| subjectCodes | No | List of Strings | |
| 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 RFC 4180). Examples: 1; "1,3,5" |
User
Filename: users.csv
Spec: doc
| Field | Required | Format | Description/Guidance |
|---|---|---|---|
| sourcedId | Yes | GUID | |
| status | Yes for Delta | Enumeration | See section 4.13.8 [OneRoster, 20a] for the enumeration list. This MUST NOT be used for the Bulk mode. |
| dateLastModified | Yes for Delta | DateTime | The date that this record was last modified. This MUST NOT be used for the Bulk mode. |
| enabledUser | Yes | Enumeration | |
| orgSourcedIds | Yes | List of GUID References. | SourcedIds of the Orgs to which this user belongs. (Note in most in cases, it is expected that users will belong to a single school). |
| role | Yes | Enumeration | student |
| username | No | String | |
| userIds | No | List of Strings | |
| 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. |
| 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 is from CEDS (Version 5) for the 'Entry Grade Level' element https://ceds.ed.gov/CEDSElementDetails.aspx?TermId=7100. |
| password | No | String | |
| metadata.commLanguage | No | Enumeration | 2 char ISO-639-1 identifier |
Enrollment
Filename: enrollments.csv
Spec: doc
| Field | Required | Format | Description/Guidance |
|---|---|---|---|
| sourcedId | Yes | GUID | Unique identifier of this enrollment. |
| status | Yes for Delta | Enumeration | |
| dateLastModified | Yes for Delta | DateTime | |
| 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 | teacher |
| primary | No | Enumeration | true |
| beginDate | No | Date | The start date for the enrollment. 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. |