{"id":45774388,"url":"https://github.com/edanalytics/edu_ext_oneroster","last_synced_at":"2026-04-01T17:39:01.131Z","repository":{"id":209957200,"uuid":"645945617","full_name":"edanalytics/edu_ext_oneroster","owner":"edanalytics","description":"OneRoster CSV standard in the EDU framework","archived":false,"fork":false,"pushed_at":"2026-03-18T17:53:34.000Z","size":87,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":6,"default_branch":"main","last_synced_at":"2026-03-19T07:20:04.616Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/edanalytics.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-05-26T20:31:12.000Z","updated_at":"2026-03-18T17:53:02.000Z","dependencies_parsed_at":null,"dependency_job_id":"83bbb466-9e6a-43fa-a9fe-a8f0931f2996","html_url":"https://github.com/edanalytics/edu_ext_oneroster","commit_stats":null,"previous_names":["edanalytics/edu_ext_oneroster"],"tags_count":13,"template":false,"template_full_name":null,"purl":"pkg:github/edanalytics/edu_ext_oneroster","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edanalytics%2Fedu_ext_oneroster","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edanalytics%2Fedu_ext_oneroster/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edanalytics%2Fedu_ext_oneroster/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edanalytics%2Fedu_ext_oneroster/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/edanalytics","download_url":"https://codeload.github.com/edanalytics/edu_ext_oneroster/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/edanalytics%2Fedu_ext_oneroster/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290537,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-26T08:44:16.394Z","updated_at":"2026-04-01T17:39:01.123Z","avatar_url":"https://github.com/edanalytics.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# edu_ext_oneroster\nOneRoster CSV standard in the EDU framework\n\n## License\nThis package is free to use for noncommercial purposes. \nSee [License](LICENSE.md).\n\n## Implementation notes\n- SourcedIds are MD5 hashes of an underlying natural key defined in [gen_sourced_id](macros/gen_sourced_id.sql).\n- User SourcedIds are forced to contain a prefix distinguishing between role. \n  This is to force separation: not all source systems guarantee uniqueness between\n  staff, student, and parent IDs. These IDs are then prefixed with 'STA', 'STU',\n  and 'PAR' respectively.\n- The SchoolYear academicSession is defined once per district using the modal begin\n  and end dates. \n- Remaining academicSessions are taken more or less as-is from the Ed-Fi Sessions object.\n- This package is defined to only support one school year at a time. Which school year\n  is supported is configurable through a variable, to avoid prematurely rotating\n  to the next school year as soon as the ODS is created if the current school year\n  is not yet concluded.\n- A feature to allow multiple school years to be created at once may be added if \n  demand arises.\n- The tables include a `tenant_code` column to support row-level security in the warehouse,\n  but this is not part of the OneRoster standard and should be excluded from extracts.\n- Unlike the rest of edu, columns in the OneRoster tables are specified case-sensitively\n  to match the OneRoster standard. Column names must therefore be double-quoted \n  in SQL statements.\n- The tables are named with the `or1_1` prefix to support namespacing for future\n  versions of the OneRoster standard, but are aliased to simpler names within the\n  database. The tables are _not_ specified with case-sensitivity, but files\n  created from them should be.\n\n## Unique Keys\nOneRoster uses the term `SourcedId` to refer to the unique key of all files in the OneRoster standard. This implementation uses the following methodology and principles:\n- All unique keys are the MD5 hash of a concatenation of Natural key values, separated by hyphens (`-`).\n- For clarity/transparency, the literal string value that is hashed is included in the file as an extension column called `metadata.edu.natural_key`\n- By default, all natural keys are prefixed with `tenant_code`, which is a human-readable string identifying a district. This can be overridden to be a constant string if desired using the variable `oneroster:id_prefix`\n- Any natural key component that is non-integer is cast to lower-case for consistency\n\nThe natural keys for each resource are defined in the macro [gen_sourced_id](macros/gen_sourced_id.sql), but are written out below for clarity.\n\n### Org\n- tenant_code (or constant string, if configured)\n- ed_org_id (`sea_id`, `lea_id`, or `school_id`, for the respective org-types)\n\n### Users\n- tenant_code (or constant string, if configured)\n- The literal string `STU`, `STA`, or `PAR`, for students, staff, or parents\n- `student_unique_id`, `staff_unique_id`, or `parent_unique_id`, respectively\n  - Note that this is the unique person identifier configured in Ed-Fi, and exactly which type of ID this is can vary across implementations.\n\n### Sessions\nFor terms/semesters/etc, this is a school-specific session definition, taken\nfrom Ed-Fi's definition of Sessions.\n- tenant_code (or constant string, if configured)\n- school_id\n- session_name\n\nFor school years, each district has its own definition:\n- tenant_code (or constant string, if configured)\n- lea_id\n- school_year (4 digit number representing the Spring year, e.g. for 2023-2024, `2024`)\n\n### Courses\n- tenant_code (or constant string, if configured)\n- lea_id\n- course_code\n\n### Classes\n- tenant_code (or constant string, if configured)\n- school_id\n- lower(section_id)\n- lower(session_name)\n\nSection ID and Session Name are cast to lower case to ensure consistency.\nSession is included in the Class definition to align with how Ed-Fi thinks about\nSections, as well as because Ed-Fi Sessions are not date-exclusive and using dates\nalone may not uniquely identify the session in which a Section is offered.\n\n### Enrollments\nStudent Enrollments are a `student_unique_id`, the `local_course_code` from Ed-Fi's `CourseOffering`, the unique key of a Class, plus the `begin_date`. Note that students may enter and exit the same Class multiple times,\nrequiring the presence of `begin_date` in the enrollment record.\n- tenant_code (or constant string, if configured)\n- student_unique_id\n- lower(local_course_code)\n- school_id\n- lower(section_id)\n- lower(session_name)\n- begin_date\n\nStaff enrollments are the same, but substituting staff_unique_id\n- tenant_code (or constant string, if configured)\n- staff_unique_id\n- lower(local_course_code)\n- school_id\n- lower(section_id)\n- lower(session_name)\n- begin_date\n\n\n\n## Required Seed Files\nTemplates for required seed files are located in the [seed_templates](seed_templates/)\n\n1. Academic Sessions Types Mapping\n- File name: `xwalk_oneroster_academic_sessions_types.csv`\n- Columns:\n  - `session_name`: Comes from the Ed-Fi Sessions resource, Session Name field.\n  - `type`: Must be one of the [OneRoster sessionType](http://www.imsglobal.org/oneroster-v11-final-specification#_Toc480452027) list of values (gradingPeriod, semester, schoolYear, term).\n \n2. Classroom Positions Primary Teacher Mapping\n- File name: `xwalk_oneroster_classroom_positions.csv`\n- Columns:\n  - `classroom_position`: Comes from the Ed-Fi Staff Section Associations resource, Classroom Position field.\n  - `is_primary`: TRUE if this is the primary teacher role, FALSE otherwise. FALSE for students.\n\n3. Grade Level Mapping\n- File name: `xwalk_oneroster_grade_levels.csv`\n- Columns: \n  - `edfi_grade_level`: Grade level descriptors in the source Ed-Fi system\n  - `oneroster_grade_level` Codes from the [CEDS Entry Grade Level definition](https://ceds.ed.gov/CEDSElementDetails.aspx?TermId=7100)\n\n4. Staff Classification Mapping\n- File name: `xwalk_oneroster_staff_classifications.csv`\n- Columns:\n  - `staff_classification`: Comes from the Ed-Fi Staff Ed Org Assignment Associations resource, Staff Classification field.\n  - `oneroster_role`: Must be one of the [OneRoster RoleType](http://www.imsglobal.org/oneroster-v11-final-specification#_Toc480452025) list of values (administrator, aide, guardian, parent, proctor, relative, student, teacher).\n\n5. Race Mapping\n- File name: `xwalk_oneroster_races.csv`\n- Columns: \n  - `edfi_race_code`: Values in the Ed-Fi RaceDescriptor\n  - `oneroster_race_code`: Must be one of the [Oneroster Race](http://www.imsglobal.org/oneroster-v11-final-specification#_Toc480452012) values (americanIndianOrAlaskaNative, asian, blackOrAfricanAmerican, nativeHawaiianOrOtherPacificIslander, white).\n\n6. Gender Mapping \n- File name: `xwalk_oneroster_gender.csv`\n- Columns: \n  - `edfi_gender_code`: Values in the Ed-Fi SexDescriptor.\n  - `oneroster_sex_code`: Must be one of the [Oneroster Gender](http://www.imsglobal.org/oneroster-v11-final-specification#_Toc480452020) list of values (male, female).\n\n\n## Configuration variables\n`oneroster:id_prefix`: A prefix to be included in all sourcedIds. By default this is just `tenant_code`, but this can be overridden if a single unique string value is desired for all tenants.\n\n`oneroster:active_school_year`: The school-year on which to build OneRoster files. This should be rotated at year-rollover time, when incoming data from the school year that's about to begin has settled enough to support rostering.\n\n`oneroster:include_parents`: Boolean, whether or not to include parents in `users`. If true, users with role `parent` will include the `sourcedIds` of students to which they're associated in `agentSourcedIds`; likewise users with role `student` will include the `sourcedIds` of parents to which they're associated in `agentSourcedIds`. (Default is false.)\n\n`oneroster:student_email_type`: The email_type that will be preferred for student users. \n`oneroster:parent_email_type`: The email_type that will be preferred for parent users. \n\n`oneroster:parent_telephone_type`: The phone_number_type that will be preferred for parent users. \n\n`oneroster:demographic_extensions`: Extensions to add to the demographic table. These are\nkey-value pairs composed of a column name from `dim_student` and the desired column name in \nthe demographics file, respectively. Note: only columns in `dim_student` can be added here at the moment.\n\nColumn names will always begin with `metadata.`, and the specified value will be appended to the end. To follow the typical standard, include `edu.` in the name, but extensions are not forced to use the `edu` namespace. \nExample:\n```\n'oneroster:demographic_extensions':\n  is_special_education_annual: 'edu.special_education'\n  is_economic_disadvantaged: 'edu.economic_disadvantage'\n```\n\n## OneRoster extensions\nOneRoster is an extensible standard. Extensions in this package begin with `metadata.edu` and are always on the right-hand side of the table, as specified in the standard.\n\n`metadata.edu.natural_key`: All sourcedIds in this implementation are an MD5 hash of an underlying natural key. The definitions of the columns included in that key are in the [gen_sourced_id macro](macros/gen_sourced_id.sql). The unhashed string is included for clarity in this extension.\n\n`metadata.edu.staff_classification`: The Ed-Fi Staff Classification field, for more\ndetailed role information. Since Ed-Fi permits multiple staffClassifications, \nbut OneRoster 1.1 does not, we have to choose one.\n\n### Department Organizations\nOneRoster allows for a type of Education Organization called a `department`.\nWhile the meaning and intended use of this is pretty loose, one use to which it \ncan be put is adding another level of organization to courses: rather than have \na flat list of all courses offered within a district, one can organize them into\nsubject-level departments. This can aid in navigating lists of courses, as it \nsubdivides the list into more manageable units.\n\nBy default this package organizes Courses by the Education Organization \nthat owns it in Ed-Fi. However we can enable departmental sorting with a \nconfiguration like this:\n\n```\n# enable the Course Departments feature\n'oneroster:use_course_departments': true\n# set the column name that will be used to define departments (must be in `dim_course`)\n'oneroster:course_dept_column': academic_subject\n```\n\nThis will create a new set of `department` organizations within `orgs`: one for \neach Academic Subject offered by each Ed Org, and will link the courses to this \ndepartment rather than the defining Ed Org. \n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedanalytics%2Fedu_ext_oneroster","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fedanalytics%2Fedu_ext_oneroster","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fedanalytics%2Fedu_ext_oneroster/lists"}