---
title: "validate_extract_schema"
method: POST
path: "/v1/extract/schema-validation"
tags: ["document-operations"]
---

# validate_extract_schema

`POST /v1/extract/schema-validation`

## Request

- Base URL: `https://ndi-api.nace.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://ndi-api.nace.ai/v1/extract/schema-validation`
- Auth: API key in header `X-API-Key`
- TypeScript: <https://skmtc.dev/nace/apis/ndi-service/docs/v1/extract/schema-validation/post.ts> (a function with typed inputs; its response is checked against the schema)

Validate an extraction schema without creating a job or consuming credits.

Cost class: **fast** (pure validation, no I/O, no model inference).

Use this before submitting an ``extract`` job to catch schema errors up
front.  On success ``valid=True`` and ``normalized_schema`` carries the
compiled form the extraction pipeline will use.  On failure ``valid=False``
and ``errors`` lists every violation — the whole list, not just the first.

Args:
    body: Exactly one of ``schema_id`` or ``schema``. Optional
        ``schema_version`` pins a registry version when ``schema_id`` is set.
    caller: Authenticated tenant used to resolve tenant/platform schemas.
    session: Database session.

Returns:
    An :class:`ExtractSchemaValidationResponse`.

Raises:
    PlatformError: ``schema_not_found`` when ``schema_id`` is unknown.

## Request body

- NdiServiceAppPlatformApiDocumentOperationsSchemasExtractSchemaValidationRequest: Body for ``POST /v1/extract/schema-validation``. Same mutual-exclusion rule as :class:`ExtractRequest`: exactly one of ``schema_id`` or ``schema`` must be present. Optional ``schema_version`` pins a registry version when resolving ``schema_id``.
  - `schema_id` string, nullable: Catalog schema family id (sch_...). Mutually exclusive with an inline schema.
  - `schema_version` integer, nullable: Pin a published catalog version. Omit with schema_id to use the latest version.
  - `schema` object, nullable: Inline JSON Schema to validate. Mutually exclusive with schema_id.

## Response `200`

Successful Response

- NdiServiceAppPlatformApiDocumentOperationsSchemasExtractSchemaValidationResponse: Result of ``POST /v1/extract/schema-validation``. On a valid schema, ``valid=True`` and ``normalized_schema`` carries the compiled form. On an invalid schema, ``valid=False`` and ``errors`` lists every violation found — the whole list, not just the first.
  - `valid` boolean, required: True when the schema can be used as an extract schema.
  - `errors` SchemaError[]: Every validation violation found. Empty when valid is true.
    - `path` string, required: JSON Pointer of the schema node that failed validation.
    - `message` string, required: Why this node is not accepted as an extract schema.
  - `normalized_schema` object, nullable: Compiled schema when valid is true. Null when the input was rejected.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `410`: Gone
- `413`: Request Entity Too Large
- `422`: Unprocessable Entity
- `424`: Failed Dependency
- `429`: Too Many Requests
- `500`: Internal Server Error
- `501`: Not Implemented
- `503`: Service Unavailable
- `504`: Gateway Timeout

---

[API](https://skmtc.dev/nace/apis/ndi-service.md) - [All operations](https://skmtc.dev/nace/apis/ndi-service/llms.txt) - [OpenAPI document](https://skmtc.dev/nace/apis/ndi-service/revisions/d9d1f8ec2207?raw)