Schema Validation — MDDB API

JSON Schema validation for metadata

Set collection schema #

POST /v1/schema/set

Set a JSON Schema for a collection's metadata validation. This is a write-protected endpoint.

Once set, all documents added to the collection will have their metadata validated against this schema.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: SetSchemaRequest

{
  "collection": "blog",
  "schema": "{\"required\":[\"author\"],\"properties\":{\"author\":{\"type\":\"string\"},\"category\":{\"type\":\"string\",\"enum\":[\"blog\",\"tutorial\"]}}}"
}

Responses #

Status	Description	Body
200	Schema set successfully	object (application/json)
400	Invalid request	ErrorResponse (application/json)
403	Read-only mode	ErrorResponse (application/json)

Get collection schema #

POST /v1/schema/get

Retrieve the JSON Schema currently set for a collection.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
collection (required)	string	Collection name

{
  "collection": "blog"
}

Responses #

Status	Description	Body
200	Schema retrieved successfully	SchemaResponse (application/json)
400	Invalid request	ErrorResponse (application/json)

Delete collection schema #

POST /v1/schema/delete

Remove the JSON Schema for a collection, disabling metadata validation. This is a write-protected endpoint.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: object

Property	Type	Description
collection (required)	string	Collection name

{
  "collection": "blog"
}

Responses #

Status	Description	Body
200	Schema deleted successfully	object (application/json)
400	Invalid request	ErrorResponse (application/json)
403	Read-only mode	ErrorResponse (application/json)

List all schemas #

POST /v1/schema/list

List all JSON Schemas set across all collections.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Content type application/json: object

Responses #

Status	Description	Body
200	List of schemas	object (application/json)
401	Auth is on (MDDB_AUTH_ENABLED=true) and the request carries no credentials, an invalid or expired JWT, or an unknown API key.	ErrorResponse (application/json)
403	The caller lacks the permission the route needs (SEC-019 access gate, auth on: read, write or admin on the collections the request names), or a write meets read-only mode (MDDB_MODE=read or the protocol's own mode).	ErrorResponse (application/json)
429	The client is over the API rate limit (MDDB_RATE_LIMIT_ENABLED=true, MDDB_RATE_LIMIT_REQUESTS per MDDB_RATE_LIMIT_WINDOW seconds). A call that embeds can also be refused by the collection's daily embedding budget, with a QuotaExceeded body.	RateLimitError (application/json)

401 example (application/json)

{
  "error": "missing authentication"
}

403 example (application/json)

{
  "error": "forbidden"
}

Validate metadata against schema #

POST /v1/validate

Validate a metadata object against the JSON Schema set for a collection.

This is a dry-run validation that does not modify any data. Useful for pre-validating metadata before adding a document.

Authorization: BearerAuth or APIKeyAuth or none

Request body #

Required.

Content type application/json: ValidateRequest

{
  "collection": "blog",
  "meta": {
    "author": [
      "John Doe"
    ],
    "category": [
      "blog"
    ]
  }
}

Responses #

Status	Description	Body
200	Validation result	ValidateResponse (application/json)
400	Invalid request	ErrorResponse (application/json)