Metadata Schemas

A declaration of what a resource's metadata must satisfy: one JSON Schema per resource type and selector, enforced by the resource's own write path.

Overview

A document filed under a governed directory must carry metadata the directory's schema accepts. The check sits in the document's own write path, so it holds for every route a write can come through: create, update, restore and a formation apply alike. A write that violates it is refused with 400 VALIDATION_FAILED, and nothing is stored.

Documents are the only governed resource type. A path_prefix matches on a path boundary: /reports governs /reports/q1.txt and never /reports-archive/q1.txt. The reserved /.system root cannot be governed.

This module is a verbatim mirror of the runtime: every field, method, status code and error shape is the runtime's own, re-rooted under the project in the path.

See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Metadata Schemas.

Data Model

MetadataSchema

Field	Type	Description
`id`	string	Public ID (`mdschema_` prefix).
`project_id`	string	The project the declaration governs.
`resource_type`	string	The governed resource: `document`. Fixed at creation.
`path_prefix`	string	The directory a `document` declaration governs.
`schema`	object	The declared JSON Schema, stored as written.
`created_at`	string (date-time)
`updated_at`	string (date-time)

Key Concepts

A declaration governs writes, not rows

The schema is compiled when declared, so one that cannot compile is refused rather than stored. One selector has one schema per resource type; declaring a second is 409 NAME_CONFLICT.

Documents already stored are not re-judged. A declaration applies to a document the next time its path or metadata is written. Deleting a declaration leaves every stored document's metadata as it is.

resource_type cannot be changed by an update, because it decides which write path reads the declaration. To govern a different type, delete the declaration and declare again.

Checking before writing

POST /v1/projects/{project_id}/metadata-schemas/validate answers what a write at a path would be told, without writing: valid, the refusing declaration's metadata_schema_id and path_prefix, and the violation in error. It reports and never enforces; the refusal is the write path's.

Who may do what

Every route needs any project member.

Examples

Declare a schema for a directory

CLI
SDK
curl

naturali create-metadata-schema \
  --project-id proj_V1StGXR8Z5jdHi6B \
  --resource-type document \
  --path-prefix /reports \
  --schema '{ "type": "object", "required": ["quarter"], "properties": { "quarter": { "enum": ["Q1", "Q2", "Q3", "Q4"] } } }'

const { data: metadataSchema } =
  await naturali.metadataSchemas.createMetadataSchema({
    path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
    body: {
      resource_type: 'document',
      path_prefix: '/reports',
      schema: {
        type: 'object',
        required: ['quarter'],
        properties: { quarter: { enum: ['Q1', 'Q2', 'Q3', 'Q4'] } },
      },
    },
  });

curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/metadata-schemas \
  -H "Authorization: Bearer $NATURALI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "document",
    "path_prefix": "/reports",
    "schema": {
      "type": "object",
      "required": ["quarter"],
      "properties": { "quarter": { "enum": ["Q1", "Q2", "Q3", "Q4"] } }
    }
  }'

Check metadata before a write

CLI
SDK
curl

naturali validate-metadata \
  --project-id proj_V1StGXR8Z5jdHi6B \
  --path /reports/q1.txt \
  --metadata '{ "quarter": "Q5" }'

const { data: verdict } = await naturali.metadataSchemas.validateMetadata({
  path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
  body: { path: '/reports/q1.txt', metadata: { quarter: 'Q5' } },
});

curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/metadata-schemas/validate \
  -H "Authorization: Bearer $NATURALI_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "path": "/reports/q1.txt", "metadata": { "quarter": "Q5" } }'

List the declarations in a project

CLI
SDK
curl

naturali list-metadata-schemas \
  --project-id proj_V1StGXR8Z5jdHi6B \
  --resource-type document

const { data: metadataSchemas } =
  await naturali.metadataSchemas.listMetadataSchemas({
    path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
    query: { resource_type: 'document' },
  });

curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/metadata-schemas?resource_type=document" \
  -H "Authorization: Bearer $NATURALI_TOKEN"

Overview​

Data Model​

MetadataSchema​

Key Concepts​

A declaration governs writes, not rows​

Checking before writing​

Who may do what​

Examples​

Declare a schema for a directory​

Check metadata before a write​

List the declarations in a project​