---
title: "JSON Schemas"
description: "The zod schemas behind every --json result, and the functions that turn them into the published JSON Schema documents."
type: "reference"
---
# JSON Schemas

The zod schemas behind every --json result, and the functions that turn them into the published JSON Schema documents.

<AvailableFrom version="0.12.0" />

Every `result` the CLI prints under `--json` has a zod 4 schema in the SDK, pinned at compile time to the TypeScript type it describes: the same fields, the same optional fields and the same value types, so a change to one without the other fails the build. Its `parse` also accepts a value from a newer verbatra: it allows fields it does not list and strips them from the result. The same schemas are published as JSON Schema documents; their URLs and the versioning rule are on [Exit codes and JSON output](https://verbatra.kreitz-webdev.de/docs/cli/output.md#schemas).

## Result schemas [#result-schemas]

### runSummarySchema [#runsummaryschema]

Describes a [`RunSummary`](https://verbatra.kreitz-webdev.de/docs/sdk/run-summary.md), the `result` of `translate`, `watch` and `import`. Published as `run-summary.json`.

```ts title="Signature"
const runSummarySchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### checkSummarySchema [#checksummaryschema]

Describes a `CheckSummary`, the `result` of [`check`](https://verbatra.kreitz-webdev.de/docs/sdk/inspect.md#check). Published as `check-summary.json`.

```ts title="Signature"
const checkSummarySchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### checkFileSummarySchema [#checkfilesummaryschema]

Describes a `CheckFileSummary`, the `result` of [`checkFile`](https://verbatra.kreitz-webdev.de/docs/sdk/inspect.md#checkfile). Published as `check-file-summary.json`.

```ts title="Signature"
const checkFileSummarySchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### diffSummarySchema [#diffsummaryschema]

Describes a `DiffSummary`, the `result` of [`diff`](https://verbatra.kreitz-webdev.de/docs/sdk/inspect.md#diff). Published as `diff-summary.json`.

```ts title="Signature"
const diffSummarySchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### doctorResultSchema [#doctorresultschema]

Describes a `DoctorResult`, the `result` of [`doctor`](https://verbatra.kreitz-webdev.de/docs/sdk/inspect.md#doctor). Its `dataFlow` field is [`dataFlowManifestSchema`](https://verbatra.kreitz-webdev.de/docs/sdk/inspect.md#dataflowmanifestschema), so `doctor-result.json` refers to `data-flow-manifest.json` instead of repeating it.

```ts title="Signature"
const doctorResultSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### provenanceReportResultSchema [#provenancereportresultschema]

Describes a `ProvenanceReportResult`, the `result` of [`provenanceReport`](https://verbatra.kreitz-webdev.de/docs/sdk/inspect.md#provenancereport), including the `available: false` variant. Published as `provenance-report.json`.

```ts title="Signature"
const provenanceReportResultSchema: z.ZodUnion<readonly [...]>;
```

### pseudolocalizeResultSchema [#pseudolocalizeresultschema]

Describes a `PseudolocalizeResult`, the `result` of [`pseudolocalize`](https://verbatra.kreitz-webdev.de/docs/sdk/run.md#pseudolocalize). Published as `pseudolocalize-result.json`.

```ts title="Signature"
const pseudolocalizeResultSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### generateTypesResultSchema [#generatetypesresultschema]

Describes a `GenerateTypesResult`, the `result` of [`generateTypes`](https://verbatra.kreitz-webdev.de/docs/sdk/run.md#generatetypes). Published as `generate-types-result.json`.

```ts title="Signature"
const generateTypesResultSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### extractResultSchema [#extractresultschema]

Describes an `ExtractResult`, the `result` of [`extract`](https://verbatra.kreitz-webdev.de/docs/sdk/inspect.md#extract). Published as `extract-result.json`.

```ts title="Signature"
const extractResultSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### exportWorkbookResultSchema [#exportworkbookresultschema]

Describes an `ExportWorkbookResult`, the `result` of [`exportWorkbook`](https://verbatra.kreitz-webdev.de/docs/sdk/exchange.md#exportworkbook). Published as `export-workbook-result.json`.

```ts title="Signature"
const exportWorkbookResultSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### importTmxResultSchema [#importtmxresultschema]

Describes an `ImportTmxResult`, the `result` of [`importTmx`](https://verbatra.kreitz-webdev.de/docs/sdk/exchange.md#importtmx). Published as `import-tmx-result.json`.

```ts title="Signature"
const importTmxResultSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### exportTmxResultSchema [#exporttmxresultschema]

Describes an `ExportTmxResult`, the `result` of [`exportTmx`](https://verbatra.kreitz-webdev.de/docs/sdk/exchange.md#exporttmx). Published as `export-tmx-result.json`.

```ts title="Signature"
const exportTmxResultSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

## Shared schemas [#shared-schemas]

### localeSummarySchema [#localesummaryschema]

Describes a `LocaleSummary`, one entry of a run summary's `locales`.

```ts title="Signature"
const localeSummarySchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### keyProvenanceSchema [#keyprovenanceschema]

Describes a `KeyProvenance`, the recorded origin and review state of one key.

```ts title="Signature"
const keyProvenanceSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### provenanceSummarySchema [#provenancesummaryschema]

Describes a `ProvenanceSummary`, the key counts per origin and per review state a locale of `check` carries.

```ts title="Signature"
const provenanceSummarySchema: z.ZodObject<{ ... }, z.core.$strip>;
```

### keyOriginSchema [#keyoriginschema]

Describes a `KeyOrigin`: who or what wrote a key's current value.

```ts title="Signature"
const keyOriginSchema: z.ZodEnum<{ ... }>;
```

## Stream records [#stream-records]

### progressEventSchema [#progresseventschema]

Describes a `ProgressEvent`, what `onProgress` receives. The CLI prints some of these events to stderr under `--json`. Published as `progress-event.json`.

```ts title="Signature"
const progressEventSchema: z.ZodUnion<readonly [...]>;
```

### lockWaitEventSchema [#lockwaiteventschema]

Describes a `LockWaitEvent`, what `onLockWait` receives while a run waits for a locale's write lock. The CLI prints it to stderr with `type: "lock-wait"` added. Published as `lock-wait-event.json`.

```ts title="Signature"
const lockWaitEventSchema: z.ZodObject<{ ... }, z.core.$strip>;
```

## Publishing [#publishing]

`SDK_JSON_SCHEMAS` lists every document the SDK publishes under `@verbatra/sdk/schemas/`, each with its `name`, `title`, `io` and zod `schema`. `JSON_SCHEMA_BASE_URL` is `https://verbatra.kreitz-webdev.de/schema/v1/`. `KNOWN_ERROR_CODES` lists every SDK, provider and adapter error code; the error envelope schema offers them as a hint while accepting any code.

### renderJsonSchemas [#renderjsonschemas]

Generates verbatra's own JSON Schema documents (draft 2020-12) from a list of `JsonSchemaDocument`s, keyed by name. Each one gets the `$id` that `jsonSchemaUrl` gives its name, a URL on this site, so use it for verbatra's documents only and `renderOutputJsonSchema` for a schema of your own. An output document allows every property it does not list; an input document, such as the config, keeps its closed objects. A schema that embeds a document from either list refers to it by URL.

```ts title="Signature"
function renderJsonSchemas(
  documents: readonly JsonSchemaDocument[],
  references?: readonly JsonSchemaDocument[],
): Readonly<Record<string, JsonSchemaObject>>;
```

**Returns:** one document per entry of `documents`, each with `$schema`, `$id` and `title`.

### renderOutputJsonSchema [#renderoutputjsonschema]

Generates the JSON Schema of one zod schema the way the output documents are generated, without an `$id`, such as for an MCP tool's `outputSchema`.

```ts title="Signature"
function renderOutputJsonSchema(schema: z.ZodType): JsonSchemaObject;
```

**Returns:** `JsonSchemaObject`

### jsonSchemaUrl [#jsonschemaurl]

Returns the public URL of a published document, which is also its `$id`: `jsonSchemaUrl("run-summary")` is `https://verbatra.kreitz-webdev.de/schema/v1/run-summary.json`.

```ts title="Signature"
function jsonSchemaUrl(name: string): string;
```

**Returns:** `string`