Metadata Schemas

Check metadata against what is declared

Answers what a write would be told, without writing: a caller preparing a batch learns which declaration would refuse it, and why, before it sends anything.

It reports; it does not enforce. The refusal itself lives in each resource's own write path, because a check a writer has to call is advisory and the writer who skips it is the one the rule exists for.

post/v1/projects/{project_id}/metadata-schemas/validate

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/metadata-schemas/validate
  • Auth: one of:
    • HTTP bearer
    • OAuth 2 (authorization code, authorization URL https://api.naturali.ai/authorize, token URL https://api.naturali.ai/token, scopes: mcp:access)

Request body

pathstring required

The path the document would be filed at, which decides which declaration governs it.

metadataNullableMetadataBag nullable

A MetadataBag on a request field where null is meaningful: a full-replacement update that clears the bag. A record whose bag is unset leaves the field out.

Example request

{
  "path": "/reports/q1.txt",
  "metadata": {
    "author": "John",
    "revision": 2
  }
}

Response

The verdict

validboolean required

Whether a write of this metadata at this path would be accepted.

resource_type'document' required
metadata_schema_idstring nullable required

The declaration that would refuse it; null when the metadata is accepted or nothing governs the path.

path_prefixstring nullable required

The refusing declaration's selector.

Example response

{
  "resource_type": "document",
  "metadata_schema_id": "mdschema_V1StGXR8Z5jdHi6B",
  "path_prefix": "/reports",
  "error": {
    "code": "AI_PROVIDER_ERROR",
    "message": "Provider returned 402: insufficient credits"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.