xschema

This page documents all options for xschema config files.

Config file structure

*.xschema.jsonc / *.jsonc

{
  "$schema": "https://xschema.dev/schemas/{language}.jsonc",
  "namespace": "optional-override",
  "schemas": [
    {
      "id": "SchemaName",
      "sourceType": "file" | "url" | "json",
      "source": "...",
      "adapter": "<package-name>",
      "headers": { ... }
    }
  ]
}

Required: `$schema`

The $schema URL is required - xschema uses it to discover config files in your project and determine the target language.

{
  "$schema": "https://xschema.dev/schemas/{language}.jsonc"
}

Without this URL, xschema won't recognize the file as a config file and will skip it.

Schema URL reference

Language	URL
TypeScript	`https://xschema.dev/schemas/typescript.jsonc`
Python	`https://xschema.dev/schemas/python.jsonc` (coming soon)

Namespace

The namespace groups related schemas together. It defaults to the filename (without extension).

Default behavior

Filename	Namespace
`user.xschema.jsonc`	`user`
`api.xschema.json`	`api`
`models.jsonc`	`models`

Explicit override

Override the default with the namespace field:

{
  "$schema": "https://xschema.dev/schemas/{language}.jsonc",
  "namespace": "my-custom-namespace",
  "schemas": [...]
}

Multiple config files

You can have multiple config files in your project:

project/
  user.xschema.jsonc      # namespace: user
  api.xschema.jsonc       # namespace: api
  subdir/
    models.xschema.jsonc  # namespace: models

All are merged into a single output. Duplicate IDs within the same namespace cause an error:

duplicate schema ID "User" in namespace "user": defined in both user.xschema.jsonc and models.xschema.jsonc

Schemas array

The schemas array defines each schema to generate.

Required fields

Field	Type	Description
`id`	string	Unique identifier within the namespace
`sourceType`	`"file"` \| `"url"` \| `"json"`	How to retrieve the schema
`source`	string \| object	The schema source (format depends on sourceType)
`adapter`	string	Adapter package name (e.g., `"@xschemadev/zod"`)

Optional fields

Field	Type	Description
`headers`	object	HTTP headers for URL sources (supports `${VAR}` syntax)

Source types

`file` - Local file

Load a JSON Schema from a file path relative to the config file:

{
  "id": "User",
  "sourceType": "file",
  "source": "./schemas/user.json",
  "adapter": "@xschemadev/zod"
}

File paths are always relative to the config file's directory, not the current working directory.

`url` - Remote URL

Fetch a JSON Schema from a URL:

{
  "id": "TSConfig",
  "sourceType": "url",
  "source": "https://json.schemastore.org/tsconfig.json",
  "adapter": "@xschemadev/zod"
}

URL sources support:

Automatic retries (3 attempts by default)
Caching to avoid redundant fetches
Custom headers (see below)

`json` - Inline schema

Embed the JSON Schema directly in the config file:

{
  "id": "Fruit",
  "sourceType": "json",
  "source": {
    "type": "object",
    "properties": {
      "name": { "type": "string" },
      "color": { "type": "string" }
    },
    "required": ["name"]
  },
  "adapter": "@xschemadev/zod"
}

Inline schemas are useful for simple schemas or when you want everything in one file.

Headers and environment variables

For URL sources, you can specify HTTP headers:

{
  "id": "PrivateSchema",
  "sourceType": "url",
  "source": "https://api.example.com/schemas/user",
  "adapter": "@xschemadev/zod",
  "headers": {
    "Authorization": "Bearer ${API_TOKEN}",
    "X-Api-Key": "${API_KEY}"
  }
}

Environment variable substitution

Header values support ${VAR} syntax for environment variables:

Variables are read from the environment
xschema auto-loads .env files in the project root
Use --env-file to specify a custom env file

# Uses .env in project root
xschema generate

# Uses custom env file
xschema generate --env-file .env.production

If a referenced variable is missing:

missing env var: API_TOKEN. use --env-file to specify env file

Headers are only allowed for sourceType: "url". Using headers with file or json sources causes an error:

headers are only allowed for sourceType "url"

Adapters

The adapter field specifies which validation library to generate code for. The value is the adapter's package name (e.g., @xschemadev/zod).

See Adapters for the full list of available adapters.

Using multiple adapters

You can use different adapters for different schemas in the same config file:

{
  "$schema": "https://xschema.dev/schemas/{language}.jsonc",
  "schemas": [
    {
      "id": "UserZod",
      "sourceType": "file",
      "source": "./user.json",
      "adapter": "@xschemadev/zod"
    },
    {
      "id": "UserArkType",
      "sourceType": "file",
      "source": "./user.json",
      "adapter": "@xschemadev/arktype"
    }
  ]
}

Complete example