langium-zod

Remarks

langium-zod — generate Zod validation schemas from Langium grammar definitions.

Before generating, ask:

• Recursive rules? Grammar rules that reference themselves (e.g. Expression: ... | left=Expression) require cycle detection. generateZodSchemas handles this automatically via detectRecursiveTypes, but if you build a custom pipeline you must run detection on the full descriptor set before any projection.
• Cross-references? Langium ref: properties become ReferenceSchema by default. Enable crossRefValidation: true only when you have a live document model to validate against at runtime; otherwise every cross-ref property will emit an unconstrained ReferenceSchema.
• Discriminated unions? Every Langium union type (e.g. Expression = Literal | BinaryExpr) maps to a Zod discriminated union keyed on $type. All member types must be emitted — use include with care when union types are involved.
• Grammar changes? Generated schemas are compile-time artifacts. Any grammar edit (new rule, renamed property, changed cardinality) requires regeneration. Wire langium-zod generate into your build step so stale schemas are caught early.
• AST imports path? The conformance artifact imports from your grammar's ast.ts. If the generated file moves, update conformance.astTypesPath to point to the new location or import errors will appear at compile time.

Entry points:

• generateZodSchemas — main programmatic API (grammar → TypeScript source string)
• generateZodCode — low-level emitter operating on pre-built descriptors
• extractTypeDescriptors — extracts the descriptor tree from AstTypesLike
• detectRecursiveTypes — identifies reference cycles before code generation
• zRef — cross-reference validation helper for generated schema factories
• ZodSchemaGeneratorModule — Langium DI module for service-based integration

Analysis

Name	Description
AstTypesLike	Duck-typed representation of the type model returned by Langium's collectAst() function. Holds the full set of interface types and union/datatype-rule types that the extractor analyses to produce ZodTypeDescriptor records.
InterfaceTypeLike	Duck-typed representation of a Langium InterfaceType, carrying only the fields that langium-zod needs. Using this abstraction instead of Langium's concrete class keeps the extractor decoupled from Langium's internal AST model and makes unit testing easier via plain object stubs.
ZodTypeDescriptor	Union of all type descriptor shapes that the extractor can produce and the code generator can consume. Each variant carries a discriminating kind field: 'object', 'union', 'primitive-alias', 'keyword-enum', or 'regex-enum'.
ZodTypeExpression	A discriminated union that represents a single Zod type node in the descriptor tree produced by the extractor and consumed by the code generator.
detectRecursiveTypes	Detects type names that participate in a reference cycle across the descriptor graph.
extractTypeDescriptors	Extracts ZodTypeDescriptor records from a Langium grammar's type model.

Configuration

Name	Description
FilterConfig	Include/exclude filter that controls which Langium type names are emitted during schema generation.
ZodGeneratorConfig	Full configuration object for generateZodSchemas.
DEFAULT_OUTPUT_PATH	Default output path used when no explicit outputPath is provided and the project's langium-config.json does not declare an out directory.

DI

Name	Description
DefaultZodSchemaGenerator	Default implementation of ZodSchemaGenerator.
ZodSchemaGenerator	Service interface for generating Zod schemas from a parsed Langium grammar.
ZodSchemaGeneratorServices	Langium DI service container shape for the langium-zod extension.
ZodSchemaGeneratorModule	Langium Module definition that registers DefaultZodSchemaGenerator under shared.ZodSchemaGenerator in the Langium DI container.

Generation

Name	Description
ZodGeneratorError	Custom error class thrown by the langium-zod code generator when it encounters a condition it cannot recover from.
generateZodCode	Generates a TypeScript source string containing Zod schema exports for all provided type descriptors.
generateZodSchemas	Main entry point for programmatic Zod schema generation from a Langium grammar.
zRef	Creates a Zod string schema that validates a cross-reference value against an allowlist of known identifiers, evaluated lazily at parse time.

Other

Name	Description
GenerateOptions	Options accepted by the programmatic generate function.
LangiumZodConfig	User-facing config file shape (langium-zod.config.js / .ts)
PropertyLike	Duck-typed representation of a single property within a Langium InterfaceType.
UnionTypeLike	Duck-typed representation of a Langium UnionType (including datatype rules that alias primitives or terminal regex patterns). The type field holds the raw Langium type-model node and is inspected structurally by the extractor to classify the union as a keyword-enum, regex-enum, discriminated-union, or primitive alias.
ZodPropertyDescriptor	Describes a single property of a Langium interface type after extraction, capturing all information the code generator needs to emit a Zod property expression.
generate	Programmatic entry point for the langium-zod generate command.