> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hyperterse.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration schemas

> JSON Schema files for editor-time validation of .hyperterse and .terse configuration files.

Hyperterse ships seven role-based JSON Schema files for editor-time validation, autocompletion, and inline documentation.

| Schema file                         | Target files                    | Purpose                                 |
| ----------------------------------- | ------------------------------- | --------------------------------------- |
| `schema/root.terse.schema.json`     | `.hyperterse`                   | Root service configuration              |
| `schema/adapter.terse.schema.json`  | `app/adapters/*.terse`          | Adapter definitions                     |
| `schema/tool.terse.schema.json`     | `app/tools/*/config.terse`      | Tool definitions                        |
| `schema/agent.terse.schema.json`    | `app/agents/*/config.terse`     | Agent definitions                       |
| `schema/prompt.terse.schema.json`   | `app/prompts/**/*.terse`        | Prompt definitions                      |
| `schema/resource.terse.schema.json` | `app/resources/**/config.terse` | Resource and resource-template settings |

## Generation

Schemas are generated from the project’s source schema definitions:

```bash theme={null}
make generate
```

The generator reads connector and primitive type enums and emits JSON Schema files with the correct `enum` constraints.

## Editor setup

Point your editor at the schema files to enable autocompletion, hover docs, and inline validation for `.terse` files.

### VS Code / Cursor

Add to `.vscode/settings.json`:

```json theme={null}
{
  "yaml.schemas": {
    "schema/root.terse.schema.json": "**/.hyperterse",
    "schema/adapter.terse.schema.json": "**/adapters/*.terse",
    "schema/tool.terse.schema.json": "**/tools/**/config.terse",
    "schema/agent.terse.schema.json": "**/agents/**/config.terse",
    "schema/prompt.terse.schema.json": "**/prompts/**/*.terse",
    "schema/resource.terse.schema.json": "**/resources/**/config.terse"
  }
}
```

Requires the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml).

### JetBrains IDEs

In the IDE: Settings → Languages & Frameworks → Schemas and DTDs → JSON Schema Mappings. Add one mapping per schema with the appropriate file pattern.

## Schema highlights

Each schema enforces required fields, value constraints, and structural rules for its configuration level.

### Root (`root.terse.schema.json`)

* `name` — Required. Pattern: `^[a-z][a-z0-9_-]*$`.
* `version` — Optional string.
* `root` — String (default discovery root: `app`).
* `tools.directory` — String (default: `tools`).
* `tools.cache` — `enabled` (boolean), `ttl` (integer).
* `tools.search.limit` — Integer (default: `10`) controlling max MCP `search` results.
* `adapters.directory` — String (default: `adapters`).
* `prompts` — Either:
  * `{ directory: string }` discovery config (default: `prompts`), or
  * inline prompt definitions array.
* `resources` — Either:
  * `{ directory: string }` discovery config (default: `resources`), or
  * inline concrete resource definitions array.
* `resource_templates` — Optional inline resource-template definitions array.
* `agents.directory` — String (default: `agents`).
* `agents.tool_access.mode` — Enum: `allow_all`, `allow_none`, `allow_list`.
* `agents.tool_access.tools` — Array of tool names; required when `mode=allow_list`.
* `server.port` — Integer or string.
* `server.log_level` — Integer, 1–4.
* `build.out` / `build.out_dir` — String.
* `build.clean_dir` — Boolean.

### Adapter (`adapter.terse.schema.json`)

* `connector` — Required. Enum: `postgres`, `redis`, `mysql`, `mongodb`, `sqlite`.
* `connection_string` — Required string.
* `name` — Optional.
* `options` — Optional map.

### Tool (`tool.terse.schema.json`)

* `description` — Required string.
* `use` — String.
* `statement` — String.
* `inputs` — Map of typed definitions.
* `handler` — Optional script handler path (`path#exportName` supported; defaults to `export default`).
* `mappers` — Optional `input` / `output` mapper paths (`path#exportName` supported; defaults to `export default`).
* `auth` — `plugin`, `policy`.
* `cache` — `enabled`, `ttl`.
* Constraint: exactly one of `use` or `handler` is required (enforced via `oneOf`).

### Prompt (`prompt.terse.schema.json`)

* `name` — Optional prompt name override (defaults to filename).
* `title` — Optional string.
* `description` — Optional string.
* `arguments` — Optional map keyed by argument name with:
  * `title` (string)
  * `description` (string)
  * `required` (boolean)
  * `completion` (string array)
* `messages` — Required non-empty array of `{ role, text }` where role is one of `user`, `assistant`, `system`.

See [Prompt configuration](/reference/prompt-config).

### Resource (`resource.terse.schema.json`)

* Supports both concrete resources and URI templates in one schema.
* Shared optional fields: `name`, `title`, `description`, `mime_type`.
* Concrete resource mode:
  * `uri` (required)
  * one of `text` or `file` (required)
* Resource template mode:
  * `uri_template` (required)
  * one of `text_template` or `file_template` (required)
  * optional `arguments` map keyed by argument name with:
    * `title` (string)
    * `description` (string)
    * `required` (boolean)
    * `completion` (string array)

See [Resource configuration](/reference/resource-config).

### Agent (`agent.terse.schema.json`)

* `name` — Required string. Pattern: `^[a-z][a-z0-9_-]*$`.
* `description` — Optional string.
* `instruction` — Required string.
* `model.provider` — Required string provider identifier.
* `model.model` — Required provider-specific model name.
* `model.options` — Optional scalar map (`string`/`number`/`boolean`) for provider options.
* `tool_access` — Optional object. Defaults to `inherit` when omitted.
* `tool_access.mode` — Enum: `inherit`, `allow_all`, `allow_none`, `allow_list`.
* `tool_access.tools` — Optional array of tool names, required when `mode=allow_list`.

## Role ownership

* Root scope (`.hyperterse`) owns service-level defaults and discovery wiring (`root`, `tools`, `adapters`, `prompts`, `resources`, `agents`, and optional inline `resource_templates`).
* Adapter scope (`app/adapters/*.terse`) owns connector and connection configuration.
* Tool scope (`app/tools/**/config.terse`) owns execution/query behavior and auth/cache controls.
* Prompt scope (`app/prompts/**/*.terse`) owns MCP prompt messages and arguments.
* Resource scope (`app/resources/**/config.terse`) owns MCP resources and URI templates.
* Agent scope (`app/agents/**/config.terse`) owns agent behavior: `instruction`, model, and tool access policy.

## Keeping schemas in sync

When configuration shapes change, schemas and documentation must update in the same change:

1. Regenerate schema artifacts in `schema/`.
2. Update field definitions in reference documentation.
3. Update `.vscode/settings.json` globs if file-role matching changed.
4. Verify checklists/reference docs include all current schema files:
   * `root.terse.schema.json`
   * `adapter.terse.schema.json`
   * `tool.terse.schema.json`
   * `agent.terse.schema.json`
   * `prompt.terse.schema.json`
   * `resource.terse.schema.json`