{ "openapi": "3.1.0", "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "info": { "title": "Control Frontier — Proposed Workforce API", "version": "1.0.0-design.1", "description": "PROPOSED design contract, 30 October 2026. No operation in this document is implemented. No live server is configured. Existing internal APIs are intentionally excluded." }, "x-contract-source": "controlfrontier/docs/developer-platform/scripts/generate.mjs", "x-required-scopes": { "capabilities:read": "Read schema metadata", "workforce:submit": "Submit only the bound source/configuration workforce", "workforce:validate": "Preview own dataset runs", "workforce:read-jobs": "Read own integration jobs and summaries", "workforce:read-canonical": "Optional resource-authorized verification, off by default" }, "tags": [ { "name": "Capabilities" }, { "name": "Workforce ingestion" }, { "name": "Verification" } ], "paths": { "/api/v1/capabilities": { "get": { "operationId": "getIntegrationCapabilities", "summary": "[PROPOSED] Read integration capabilities", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Capabilities" ], "x-implementation-status": "proposed", "x-required-scopes": [ "capabilities:read" ], "security": [ { "IntegrationKey": [] } ], "parameters": [], "responses": { "200": { "description": "Read integration capabilities", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" }, "example": { "apiVersion": "v1", "contractVersion": "sianlabs.workforce/1.0-draft", "status": "proposed", "maxChunkItems": 2000, "maxChunkBytes": 10485760, "maxPageSize": 500, "scopes": [ "capabilities:read", "workforce:submit", "workforce:validate", "workforce:read-jobs" ] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/schemas/workforce": { "get": { "operationId": "getWorkforceSchema", "summary": "[PROPOSED] Locate supported workforce schema", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Capabilities" ], "x-implementation-status": "proposed", "x-required-scopes": [ "capabilities:read" ], "security": [ { "IntegrationKey": [] } ], "parameters": [], "responses": { "200": { "description": "Locate supported workforce schema", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SchemaIndex" }, "example": { "contractVersion": "sianlabs.workforce/1.0-draft", "schemaUrl": "/specs/control-frontier/v1/schemas/workforce-dataset.schema.json", "sha256": "0000000000000000000000000000000000000000000000000000000000000000" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/workforce/datasets": { "post": { "operationId": "createWorkforceDataset", "summary": "[PROPOSED] Create a bounded dataset run", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Workforce ingestion" ], "x-implementation-status": "proposed", "x-required-scopes": [ "workforce:submit" ], "security": [ { "IntegrationKey": [] } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DatasetCreate" } } } }, "responses": { "201": { "description": "Create a bounded dataset run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "state": "collecting", "requestId": "11111111-1111-4111-8111-111111111111" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/workforce/datasets/{datasetId}/chunks": { "post": { "operationId": "appendWorkforceChunk", "summary": "[PROPOSED] Retain a deterministic workforce chunk", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Workforce ingestion" ], "x-implementation-status": "proposed", "x-required-scopes": [ "workforce:submit" ], "security": [ { "IntegrationKey": [] } ], "parameters": [ { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkforceChunk" }, "example": { "contractVersion": "sianlabs.workforce/1.0-draft", "chunkIndex": 0, "chunkSha256": "07ef2cc7f2669bb079b724daf8404bd9946c2accce10898a373f853f5bccf0bd", "world": { "asOf": "2026-10-30", "jurisdictions": [ { "id": "jur_gb", "code": "GB", "name": "United Kingdom", "region": "Europe" } ], "legalEntities": [ { "id": "le_bank", "code": "BANK", "name": "Example Synthetic Bank", "kind": "bank", "jurisdictionId": "jur_gb", "parentLegalEntityId": null, "branchJurisdictionIds": [], "status": "active" } ], "locations": [ { "id": "loc_london", "code": "LDN", "name": "London office", "city": "London", "countryCode": "GB", "jurisdictionId": "jur_gb", "region": "Europe", "siteType": "office", "timeZone": "Europe/London" } ], "teams": [ { "id": "team_risk", "name": "Risk", "unitType": "team", "jobFunction": "Risk", "divisionCode": null, "parentTeamId": null, "scope": "global", "region": "Europe", "primaryLocationId": "loc_london", "legalEntityId": "le_bank", "costCentre": "CC001", "headPersonId": "per_alex", "alignedDivisionCode": null, "establishedOn": "2020-01-01" } ], "people": [ { "id": "per_alex", "workerId": "W00000001", "givenName": "Alex", "familyName": "Example", "preferredGivenName": null, "displayName": "Alex Example", "email": "alex@example.invalid", "employment": { "type": "permanent", "status": "active", "hireDate": "2020-01-01", "endDate": null, "fte": 1 }, "job": { "familyCode": "RISK", "jobFunction": "Risk", "title": "Risk lead", "corporateTitle": "Director", "grade": "G08", "seniority": "senior", "role": "team_lead", "isPeopleManager": false }, "primaryTeamId": "team_risk", "divisionCode": null, "locationId": "loc_london", "legalEntityId": "le_bank", "managerId": null, "directory": { "objectId": "11111111-1111-4111-8111-111111111111", "userPrincipalName": "alex@example.invalid", "mailNickname": "alex", "samAccountName": "aexample" } } ], "memberships": [ { "id": "mem_alex", "personId": "per_alex", "teamId": "team_risk", "kind": "primary", "role": "lead", "validFrom": "2020-01-01", "validTo": null } ], "reportingLines": [], "teamHierarchy": [], "exceptions": [ { "rule": "manager_required", "subjectId": "per_alex", "reason": "designated_root" } ] }, "revisions": [] } } } }, "responses": { "201": { "description": "Retain a deterministic workforce chunk", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "state": "collecting", "requestId": "11111111-1111-4111-8111-111111111111" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/workforce/datasets/{datasetId}/preview": { "post": { "operationId": "previewWorkforceDataset", "summary": "[PROPOSED] Validate and preview the complete dataset", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Workforce ingestion" ], "x-implementation-status": "proposed", "x-required-scopes": [ "workforce:validate" ], "security": [ { "IntegrationKey": [] } ], "parameters": [ { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "200": { "description": "Validate and preview the complete dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Preview" }, "example": { "datasetId": "11111111-1111-4111-8111-111111111111", "validationId": "11111111-1111-4111-8111-111111111111", "valid": true, "counts": { "created": 5, "updated": 0, "unchanged": 0, "conflicted": 0, "rejected": 0, "proposed": 5, "accepted": 0, "applied": 0 }, "requiresHumanReview": true, "errors": [] } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/workforce/datasets/{datasetId}/start": { "post": { "operationId": "startWorkforceIngestion", "summary": "[PROPOSED] Queue proposal generation", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Workforce ingestion" ], "x-implementation-status": "proposed", "x-required-scopes": [ "workforce:submit" ], "security": [ { "IntegrationKey": [] } ], "parameters": [ { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200 } } ], "responses": { "202": { "description": "Queue proposal generation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "state": "queued", "requestId": "11111111-1111-4111-8111-111111111111" } } }, "headers": { "Location": { "description": "Proposed job status path", "schema": { "type": "string", "format": "uri-reference" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/workforce/datasets/{datasetId}/summary": { "get": { "operationId": "getWorkforceDatasetSummary", "summary": "[PROPOSED] Read reconciliation and institutional outcomes", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Workforce ingestion" ], "x-implementation-status": "proposed", "x-required-scopes": [ "workforce:read-jobs" ], "security": [ { "IntegrationKey": [] } ], "parameters": [ { "name": "datasetId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read reconciliation and institutional outcomes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Summary" }, "example": { "datasetId": "11111111-1111-4111-8111-111111111111", "completeSourceSnapshot": false, "expectedItems": 5, "receivedItems": 5, "counts": { "created": 5, "updated": 0, "unchanged": 0, "conflicted": 0, "rejected": 0, "proposed": 5, "accepted": 0, "applied": 0 }, "governance": "pending_review", "application": "not_started" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/ingestion-jobs/{jobId}": { "get": { "operationId": "getIngestionJob", "summary": "[PROPOSED] Read asynchronous execution status", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Workforce ingestion" ], "x-implementation-status": "proposed", "x-required-scopes": [ "workforce:read-jobs" ], "security": [ { "IntegrationKey": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Read asynchronous execution status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Job" }, "example": { "id": "11111111-1111-4111-8111-111111111111", "datasetId": "11111111-1111-4111-8111-111111111111", "execution": "completed", "governance": "pending_review", "application": "not_started", "counts": { "created": 5, "updated": 0, "unchanged": 0, "conflicted": 0, "rejected": 0, "proposed": 5, "accepted": 0, "applied": 0 }, "requestId": "11111111-1111-4111-8111-111111111111" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/ingestion-jobs/{jobId}/items": { "get": { "operationId": "listIngestionItems", "summary": "[PROPOSED] Page through item reconciliation and errors", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Workforce ingestion" ], "x-implementation-status": "proposed", "x-required-scopes": [ "workforce:read-jobs" ], "security": [ { "IntegrationKey": [] } ], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } } ], "responses": { "200": { "description": "Page through item reconciliation and errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ItemPage" }, "example": { "items": [ { "ordinal": 0, "sourceRecordId": "per_alex", "sourceRevisionId": null, "entity": "person", "outcome": "created", "proposalId": "11111111-1111-4111-8111-111111111111", "canonicalId": null, "proposalState": "pending", "code": null, "field": null } ], "nextCursor": null } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } }, "/api/v1/workforce/records": { "get": { "operationId": "listCanonicalWorkforceRecords", "summary": "[PROPOSED] Verify authorized accepted workforce revisions", "description": "Design specification only. This operation is not implemented or callable. It will reuse governed Data Exchange; no autonomous institutional approval.", "tags": [ "Verification" ], "x-implementation-status": "proposed", "x-required-scopes": [ "workforce:read-canonical" ], "security": [ { "IntegrationKey": [] } ], "parameters": [ { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 2000 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 } }, { "name": "at", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "knownAt", "in": "query", "required": true, "schema": { "type": "string", "format": "date-time" } }, { "name": "entity", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "jurisdiction", "legal_entity", "location", "team", "person", "membership", "reporting_line", "team_parent" ] } }, { "name": "sourceRecordId", "in": "query", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 255 } } ], "responses": { "200": { "description": "Verify authorized accepted workforce revisions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CanonicalPage" }, "example": { "items": [], "nextCursor": null, "at": "2026-10-30T00:00:00Z", "knownAt": "2026-10-30T12:00:00Z" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "401": { "description": "Missing, expired or revoked credential", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "403": { "description": "Scope or resource authorization denied", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "404": { "description": "Resource unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "409": { "description": "Idempotency, revision or state conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "413": { "description": "Bounded input limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "415": { "description": "Use application/json", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "422": { "description": "Validation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } } }, "429": { "description": "Shared request budget exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } }, "503": { "description": "Temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": "validation_failed", "message": "One or more source records require correction.", "requestId": "11111111-1111-4111-8111-111111111111", "retryable": false, "details": [ { "field": "people[0].employment.fte", "code": "out_of_range" } ] } } }, "headers": { "Retry-After": { "description": "Seconds until retry is permitted", "schema": { "type": "integer", "minimum": 1 } } } } } } } }, "components": { "securitySchemes": { "IntegrationKey": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque tenant-bound integration key (proposed)", "description": "Proposed named integration credential; scopes are x-required-scopes, not OAuth scopes. Never use SCIM or Clerk credentials here." } }, "schemas": { "Jurisdiction": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "code": { "type": "string", "minLength": 1, "maxLength": 32 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "code", "name", "region" ], "additionalProperties": false }, "LegalEntity": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "code": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "kind": { "type": "string", "minLength": 1, "maxLength": 80 }, "jurisdictionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "parentLegalEntityId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "branchJurisdictionIds": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 255 }, "maxItems": 250 }, "status": { "type": "string", "enum": [ "active", "dormant" ] } }, "required": [ "id", "code", "name", "kind", "jurisdictionId", "parentLegalEntityId", "branchJurisdictionIds", "status" ], "additionalProperties": false }, "Location": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "code": { "type": "string", "minLength": 1, "maxLength": 64 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "city": { "type": "string", "minLength": 1, "maxLength": 200 }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$" }, "jurisdictionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "siteType": { "type": "string", "minLength": 1, "maxLength": 80 }, "timeZone": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "id", "code", "name", "city", "countryCode", "jurisdictionId", "region", "siteType", "timeZone" ], "additionalProperties": false }, "Team": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "unitType": { "type": "string", "enum": [ "group", "division", "business_unit", "department", "sub_department", "team" ] }, "jobFunction": { "type": "string", "minLength": 1, "maxLength": 200 }, "divisionCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "parentTeamId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "scope": { "type": "string", "enum": [ "global", "regional", "local" ] }, "region": { "type": "string", "minLength": 1, "maxLength": 100 }, "primaryLocationId": { "type": "string", "minLength": 1, "maxLength": 255 }, "legalEntityId": { "type": "string", "minLength": 1, "maxLength": 255 }, "costCentre": { "type": "string", "minLength": 1, "maxLength": 100 }, "headPersonId": { "type": "string", "minLength": 1, "maxLength": 255 }, "alignedDivisionCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "establishedOn": { "type": "string", "format": "date" } }, "required": [ "id", "name", "unitType", "jobFunction", "divisionCode", "parentTeamId", "scope", "region", "primaryLocationId", "legalEntityId", "costCentre", "headPersonId", "alignedDivisionCode", "establishedOn" ], "additionalProperties": false }, "Person": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "workerId": { "type": "string", "pattern": "^[WC][0-9]{8}$" }, "givenName": { "type": "string", "minLength": 1, "maxLength": 200 }, "familyName": { "type": "string", "minLength": 1, "maxLength": 200 }, "preferredGivenName": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "displayName": { "type": "string", "minLength": 1, "maxLength": 200 }, "email": { "type": "string", "format": "email", "maxLength": 320 }, "employment": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "permanent", "fixed_term", "contractor" ] }, "status": { "type": "string", "enum": [ "active", "on_leave", "pending_start", "terminated" ] }, "hireDate": { "type": "string", "format": "date" }, "endDate": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] }, "fte": { "type": "number", "exclusiveMinimum": 0, "maximum": 1 } }, "required": [ "type", "status", "hireDate", "endDate", "fte" ], "additionalProperties": false }, "job": { "type": "object", "properties": { "familyCode": { "type": "string", "minLength": 1, "maxLength": 80 }, "jobFunction": { "type": "string", "minLength": 1, "maxLength": 200 }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "corporateTitle": { "type": "string", "minLength": 1, "maxLength": 200 }, "grade": { "type": "string", "minLength": 1, "maxLength": 80 }, "seniority": { "type": "string", "minLength": 1, "maxLength": 80 }, "role": { "type": "string", "enum": [ "group_head", "unit_head", "team_lead", "staff", "individual_contributor" ] }, "isPeopleManager": { "type": "boolean" } }, "required": [ "familyCode", "jobFunction", "title", "corporateTitle", "grade", "seniority", "role", "isPeopleManager" ], "additionalProperties": false }, "primaryTeamId": { "type": "string", "minLength": 1, "maxLength": 255 }, "divisionCode": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 64 }, { "type": "null" } ] }, "locationId": { "type": "string", "minLength": 1, "maxLength": 255 }, "legalEntityId": { "type": "string", "minLength": 1, "maxLength": 255 }, "managerId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "directory": { "type": "object", "properties": { "objectId": { "type": "string", "format": "uuid" }, "userPrincipalName": { "type": "string", "minLength": 1, "maxLength": 320 }, "mailNickname": { "type": "string", "minLength": 1, "maxLength": 200 }, "samAccountName": { "type": "string", "minLength": 1, "maxLength": 200 } }, "required": [ "objectId", "userPrincipalName", "mailNickname", "samAccountName" ], "additionalProperties": false } }, "required": [ "id", "workerId", "givenName", "familyName", "preferredGivenName", "displayName", "email", "employment", "job", "primaryTeamId", "divisionCode", "locationId", "legalEntityId", "managerId", "directory" ], "additionalProperties": false }, "TeamMembership": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "personId": { "type": "string", "minLength": 1, "maxLength": 255 }, "teamId": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": [ "primary", "matrix" ] }, "role": { "type": "string", "enum": [ "head", "lead", "member" ] }, "validFrom": { "type": "string", "format": "date" }, "validTo": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "personId", "teamId", "kind", "role", "validFrom", "validTo" ], "additionalProperties": false }, "ReportingLine": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "personId": { "type": "string", "minLength": 1, "maxLength": 255 }, "managerId": { "type": "string", "minLength": 1, "maxLength": 255 }, "kind": { "type": "string", "enum": [ "solid", "dotted" ] }, "validFrom": { "type": "string", "format": "date" }, "validTo": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "personId", "managerId", "kind", "validFrom", "validTo" ], "additionalProperties": false }, "TeamParent": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 255 }, "childTeamId": { "type": "string", "minLength": 1, "maxLength": 255 }, "parentTeamId": { "type": "string", "minLength": 1, "maxLength": 255 }, "validFrom": { "type": "string", "format": "date" }, "validTo": { "anyOf": [ { "type": "string", "format": "date" }, { "type": "null" } ] } }, "required": [ "id", "childTeamId", "parentTeamId", "validFrom", "validTo" ], "additionalProperties": false }, "DocumentedException": { "type": "object", "properties": { "rule": { "type": "string", "minLength": 1, "maxLength": 100 }, "subjectId": { "type": "string", "minLength": 1, "maxLength": 255 }, "reason": { "type": "string", "minLength": 1, "maxLength": 2000 } }, "required": [ "rule", "subjectId", "reason" ], "additionalProperties": false }, "World": { "type": "object", "properties": { "asOf": { "type": "string", "format": "date" }, "jurisdictions": { "type": "array", "items": { "$ref": "#/components/schemas/Jurisdiction" }, "maxItems": 2000 }, "legalEntities": { "type": "array", "items": { "$ref": "#/components/schemas/LegalEntity" }, "maxItems": 2000 }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/Location" }, "maxItems": 2000 }, "teams": { "type": "array", "items": { "$ref": "#/components/schemas/Team" }, "maxItems": 2000 }, "people": { "type": "array", "items": { "$ref": "#/components/schemas/Person" }, "maxItems": 2000 }, "memberships": { "type": "array", "items": { "$ref": "#/components/schemas/TeamMembership" }, "maxItems": 2000 }, "reportingLines": { "type": "array", "items": { "$ref": "#/components/schemas/ReportingLine" }, "maxItems": 2000 }, "teamHierarchy": { "type": "array", "items": { "$ref": "#/components/schemas/TeamParent" }, "maxItems": 2000 }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentedException" }, "maxItems": 2000 } }, "required": [ "asOf", "jurisdictions", "legalEntities", "locations", "teams", "people", "memberships", "reportingLines", "teamHierarchy", "exceptions" ], "additionalProperties": false }, "Manifest": { "type": "object", "properties": { "contract": { "const": "demoforge.workforce.manifest/1" }, "generator": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 255 }, "version": { "type": "string", "minLength": 1, "maxLength": 80 } }, "required": [ "name", "version" ], "additionalProperties": false }, "profile": { "type": "string", "minLength": 1, "maxLength": 100 }, "seed": { "oneOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "object", "properties": { "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "sha256" ], "additionalProperties": false } ] }, "asOf": { "type": "string", "format": "date" }, "configSchema": { "type": "string", "minLength": 1, "maxLength": 255 }, "configVersion": { "type": "string", "minLength": 1, "maxLength": 80 }, "configSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "neutralContract": { "const": "demoforge.neutral.workforce/1.0" }, "sourceContracts": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 255 } }, "quality": { "type": "string", "enum": [ "clean", "realistic", "hostile" ] }, "reference": { "type": "object", "additionalProperties": { "type": "object", "properties": { "version": { "type": "string", "minLength": 1, "maxLength": 80 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "version", "sha256" ], "additionalProperties": false } }, "counts": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 0 } }, "validation": { "type": "object", "properties": { "passed": { "type": "boolean" }, "hard": { "type": "integer", "minimum": 0 }, "soft": { "type": "integer", "minimum": 0 } }, "required": [ "passed", "hard", "soft" ], "additionalProperties": false }, "files": { "type": "array", "items": { "type": "object", "properties": { "path": { "type": "string", "minLength": 1, "maxLength": 500 }, "records": { "type": "integer", "minimum": 0 }, "bytes": { "type": "integer", "minimum": 0 }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "path", "records", "bytes", "sha256" ], "additionalProperties": false }, "maxItems": 1000 }, "datasetSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "contract", "generator", "profile", "seed", "asOf", "configSchema", "configVersion", "configSha256", "neutralContract", "sourceContracts", "quality", "reference", "counts", "validation", "files", "datasetSha256" ], "additionalProperties": false }, "Revision": { "oneOf": [ { "type": "object", "properties": { "entity": { "const": "jurisdiction" }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionGroupId": { "type": "string", "minLength": 1, "maxLength": 255 }, "episodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersedesSourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "observe", "correct", "close" ] }, "record": { "$ref": "#/components/schemas/Jurisdiction" } }, "required": [ "entity", "sourceRecordId", "sourceRevisionId", "revisionGroupId", "episodeId", "effectiveFrom", "effectiveTo", "supersedesSourceRevisionId", "operation", "record" ], "additionalProperties": false }, { "type": "object", "properties": { "entity": { "const": "legal_entity" }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionGroupId": { "type": "string", "minLength": 1, "maxLength": 255 }, "episodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersedesSourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "observe", "correct", "close" ] }, "record": { "$ref": "#/components/schemas/LegalEntity" } }, "required": [ "entity", "sourceRecordId", "sourceRevisionId", "revisionGroupId", "episodeId", "effectiveFrom", "effectiveTo", "supersedesSourceRevisionId", "operation", "record" ], "additionalProperties": false }, { "type": "object", "properties": { "entity": { "const": "location" }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionGroupId": { "type": "string", "minLength": 1, "maxLength": 255 }, "episodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersedesSourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "observe", "correct", "close" ] }, "record": { "$ref": "#/components/schemas/Location" } }, "required": [ "entity", "sourceRecordId", "sourceRevisionId", "revisionGroupId", "episodeId", "effectiveFrom", "effectiveTo", "supersedesSourceRevisionId", "operation", "record" ], "additionalProperties": false }, { "type": "object", "properties": { "entity": { "const": "team" }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionGroupId": { "type": "string", "minLength": 1, "maxLength": 255 }, "episodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersedesSourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "observe", "correct", "close" ] }, "record": { "$ref": "#/components/schemas/Team" } }, "required": [ "entity", "sourceRecordId", "sourceRevisionId", "revisionGroupId", "episodeId", "effectiveFrom", "effectiveTo", "supersedesSourceRevisionId", "operation", "record" ], "additionalProperties": false }, { "type": "object", "properties": { "entity": { "const": "person" }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionGroupId": { "type": "string", "minLength": 1, "maxLength": 255 }, "episodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersedesSourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "observe", "correct", "close" ] }, "record": { "$ref": "#/components/schemas/Person" } }, "required": [ "entity", "sourceRecordId", "sourceRevisionId", "revisionGroupId", "episodeId", "effectiveFrom", "effectiveTo", "supersedesSourceRevisionId", "operation", "record" ], "additionalProperties": false }, { "type": "object", "properties": { "entity": { "const": "membership" }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionGroupId": { "type": "string", "minLength": 1, "maxLength": 255 }, "episodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersedesSourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "observe", "correct", "close" ] }, "record": { "$ref": "#/components/schemas/TeamMembership" } }, "required": [ "entity", "sourceRecordId", "sourceRevisionId", "revisionGroupId", "episodeId", "effectiveFrom", "effectiveTo", "supersedesSourceRevisionId", "operation", "record" ], "additionalProperties": false }, { "type": "object", "properties": { "entity": { "const": "reporting_line" }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionGroupId": { "type": "string", "minLength": 1, "maxLength": 255 }, "episodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersedesSourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "observe", "correct", "close" ] }, "record": { "$ref": "#/components/schemas/ReportingLine" } }, "required": [ "entity", "sourceRecordId", "sourceRevisionId", "revisionGroupId", "episodeId", "effectiveFrom", "effectiveTo", "supersedesSourceRevisionId", "operation", "record" ], "additionalProperties": false }, { "type": "object", "properties": { "entity": { "const": "team_parent" }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionGroupId": { "type": "string", "minLength": 1, "maxLength": 255 }, "episodeId": { "type": "string", "minLength": 1, "maxLength": 255 }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "supersedesSourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "operation": { "type": "string", "enum": [ "observe", "correct", "close" ] }, "record": { "$ref": "#/components/schemas/TeamParent" } }, "required": [ "entity", "sourceRecordId", "sourceRevisionId", "revisionGroupId", "episodeId", "effectiveFrom", "effectiveTo", "supersedesSourceRevisionId", "operation", "record" ], "additionalProperties": false } ] }, "WorkforceChunk": { "type": "object", "properties": { "contractVersion": { "const": "sianlabs.workforce/1.0-draft" }, "chunkIndex": { "type": "integer", "minimum": 0, "maximum": 9999 }, "chunkSha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" }, "world": { "$ref": "#/components/schemas/World" }, "revisions": { "type": "array", "items": { "$ref": "#/components/schemas/Revision" }, "maxItems": 2000 } }, "required": [ "contractVersion", "chunkIndex", "chunkSha256", "world", "revisions" ], "additionalProperties": false }, "DatasetCreate": { "type": "object", "properties": { "contractVersion": { "const": "sianlabs.workforce/1.0-draft" }, "manifest": { "$ref": "#/components/schemas/Manifest" }, "expectedChunks": { "type": "integer", "minimum": 1, "maximum": 10000 }, "expectedItems": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "mode": { "type": "string", "enum": [ "snapshot", "incremental" ] }, "snapshotEffectiveFrom": { "type": "string", "format": "date-time" } }, "required": [ "contractVersion", "manifest", "expectedChunks", "expectedItems", "mode", "snapshotEffectiveFrom" ], "additionalProperties": false }, "Receipt": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "state": { "type": "string", "enum": [ "collecting", "ready", "queued" ] }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "id", "state", "requestId" ], "additionalProperties": false }, "Counts": { "type": "object", "properties": { "created": { "type": "integer", "minimum": 0 }, "updated": { "type": "integer", "minimum": 0 }, "unchanged": { "type": "integer", "minimum": 0 }, "conflicted": { "type": "integer", "minimum": 0 }, "rejected": { "type": "integer", "minimum": 0 }, "proposed": { "type": "integer", "minimum": 0 }, "accepted": { "type": "integer", "minimum": 0 }, "applied": { "type": "integer", "minimum": 0 } }, "required": [ "created", "updated", "unchanged", "conflicted", "rejected", "proposed", "accepted", "applied" ], "additionalProperties": false }, "Job": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "datasetId": { "type": "string", "format": "uuid" }, "execution": { "type": "string", "enum": [ "queued", "running", "completed", "partial", "failed" ] }, "governance": { "type": "string", "enum": [ "not_ready", "pending_review", "partially_approved", "approved", "rejected" ] }, "application": { "type": "string", "enum": [ "not_started", "running", "partial", "completed", "failed" ] }, "counts": { "$ref": "#/components/schemas/Counts" }, "requestId": { "type": "string", "format": "uuid" } }, "required": [ "id", "datasetId", "execution", "governance", "application", "counts", "requestId" ], "additionalProperties": false }, "Item": { "type": "object", "properties": { "ordinal": { "type": "integer", "minimum": 0 }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "sourceRevisionId": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 255 }, { "type": "null" } ] }, "entity": { "type": "string", "enum": [ "jurisdiction", "legal_entity", "location", "team", "person", "membership", "reporting_line", "team_parent" ] }, "outcome": { "type": "string", "enum": [ "created", "updated", "unchanged", "conflicted", "rejected" ] }, "proposalId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "canonicalId": { "anyOf": [ { "type": "string", "format": "uuid" }, { "type": "null" } ] }, "proposalState": { "type": "string", "enum": [ "none", "pending", "approved", "accepted", "rejected", "applied" ] }, "code": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "field": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] } }, "required": [ "ordinal", "sourceRecordId", "sourceRevisionId", "entity", "outcome", "proposalId", "canonicalId", "proposalState", "code", "field" ], "additionalProperties": false }, "ItemPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Item" }, "maxItems": 500 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] } }, "required": [ "items", "nextCursor" ], "additionalProperties": false }, "Preview": { "type": "object", "properties": { "datasetId": { "type": "string", "format": "uuid" }, "validationId": { "type": "string", "format": "uuid" }, "valid": { "type": "boolean" }, "counts": { "$ref": "#/components/schemas/Counts" }, "requiresHumanReview": { "const": true }, "errors": { "type": "array", "items": { "type": "object", "properties": { "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "code": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "sourceRecordId", "field", "code" ], "additionalProperties": false }, "maxItems": 500 } }, "required": [ "datasetId", "validationId", "valid", "counts", "requiresHumanReview", "errors" ], "additionalProperties": false }, "Summary": { "type": "object", "properties": { "datasetId": { "type": "string", "format": "uuid" }, "completeSourceSnapshot": { "type": "boolean" }, "expectedItems": { "type": "integer", "minimum": 0 }, "receivedItems": { "type": "integer", "minimum": 0 }, "counts": { "$ref": "#/components/schemas/Counts" }, "governance": { "type": "string", "enum": [ "not_ready", "pending_review", "partially_approved", "approved", "rejected" ] }, "application": { "type": "string", "enum": [ "not_started", "running", "partial", "completed", "failed" ] } }, "required": [ "datasetId", "completeSourceSnapshot", "expectedItems", "receivedItems", "counts", "governance", "application" ], "additionalProperties": false }, "Error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_request", "unauthenticated", "forbidden", "not_found", "conflict", "payload_too_large", "unsupported_media_type", "validation_failed", "rate_limited", "unavailable" ] }, "message": { "type": "string", "minLength": 1, "maxLength": 500 }, "requestId": { "type": "string", "format": "uuid" }, "retryable": { "type": "boolean" }, "details": { "type": "array", "items": { "type": "object", "properties": { "field": { "type": "string", "minLength": 1, "maxLength": 200 }, "code": { "type": "string", "minLength": 1, "maxLength": 100 } }, "required": [ "field", "code" ], "additionalProperties": false }, "maxItems": 100 } }, "required": [ "code", "message", "requestId", "retryable", "details" ], "additionalProperties": false }, "Capabilities": { "type": "object", "properties": { "apiVersion": { "const": "v1" }, "contractVersion": { "const": "sianlabs.workforce/1.0-draft" }, "status": { "const": "proposed" }, "maxChunkItems": { "const": 2000 }, "maxChunkBytes": { "const": 10485760 }, "maxPageSize": { "const": 500 }, "scopes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 100 }, "maxItems": 20 } }, "required": [ "apiVersion", "contractVersion", "status", "maxChunkItems", "maxChunkBytes", "maxPageSize", "scopes" ], "additionalProperties": false }, "SchemaIndex": { "type": "object", "properties": { "contractVersion": { "const": "sianlabs.workforce/1.0-draft" }, "schemaUrl": { "type": "string", "format": "uri-reference" }, "sha256": { "type": "string", "pattern": "^[a-f0-9]{64}$" } }, "required": [ "contractVersion", "schemaUrl", "sha256" ], "additionalProperties": false }, "CanonicalPage": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "canonicalId": { "type": "string", "format": "uuid" }, "entity": { "type": "string", "enum": [ "jurisdiction", "legal_entity", "location", "team", "person", "membership", "reporting_line", "team_parent" ] }, "sourceRecordId": { "type": "string", "minLength": 1, "maxLength": 255 }, "revisionId": { "type": "string", "format": "uuid" }, "effectiveFrom": { "type": "string", "format": "date-time" }, "effectiveTo": { "anyOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "recordedAt": { "type": "string", "format": "date-time" }, "record": { "oneOf": [ { "$ref": "#/components/schemas/Jurisdiction" }, { "$ref": "#/components/schemas/LegalEntity" }, { "$ref": "#/components/schemas/Location" }, { "$ref": "#/components/schemas/Team" }, { "$ref": "#/components/schemas/Person" }, { "$ref": "#/components/schemas/TeamMembership" }, { "$ref": "#/components/schemas/ReportingLine" }, { "$ref": "#/components/schemas/TeamParent" } ] } }, "required": [ "canonicalId", "entity", "sourceRecordId", "revisionId", "effectiveFrom", "effectiveTo", "recordedAt", "record" ], "additionalProperties": false }, "maxItems": 500 }, "nextCursor": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2000 }, { "type": "null" } ] }, "at": { "type": "string", "format": "date-time" }, "knownAt": { "type": "string", "format": "date-time" } }, "required": [ "items", "nextCursor", "at", "knownAt" ], "additionalProperties": false } } } }