Generate Zod validators and TypeScript types from XSD schemas
npm install xsd-zod
> Seamlessly convert XSD (XML Schema Definition) documents into Zod validators and TypeScript types
Transform your XML schemas into type-safe TypeScript code with full runtime validation. xsd-zod parses XSD files and generates both TypeScript interfaces and Zod schemas, enabling you to validate XML payloads with confidence and type safety.
Working with XML APIs and legacy systems often means dealing with XSD schemas. Writing TypeScript types and validation logic by hand is error-prone and tedious. xsd-zod automates this process, giving you:
- Type Safety: Generated TypeScript interfaces that match your XSD exactly
- Runtime Validation: Zod schemas to validate data at runtime
- Maintainability: Regenerate types whenever schemas change
- Flexibility: Support for complex XSD features including nested types, enums, and constraints
- ✅ All common XSD primitive types (string, int, boolean, decimal, date, etc.)
- ✅ Complex types with nested elements and sequences
- ✅ Full attribute support (required, optional, default values)
- ✅ Enumerations converted to TypeScript unions and Zod enums
- ✅ Type facets (minLength, maxLength, pattern, min/max values, totalDigits, etc.)
- ✅ Flexible naming conventions (camel, pascal, original, kebab)
- ✅ Batch processing - handle single files or entire directories
- ✅ Configurable output - separate type/validator files or combined
- ✅ CLI and programmatic API
- ✅ TypeScript-first - fully typed API and generated code
Install globally for CLI usage:
``bash`
npm install -g xsd-zod
Or use as a local dependency:
`bash`
npm install xsd-zodor
pnpm add xsd-zodor
yarn add xsd-zod
Generate types and validators from an XSD file:
`bash`
xsd-zod schema.xsd
This creates schema.types.ts and schema.validators.ts in the ./generated directory.
`typescript
import { compileXsd } from "xsd-zod";
await compileXsd({
input: "schema.xsd",
output: "./generated",
naming: "camel",
separate: true,
});
`
Specify output directory:
`bash`
xsd-zod schema.xsd -o ./src/types
Use Pascal case naming:
`bash`
xsd-zod schema.xsd -n pascal
Generate a single combined file:
`bash`
xsd-zod schema.xsd -c
Process all XSD files in a directory:
`bash`
xsd-zod ./schemas -o ./generated
Batch process multiple schemas:
`typescript
import { compileXsd } from "xsd-zod";
await compileXsd({
input: "./schemas",
output: "./src/validators",
naming: "pascal",
separate: false, // Single file per schema
});
`
Custom naming convention:
`typescript`
await compileXsd({
input: "schema.xsd",
output: "./generated",
naming: "kebab", // kebab-case names
});
| Option | Alias | Description | Default |
| ----------------- | ----- | --------------------------------------------------------- | ------------- |
| --output
| -o | Output directory for generated files | ./generated |
| --naming | -n | Naming convention: camel, pascal, original, kebab | camel |
| --separate | -s | Generate separate type and validator files | true |
| --combined | -c | Generate single combined file | false |🔌 API Reference
$3
Main function to compile XSD files into TypeScript and Zod code.
#### Options
`typescript
interface CompileOptions {
input: string; // Path to XSD file or directory
output: string; // Output directory path
naming?: "camel" | "pascal" | "original" | "kebab"; // Naming convention
separate?: boolean; // Generate separate files (true) or combined (false)
}
`$3
Parse XSD content into an internal schema representation.
$3
Generate TypeScript type definitions from a parsed schema.
$3
Generate Zod validation schemas from a parsed schema.
📋 Supported XSD Features
$3
-
, xs:int, xs:integer, xs:decimal, xs:float, xs:double
- , xs:date, xs:dateTime, xs:time
- , xs:base64Binary, xs:hexBinary
- , xs:nonNegativeInteger, xs:unsignedInt$3
- String constraints:
, maxLength, length, pattern
- Numeric constraints: , maxInclusive, minExclusive, maxExclusive
- Precision: , fractionDigits
- Enumerations: $3
- Element groups:
, choice, all
- Nested elements and recursive types
- Cardinality: , maxOccurs (including unbounded)
- Type extensions: extension and restriction
- Mixed content types$3
- Required and optional attributes (
, use="optional")
- Attribute types and constraints
- Default and fixed values
- Attribute groups💡 Complete Example
Input XSD (
schema.xsd):`xml
`Generated TypeScript Types (
):`typescript
export type StatusType = "active" | "inactive" | "pending";export interface AddressType {
street: string;
city: string;
zipCode?: string;
type: string;
}
export interface UserType {
firstName: string;
lastName: string;
email?: string;
age?: number;
status: StatusType;
address?: AddressType;
id: string;
created?: string;
}
`Generated Zod Validators (
):`typescript
import { z } from "zod";export const StatusTypeSchema = z.enum(["active", "inactive", "pending"]);
export const AddressTypeSchema = z.object({
street: z.string(),
city: z.string(),
zipCode: z.string().optional(),
type: z.string(),
});
export const UserTypeSchema = z.object({
firstName: z.string(),
lastName: z.string(),
email: z.string().optional(),
age: z.number().int().optional(),
status: StatusTypeSchema,
address: AddressTypeSchema.optional(),
id: z.string(),
created: z.string().datetime().optional(),
});
`🧪 Development
bash
Install dependencies
npm installBuild the project
npm run buildRun tests
npm testRun tests in watch mode
npm test -- --watchType check
npm run typecheckBuild in watch mode
npm run dev
`🔨 Advanced Usage
$3
For advanced customization, you can modify the generated code after generation or extend the type mapping in your own code.
$3
The parser handles XML namespaces and preserves namespace information in the generated types where applicable.
$3
Add xsd-zod to your build process:
json
{
"scripts": {
"generate-types": "xsd-zod ./schemas -o ./src/generated",
"build": "npm run generate-types && tsc"
}
}
`🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
1. Fork the repository
2. Create your feature branch (
)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature`)MIT © [Your Name]
- Zod Documentation
- XML Schema Definition (XSD) Specification
- TypeScript Handbook
Found a bug or have a feature request? Please open an issue on the GitHub issue tracker.
---
Made with ❤️ for type-safe XML handling