With Zod:
`typescript
import { z } from 'zod';

export const UserSchema = z.object({
id: z.string().uuid(),
email: z.string().email(),
name: z.string(),
age: z.number().optional(),
createdAt: z.string().datetime().optional(),
});

export type User = z.infer;

// Runtime validation
const user = UserSchema.parse(apiResponse); // ✅ Type-safe!
`

With io-ts:
`typescript
import * as t from 'io-ts';
import { DateFromISOString } from 'io-ts-types';

export const User = t.intersection([
t.type({
id: t.string,
email: t.string,
name: t.string,
}),
t.partial({
age: t.number,
createdAt: DateFromISOString,
})
]);

export interface User extends t.TypeOf {}

// Runtime validation with detailed errors
const result = User.decode(apiResponse);
if (isRight(result)) {
const user: User = result.right; // ✅ Type-safe!
}
`

🎨 Real-World Usage

$3

function validateForm(formData: unknown) {
const result = UserFormSchema.safeParse(formData);
return result.success ? result.data : result.error;
}
`

$3

Create dtoforge.config.yaml:

`yaml


Output configuration

#### Configuration:
`yaml
exclude:
exact:
- "InternalSchema"
- "DeprecatedUser"
startsWith:
- "Debug"
- "_"
endsWith:
- "Internal"
- "Request"
contains:
- "Test"
- "Mock"
`

#### Matching Rules:

| Rule | Description | Example Pattern | Matches |
|------|-------------|-----------------|---------|
| exact | Exact name match | "InternalSchema" | InternalSchema only |
| startsWith | Prefix match | "Debug" | DebugUser, DebugConfig |
| endsWith | Suffix match | "Internal" | UserInternal, ConfigInternal |
| contains | Substring match | "Test" | TestUser, UserTest, MyTestData |

#### Example Use Cases:

Exclude internal/private schemas:
`yaml
exclude:
endsWith:
- "Internal"
- "Private"
`

Exclude test and mock schemas:
`yaml
exclude:
contains:
- "Test"
- "Mock"
- "Stub"
`

Exclude specific legacy schemas:
`yaml
exclude:
exact:
- "LegacyUser"
- "DeprecatedOrder"
startsWith:
- "V1_" # Old API version prefixes
`

When schemas are excluded, DtoForge will log them:
`
📝 Excluded 3 schemas: [DebugConfig, TestUser, InternalData]
`

---

$3

When DtoForge encounters a property without a recognized type, it generates t.unknown by default. You can customize this behavior using the defaultUnknownType configuration option.

#### Configuration:
`yaml
generation:
defaultUnknownType: "t.unknownRecord" # Use t.unknownRecord instead of t.unknown
`

#### Common Values:

| Value | Description | Use Case |
|-------|-------------|----------|
| t.unknown | Any value (default) | General purpose, most flexible |
| t.unknownRecord | Object with unknown values | When you expect objects but don't know the shape |
| t.record(t.string, t.unknown) | String-keyed record | Explicit record type |

#### Example:

OpenAPI Schema:
`yaml
components:
schemas:
Config:
type: object
properties:
settings:
description: Dynamic settings object
# No type specified
`

With default (t.unknown):
`typescript
export const Config = t.partial({
settings: t.unknown,
})
`

With defaultUnknownType: "t.unknownRecord":
`typescript
export const Config = t.partial({
settings: t.unknownRecord,
})
`

---

$3

DtoForge supports the x-nullable OpenAPI extension to explicitly mark fields as nullable, providing more precise type generation than the standard nullable property.

Supported in both io-ts and Zod generators.

#### Usage in OpenAPI Schema:
`yaml
components:
schemas:
User:
type: object
required: [id, email]
properties:
id:
type: string
email:
type: string
x-nullable: true # Email is required but can be null
phone:
type: string
x-nullable: false # Explicitly not nullable (optional)
address:
type: string # Regular optional field
`

#### Configuration:

Configure x-nullable behavior in your config file:
`yaml
extensions:
x-nullable:
enabled: true # Enable/disable x-nullable processing (default: true)
behavior: "null" # "null" | "undefined" | "nullish"
`

#### Behavior Options:

| Behavior | Description | io-ts Output | Zod Output |
|----------|-------------|--------------|------------|
| "null" (default) | Field can be null | t.union([T, t.null]) | .nullable() |
| "undefined" | Field becomes optional | Moves to t.partial | .optional() |
| "nullish" | Both null and optional | In t.partial with t.union([T, t.null]) | .nullable().optional() |

#### Generated Output Examples:

With behavior: "null" (default)
`typescript
// io-ts
export const User = t.intersection([
t.type({
id: t.string,
email: t.union([t.string, t.null]), // Required but nullable
}),
t.partial({ phone: t.string, address: t.string })
])

// Zod
export const UserSchema = z.object({
id: z.string(),
email: z.string().nullable(), // Required but nullable
phone: z.string().optional(),
address: z.string().optional(),
});
`

With behavior: "undefined"
`typescript
// io-ts
export const User = t.intersection([
t.type({ id: t.string }),
t.partial({
email: t.string, // Moved to partial (optional)
phone: t.string,
address: t.string
})
])

// Zod
export const UserSchema = z.object({
id: z.string(),
email: z.string().optional(), // Made optional by x-nullable
phone: z.string().optional(),
address: z.string().optional(),
});
`

With behavior: "nullish"
`typescript
// io-ts
export const User = t.intersection([
t.type({ id: t.string }),
t.partial({
email: t.union([t.string, t.null]), // Partial (optional) + nullable
phone: t.string,
address: t.string
})
])

// Zod
export const UserSchema = z.object({
id: z.string(),
email: z.string().nullable().optional(), // Both nullable and optional
phone: z.string().optional(),
address: z.string().optional(),
});
`

#### Key Differences:
- Standard nullable: Makes a field accept null values
- x-nullable: true: Behavior depends on configuration (null, undefined, or both)
- x-nullable: false: Explicitly prevents the x-nullable effect

$3

// Configure DtoForge to use them
customTypes:
uuid:
zodType: "UUID"
import: "import { UUID } from './types';"
`

$3

`bash
dtoforge [options]

Options:
-openapi string Path to OpenAPI spec (JSON or YAML)
-out string Output directory (default: "./generated")
-lang string typescript | typescript-zod (default: "typescript")
-package string Package name for generated code
-config string Config file path
-no-config Disable config file discovery
-example-config Generate example config file
-version Print version and exit

Examples:
dtoforge -openapi api.yaml -out ./types
dtoforge -openapi api.yaml -lang typescript-zod
dtoforge -openapi api.yaml -config my-config.yaml
dtoforge -example-config
dtoforge -version
`

🔍 Troubleshooting

$3

Q: Generated schemas don't match my API
`bash


Ensure your OpenAPI spec is valid

Q: Import errors in generated code
`bash


Check your custom type imports

Q: Performance issues
`bash


Use single file mode for faster builds

🤝 Contributing

DtoForge is open source! Contributions are welcome:

- 🐛 Report bugs - GitHub Issues
- 💡 Request features - GitHub Discussions
- 🔧 Submit PRs - Contributing Guide

💖 Support DtoForge

If DtoForge saves you time and makes your development workflow better, consider supporting its development:

$3

- 🛠️ Active Development - Regular updates and new features
- 🐛 Bug Fixes - Quick response to issues and problems
- 📚 Documentation - Comprehensive guides and examples
- 💡 Feature Requests - Your ideas shape the future of DtoForge
- ⚡ Performance - Continuous optimization and improvements

$3

- More time for development and maintenance
- Better documentation and tutorials
- Additional language generators (C#, Java, Python)
- Community support and faster issue resolution

---

📄 License

MIT License - see the LICENSE file for details.

🙏 Acknowledgments

- Zod - Modern TypeScript schema validation
- io-ts - Excellent runtime type validation library
- fp-ts - Functional programming utilities
- The OpenAPI community for the great specification

---

Made with ❤️ by developers, for developers

DtoForge helps you build type-safe applications by bridging the gap between API specifications and runtime validation. Whether you prefer functional programming with io-ts or modern validation with Zod, DtoForge adapts to your development style and project needs.