@oniryk/forma

Schema-driven invalid payload generator for validation testing. Produces payload variations that violate JSON Schema constraints — null, omission, wrong types, bounds, formats, and patterns — so you can verify your validation logic handles them correctly.

Installation

npm install @oniryk/forma

Usage

Generate payloads that violate schema constraints:

import { Forma } from '@oniryk/forma';
import { z } from 'zod';

const userSchema = z.object({
  email: z.string().email(),
  age: z.number().min(18).max(120),
  bio: z.string().nullable(),
});

// Convert Zod to JSON Schema for Forma
const schema = userSchema.toJSONSchema();
const forma = new Forma(schema);

// Iterate over all edge cases
for (const payload of forma.variate()) {
  const response = await fetch('http://localhost:3000/api/users', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
  });

  // Verify proper error handling
  if (!response.ok) {
    console.log(`✓ Correctly rejected invalid payload (status: ${response.status})`);
  } else {
    console.warn('✗ Should have been rejected but was accepted');
  }
}

This package works with any JSON Schema. Zod is used in the example but not required.

Rate limit awareness: variate() can yield many payloads — schemas with nested objects and arrays can produce hundreds of variations. When testing against external APIs, consider adding a throttle or limit to avoid overwhelming the server.

Features

• JSON Schema Support — Works with standard JSON Schema from any validator or framework (Zod, Vine, ArkType, etc.)
• Comprehensive Coverage — Generates variations for:
  • Null values injected into non-nullable fields
  • Required fields omitted from the payload
  • Constraint violations (min/max, length, pattern, enum, format, multipleOf)
  • Incorrect types (string instead of number, object instead of array, etc.)
  • Nested objects and array items (applies all violations recursively)

API Reference

Forma(schema)

Creates a new payload variation generator.

Parameters:

• schema — JSON Schema object describing the expected structure. Must describe an object (type: "object" or properties defined).

Returns: New Forma instance

.variate(): Generator<Variation>

Lazily yields payload variations, one per iteration. Each variation is a shallow clone of the valid payload with exactly one field mutated.

Yields: Objects with a single field altered to test a specific violation:

• Null for non-nullable fields
• Omission of required fields
• Wrong type value (e.g., string where a number is expected)
• Constraint violation (below minimum, above maximum, invalid format, etc.)
• Nested violations inside objects and array items (recursive)

AI-Assisted Development

This package was developed with the assistance of artificial intelligence as a productivity tool, under human supervision and direction.

License

MIT