{ "openapi": "3.1.0", "info": { "title": "People & Orgs (Alpha)", "description": "The Alpha People & Orgs API provides school-language person, organization, section, and term views over OneRoster, plus effective-dated histories (age/grade, Alpha level, guide assignment) and as-of enrollment, school, guardian, staff, and program reads. It also exposes the school-day calendar over Ed-Fi calendar dates. Uses cursor pagination, flat envelopes, and RFC 7807 errors.", "version": "1.0" }, "tags": [ { "name": "Age Grade History", "description": "The single most load-bearing entity in the module (age-grade switchover). One row = one effective period of a student's roster cohort grade, half-open [beginDate, endDate). Switchover happens ON the beginDate of the next academic year's row; platform4 never computes promotion from birthday/MAP/mastery — the history row IS the fact. ageGrade is the numeric position PreK=-1.. 12, set at write time, never parsed from a name. ONE home for the fact: the person projection carries no age-grade scalar. working_grade / highest_mastered_grade live in results — no grade comparison is computed here." }, { "name": "Alpha Level History", "description": "Effective-dated Alpha age-band history. Same shape as ageGradeHistory: one row per half-open [beginDate, endDate) period per student. alphaLevel is the typed CLOSED enum {WL, LL, L1, L2, MS, HS}, set at write time. alphaLevel(student, date) is the ?asOf= read; when asOf is absent the full history is returned, and when present a single matching row is returned. currentOnly=true has no representation and is rejected." }, { "name": "Section", "description": "The Alpha section surface — a projection of the imported oneroster:class master. subjects/grades stay VERBATIM jsonb here — subject/grade canonicalization is the curriculum/content authoring surface's restrict, never this projection's. Anchors the getStudentsInClass as-of computed read. Entity is named classSection because Ed-Fi's own section table shares the stacked database namespace; the API surface stays /v1/section." }, { "name": "Course Catalog", "description": "The Alpha course-catalog surface — a projection of the imported oneroster:course master (plain renames). grades/subjects stay verbatim (canonicalization is external)." }, { "name": "Export Batch", "description": "The bulk-export receipt. exportPeopleAndOrgs is the command POST that writes one of these rows inside its transaction; this entity's plain CRUD GET is the status endpoint. Data freshness is the exposed managed timestamps — no separate freshness machinery. Table name is prefixed to avoid colliding with oneroster's own export_batch in a stacked database." }, { "name": "Guide Assignment", "description": "Alpha guide → student over time. Effective-dated with subjectKey [studentSourcedId] — a student has ONE guide per half-open [beginDate, endDate) period. Reads both directions: guideForStudent(student, asOfDate) is the ?asOf= list for the student; studentsForGuide(guide, asOfDate) is the list filtered by guideSourcedId + ?asOf=. No 1EdTech base." }, { "name": "Organization", "description": "The Alpha org surface — a multi-base projection of the imported oneroster:org master, RESTRICTED to the Alpha rungs {district, school} and joined 1:1 to the owned organizationExtension companion carrying the governed org tags: modality, brand, segment (locked registry enums set at write time) and nweaDistrictId (the Brand×Modality = one-NWEA-account grouping key). Presence optional (LEFT JOIN): the tag columns are nullable, so a bare roster org stays visible; wire requiredness of modality/brand/segment is API-enforced. Named organization, not place. Anchors the school-day calendar computed reads." }, { "name": "Person", "description": "The Alpha person surface — a projection of the imported oneroster:user master. Plain-language renames (firstName/lastName), a boolean isEnabled, and PII-minimizing cuts (phone/sms/middleName read the master under the demographics scope instead). Deliberately carries NO age_grade / alpha_level / guide columns — those live on effective-dated history entities, one home per fact. Anchors the as-of and Ed-Fi-sourced computed reads." }, { "name": "Term", "description": "The Alpha term surface — a projection of the imported oneroster:academicSession master, RESTRICTED to type ∈ {schoolYear, term, semester}. Grading periods are not an Alpha surface concern. reads school-year boundaries from the type='schoolYear' rows — never a hardcoded Aug 1 / May 19." } ], "paths": { "/people-and-orgs/v1/age-grade-history": { "get": { "operationId": "listAgeGradeHistory", "summary": "List age-grade periods (full history; ?asOf= narrows to the covering period)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Age Grade History" ], "parameters": [ { "name": "personSourcedId", "in": "query", "description": "Restrict to one student's history.", "schema": { "type": "string" }, "x-filter": { "column": "personSourcedId", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } }, { "name": "asOf", "in": "query", "required": false, "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AgeGradeHistory" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createAgeGradeHistory", "summary": "Open a new age-grade period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Age Grade History" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAgeGradeHistoryRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgeGradeHistory" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (age_grade_period_overlap).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/age-grade-history/{id}": { "get": { "operationId": "getAgeGradeHistory", "summary": "Get one age-grade period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Age Grade History" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asOf", "in": "query", "required": false, "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgeGradeHistory" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (age_grade_history_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateAgeGradeHistory", "summary": "Amend a period (e.g. close the open period by setting endDate)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Age Grade History" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "The resource's current ETag (from the last GET/write response), quoted per RFC 9110. REQUIRED — absent returns 428; a stale ETag returns 412 (refetch and retry). Send `*` to overwrite unconditionally.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAgeGradeHistoryRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AgeGradeHistory" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (age_grade_history_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (age_grade_period_overlap).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "Precondition Failed — the If-Match ETag is stale (the resource was modified); refetch and retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this write requires the If-Match header (send the resource's ETag).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteAgeGradeHistory", "summary": "Soft-delete a period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Age Grade History" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "The resource's current ETag (from the last GET/write response), quoted per RFC 9110. REQUIRED — absent returns 428; a stale ETag returns 412 (refetch and retry). Send `*` to overwrite unconditionally.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No Content.", "content": { "application/json": { "schema": { "type": "object", "description": "Period soft-deleted." } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (age_grade_history_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "Precondition Failed — the If-Match ETag is stale (the resource was modified); refetch and retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this write requires the If-Match header (send the resource's ETag).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/alpha-level-history": { "get": { "operationId": "listAlphaLevelHistory", "summary": "List alpha-level periods (full history; ?asOf= narrows to the covering period)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Alpha Level History" ], "parameters": [ { "name": "personSourcedId", "in": "query", "description": "Restrict to one student's history.", "schema": { "type": "string" }, "x-filter": { "column": "personSourcedId", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } }, { "name": "asOf", "in": "query", "required": false, "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/AlphaLevelHistory" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createAlphaLevelHistory", "summary": "Open a new alpha-level period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Alpha Level History" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAlphaLevelHistoryRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlphaLevelHistory" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (alpha_level_period_overlap).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/alpha-level-history/{id}": { "get": { "operationId": "getAlphaLevelHistory", "summary": "Get one alpha-level period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Alpha Level History" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asOf", "in": "query", "required": false, "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlphaLevelHistory" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (alpha_level_history_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateAlphaLevelHistory", "summary": "Amend a period (e.g. close the open period)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Alpha Level History" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "The resource's current ETag (from the last GET/write response), quoted per RFC 9110. REQUIRED — absent returns 428; a stale ETag returns 412 (refetch and retry). Send `*` to overwrite unconditionally.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAlphaLevelHistoryRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AlphaLevelHistory" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (alpha_level_history_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (alpha_level_period_overlap).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "Precondition Failed — the If-Match ETag is stale (the resource was modified); refetch and retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this write requires the If-Match header (send the resource's ETag).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteAlphaLevelHistory", "summary": "Soft-delete a period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Alpha Level History" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "The resource's current ETag (from the last GET/write response), quoted per RFC 9110. REQUIRED — absent returns 428; a stale ETag returns 412 (refetch and retry). Send `*` to overwrite unconditionally.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No Content.", "content": { "application/json": { "schema": { "type": "object", "description": "Period soft-deleted." } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (alpha_level_history_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "Precondition Failed — the If-Match ETag is stale (the resource was modified); refetch and retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this write requires the If-Match header (send the resource's ETag).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/class-section": { "get": { "operationId": "listSections", "summary": "List sections", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Section" ], "parameters": [ { "name": "schoolSourcedId", "in": "query", "description": "Restrict to one school.", "schema": { "type": "string" }, "x-filter": { "column": "schoolSourcedId", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ClassSection" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/class-section/{sourcedId}": { "get": { "operationId": "getSection", "summary": "Get a section", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Section" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClassSection" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (section_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/class-section/{sourcedId}/students": { "get": { "operationId": "getStudentsInClass", "summary": "Students in this class as-of a date (inverse)", "description": "Computed read over oneroster:enrollment. null rule + half-open window beginDate <= onDate < endDate.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Section" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "onDate", "in": "query", "required": true, "description": "The as-of date.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "personSourcedId": { "type": "string" }, "role": { "type": [ "string", "null" ] }, "beginDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] } }, "required": [ "personSourcedId" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/course-catalog": { "get": { "operationId": "listCourseCatalog", "summary": "List catalog courses", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Course Catalog" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CourseCatalog" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/course-catalog/{sourcedId}": { "get": { "operationId": "getCourseCatalogEntry", "summary": "Get a catalog course", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Course Catalog" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CourseCatalog" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (course_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/export-batch": { "get": { "operationId": "listExportBatches", "summary": "List export receipts", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Export Batch" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ExportBatch" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/export-batch/{batchId}": { "get": { "operationId": "getExportBatch", "summary": "Get an export receipt (the status endpoint)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Export Batch" ], "parameters": [ { "name": "batchId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBatch" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (export_batch_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/export-batch/export": { "post": { "operationId": "exportPeopleAndOrgs", "summary": "Run a people/orgs bulk export (writes the receipt row)", "description": "The bulk export door. Synchronous: the hook assembles the export inside one transaction and writes THIS receipt row; the response is the receipt at 201. Idempotency is optional — with an Idempotency-Key header the engine replays the stored response (same key + different request hash → 422 IdempotencyKeyReuseError).\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Export Batch" ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "The idempotency key (max 128 chars). Optional — when present, the call is replay-protected; a completed replay returns the stored response at 200 with idempotency-replayed: true.", "schema": { "type": "string", "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "scope": { "type": "string", "enum": [ "people", "orgs", "all" ], "description": "What to export." } }, "required": [ "scope" ], "additionalProperties": false } } } }, "responses": { "200": { "description": "OK (idempotent replay — the stored first response; idempotency-replayed: true).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBatch" } } }, "headers": { "idempotency-replayed": { "description": "true when this response is a stored idempotent replay (the hook did not run).", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportBatch" } } }, "headers": { "idempotency-replayed": { "description": "true when this response is a stored idempotent replay (the hook did not run).", "schema": { "type": "string", "enum": [ "true", "false" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict — an operation with this Idempotency-Key is already in progress (60s lock).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "422": { "description": "Unprocessable Entity — this Idempotency-Key was already used with a different request body.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this operation requires the Idempotency-Key header.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/guide-assignment": { "get": { "operationId": "listGuideAssignments", "summary": "List guide assignments (both read directions via filters + ?asOf=)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Guide Assignment" ], "parameters": [ { "name": "studentSourcedId", "in": "query", "description": "guideForStudent: restrict to one student's assignment history.", "schema": { "type": "string" }, "x-filter": { "column": "studentSourcedId", "operator": "eq" } }, { "name": "guideSourcedId", "in": "query", "description": "studentsForGuide: restrict to one guide's assigned students (inverse).", "schema": { "type": "string" }, "x-filter": { "column": "guideSourcedId", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } }, { "name": "asOf", "in": "query", "required": false, "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GuideAssignment" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createGuideAssignment", "summary": "Open a new assignment period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Guide Assignment" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateGuideAssignmentRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideAssignment" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (guide_assignment_period_overlap).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/guide-assignment/{id}": { "get": { "operationId": "getGuideAssignment", "summary": "Get one assignment period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Guide Assignment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "asOf", "in": "query", "required": false, "description": "Return only rows whose effective period covers this date: beginDate <= asOf and (endDate is null or asOf < endDate). Absent, the full history is returned.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideAssignment" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (guide_assignment_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateGuideAssignment", "summary": "Amend a period (e.g. close the open period)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Guide Assignment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "The resource's current ETag (from the last GET/write response), quoted per RFC 9110. REQUIRED — absent returns 428; a stale ETag returns 412 (refetch and retry). Send `*` to overwrite unconditionally.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateGuideAssignmentRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GuideAssignment" } } }, "headers": { "ETag": { "description": "The resource's current entity-tag (RFC 9110, quoted). Send it back in If-Match on the next write (optimistic concurrency).", "schema": { "type": "string" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (guide_assignment_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Problem (guide_assignment_period_overlap).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "Precondition Failed — the If-Match ETag is stale (the resource was modified); refetch and retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this write requires the If-Match header (send the resource's ETag).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "delete": { "operationId": "deleteGuideAssignment", "summary": "Soft-delete a period", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Guide Assignment" ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "If-Match", "in": "header", "required": true, "description": "The resource's current ETag (from the last GET/write response), quoted per RFC 9110. REQUIRED — absent returns 428; a stale ETag returns 412 (refetch and retry). Send `*` to overwrite unconditionally.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "204": { "description": "No Content.", "content": { "application/json": { "schema": { "type": "object", "description": "Period soft-deleted." } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (guide_assignment_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "412": { "description": "Precondition Failed — the If-Match ETag is stale (the resource was modified); refetch and retry.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "428": { "description": "Precondition Required — this write requires the If-Match header (send the resource's ETag).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/organization": { "get": { "operationId": "listOrganizations", "summary": "List Alpha organizations (districts + schools)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "parameters": [ { "name": "type", "in": "query", "description": "Restrict to one Alpha org rung.", "schema": { "type": "string", "enum": [ "district", "school" ] }, "x-filter": { "column": "type", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Organization" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createOrganization", "summary": "Create an organization (writes the oneroster org master + the governed tags)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateOrganizationRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/organization/{sourcedId}": { "get": { "operationId": "getOrganization", "summary": "Get an organization", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (organization_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updateOrganization", "summary": "Update an organization", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateOrganizationRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Organization" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (organization_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/organization/{sourcedId}/calendar/is-school-day": { "get": { "operationId": "isSchoolDay", "summary": "Is this date a school day for this school?", "description": "Computed read over edfi:calendarDate + calendarDateCalendarEvent. The reason is a typed closed enum sourced from the calendar-event descriptor; an unknown source row returns other, NEVER inferred from dates.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "date", "in": "query", "required": true, "description": "The calendar date to classify.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schoolId": { "type": "string" }, "date": { "type": "string" }, "isSchoolDay": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "instructional", "weekend", "teacher_workshop", "holiday_break", "nwea_map_testing", "other" ], "description": "The typed closed reason enum. MAP windows are calendar DATA rows, not a hardcoded constant." } }, "required": [ "schoolId", "date", "isSchoolDay", "reason" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (calendar_date_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/organization/{sourcedId}/calendar/days": { "get": { "operationId": "schoolDaysInRange", "summary": "Bulk day classification over a range", "description": "One row per calendar day in [startDate, endDate], each with isSchoolDay + the typed reason.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schoolId": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string" }, "isSchoolDay": { "type": "boolean" }, "reason": { "type": "string", "enum": [ "instructional", "weekend", "teacher_workshop", "holiday_break", "nwea_map_testing", "other" ] } }, "required": [ "date", "isSchoolDay", "reason" ] } } }, "required": [ "schoolId", "data" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/organization/{sourcedId}/calendar/count": { "get": { "operationId": "countSchoolDays", "summary": "Count school days over a range", "description": "The count of instructional days in [startDate, endDate]. When personSourcedId is given, the range is INTERSECTED with the student's enrollment window at this school (begin_date <= d < end_date; null rule)\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } }, { "name": "personSourcedId", "in": "query", "description": "Narrow the count to this student's enrollment window.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schoolId": { "type": "string" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "count": { "type": "integer" } }, "required": [ "schoolId", "startDate", "endDate", "count" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/organization/{sourcedId}/calendar/remaining": { "get": { "operationId": "remainingSchoolDays", "summary": "School days remaining to the school-year end", "description": "The count of instructional days from onDate (inclusive) to the end of the school year covering onDate. School-year boundaries come from type='schoolYear' oneroster:academicSession rows, per-org — never a hardcoded date.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "onDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schoolId": { "type": "string" }, "onDate": { "type": "string" }, "remaining": { "type": "integer" } }, "required": [ "schoolId", "onDate", "remaining" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/organization/{sourcedId}/calendar/next-school-year-start": { "get": { "operationId": "nextSchoolYearStart", "summary": "The next school year's start date", "description": "The earliest type='schoolYear' oneroster:academicSession startDate strictly after onDate.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Organization" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "onDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "schoolId": { "type": "string" }, "onDate": { "type": "string" }, "nextSchoolYearStart": { "type": [ "string", "null" ], "description": "NULL when no future schoolYear session exists." } }, "required": [ "schoolId", "onDate" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person": { "get": { "operationId": "listPersons", "summary": "List persons (reads through the projection view)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Person" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "post": { "operationId": "createPerson", "summary": "Create a person (writes the oneroster user master through the inverse column map)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePersonRequest" } } } }, "responses": { "201": { "description": "Created.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}": { "get": { "operationId": "getPerson", "summary": "Get a person", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (person_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } }, "patch": { "operationId": "updatePerson", "summary": "Update a person (writes the oneroster user master)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePersonRequest" } } } }, "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Person" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (person_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/sensitive-profile": { "get": { "operationId": "getPersonSensitiveProfile", "summary": "PII-restricted profile (user + demographics joined)", "description": "The person_sensitive_profile computed read: joins the oneroster user master with its demographics row. Gated by people-demographics:read — DISTINCT from people:read.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "sourcedId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "middleName": { "type": [ "string", "null" ], "description": "Quasi-identifying — only served here, under the demographics scope." }, "phone": { "type": [ "string", "null" ] }, "sms": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "birthDate": { "type": [ "string", "null" ], "description": "From oneroster demographics (regulated)." }, "sex": { "type": [ "string", "null" ] } }, "required": [ "sourcedId", "firstName", "lastName" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (person_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/guardians": { "get": { "operationId": "getGuardians", "summary": "The student's guardian contacts (Ed-Fi contact family)", "description": "Computed read over edfi:studentContactAssociation × edfi:contact returning guardian contacts for the person.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "contactUniqueId": { "type": "string" }, "firstName": { "type": "string" }, "lastName": { "type": "string" }, "relation": { "type": [ "string", "null" ], "description": "Ed-Fi RelationDescriptor (governed code list)." }, "primaryContactStatus": { "type": [ "boolean", "null" ] }, "livesWith": { "type": [ "boolean", "null" ] }, "emergencyContactStatus": { "type": [ "boolean", "null" ] }, "contactPriority": { "type": [ "integer", "null" ] } }, "required": [ "contactUniqueId", "firstName", "lastName" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/guardian-relationships": { "get": { "operationId": "getGuardianRelationships", "summary": "Typed guardian relationship rows", "description": "Computed read over edfi:studentContactAssociation returning guardian relationships. The relation is a typed Ed-Fi descriptor, not free text.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "contactUniqueId": { "type": "string" }, "relation": { "type": "string" }, "primaryContactStatus": { "type": [ "boolean", "null" ] }, "livesWith": { "type": [ "boolean", "null" ] }, "emergencyContactStatus": { "type": [ "boolean", "null" ] }, "contactPriority": { "type": [ "integer", "null" ] } }, "required": [ "contactUniqueId", "relation" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/staff-assignments": { "get": { "operationId": "getStaffAssignments", "summary": "Staff school/section assignments, as-of", "description": "Computed read over edfi:staffSchoolAssociation + edfi:staffSectionAssociation. As-of window: beginDate <= onDate < endDate; endDate NULL = still active.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "onDate", "in": "query", "description": "The as-of date; absent = all assignments.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "assignmentType": { "type": "string", "enum": [ "school", "section" ] }, "schoolSourcedId": { "type": [ "string", "null" ] }, "classSourcedId": { "type": [ "string", "null" ] }, "positionDescriptor": { "type": [ "string", "null" ], "description": "programAssignmentDescriptor (school) / classroomPositionDescriptor (section)." }, "beginDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] } }, "required": [ "assignmentType" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/program-participation": { "get": { "operationId": "getProgramParticipation", "summary": "Student program participation over time", "description": "Computed read over edfi:generalStudentProgramAssociation + its participation-status children. As-of window: beginDate <= onDate < endDate; endDate NULL = active.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "onDate", "in": "query", "description": "The as-of date; absent = full participation history.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "programName": { "type": "string" }, "programTypeDescriptor": { "type": "string" }, "programEducationOrganizationSourcedId": { "type": "string" }, "beginDate": { "type": "string" }, "endDate": { "type": [ "string", "null" ] }, "participationStatuses": { "type": "array", "items": { "type": "object", "properties": { "participationStatusDescriptor": { "type": "string" }, "statusBeginDate": { "type": [ "string", "null" ] }, "statusEndDate": { "type": [ "string", "null" ] } }, "required": [ "participationStatusDescriptor" ] } } }, "required": [ "programName", "programTypeDescriptor", "beginDate" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/school": { "get": { "operationId": "getSchoolForStudent", "summary": "The student's school as-of a date", "description": "Computed read over edfi:studentSchoolAssociation entry/exit dates (the campus→school rename). Half-open window: entryDate <= onDate < exitWithdrawDate; exit NULL = current.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "onDate", "in": "query", "required": true, "description": "The as-of date.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "personSourcedId": { "type": "string" }, "schoolSourcedId": { "type": "string" }, "schoolName": { "type": [ "string", "null" ] }, "entryDate": { "type": "string" }, "exitWithdrawDate": { "type": [ "string", "null" ] } }, "required": [ "personSourcedId", "schoolSourcedId", "entryDate" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (school_membership_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/classes": { "get": { "operationId": "getClassesForStudent", "summary": "The student's classes as-of a date", "description": "Computed read over oneroster:enrollment × oneroster:class. null rule: begin_date NULL ⇒ excluded; end_date NULL ⇒ still active. Half-open window beginDate <= onDate < endDate.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "onDate", "in": "query", "required": true, "description": "The as-of date.", "schema": { "type": "string", "format": "date" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "classSourcedId": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "schoolSourcedId": { "type": [ "string", "null" ] }, "beginDate": { "type": [ "string", "null" ] }, "endDate": { "type": [ "string", "null" ] } }, "required": [ "classSourcedId" ] } } }, "required": [ "data" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/enrollment-window": { "get": { "operationId": "getEnrollmentWindow", "summary": "The enrollment begin/end window for a class", "description": "Computed read over oneroster:enrollment: begin AND end, both nullable, returned as named distinct fields; isTimeLocatable is synthesized on the read (beginDate is not null), never a stored column.\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "classSourcedId", "in": "query", "required": true, "description": "The class whose enrollment window to read.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "personSourcedId": { "type": "string" }, "classSourcedId": { "type": "string" }, "beginDate": { "type": [ "string", "null" ], "description": "NULL ⇒ not time-locatable (excluded from as-of reads)." }, "endDate": { "type": [ "string", "null" ], "description": "NULL ⇒ still active." }, "isTimeLocatable": { "type": "boolean", "description": "Synthesized: beginDate is not null." } }, "required": [ "personSourcedId", "classSourcedId", "isTimeLocatable" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (enrollment_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/person/{sourcedId}/first-single-grade-enrollment-date": { "get": { "operationId": "getFirstSingleGradeEnrollmentDate", "summary": "The SY-start anchor: first single-grade enrollment date", "description": "Computed read over oneroster:enrollment filtered to classes carrying exactly ONE grade. Returns the earliest non-null beginDate among them; the null rule applies (begin NULL ⇒ excluded).\n\n> **Auth required:** a verified bearer token is required.", "tags": [ "Person" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "properties": { "personSourcedId": { "type": "string" }, "firstSingleGradeEnrollmentDate": { "type": [ "string", "null" ], "description": "NULL when the student has no time-locatable single-grade enrollment." } }, "required": [ "personSourcedId" ] } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/term": { "get": { "operationId": "listTerms", "summary": "List terms (schoolYear/term/semester sessions)", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Term" ], "parameters": [ { "name": "type", "in": "query", "description": "Restrict to one session kind.", "schema": { "type": "string", "enum": [ "schoolYear", "term", "semester" ] }, "x-filter": { "column": "type", "operator": "eq" } }, { "name": "limit", "in": "query", "required": false, "description": "Maximum number of items to return on this page (clamped server-side).", "schema": { "type": "integer", "minimum": 1 } }, { "name": "cursor", "in": "query", "required": false, "description": "Opaque pagination cursor — pass the previous page's `nextCursor` to fetch the next page.", "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "type": "object", "required": [ "data", "nextCursor" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Term" } }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for the next page, or null when this is the last page." } } } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Not Found.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/people-and-orgs/v1/term/{sourcedId}": { "get": { "operationId": "getTerm", "summary": "Get a term", "description": "> **Auth required:** a verified bearer token is required.", "tags": [ "Term" ], "parameters": [ { "name": "sourcedId", "in": "path", "required": true, "schema": { "type": "string" } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "OK.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Term" } } } }, "400": { "description": "Bad Request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "Unauthorized.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "Forbidden.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "Problem (term_not_found).", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "Conflict.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "Internal Server Error.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "501": { "description": "Not Implemented.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } } }, "components": { "schemas": { "AgeGradeHistory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Server-generated unique identifier for this period. The natural (tenant, subject, beginDate) tuple is enforced by an EXCLUDE constraint rather than the primary key.", "readOnly": true }, "personSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The student whose roster-cohort grade this period records — the SUBJECT of the history. Two-leg composite FK to oneroster user; restrict-on-delete: a roster delete must not silently destroy Alpha history.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "ageGrade": { "type": "integer", "minimum": -1, "maximum": 12, "description": "The numeric roster-cohort grade position: PreK=-1, K=0, 1..12. A typed integer set at write time — never parsed from a grade name." }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required — the effective-dated from bound; a period always starts). The typed-null rule is structural: not-time-locatable rows cannot exist here." }, "endDate": { "type": "string", "format": "date", "description": "Period end, EXCLUSIVE (half-open [beginDate, endDate)). NULL = the open current period." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "personSourcedId", "ageGrade", "beginDate", "updatedAt" ] }, "AlphaLevelHistory": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Server-generated unique identifier for this period. The natural (tenant, subject, beginDate) tuple is enforced by an EXCLUDE constraint rather than the primary key.", "readOnly": true }, "personSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The student whose Alpha level this period records — the SUBJECT of the history.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "alphaLevel": { "type": "string", "enum": [ "WL", "LL", "L1", "L2", "MS", "HS" ], "description": "The Alpha age-band — a locked registry enum. No folding: spellings are exact." }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required effective-dated from bound)." }, "endDate": { "type": "string", "format": "date", "description": "Period end, EXCLUSIVE. NULL = the open current period." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "personSourcedId", "alphaLevel", "beginDate", "updatedAt" ] }, "ClassSection": { "type": "object", "properties": { "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The natural business key for this class." }, "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status.", "default": "active" }, "title": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The human-readable title of the class section." }, "classCode": { "type": "string", "maxLength": 256, "description": "An optional class section code." }, "classType": { "type": "string", "pattern": "^(homeroom|scheduled|ext:.+)$", "description": "The class type: homeroom, scheduled, or a governed ext: extension." }, "location": { "type": "string", "maxLength": 512, "description": "Physical or virtual location of the class." }, "courseSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the course this class instantiates. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `course` (G-GUIDREF, CLS-01)." }, "schoolSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the school organization that owns this class. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `school` of type org (G-GUIDREF, CLS-01)." }, "termSourcedIds": { "type": "array", "items": { "type": "string" }, "description": "SourcedIds of academic session terms this class spans." }, "grades": { "type": "array", "items": { "type": "string" }, "description": "Grade levels applicable to this class." }, "subjects": { "type": "array", "items": { "type": "string" }, "description": "Subject names applicable to this class." }, "subjectCodes": { "type": "array", "items": { "type": "string" }, "description": "Subject codes applicable to this class." }, "periods": { "type": "array", "items": { "type": "string" }, "description": "Period identifiers when this class meets." }, "dateLastModified": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "sourcedId", "status", "title", "schoolSourcedId", "dateLastModified" ] }, "CourseCatalog": { "type": "object", "properties": { "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The natural business key for this course." }, "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status.", "default": "active" }, "title": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The human-readable title of the course." }, "courseCode": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The course code assigned by the organization." }, "orgSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the organization that owns this course. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `org` (G-GUIDREF, CRS-01)." }, "schoolYearSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the school year academic session this course belongs to. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `schoolYear` of type academicSession (G-GUIDREF, CRS-01)." }, "grades": { "type": "array", "items": { "type": "string" }, "description": "Grade levels applicable to this course." }, "subjects": { "type": "array", "items": { "type": "string" }, "description": "Subject names applicable to this course." }, "subjectCodes": { "type": "array", "items": { "type": "string" }, "description": "Subject codes (e.g. SCED codes) applicable to this course." }, "dateLastModified": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "sourcedId", "status", "title", "courseCode", "orgSourcedId", "dateLastModified" ] }, "ExportBatch": { "type": "object", "properties": { "batchId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Server-minted receipt identifier (the natural id)." }, "status": { "type": "string", "enum": [ "completed", "failed" ], "description": "Export outcome. All evidenced commands run synchronously — no async job/queue states." }, "scope": { "type": "string", "enum": [ "people", "orgs", "all" ], "description": "What the export covers." }, "rowCount": { "type": "integer", "minimum": 0, "description": "How many rows the export covered." }, "downloadRef": { "type": "string", "description": "Where the export artifact can be fetched (a reference, not the bytes)." }, "createdAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed row-creation timestamp (RFC 3339). Read-only — never accepted on create or update." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "batchId", "status", "scope", "createdAt", "updatedAt" ] }, "GuideAssignment": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "Server-generated unique identifier for this period. The natural (tenant, subject, beginDate) tuple is enforced by an EXCLUDE constraint rather than the primary key.", "readOnly": true }, "studentSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The student — the SUBJECT of the assignment history.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "guideSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The Alpha guide assigned for this period.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required effective-dated from bound)." }, "endDate": { "type": "string", "format": "date", "description": "Period end, EXCLUSIVE. NULL = the open current period." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "studentSourcedId", "guideSourcedId", "beginDate", "updatedAt" ] }, "Organization": { "type": "object", "properties": { "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The OneRoster sourcedId — the natural business key for this organization, unique within the tenant." }, "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status. Records marked tobedeleted remain queryable for sync consumers rather than being physically removed.", "default": "active" }, "name": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The human-readable name of the organization." }, "type": { "type": "string", "enum": [ "district", "school" ], "description": "RESTRICTED to the Alpha org rungs: district = the Brand×Modality grouping grain, school = the enrollment-anchoring unit. Other base org types are not visible through this projection." }, "identifier": { "type": "string", "maxLength": 256, "description": "An optional human-readable identifier for the organization, such as an NCES school ID." }, "parentSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the parent organization in the hierarchy. Null for root organizations. Forms an acyclic tree. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `parent` of type org (G-GUIDREF, ORG-01)." }, "modality": { "type": "string", "enum": [ "physical", "virtual" ], "description": "Delivery modality — locked registry enum, NO hybrid." }, "brand": { "type": "string", "enum": [ "100for100", "alpha", "gt", "limitless_education", "montessorium", "nextgen", "nova_academy", "novatio", "sw_sales", "texas_sports_academy", "towermath", "unbound", "waypoint" ], "description": "The 13 closed brand values — the Brand×Modality grouping grain (/307-313)." }, "segment": { "type": "string", "enum": [ "charter", "private", "sw_sales", "virtual", "mixed" ], "description": "Business segment — locked registry enum." }, "nweaDistrictId": { "type": "string", "minLength": 1, "description": "The NWEA account grouping key — 1:1 on type='district' rows (inspiration: Ed-Fi EducationOrganizationIdentificationCode)." }, "dateLastModified": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "sourcedId", "status", "name", "type", "modality", "brand", "segment", "dateLastModified" ] }, "OrganizationExtension": { "type": "object", "properties": { "orgSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Shared natural id with the OneRoster org this organization extension belongs to 1:1. FK CASCADE so deleting the org reaps the companion.", "x-references": "oneroster:org.sourcedId", "x-onDelete": "cascade" }, "modality": { "type": "string", "enum": [ "physical", "virtual" ], "description": "Delivery modality — locked registry enum, NO hybrid." }, "brand": { "type": "string", "enum": [ "100for100", "alpha", "gt", "limitless_education", "montessorium", "nextgen", "nova_academy", "novatio", "sw_sales", "texas_sports_academy", "towermath", "unbound", "waypoint" ], "description": "The 13 closed brand values — the Brand×Modality grouping grain (/307-313)." }, "segment": { "type": "string", "enum": [ "charter", "private", "sw_sales", "virtual", "mixed" ], "description": "Business segment — locked registry enum." }, "nweaDistrictId": { "type": "string", "minLength": 1, "description": "The NWEA account grouping key — 1:1 on type='district' rows (inspiration: Ed-Fi EducationOrganizationIdentificationCode)." } }, "required": [ "orgSourcedId" ] }, "Person": { "type": "object", "properties": { "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The natural business key for this user." }, "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status.", "default": "active" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The person's first name (the master's givenName, renamed — plain-language Alpha name)." }, "lastName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The person's last name (the master's familyName, renamed)." }, "preferredFirstName": { "type": "string", "maxLength": 256, "description": "The user's preferred first name (REST) / preferredGivenName (CSV)." }, "preferredLastName": { "type": "string", "maxLength": 256, "description": "The user's preferred last name." }, "email": { "type": "string", "format": "email", "maxLength": 512, "description": "The user's primary email address." }, "username": { "type": "string", "maxLength": 256, "description": "The user's login username." }, "isEnabled": { "type": "boolean", "description": "Whether the person is enabled — a real boolean on the Alpha surface (the master's enabledUser, renamed).", "default": true }, "primaryOrgSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the user's primary organization. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `org` (G-GUIDREF, USR-04/USR-06)." }, "roles": { "type": "array", "items": { "type": "object", "$ref": "#/$defs/userRole" }, "description": "The user's role assignments within organizations." }, "userIds": { "type": "array", "items": { "type": "object", "$ref": "#/$defs/userId" }, "description": "External identifier bindings for this user." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string", "minLength": 1, "description": "Dereferenceable URI of the referenced agent user." }, "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The sourcedId of the agent user." }, "type": { "type": "string", "enum": [ "user" ], "description": "The GUIDRef type literal — always user." } }, "required": [ "href", "sourcedId", "type" ] }, "description": "GUIDRefs to agent users (parents/guardians for a student) — USR-04. Nested inside jsonb, so not a DB FK; validated by the import adapter at write time." }, "grades": { "type": "array", "items": { "type": "string" }, "description": "Grade levels applicable to this user." }, "updatedAt": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "sourcedId", "status", "firstName", "lastName", "updatedAt" ] }, "Term": { "type": "object", "properties": { "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The natural business key for this academic session, unique within the tenant." }, "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status.", "default": "active" }, "title": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The human-readable title of the academic session." }, "type": { "type": "string", "enum": [ "schoolYear", "term", "semester" ], "description": "RESTRICTED to the Alpha session kinds; gradingPeriod rows are not visible through this projection." }, "startDate": { "type": "string", "format": "date", "description": "The start date of the academic session." }, "endDate": { "type": "string", "format": "date", "description": "The end date of the academic session." }, "schoolYear": { "type": "string", "pattern": "^[0-9]{4}$", "description": "The four-digit school year this session belongs to." }, "parentSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the parent academic session. Null for top-level school years. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `parent` of type academicSession (G-GUIDREF, SES-01)." }, "dateLastModified": { "type": "string", "format": "date-time", "readOnly": true, "description": "Server-managed last-update timestamp (RFC 3339). Read-only — never accepted on create or update." } }, "required": [ "sourcedId", "status", "title", "type", "startDate", "endDate", "schoolYear", "dateLastModified" ] }, "CreateAgeGradeHistoryRequest": { "type": "object", "description": "Create-AgeGradeHistory request body (readOnly/server-managed fields excluded).", "required": [ "personSourcedId", "ageGrade", "beginDate" ], "additionalProperties": false, "properties": { "personSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The student whose roster-cohort grade this period records — the SUBJECT of the history. Two-leg composite FK to oneroster user; restrict-on-delete: a roster delete must not silently destroy Alpha history.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "ageGrade": { "type": "integer", "minimum": -1, "maximum": 12, "description": "The numeric roster-cohort grade position: PreK=-1, K=0, 1..12. A typed integer set at write time — never parsed from a grade name." }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required — the effective-dated from bound; a period always starts). The typed-null rule is structural: not-time-locatable rows cannot exist here." }, "endDate": { "type": "string", "format": "date", "description": "Period end, EXCLUSIVE (half-open [beginDate, endDate)). NULL = the open current period." } } }, "UpdateAgeGradeHistoryRequest": { "type": "object", "description": "Update-AgeGradeHistory request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "ageGrade": { "type": "integer", "minimum": -1, "maximum": 12, "description": "The numeric roster-cohort grade position: PreK=-1, K=0, 1..12. A typed integer set at write time — never parsed from a grade name." }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required — the effective-dated from bound; a period always starts). The typed-null rule is structural: not-time-locatable rows cannot exist here." }, "endDate": { "type": [ "string", "null" ], "format": "date", "description": "Period end, EXCLUSIVE (half-open [beginDate, endDate)). NULL = the open current period." } } }, "CreateAlphaLevelHistoryRequest": { "type": "object", "description": "Create-AlphaLevelHistory request body (readOnly/server-managed fields excluded).", "required": [ "personSourcedId", "alphaLevel", "beginDate" ], "additionalProperties": false, "properties": { "personSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The student whose Alpha level this period records — the SUBJECT of the history.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "alphaLevel": { "type": "string", "enum": [ "WL", "LL", "L1", "L2", "MS", "HS" ], "description": "The Alpha age-band — a locked registry enum. No folding: spellings are exact." }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required effective-dated from bound)." }, "endDate": { "type": "string", "format": "date", "description": "Period end, EXCLUSIVE. NULL = the open current period." } } }, "UpdateAlphaLevelHistoryRequest": { "type": "object", "description": "Update-AlphaLevelHistory request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "alphaLevel": { "type": "string", "enum": [ "WL", "LL", "L1", "L2", "MS", "HS" ], "description": "The Alpha age-band — a locked registry enum. No folding: spellings are exact." }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required effective-dated from bound)." }, "endDate": { "type": [ "string", "null" ], "format": "date", "description": "Period end, EXCLUSIVE. NULL = the open current period." } } }, "CreateGuideAssignmentRequest": { "type": "object", "description": "Create-GuideAssignment request body (readOnly/server-managed fields excluded).", "required": [ "studentSourcedId", "guideSourcedId", "beginDate" ], "additionalProperties": false, "properties": { "studentSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The student — the SUBJECT of the assignment history.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "guideSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The Alpha guide assigned for this period.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required effective-dated from bound)." }, "endDate": { "type": "string", "format": "date", "description": "Period end, EXCLUSIVE. NULL = the open current period." } } }, "UpdateGuideAssignmentRequest": { "type": "object", "description": "Update-GuideAssignment request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "guideSourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The Alpha guide assigned for this period.", "x-references": "oneroster:user.sourcedId", "x-onDelete": "restrict" }, "beginDate": { "type": "string", "format": "date", "description": "Period start (required effective-dated from bound)." }, "endDate": { "type": [ "string", "null" ], "format": "date", "description": "Period end, EXCLUSIVE. NULL = the open current period." } } }, "CreateOrganizationRequest": { "type": "object", "description": "Create-Organization request body (readOnly/server-managed fields excluded).", "required": [ "sourcedId", "status", "name", "type", "modality", "brand", "segment" ], "additionalProperties": false, "properties": { "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The OneRoster sourcedId — the natural business key for this organization, unique within the tenant." }, "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status. Records marked tobedeleted remain queryable for sync consumers rather than being physically removed.", "default": "active" }, "name": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The human-readable name of the organization." }, "type": { "type": "string", "enum": [ "district", "school" ], "description": "RESTRICTED to the Alpha org rungs: district = the Brand×Modality grouping grain, school = the enrollment-anchoring unit. Other base org types are not visible through this projection." }, "identifier": { "type": "string", "maxLength": 256, "description": "An optional human-readable identifier for the organization, such as an NCES school ID." }, "parentSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the parent organization in the hierarchy. Null for root organizations. Forms an acyclic tree. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `parent` of type org (G-GUIDREF, ORG-01)." }, "modality": { "type": "string", "enum": [ "physical", "virtual" ], "description": "Delivery modality — locked registry enum, NO hybrid." }, "brand": { "type": "string", "enum": [ "100for100", "alpha", "gt", "limitless_education", "montessorium", "nextgen", "nova_academy", "novatio", "sw_sales", "texas_sports_academy", "towermath", "unbound", "waypoint" ], "description": "The 13 closed brand values — the Brand×Modality grouping grain (/307-313)." }, "segment": { "type": "string", "enum": [ "charter", "private", "sw_sales", "virtual", "mixed" ], "description": "Business segment — locked registry enum." }, "nweaDistrictId": { "type": "string", "minLength": 1, "description": "The NWEA account grouping key — 1:1 on type='district' rows (inspiration: Ed-Fi EducationOrganizationIdentificationCode)." } } }, "UpdateOrganizationRequest": { "type": "object", "description": "Update-Organization request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status. Records marked tobedeleted remain queryable for sync consumers rather than being physically removed.", "default": "active" }, "name": { "type": "string", "minLength": 1, "maxLength": 512, "description": "The human-readable name of the organization." }, "type": { "type": "string", "enum": [ "district", "school" ], "description": "RESTRICTED to the Alpha org rungs: district = the Brand×Modality grouping grain, school = the enrollment-anchoring unit. Other base org types are not visible through this projection." }, "identifier": { "type": [ "string", "null" ], "maxLength": 256, "description": "An optional human-readable identifier for the organization, such as an NCES school ID." }, "parentSourcedId": { "type": [ "string", "null" ], "maxLength": 256, "description": "The sourcedId of the parent organization in the hierarchy. Null for root organizations. Forms an acyclic tree. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `parent` of type org (G-GUIDREF, ORG-01)." }, "modality": { "type": "string", "enum": [ "physical", "virtual" ], "description": "Delivery modality — locked registry enum, NO hybrid." }, "brand": { "type": "string", "enum": [ "100for100", "alpha", "gt", "limitless_education", "montessorium", "nextgen", "nova_academy", "novatio", "sw_sales", "texas_sports_academy", "towermath", "unbound", "waypoint" ], "description": "The 13 closed brand values — the Brand×Modality grouping grain (/307-313)." }, "segment": { "type": "string", "enum": [ "charter", "private", "sw_sales", "virtual", "mixed" ], "description": "Business segment — locked registry enum." }, "nweaDistrictId": { "type": [ "string", "null" ], "minLength": 1, "description": "The NWEA account grouping key — 1:1 on type='district' rows (inspiration: Ed-Fi EducationOrganizationIdentificationCode)." } } }, "CreatePersonRequest": { "type": "object", "description": "Create-Person request body (readOnly/server-managed fields excluded).", "required": [ "sourcedId", "status", "firstName", "lastName" ], "additionalProperties": false, "properties": { "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The natural business key for this user." }, "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status.", "default": "active" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The person's first name (the master's givenName, renamed — plain-language Alpha name)." }, "lastName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The person's last name (the master's familyName, renamed)." }, "preferredFirstName": { "type": "string", "maxLength": 256, "description": "The user's preferred first name (REST) / preferredGivenName (CSV)." }, "preferredLastName": { "type": "string", "maxLength": 256, "description": "The user's preferred last name." }, "email": { "type": "string", "format": "email", "maxLength": 512, "description": "The user's primary email address." }, "username": { "type": "string", "maxLength": 256, "description": "The user's login username." }, "isEnabled": { "type": "boolean", "description": "Whether the person is enabled — a real boolean on the Alpha surface (the master's enabledUser, renamed).", "default": true }, "primaryOrgSourcedId": { "type": "string", "maxLength": 256, "description": "The sourcedId of the user's primary organization. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `org` (G-GUIDREF, USR-04/USR-06)." }, "roles": { "type": "array", "items": { "type": "object", "$ref": "#/$defs/userRole" }, "description": "The user's role assignments within organizations." }, "userIds": { "type": "array", "items": { "type": "object", "$ref": "#/$defs/userId" }, "description": "External identifier bindings for this user." }, "agents": { "type": "array", "items": { "type": "object", "properties": { "href": { "type": "string", "minLength": 1, "description": "Dereferenceable URI of the referenced agent user." }, "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The sourcedId of the agent user." }, "type": { "type": "string", "enum": [ "user" ], "description": "The GUIDRef type literal — always user." } }, "required": [ "href", "sourcedId", "type" ] }, "description": "GUIDRefs to agent users (parents/guardians for a student) — USR-04. Nested inside jsonb, so not a DB FK; validated by the import adapter at write time." }, "grades": { "type": "array", "items": { "type": "string" }, "description": "Grade levels applicable to this user." } } }, "UpdatePersonRequest": { "type": "object", "description": "Update-Person request body (partial — all fields optional; readOnly + immutable fields excluded; null clears a nullable column).", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "active", "tobedeleted" ], "description": "OneRoster sync status.", "default": "active" }, "firstName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The person's first name (the master's givenName, renamed — plain-language Alpha name)." }, "lastName": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The person's last name (the master's familyName, renamed)." }, "preferredFirstName": { "type": [ "string", "null" ], "maxLength": 256, "description": "The user's preferred first name (REST) / preferredGivenName (CSV)." }, "preferredLastName": { "type": [ "string", "null" ], "maxLength": 256, "description": "The user's preferred last name." }, "email": { "type": [ "string", "null" ], "format": "email", "maxLength": 512, "description": "The user's primary email address." }, "username": { "type": [ "string", "null" ], "maxLength": 256, "description": "The user's login username." }, "isEnabled": { "type": [ "boolean", "null" ], "description": "Whether the person is enabled — a real boolean on the Alpha surface (the master's enabledUser, renamed).", "default": true }, "primaryOrgSourcedId": { "type": [ "string", "null" ], "maxLength": 256, "description": "The sourcedId of the user's primary organization. Stored as the scalar sourcedId; serialized on the REST wire as the OneRoster GUIDRef object `org` (G-GUIDREF, USR-04/USR-06)." }, "roles": { "type": [ "array", "null" ], "items": { "type": "object", "$ref": "#/$defs/userRole" }, "description": "The user's role assignments within organizations." }, "userIds": { "type": [ "array", "null" ], "items": { "type": "object", "$ref": "#/$defs/userId" }, "description": "External identifier bindings for this user." }, "agents": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "href": { "type": "string", "minLength": 1, "description": "Dereferenceable URI of the referenced agent user." }, "sourcedId": { "type": "string", "minLength": 1, "maxLength": 256, "description": "The sourcedId of the agent user." }, "type": { "type": "string", "enum": [ "user" ], "description": "The GUIDRef type literal — always user." } }, "required": [ "href", "sourcedId", "type" ] }, "description": "GUIDRefs to agent users (parents/guardians for a student) — USR-04. Nested inside jsonb, so not a DB FK; validated by the import adapter at write time." }, "grades": { "type": [ "array", "null" ], "items": { "type": "string" }, "description": "Grade levels applicable to this user." } } }, "Problem": { "type": "object", "description": "RFC 7807 problem details.", "properties": { "type": { "type": "string", "format": "uri", "description": "A URI identifying the problem type." }, "title": { "type": "string", "description": "A short, human-readable summary of the problem." }, "status": { "type": "integer", "description": "The HTTP status code." }, "detail": { "type": "string", "description": "A human-readable explanation specific to this occurrence." }, "instance": { "type": "string", "format": "uri", "description": "A URI identifying this occurrence." } }, "required": [ "title", "status" ] } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } }, "servers": [ { "url": "https://alpha.platform4.alphaschool.dev" } ] }