---
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`
- 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-platform-api/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.

## 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` object, nullable: Inline JSON Schema to validate. Mutually exclusive with 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.

## 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.
  - `errors` SchemaError[]: Every validation violation found. Empty when valid is true.
    - `message` string, required: Why this node is not accepted as an extract schema.
    - `path` string, required: JSON Pointer of the schema node that failed validation.
  - `normalized_schema` object, nullable: Compiled schema when valid is true. Null when the input was rejected.
  - `valid` boolean, required: True when the schema can be used as an extract schema.

## Other responses

- `504`: Gateway Timeout
- `default`: Typed error envelope used by every 4xx and 5xx. ``error.code`` distinguishes the failure; HTTP status is a consequence of the code.

---

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