{ "openapi": "3.1.1", "info": { "title": "XRepository External XML API", "version": "1.0.0", "description": "Opt-in external REST interface. Bearer PAT only; cookies are rejected. A separate same-origin browser client uses cookie plus CSRF. See README.md for deployment gates and integration instructions." }, "servers": [ { "url": "/api/xrepo/v1", "description": "This Repository instance" } ], "security": [ { "PersonalAccessToken": [] } ], "x-status": "implemented-not-deployed", "paths": { "/capabilities": { "get": { "operationId": "getCapabilities", "summary": "Discover repository identity and external API capabilities", "x-required-scopes": [], "responses": { "200": { "description": "Effective external API capabilities; no private workspace inventory.", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Capabilities" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/me": { "get": { "operationId": "getCurrentPrincipal", "summary": "Read current principal and credential restrictions", "x-required-scopes": [], "responses": { "200": { "description": "Current approved principal and non-secret delegation summary.", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Principal" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/workspaces": { "get": { "operationId": "listWorkspaces", "summary": "List current principal/token Workspace intersection", "x-required-scopes": [], "responses": { "200": { "description": "Only authorized Workspaces; reevaluate current membership.", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WorkspacePage" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/workspaces/{workspaceId}/documents": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "get": { "operationId": "listDocuments", "summary": "List ACL-filtered current documents", "x-required-scopes": [ "documents:read" ], "responses": { "200": { "description": "Non-snapshot page; no unauthorized counts.", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentPage" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "parameters": [ { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" }, { "name": "lane", "in": "query", "schema": { "enum": [ "intake", "library", "all" ], "default": "intake" } } ] } }, "/workspaces/{workspaceId}/documents/{recordId}": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" }, { "$ref": "#/components/parameters/RecordId" } ], "get": { "operationId": "getDocument", "summary": "Read canonical XML", "x-required-scopes": [ "documents:read" ], "responses": { "200": { "description": "Canonical XML; not guaranteed identical to submitted source bytes.", "headers": { "ETag": { "description": "Strong ETag of the resulting current document or tombstone.", "schema": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." } }, "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/xml": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } }, "put": { "operationId": "putDocument", "summary": "Create or replace complete XML under server-selected governance", "x-required-scopes": [ "documents:create OR documents:update" ], "responses": { "200": { "description": "Successful atomic document write.", "headers": { "ETag": { "description": "Strong ETag of the resulting current document or tombstone.", "schema": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." } }, "Location": { "schema": { "type": "string" }, "description": "Canonical document API URI." }, "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "201": { "description": "Successful atomic document write.", "headers": { "ETag": { "description": "Strong ETag of the resulting current document or tombstone.", "schema": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." } }, "Location": { "schema": { "type": "string" }, "description": "Canonical document API URI." }, "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "description": "Exactly one precondition is required: If-None-Match: * for create (documents:create), or one exact strong If-Match for update (documents:update). Neither means 428; both/weak/wildcard/list If-Match means 400. Create defaults private/intake. Update preserves governance metadata. No documentType, definitionVersionId, owner, lane or profile input. Known roots never fall back to general after rejection.", "parameters": [ { "$ref": "#/components/parameters/IfMatchOptional" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string", "description": "Complete UTF-8 XML document. Preserve the native root; do not wrap in JSON. See general-xml/1 rules in DESIGN.md." }, "example": "Synthetic fixture" } } } }, "delete": { "operationId": "deleteDocument", "summary": "Soft-delete a document, preserving history", "x-required-scopes": [ "documents:delete" ], "responses": { "204": { "description": "Tombstone committed; other documents may retain unresolved references.", "headers": { "ETag": { "description": "Strong ETag of the resulting current document or tombstone.", "schema": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." } }, "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "parameters": [ { "$ref": "#/components/parameters/IfMatchRequired" } ] } }, "/workspaces/{workspaceId}/documents/{recordId}/description": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" }, { "$ref": "#/components/parameters/RecordId" } ], "get": { "operationId": "getDocumentDescription", "summary": "Read governance metadata and diagnostic summary", "x-required-scopes": [ "documents:read" ], "responses": { "200": { "description": "Current description under current ACL.", "headers": { "ETag": { "description": "Strong ETag of the resulting current document or tombstone.", "schema": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." } }, "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/workspaces/{workspaceId}/documents/{recordId}/references": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" }, { "$ref": "#/components/parameters/RecordId" } ], "get": { "operationId": "getDocumentReferences", "summary": "Read paged ACL-filtered references for a source version", "x-required-scopes": [ "documents:read" ], "responses": { "200": { "description": "Unresolved and denied targets are indistinguishable; external URIs are not fetched.", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferencePage" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "parameters": [ { "$ref": "#/components/parameters/IfMatchOptional" }, { "$ref": "#/components/parameters/Limit" }, { "$ref": "#/components/parameters/Cursor" } ] } }, "/workspaces/{workspaceId}/documents/{recordId}/validate": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" }, { "$ref": "#/components/parameters/RecordId" } ], "post": { "operationId": "validateDocument", "summary": "Validate a proposed write without persistence", "x-required-scopes": [ "documents:create OR documents:update" ], "responses": { "200": { "description": "Valid under current preconditions and policy; not a reservation or future write guarantee.", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationReceipt" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "description": "Same XML, scope, policy selection and mutually exclusive preconditions as PUT; must not create XML, revision or projection. A subsequent PUT repeats all checks.", "parameters": [ { "$ref": "#/components/parameters/IfMatchOptional" }, { "$ref": "#/components/parameters/IfNoneMatch" } ], "requestBody": { "required": true, "content": { "application/xml": { "schema": { "type": "string", "description": "Complete UTF-8 XML document. Preserve the native root; do not wrap in JSON. See general-xml/1 rules in DESIGN.md." }, "example": "Synthetic fixture" } } } } }, "/workspaces/{workspaceId}/documents/{recordId}/metadata": { "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" }, { "$ref": "#/components/parameters/RecordId" } ], "patch": { "operationId": "setDocumentVisibility", "summary": "Change visibility with current share permission", "x-required-scopes": [ "documents:share" ], "responses": { "200": { "description": "Successful atomic document write.", "headers": { "ETag": { "description": "Strong ETag of the resulting current document or tombstone.", "schema": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." } }, "Location": { "schema": { "type": "string" }, "description": "Canonical document API URI." }, "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Receipt" } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "412": { "$ref": "#/components/responses/Error412" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "422": { "$ref": "#/components/responses/Error422" }, "428": { "$ref": "#/components/responses/Error428" }, "429": { "$ref": "#/components/responses/Error429" }, "500": { "$ref": "#/components/responses/Error500" }, "503": { "$ref": "#/components/responses/Error503" } }, "parameters": [ { "$ref": "#/components/parameters/IfMatchRequired" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "visibility" ], "properties": { "visibility": { "enum": [ "private", "shared" ] } } } } } }, "description": "First version changes visibility only. Requires current ACL share permission and exact ETag; creates revision/audit. Lane promotion and profile adoption require separate future governance commands." } }, "/workspaces/{workspaceId}/query": { "post": { "operationId": "queryDocuments", "summary": "Query exact facets and scoped full text with metadata, manifest or canonical XML", "description": "Uses the shared Explorer query engine. Requires a current PAT with documents:read and Workspace access; cookies are rejected. Full-text search matches declared XML ranges, while filters such as TOPIC remain exact facets. All query data and full canonical XML are read in one currently authorized transaction. Unknown fields and unsupported filters fail closed. A changed query, data or authorization snapshot invalidates pagination with 409 cursor_stale. Body is uncompressed UTF-8 JSON, at most 16384 bytes. IP rate limit remains 120 requests/minute with Retry-After: 60. Before switching clients, verify /capabilities query.projections, searchModes, scopedFullText, dimensionKey and maximumResponseBytes; an existing /query route alone does not prove support. This source contract is not a deployment receipt.", "x-required-scopes": [ "documents:read" ], "x-request-body-max-bytes": 16384, "parameters": [ { "$ref": "#/components/parameters/WorkspaceId" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryRequest" }, "example": { "queryVersion": "explorer-query/1", "search": { "text": "壓力", "mode": "fullText", "dimensions": [ "ADVICE", "QUESTION" ] }, "filters": [ { "dimensionKey": "TOPIC", "operator": "anyOf", "values": [ "情緒調節" ] } ], "system": { "lifecycle": "active" }, "result": { "projection": "full", "maxBytes": 8388608 }, "page": { "limit": 20 }, "count": "exact" } } } }, "responses": { "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "413": { "$ref": "#/components/responses/Error413" }, "415": { "$ref": "#/components/responses/Error415" }, "429": { "$ref": "#/components/responses/Error429" }, "503": { "$ref": "#/components/responses/Error503" }, "200": { "description": "One authorized query page. Metadata is the compatible default. Manifest/full carry per-document identity and version; full adds canonical XML. Follow nextCursor even when the page has fewer than limit items.", "headers": { "Cache-Control": { "schema": { "type": "string", "const": "no-store" }, "description": "Authenticated response is not an HTTP cache entry; no collection ETag or 304." } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueryResponse" } } } } } } } }, "components": { "securitySchemes": { "PersonalAccessToken": { "type": "http", "scheme": "bearer", "bearerFormat": "Opaque XRepository personal access token", "description": "Issued by signed-in owner with a lifetime of 1 to 180 days (default 30); limited by current principal ACL, Workspace scope and operation scope. Never supply token as a model tool argument, query, XML, cookie or source-controlled file." } }, "parameters": { "WorkspaceId": { "name": "workspaceId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Server-returned Workspace UUID; no Framework App dimension." }, "RecordId": { "name": "recordId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" } }, "IfMatchOptional": { "name": "If-Match", "in": "header", "required": false, "schema": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." }, "description": "One exact strong ETag. Mandatory for update; optional for reference read. Weak, wildcard and lists rejected." }, "IfMatchRequired": { "name": "If-Match", "in": "header", "required": true, "schema": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." }, "description": "One exact strong ETag; never wildcard, weak or list." }, "IfNoneMatch": { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string", "const": "*" }, "description": "Mandatory for create-only; mutually exclusive with If-Match." }, "Limit": { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, "Cursor": { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "Opaque cursor bound to principal, Workspace and query. Current ACL is always reapplied." } }, "responses": { "Error400": { "description": "Malformed request, XML, precondition or mixed credentials", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error401": { "description": "Missing or invalid bearer credential", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } }, "WWW-Authenticate": { "schema": { "type": "string" }, "description": "Bearer challenge; never redirect to browser login." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error403": { "description": "Insufficient token scope or current permission", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error404": { "description": "Unavailable or missing resource; no existence disclosure", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error409": { "description": "Policy/binding/root conflict, general mode unavailable or quota exceeded", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error412": { "description": "Create collision or stale ETag", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error413": { "description": "Resource limit exceeded", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error415": { "description": "Unsupported media type or encoding", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error422": { "description": "Governance or domain validation failed", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error428": { "description": "Required precondition missing", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error429": { "description": "Rate limited", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay seconds or HTTP date." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error500": { "description": "Internal failure; outcome may need reconciliation", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "Error503": { "description": "Temporarily unavailable", "headers": { "Cache-Control": { "description": "Private authenticated responses must use no-store.", "schema": { "type": "string", "const": "no-store" } }, "Retry-After": { "schema": { "type": "string" }, "description": "Delay seconds or HTTP date." } }, "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } }, "schemas": { "Receipt": { "type": "object", "required": [ "repositoryInstanceId", "workspaceId", "recordId", "etag", "revision", "profile", "contentLane", "visibility", "diagnosticCodes", "governanceReceiptId" ], "properties": { "repositoryInstanceId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "etag": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Int64 revision serialized as a decimal string." }, "profile": { "type": "string", "description": "Server-selected versioned general or domain policy identifier." }, "governanceReceiptId": { "type": "string", "format": "uuid", "description": "Immutable server governance receipt: general Workspace policy receipt or domain Definition receipt, selected by the server, never the client." }, "contentLane": { "enum": [ "intake", "library" ] }, "visibility": { "enum": [ "private", "shared" ] }, "diagnosticCodes": { "type": "array", "items": { "type": "string" } } } }, "ValidationReceipt": { "type": "object", "required": [ "valid", "profile", "diagnosticCodes" ], "properties": { "valid": { "const": true }, "profile": { "type": "string" }, "diagnosticCodes": { "type": "array", "items": { "type": "string" } } } }, "Problem": { "type": "object", "required": [ "type", "title", "status", "code", "requestId" ], "properties": { "type": { "type": "string", "format": "uri-reference" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "code": { "type": "string" }, "requestId": { "type": "string" }, "errors": { "type": "array", "items": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "nodePath": { "type": "string" }, "message": { "type": "string" } } } } } }, "Limits": { "type": "object", "required": [ "maximumBytes", "maximumDepth", "maximumElements", "maximumIndexes", "maximumReferences", "maximumAnchors" ], "properties": { "maximumBytes": { "type": "integer", "minimum": 1 }, "maximumDepth": { "type": "integer", "minimum": 1 }, "maximumElements": { "type": "integer", "minimum": 1 }, "maximumIndexes": { "type": "integer", "minimum": 1 }, "maximumReferences": { "type": "integer", "minimum": 1 }, "maximumAnchors": { "type": "integer", "minimum": 1 } } }, "Capabilities": { "type": "object", "required": [ "repositoryInstanceId", "apiContract", "generalProfileAvailable", "limits" ], "properties": { "repositoryInstanceId": { "type": "string", "format": "uuid" }, "apiContract": { "const": "xrepo-external/1" }, "generalProfileAvailable": { "type": "boolean" }, "limits": { "$ref": "#/components/schemas/Limits" }, "supportedAuthentication": { "type": "array", "items": { "enum": [ "personal-access-token", "oauth" ] } }, "openApiUrl": { "type": "string", "format": "uri" }, "query": { "$ref": "#/components/schemas/QueryCapabilities" } } }, "Principal": { "type": "object", "required": [ "principalId", "credentialId", "scopes", "workspaceIds", "expiresAt" ], "properties": { "principalId": { "type": "string", "format": "uuid" }, "credentialId": { "type": "string", "format": "uuid" }, "scopes": { "type": "array", "items": { "enum": [ "documents:read", "documents:create", "documents:update", "documents:delete", "documents:share" ] } }, "workspaceIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }, "expiresAt": { "type": "string", "format": "date-time" }, "clientLabel": { "type": "string", "description": "User-supplied PAT label; not verified agent identity." } } }, "WorkspacePage": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "workspaceId", "name", "generalXmlEnabled", "allowedOperations", "limits" ], "properties": { "workspaceId": { "type": "string", "format": "uuid" }, "name": { "type": "string" }, "generalXmlEnabled": { "type": "boolean" }, "generalProfile": { "type": "string" }, "allowedOperations": { "type": "array", "items": { "type": "string" } }, "limits": { "$ref": "#/components/schemas/Limits" } } } }, "nextCursor": { "type": [ "string", "null" ] } } }, "DocumentPage": { "type": "object", "required": [ "items", "nextCursor" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Receipt" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "ReferencePage": { "type": "object", "required": [ "sourceRevision", "sourceEtag", "computedAt", "items", "nextCursor" ], "properties": { "sourceRevision": { "type": "string", "pattern": "^[1-9][0-9]*$", "description": "Int64 revision serialized as a decimal string." }, "sourceEtag": { "type": "string", "minLength": 3, "description": "Opaque strong ETag, including its quotation marks; preserve exactly." }, "computedAt": { "type": "string", "format": "date-time" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Reference" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "Reference": { "type": "object", "required": [ "nodePath", "locator", "status" ], "properties": { "nodePath": { "type": "string" }, "locator": { "type": "string" }, "status": { "enum": [ "resolved", "unresolved-or-unavailable", "external-uri", "unmapped" ] }, "target": { "type": "object", "description": "Present only for resolved targets currently visible to this caller.", "required": [ "repositoryInstanceId", "workspaceId", "recordId" ], "properties": { "repositoryInstanceId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "anchor": { "type": "string" }, "title": { "type": "string" } } } }, "allOf": [ { "if": { "properties": { "status": { "enum": [ "unresolved-or-unavailable", "external-uri", "unmapped" ] } }, "required": [ "status" ] }, "then": { "not": { "required": [ "target" ] } } } ] }, "QueryResultSelection": { "type": "object", "properties": { "projection": { "type": "string", "enum": [ "metadata", "manifest", "full" ], "default": "metadata" }, "maxBytes": { "type": "integer", "minimum": 65536, "maximum": 8388608, "default": 8388608, "description": "Serialized UTF-8 response limit. Omitted result preserves legacy metadata bounds; explicit metadata over this budget returns 413 query_response_too_large. Manifest/full may shorten pages, reserving envelope space; an oversized first document returns 413 query_document_too_large." } }, "additionalProperties": false }, "QueryIndexFilter": { "type": "object", "properties": { "dimensionId": { "type": [ "string", "null" ], "maxLength": 8192, "description": "Existing server-issued opaque dim2 identifier. Specify exactly one non-null dimensionId or dimensionKey." }, "dimensionKey": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 128, "description": "Complete exact index key; trim, NFC and invariant uppercase normalization. Known keys need no discovery request." }, "operator": { "type": "string", "enum": [ "anyOf" ] }, "values": { "type": "array", "items": { "type": "string", "maxLength": 4096 }, "minItems": 1, "maxItems": 20, "description": "NFC-normalized lexical exact values. No trim, case folding or numeric/date coercion. Values OR within one dimension; filters AND at document level." } }, "required": [ "operator", "values" ], "additionalProperties": false, "oneOf": [ { "required": [ "dimensionId" ], "properties": { "dimensionId": { "type": "string" }, "dimensionKey": { "type": "null" } } }, { "required": [ "dimensionKey" ], "properties": { "dimensionKey": { "type": "string" }, "dimensionId": { "type": "null" } } } ] }, "QuerySearch": { "type": "object", "properties": { "text": { "type": "string", "maxLength": 500, "default": "" }, "mode": { "type": "string", "enum": [ "titleAndIdentity", "fullText" ], "default": "titleAndIdentity" }, "dimensions": { "type": [ "array", "null" ], "maxItems": 16, "items": { "type": "string", "maxLength": 128, "minLength": 1 }, "description": "Exact full-text scope names, already trimmed, NFC-normalized and invariant uppercase. ADVICE and QUESTION are application-declared examples, not reserved Framework keys. Empty means all declared scopes. A non-empty scope list is accepted only with mode fullText; scope names do not create exact facet filters." } }, "additionalProperties": false, "allOf": [ { "if": { "properties": { "mode": { "const": "fullText" } }, "required": [ "mode" ] }, "else": { "properties": { "dimensions": { "maxItems": 0 } } } } ], "description": "titleAndIdentity preserves title/ID matching. fullText uses lexical AND within one current passage; terms from different scopes or passages are never combined. Full-text ranks by score descending, updated time descending, then record ID in PostgreSQL C collation. Blank text does not constrain the document set; nonblank punctuation-only text has no full-text matches." }, "QuerySystem": { "type": "object", "properties": { "lifecycle": { "type": "string", "enum": [ "active", "deleted", "all" ], "default": "active", "description": "Full projection accepts active only. Deleted metadata/manifest require current owner/manager access." }, "lanes": { "type": "array", "items": { "type": "string", "enum": [ "intake", "library" ] }, "maxItems": 2 }, "visibility": { "type": "array", "items": { "type": "string", "enum": [ "private", "shared" ] }, "maxItems": 2 }, "owner": { "type": "string", "enum": [ "all", "mine" ], "default": "all" }, "documentTypes": { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 128 }, "maxItems": 16 }, "changedFromUtc": { "type": [ "string", "null" ], "format": "date-time", "description": "Inclusive UTC mutation-event time; must precede changedBeforeUtc when both supplied." }, "changedBeforeUtc": { "type": [ "string", "null" ], "format": "date-time", "description": "Exclusive UTC mutation-event time." } }, "additionalProperties": false }, "QueryFacetRequest": { "type": "object", "properties": { "dimensionId": { "type": "string", "maxLength": 8192 }, "excludeOwnFilter": { "type": "boolean", "const": true, "default": true }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 20 }, "lookup": { "type": "string", "maxLength": 500, "default": "" }, "after": { "type": [ "string", "null" ], "maxLength": 4096 } }, "required": [ "dimensionId" ], "additionalProperties": false }, "QueryPageRequest": { "type": "object", "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 }, "cursor": { "type": [ "string", "null" ], "maxLength": 4096, "description": "Opaque signed cursor; 15-minute expiry. Reuse the same normalized query including search mode/scopes, projection, byte budget, count and limit. Ranking position and current data/ACL snapshot are bound. Restart on 409 cursor_stale." } }, "additionalProperties": false }, "QueryRequest": { "type": "object", "properties": { "queryVersion": { "type": "string", "const": "explorer-query/1", "default": "explorer-query/1" }, "search": { "$ref": "#/components/schemas/QuerySearch" }, "system": { "$ref": "#/components/schemas/QuerySystem" }, "filters": { "type": "array", "items": { "$ref": "#/components/schemas/QueryIndexFilter" }, "maxItems": 16, "description": "At most one filter for each normalized complete dimension key." }, "facets": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/QueryFacetRequest" }, "maxItems": 8, "description": "Metadata only: omitted/null selects up to six dimensions; [] omits buckets. Manifest/full do not compute facets." }, "page": { "$ref": "#/components/schemas/QueryPageRequest" }, "count": { "type": "string", "enum": [ "exact", "omit" ], "default": "exact", "description": "omit suppresses totalCount; it does not suppress coverage." }, "result": { "anyOf": [ { "$ref": "#/components/schemas/QueryResultSelection" }, { "type": "null" } ] } }, "additionalProperties": false, "description": "All members are optional. Omission of result retains metadata. Full-text selection and exact-index filters are combined at document level. TOPIC exact values remain separate from ADVICE/QUESTION lexical scope selection. Arbitrary expression, XPath, SQL and typed ranges are unsupported. Full projection requires active lifecycle.", "allOf": [ { "if": { "required": [ "result" ], "properties": { "result": { "type": "object", "required": [ "projection" ], "properties": { "projection": { "const": "full" } } } } }, "then": { "properties": { "system": { "properties": { "lifecycle": { "const": "active" } } } } } } ] }, "QueryManifestItem": { "type": "object", "properties": { "repositoryInstanceId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "etag": { "type": "string", "minLength": 3, "description": "Exact opaque document strong ETag including quotation marks. Use only for this document, never as a collection ETag." }, "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Digest of the stored canonical XML UTF-8 bytes." }, "updatedAt": { "type": "string", "format": "date-time" }, "lifecycle": { "type": "string", "enum": [ "active", "deleted" ] } }, "required": [ "repositoryInstanceId", "workspaceId", "recordId", "revision", "etag", "contentSha256", "updatedAt", "lifecycle" ], "additionalProperties": false }, "QueryFullItem": { "type": "object", "properties": { "repositoryInstanceId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "recordId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "etag": { "type": "string", "minLength": 3, "description": "Exact opaque document strong ETag including quotation marks. Use only for this document, never as a collection ETag." }, "contentSha256": { "type": "string", "pattern": "^[0-9a-f]{64}$", "description": "Digest of the stored canonical XML UTF-8 bytes." }, "updatedAt": { "type": "string", "format": "date-time" }, "lifecycle": { "type": "string", "const": "active" }, "canonicalXml": { "type": "string", "description": "The complete canonical XML for this item identity/revision/ETag. JSON-decode the string before parsing XML. Never truncate, merge or execute XML as HTML." } }, "required": [ "repositoryInstanceId", "workspaceId", "recordId", "revision", "etag", "contentSha256", "updatedAt", "lifecycle", "canonicalXml" ], "additionalProperties": false }, "QueryMetadataItem": { "type": "object", "properties": { "recordId": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" }, "title": { "type": "string" }, "documentType": { "type": "string" }, "etag": { "type": "string", "minLength": 3, "description": "Exact opaque document strong ETag including quotation marks. Use only for this document, never as a collection ETag." }, "revision": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "contentLane": { "type": "string", "enum": [ "intake", "library" ] }, "visibility": { "type": "string", "enum": [ "private", "shared" ] }, "ownerPrincipalId": { "type": "string", "format": "uuid" }, "updatedAt": { "type": "string", "format": "date-time" }, "lifecycle": { "type": "string", "enum": [ "active", "deleted" ] }, "profile": { "type": "string" }, "governanceReceiptId": { "type": [ "string", "null" ], "format": "uuid" }, "definitionVersionId": { "type": [ "string", "null" ], "format": "uuid" }, "rootNamespace": { "type": "string" }, "rootLocalName": { "type": "string" }, "projectionStatus": { "type": "string", "enum": [ "current", "stale", "unprojected" ] }, "allowedActions": { "type": "object", "properties": { "read": { "type": "boolean" }, "update": { "type": "boolean" }, "share": { "type": "boolean" }, "delete": { "type": "boolean" }, "restore": { "type": "boolean" }, "reasonCode": { "type": [ "string", "null" ] } }, "required": [ "read", "update", "share", "delete", "restore", "reasonCode" ] }, "score": { "type": "number", "description": "Highest matching passage rank; zero for title/identity queries." }, "passages": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/QueryPassage" }, "description": "Present for a nonblank full-text metadata query only; source-bound plain text, never canonical XML." } }, "required": [ "recordId", "title", "documentType", "etag", "revision", "contentLane", "visibility", "ownerPrincipalId", "updatedAt", "lifecycle", "profile", "governanceReceiptId", "definitionVersionId", "rootNamespace", "rootLocalName", "projectionStatus", "allowedActions" ] }, "QueryCoverage": { "type": "object", "properties": { "searchMode": { "type": "string", "enum": [ "titleAndIdentity", "fullText" ] }, "unavailableProjectionCount": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "searchMode", "unavailableProjectionCount" ], "description": "ACL-filtered projection coverage. In fullText mode, unavailableProjectionCount counts readable documents with declared full-text scopes lacking current source/projection/tokenizer/dictionary/section receipts, before lexical and exact-filter matching. It is not a count of missing matches for the requested terms or scopes." }, "QueryReceipt": { "type": "object", "properties": { "snapshotId": { "type": "string" }, "queryHash": { "type": "string" }, "repositoryEpoch": { "type": "string", "pattern": "^[0-9]+$" }, "authorizationEpoch": { "type": "string", "pattern": "^[0-9]+$" }, "asOfUtc": { "type": "string", "format": "date-time" }, "expiresAtUtc": { "type": "string", "format": "date-time" } }, "required": [ "snapshotId", "queryHash", "repositoryEpoch", "authorizationEpoch", "asOfUtc", "expiresAtUtc" ] }, "QueryDimension": { "type": "object", "properties": { "dimensionId": { "type": "string" }, "key": { "type": "string" }, "label": { "type": "string" }, "valueKinds": { "type": "array", "items": { "type": "string" } }, "documentCount": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "dimensionId", "key", "label", "valueKinds", "documentCount" ], "description": "Exact comparison/facet catalog; full-text-only scopes do not appear here." }, "QueryFacet": { "type": "object", "properties": { "dimensionId": { "type": "string" }, "buckets": { "type": "array", "items": { "type": "object", "properties": { "value": { "type": "string" }, "label": { "type": "string" }, "count": { "type": "string", "pattern": "^[0-9]+$" }, "selected": { "type": "boolean" } }, "required": [ "value", "label", "count", "selected" ] } }, "nextAfter": { "type": [ "string", "null" ] }, "missingCount": { "type": "string", "pattern": "^[0-9]+$" }, "unavailableCount": { "type": "string", "pattern": "^[0-9]+$" } }, "required": [ "dimensionId", "buckets", "nextAfter", "missingCount", "unavailableCount" ] }, "QueryMetadataPage": { "type": "object", "properties": { "apiContract": { "type": "string", "const": "explorer/1" }, "repositoryInstanceId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "workspaceKey": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "totalCount": { "type": "string", "pattern": "^[0-9]+$" }, "coverage": { "$ref": "#/components/schemas/QueryCoverage" }, "receipt": { "$ref": "#/components/schemas/QueryReceipt" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/QueryMetadataItem" }, "maxItems": 100 }, "dimensions": { "type": "array", "items": { "$ref": "#/components/schemas/QueryDimension" }, "maxItems": 64 }, "dimensionsTruncated": { "type": "boolean" }, "facets": { "type": "array", "items": { "$ref": "#/components/schemas/QueryFacet" } }, "searchDimensions": { "type": "array", "maxItems": 64, "items": { "$ref": "#/components/schemas/QuerySearchDimension" }, "description": "Declared scope catalog from currently readable documents with current index projections, before search text and exact filters. This catalog is separate from exact dimensions/facets and does not assert complete current passage coverage." } }, "required": [ "apiContract", "repositoryInstanceId", "workspaceId", "workspaceKey", "items", "nextCursor", "coverage", "receipt", "dimensions", "dimensionsTruncated", "facets" ], "not": { "required": [ "result" ] } }, "QueryManifestPage": { "type": "object", "properties": { "apiContract": { "type": "string", "const": "explorer/1" }, "repositoryInstanceId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "workspaceKey": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "totalCount": { "type": "string", "pattern": "^[0-9]+$" }, "coverage": { "$ref": "#/components/schemas/QueryCoverage" }, "receipt": { "$ref": "#/components/schemas/QueryReceipt" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/QueryManifestItem" }, "maxItems": 100 }, "result": { "type": "object", "properties": { "projection": { "type": "string", "const": "manifest" }, "maxBytes": { "type": "integer", "minimum": 65536, "maximum": 8388608 } }, "required": [ "projection", "maxBytes" ], "additionalProperties": false } }, "required": [ "apiContract", "repositoryInstanceId", "workspaceId", "workspaceKey", "items", "nextCursor", "coverage", "receipt", "result" ], "additionalProperties": false }, "QueryFullPage": { "type": "object", "properties": { "apiContract": { "type": "string", "const": "explorer/1" }, "repositoryInstanceId": { "type": "string", "format": "uuid" }, "workspaceId": { "type": "string", "format": "uuid" }, "workspaceKey": { "type": "string" }, "nextCursor": { "type": [ "string", "null" ] }, "totalCount": { "type": "string", "pattern": "^[0-9]+$" }, "coverage": { "$ref": "#/components/schemas/QueryCoverage" }, "receipt": { "$ref": "#/components/schemas/QueryReceipt" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/QueryFullItem" }, "maxItems": 100 }, "result": { "type": "object", "properties": { "projection": { "type": "string", "const": "full" }, "maxBytes": { "type": "integer", "minimum": 65536, "maximum": 8388608 } }, "required": [ "projection", "maxBytes" ], "additionalProperties": false } }, "required": [ "apiContract", "repositoryInstanceId", "workspaceId", "workspaceKey", "items", "nextCursor", "coverage", "receipt", "result" ], "additionalProperties": false }, "QueryResponse": { "description": "Homogeneous page selected by result.projection. totalCount is absent when count=omit. Manifest/full echo effective result and exclude metadata UI sections. Independent document ETags are preserved; there is no collection ETag or 304.", "oneOf": [ { "$ref": "#/components/schemas/QueryMetadataPage" }, { "$ref": "#/components/schemas/QueryManifestPage" }, { "$ref": "#/components/schemas/QueryFullPage" } ] }, "QueryCapabilities": { "type": "object", "required": [ "queryVersion", "projections", "dimensionKey", "maximumResponseBytes", "searchModes", "scopedFullText" ], "properties": { "queryVersion": { "type": "string", "const": "explorer-query/1" }, "projections": { "type": "array", "items": { "type": "string", "enum": [ "metadata", "manifest", "full" ] } }, "dimensionKey": { "type": "boolean" }, "maximumResponseBytes": { "type": "integer", "minimum": 65536, "maximum": 8388608 }, "searchModes": { "type": "array", "items": { "type": "string", "enum": [ "titleAndIdentity", "fullText" ] }, "uniqueItems": true }, "scopedFullText": { "type": "boolean" } }, "description": "Check before adopting result projections or scoped full text. Older deployments may expose /query without these capabilities; missing capability metadata does not mean full canonical documents or scoped retrieval are available." }, "QueryPassage": { "type": "object", "required": [ "dimension", "nodePath", "startOffset", "text", "etag", "sourceVersion", "projectionVersion", "tokenizerVersion", "dictionaryVersion", "anchor", "snippet", "score" ], "properties": { "dimension": { "type": "string" }, "nodePath": { "type": "string" }, "anchor": { "type": [ "string", "null" ] }, "startOffset": { "type": "integer", "minimum": 0, "description": "UTF-16 offset into trimmed NFC marker text; not raw XML byte offset." }, "text": { "type": "string", "maxLength": 2048 }, "snippet": { "type": "string", "description": "Plain text match excerpt, never HTML." }, "score": { "type": "number" }, "sourceVersion": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "etag": { "type": "string" }, "projectionVersion": { "type": "integer" }, "tokenizerVersion": { "type": "string" }, "dictionaryVersion": { "type": "string" } }, "additionalProperties": false }, "QuerySearchDimension": { "type": "object", "required": [ "key", "label", "kind", "documentCount" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "kind": { "const": "fullText" }, "documentCount": { "type": "string", "pattern": "^[0-9]+$" } }, "additionalProperties": false } } } }