Skip to content

MTHDS JSON Schema

The MTHDS standard includes a machine-readable JSON Schema that describes the structure of .mthds files. Tools and editors can use this schema for validation, autocompletion, and documentation.

What It Covers

The schema defines the complete structure of an .mthds bundle:

  • Header fields: domain, description, system_prompt, main_pipe.
  • Concept definitions: both simple (string) and structured forms, including structure fields, refines, and all field types (text, integer, number, boolean, date, datetime, time, list, dict, concept) and the choices enum mechanism.
  • Pipe definitions: all concrete pipe types with their specific fields — PipeLLM, PipeStructure, PipeFunc, PipeImgGen, PipeExtract, PipeSearch, PipeJudge, PipeDocGen, PipeCompose, PipeSequence, PipeParallel, PipeCondition, PipeBatch — plus contract-only PipeSignature sections where type is omitted. Every inputs table accepts only plain input names, matching [a-z][a-z0-9_]*.
  • Sub-pipe blueprints: the steps, branches, outcomes, and construct structures used by controllers and PipeCompose. A sequence step is either a pipe step or a binding step (from and result), while a parallel branch is always a pipe step whose batch_over is a plain name.
  • Inline model settings: the LLMSetting, ImgGenSetting, ExtractSetting, SearchSetting, JudgmentSetting, and DocGenSetting objects that can be used in place of string model references.

Schema Version

The schema is generated from the bundle data model of the reference implementation, and its $comment field names the implementation version it was generated from. The hosted schema is refreshed from a release of the reference implementation, and a release of the standard that changes the language usually comes before the implementation release that carries the change. Until that implementation release is published and the refreshed schema reaches this site, the hosted schema still describes the previous standard and may reject what the new one allows. The changelog entry of such a release says which of its changes the hosted schema does not describe yet, and a later release of this site publishes the schema that does.

Where to Find It

The schema is distributed with the tools that use it:

  • VS Code extension — the Pipelex extension bundles the schema and uses it for autocompletion and inline validation.
  • plxt CLI — the plxt binary includes the schema for local validation.
  • pipelex-tools PyPI package — the schema is included in the Python distribution.

The schema is also hosted at a stable URL for direct use by editors and other tooling:

Hosted URL: https://mthds.ai/mthds_schema.json

How to Use It

With the VS Code Extension

The Pipelex VS Code extension includes the schema and uses it automatically for autocompletion and inline validation of .mthds files. No configuration is required.

With Other Editors

Any editor that supports JSON Schema for TOML can use the MTHDS schema. Configure your editor's TOML language server to associate .mthds files with the schema URL https://mthds.ai/mthds_schema.json.

For Tooling

The schema can be used programmatically for:

  • Building custom validators for .mthds files.
  • Generating documentation from the schema structure.
  • Implementing autocompletion in non-VS Code editors.

For detailed guidance on building editor support, see For Implementers: Building Editor Support.