Metadata Schemas

Declare a metadata schema

Declares what metadata must satisfy for one resource type under one selector. A document is selected by path_prefix, matched on a path boundary: /reports covers /reports/q1.txt and never /reports-archive/q1.txt.

The schema is compiled here, so one JSON Schema cannot parse is refused rather than stored — a stored one would be a rule that silently governs nothing. One selector has one schema per resource type; a second declaration of the same one is 409 NAME_CONFLICT. The reserved root /.system cannot be governed: a platform-written document carries no caller metadata.

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

Request

  • Base URL: https://api.naturali.ai
  • URL: https://api.naturali.ai/v1/projects/{project_id}/metadata-schemas
  • 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

resource_type'document' required

The resource whose metadata this declaration governs. A type appears here once its write path reads the registry, so a declaration always has a door that enforces it.

path_prefixstring

The selector a document declaration must carry: the directory it governs.

schemaobject required

A JSON Schema. Its keywords are its own vocabulary and are stored as written.

Example request

{
  "resource_type": "document",
  "path_prefix": "/reports",
  "schema": {
    "type": "object",
    "required": [
      "quarter"
    ],
    "properties": {
      "quarter": {
        "type": "string"
      }
    }
  }
}

Response

The declaration

idstring

Public ID (mdschema_ prefix)

project_idstring
resource_type'document'

The resource whose metadata this declaration governs.

path_prefixstring

The selector, in the field its resource type is addressed by. A document's is the directory it is filed under.

schemaobject

The declared JSON Schema, as written.

created_atstring date-time
updated_atstring date-time

Example response

{
  "id": "mdschema_V1StGXR8Z5jdHi6B",
  "project_id": "proj_V1StGXR8Z5jdHi6B",
  "resource_type": "document",
  "path_prefix": "/reports",
  "schema": {
    "type": "object",
    "required": [
      "quarter"
    ],
    "properties": {
      "quarter": {
        "type": "string"
      }
    }
  },
  "created_at": "2024-01-01T00:00:00.000Z",
  "updated_at": "2024-01-01T00:00:00.000Z"
}

Changes

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