# Document Schemas

Schemas define the metadata field structure for a Document Type — specifying which fields
should be present, their data types, display labels, and validation rules (required, allowed
values, min/max constraints). The platform stores metadata as schemaless name/value pairs
at the document layer, but schemas allow you to enforce structure when needed.

**Schema types:**

| SchemaType | Description |
|---|---|
| `ROOT` | Top-level schema attached directly to a Document Kind |
| `SUB` | Nested schema for structured sub-objects within a document |
| `TRAIT` | Schema associated with a behavioral trait (e.g., SUMMARY, TIMELINE) |

**Available field types:**

| Field Type | Description |
|---|---|
| `string` | Plain text value |
| `integer` | Whole number |
| `number` | Floating point number |
| `bool` | Boolean true/false |
| `date` | ISO 8601 date or datetime |
| `array` | List of values — element type can be `string`, `integer`, `number`, `bool`, or `date` |
| `object` | Nested JSON object (references a `SUB` schema) |
| `link` | Edge to another document; has a `cardinality` (`ONE_TO_ONE`, `ONE_TO_MANY`, `MANY_TO_ONE`, `MANY_TO_MANY`) |
| `ref` | Read-only reference to a field on a linked document |
| `computed` | Derived field calculated from other field values |

**Schema operations:**
- `create-schema` — define a new schema and attach it to a kind
- `update-schema` — revise field definitions; changes apply to subsequent document writes
- `retrieve-schema / list-schema` — inspect field definitions for a given kind
- `delete-schema` — remove a schema, returning the kind to free-form metadata mode


## Get a metadata schema

 - [POST /api/v1/schema/retrieve-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.retrieveschema.md): Retrieves full document schema definitions by their IDs.

Request:
ids       - List of schema IDs to retrieve.

Response:
schemas   - List of DocumentSchema objects with the full field definitions.

## Search document schemas

 - [POST /api/v1/schema/list-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.listschema.md): Lists all document schemas as lightweight summaries with optional cursor-based pagination.

Request:
pagination   - Optional Pagination cursor and page size.

Response:
schemas       - List of DocumentSchemaSummary objects.
pageCursor   - Opaque cursor for the next page. Absent when there are no further results.

## Create a metadata schema

 - [POST /api/v1/schema/create-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.createschema.md): Creates one or more new document schemas.

Request:
schemas   - List of CreateDocumentSchema definitions to create.

Response:
schemas   - List of DocumentSchemaSummary objects for the created schemas.

## Update a metadata schema

 - [POST /api/v1/schema/update-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.updateschema.md): Updates one or more existing document schemas by their IDs.

Request:
schemas   - List of UpdateDocumentSchema payloads, each identifying a schema by ID and
providing the replacement field definitions.

Response:
ids   - List of schema IDs that were successfully updated.

## Delete a metadata schema

 - [POST /api/v1/schema/delete-schema](https://api.tenovos.com/openapi/content-intelligence/document-schemas/tenovos.document.schemaservice.deleteschema.md): Permanently deletes one or more document schemas by their IDs.

Request:
ids   - List of schema IDs to permanently delete.

Response:
ids   - List of schema IDs that were successfully deleted.