Zontax

Zontax is a powerful superset of the Zod schema language that allows you to embed arbitrary metadata directly within your schema definitions. It provides a parser that transforms and composes multiple schema strings into two separate, useful outputs:

1. A clean, merged Zod schema string (using lowercase z) for validation.
2. A structured JSON definition object containing all the extracted metadata, perfect for UI generation, documentation, or API behavior.

This allows you to maintain a single source of truth for both data validation and any contextual information attached to your data structures.

Key Features

• Distinct Syntax: Uses a capital Z (Z.object) to clearly distinguish Zontax schemas from standard Zod schemas.
• Multi-Version Support: Write once, target any Zod version - generate compatible schemas for both Zod 3 and Zod 4.
• Complete Zod Method Coverage: Supports all 22 standard Zod methods including complex types like enum, tuple, union, and literal.
• Namespaces: Register extensions under namespaces (ui, doc, etc.) to prevent name collisions and organize your schemas.
• Schema Composition: Intelligently deep-merge multiple schema strings into a single, unified definition.
• Conflict Detection: Automatically throws an error on conflicting types or validations during a merge.
• Flexible Modes: Use strict mode for production and loose mode for rapid development.
• Helper Utilities: Includes built-in static methods to query the definition object and generate new schemas from it.

Installation

pnpm add zontax
# or
npm install zontax
# or
yarn add zontax

How It Works: A Simple Example

The ZontaxParser takes a Zontax string (using Z.) and returns a standard Zod string (using z.) and a structured definition object.

Given this Zontax string:

const schemaString = `
  Z.object({
    name: Z.string().min(1).ui$label("Full Name"),
    id: Z.string().uuid().analyticsId("user-id")
  })
`;

A single call to parser.parse(schemaString) returns:

{
  "schema": "z.object({ name: z.string().min(1), id: z.string().uuid() })",
  "definition": {
    "type": "object",
    "fields": {
      "name": {
        "type": "string",
        "validations": { "min": 1 },
        "namespaces": {
          "ui": { "label": { "value": "Full Name" } }
        }
      },
      "id": {
        "type": "string",
        "validations": { "uuid": true },
        "extensions": {
          "analyticsId": { "value": "user-id" }
        }
      }
    }
  }
}

Schema Composition

A key feature of Zontax is its ability to compose multiple schemas. The parse method accepts multiple strings and merges them using an "Intelligent Deep Merge" strategy.

base.schema.js

const baseSchema = `Z.object({ username: Z.string().min(3) })`;

ui.schema.js

const uiSchema = `Z.object({ username: Z.string().ui$label("Username") })`;

Composition:

import { ZontaxParser } from 'zontax';
const parser = new ZontaxParser({}, [/* ...registrations */]);
const { schema, definition } = parser.parse(baseSchema, uiSchema);

Result:

• schema: "z.object({ username: z.string().min(3) })"
• definition: A merged object containing both the min(3) validation and the ui$label extension.

Zod Version Support

One of Zontax's most powerful features is its ability to generate compatible schemas for different Zod versions. This is particularly useful for teams migrating between Zod versions or maintaining multiple codebases.

Usage

import { ZontaxParser } from 'zontax';

// Default (Zod 4)
const parser = new ZontaxParser();

// Explicit Zod 4
const parser4 = new ZontaxParser([], { zodVersion: '4' });

// Explicit Zod 3
const parser3 = new ZontaxParser([], { zodVersion: '3' });

Example: Single Schema, Multiple Targets

const userSchema = `
  Z.object({
    name: Z.string().min(1).describe('Full name'),
    email: Z.string().email(),
    role: Z.enum(['admin', 'user']).default('user'),
    metadata: Z.object({
      createdAt: Z.date(),
      tags: Z.array(Z.string()).optional()
    }).optional()
  })
`;

const legacyParser = new ZontaxParser({ zodVersion: '3' });
const modernParser = new ZontaxParser({ zodVersion: '4' });

const legacyZod = legacyParser.parse(userSchema).schema;
const modernZod = modernParser.parse(userSchema).schema;

// Both schemas are functionally identical and work with their respective Zod versions!
// The team can maintain one Zontax schema and deploy to both codebases.

Supported Zod Methods

Zontax supports all 22 standard Zod methods across both versions:

Basic Types: string, number, boolean, date
Validations: min, max, length, email, url, uuid, int, positive, negative
Modifiers: optional, nullable, default, describe
Complex Types: object, array, enum, literal, tuple, union

Usage & Customization

Registering Schemas and Namespaces

The ZontaxParser constructor accepts an array of schema registrations and optional configuration. The Extension schema allows for powerful, self-documenting validation rules.

import { ZontaxParser, Extension } from 'zontax';

const uiSchema: Extension[] = [
  { 
    name: 'label', 
    allowedOn: ['string'], 
    args: ['string'],
    // Restrict this extension to specific paths
    allowedOnPath: [
        'user.name', // Exact match
        'user.profile.*', // Wildcard match for direct children
        /^user\.address\.(street|city)$/ // RegExp for advanced matching
    ]
  },
];

// Register uiSchema under the 'ui' namespace
const parser = new ZontaxParser({
  mode: 'strict',      // or 'loose' for development
  zodVersion: '4'      // or '3' for legacy support
}, [
  { namespace: 'ui', extensions: uiSchema }
]);

Introspection

You can inspect the parser's configuration at any time.

getExtensions()

Returns a map of all registered extensions, keyed by their namespace. Global extensions are stored under the _global key.

const extensions = parser.getExtensions();
// { _global: [...], ui: [...] }

Parser Configuration Options

The ZontaxParser constructor accepts these options:

interface ZontaxParserOptions {
  mode?: 'strict' | 'loose';     // Default: 'strict'
  zodVersion?: '3' | '4';         // Default: '4'
}

• mode: In strict mode, unregistered extensions throw errors. In loose mode, they're captured for later introspection.
• zodVersion: Specifies the target Zod version for generated schemas.

Helper Methods

Zontax includes static helper methods to make working with the definition object easier.

generateSchemaFromDefinition(definition, namespace?)

This powerful helper generates a formal Extension[] array from a definition object created in loose mode. This makes it incredibly easy to bootstrap a formal schema from a prototype.

Recent Improvements

v0.15.0 - Complete Zod Method Coverage & Multi-Version Support

• 🎯 Complete Zod Method Coverage: All 22 standard Zod methods now fully supported

  • Fixed nullable, default, int, positive, negative methods
  • Enhanced complex type support for enum, literal, tuple, union
  • Improved argument parsing for array-based methods

• 🔄 Multi-Version Support: Write once, target any Zod version

  • Single Zontax syntax generates compatible schemas for both Zod 3 and 4
  • Seamless migration support for teams upgrading between versions
  • Future-proof architecture for upcoming Zod releases

• 🐛 Bug Fixes:

  • Fixed object property parsing for quoted keys (e.g., {'summary': Z.string()})
  • Enhanced .describe() method forwarding to generated schemas
  • Improved type inference and validation handling

• 📚 Enhanced Documentation: Updated README with comprehensive examples and usage patterns

License

This project is licensed under the ISC License.