用途
oneroster-csv-validator 用于在将 OneRoster v1.1 / v1.2 CSV 名册数据包交由 SIS、Clever 或 ClassLink 等系统导入之前，执行严格的上线前校验。它帮助定位导入被拒的常见原因，例如清单缺失、外键悬空、模式混用或编码异常。
主要能力
- 清单与包结构检查：要求 manifest.csv 位于 ZIP 根目录（不可嵌套于子目录），声明准确的规范版本（oneroster.version,1.1 或 1.2），并且 manifest 列出的文件与实际包内文件一一对应。
- bulk 与 delta 模式区分：一个交换包只允许一种模式。bulk 为完整快照，保留必需表头但 status 与 dateLastModified 留空；delta 每行必须包含 ISO 8601 UTC 时间戳（YYYY-MM-DDTHH:MM:SS.sssZ）和 active 或 tobedeleted 状态。同一包内混用视为致命错误。
- 外键引用完整性：沿 orgs → courses → classes → enrollments → users 的依赖链校验引用，包括版本相关的组织引用字段（如 1.1 的多值 orgSourcedIds 与 1.2 的独立角色）。完整 bulk 快照中选课引用必须可解析；delta 需结合接收方基线状态与删除语义判断。单个孤儿链接即可使整批失效。
- 角色枚举约束：users.csv 的 role 必须匹配对应版本的枚举（1.2 将角色关系移至 roles.csv，不应套用 1.1 的 users.role 检查）；enrollments.csv 的 role 限定为 administrator、proctor、student、teacher，厂商自定义角色需映射为规范枚举。sourcedId 须大小写敏感且唯一，推荐 RFC 4122 UUID。
- 编码与 CSV 规范：文件须为无 BOM 的 UTF-8；检测并剥离 Excel 导出常见的 \xEF\xBB\xBF 前缀以防首列表头损坏；含逗号、双引号或换行的字段须按 RFC 4180 用双引号包裹，内部引号转义为 ""。
- 其他检查：对 orgs.csv 做有向无环图（DAG）循环检测，避免组织父子关系互为循环。
使用方式
资料提供了 Python 预检脚本示例（validate_oneroster_archive），演示 ZIP 成员数量与解压体积限制、BOM 剥离、核心文件存在性检查、org / user / class / enrollment 外键校验与角色枚举校验，以及一份 OneRoster v1.1 manifest 片段和 delta 行示例。示例脚本仅覆盖 1.1 风格的 bulk 子集，输出状态为 PARTIAL_CHECKS_ONLY，不能据此宣称完全合规。
适用场景
- 调试 SIS 名册导出包为何被下游平台拒绝。
- 排查 enrollments.csv 中悬空的 userSourcedId。
- 校验 bulk / delta 模式是否合规。
- 清理 UTF-8 BOM 等编码问题。
- 在夜间 SIS 同步前的 CI/CD 流程中执行自动预检。
限制
- 不用于 OneRoster REST / OAuth 2.0 API 对接，仅聚焦 CSV 表绑定。
- 不适用于非 1EdTech 标准的普通 CSV 表格。
- 各交换配置与厂商实现所需的版本细节和必需文件可能不同，应以准确的 1EdTech 规范和接收方当前导入约定为准。
- 名册含敏感教育记录，须在授权下处理、最小化留存数据、在诊断信息中脱敏标识符，且不得将源 CSV 上传至外部服务。
- 资料中的代码仅为示意，并非完整认证校验器；大文件、命名空间、delta 语义与厂商扩展需要额外处理与测试。示例脚本未实现 manifest 校验、完整版本 / 表头 / 枚举规则、重复 ID、组织循环及 1.2 角色检查。BOM 容错属于规范化选择，不代表可静默改写源名册。