Coder Legion - Recent posts tagged ajv

🧩 Engineering a Machine-Validatable Contributor Evidence Workflow

Thu, 08 Oct 2026 13:50:59 +0000

🧩 Engineering a Machine-Validatable Contributor Evidence Workflow

I just merged a new infrastructure milestone into MyZubster:

PR #1572 — standardized contributor interoperability checkpoints

The problem I wanted to solve was not just “how do we document a successful contributor test?”

The real problem was:

How do we make technical evidence portable across contributors, technologies and verification paths without losing provenance or inflating claims?

Until now, MyZubster already had reproducible contributor checkpoints, but the structure was mostly expressed through Markdown, PR discussions and manually reviewed evidence.

That works at small scale.

It does not scale well when multiple contributors are producing different kinds of evidence.

So I introduced a common machine-readable format:

myzubster.interoperability-checkpoint.v1

Each checkpoint now describes:

contributor identity
repository / PR
immutable commit reference
technical bridge type
exact scope
test environment
reproduction procedure
observed output
evidence state
limitations
canonical provenance

Why the limitations field matters

One of the most important design decisions was making limitations mandatory.

A technical checkpoint should not silently become a broader claim.

For example:

A successful broker-to-agent test does not automatically mean:

full decentralization
direct P2P networking
security certification

A research Knowledge Card marked SUPPORTED should not become “scientifically validated.”

A signed webhook regression should not become “payment settlement verified.”

The schema is intentionally designed to preserve those boundaries.

Evidence state is constrained by observation

The validator enforces an important rule:

TESTED

requires:

observation.result = PASS

That sounds obvious, but encoding it into the schema means it is no longer just a documentation convention.

It becomes something CI can reject.

AJV + CI integration

I added an AJV-based validator and connected it to the existing Continuous Evidence Gate.

So the pipeline now looks like this:

Contributor work
        ↓
Scoped reproducible test
        ↓
Machine-readable checkpoint
        ↓
JSON Schema validation
        ↓
Continuous Evidence Gate
        ↓
Human review
        ↓
Canonical merge

The important distinction:

automation validates evidence structure; it does not replace engineering judgment.

Testing the format across different contribution types

I did not want the first schema version to be designed around one specific contributor.

So the initial dataset already includes multiple technical paths.

N4K48 / Nicola

Runtime interoperability:

MyZubster VPS
→ authenticated HTTPS broker
→ contributor-controlled agent
→ local catalog
→ result returned to Bridge

wasim-builds

Security regression:

unconfigured auth → rejected
missing credential → rejected
wrong credential → rejected
correct credential → accepted

khongten124 / Open Period Care

Semantic evidence bridge:

public research evidence
→ structured ingestion
→ contributor-scoped retrieval
→ Knowledge Cards returned
→ original SUPPORTED state preserved

Aming9303

Signed webhook regression:

HMAC signing
→ stable delivery identity
→ unsigned request rejection
→ replay protection
→ stale-event rejection

These are very different systems.

That is exactly why using the same evidence structure is useful.

Current maturity

I would describe the workflow as:

repeatable
→ auditable
→ multi-contributor
→ machine-validatable

The next layer will be:

automated ingestion
→ Contributor Passport linkage
→ Knowledge Graph integration

while preserving the original evidence state and provenance.

Merge result

PR #1572 passed:

CI – Test & Lint
Security Audit
Continuous Evidence Gate
policy checks

Canonical merge:

2be06b7e34f22744ecf81a9daef12f7ba11864be

What I like about this milestone is that it is not visually impressive.

There is no shiny UI involved.

But it improves something much more fundamental:

the trust model between contributors and the platform.

Instead of:

“This was tested.”

the system can increasingly answer:

Who tested it?
Against which commit?
In which environment?
Using which procedure?
What was observed?
What does the evidence not prove?

That is the direction I want to keep pushing.

Evidence should be inspectable data, not just prose.

CoderLegion #SoftwareEngineering #JSONSchema #AJV #CI #DevOps #SystemDesign #OpenSource #Reproducibility #Testing #DeveloperTools

JSON Schema in the Wild: Real World Applications & HAL

Wed, 08 Oct 2025 13:05:06 +0000

Part 3 of 3: Where Theory Meets Production

Welcome to the final part of our JSON Schema journey! We've covered the theory and implementation – now let's see how JSON Schema solves real problems in production environments. Plus, we'll dive into HAL (Hypermedia Application Language) and how it plays beautifully with JSON Schema.

1. API Validation Middleware (Your APIs' Bodyguard)

Let's build bulletproof API validation that catches bad data before it causes havoc:

import express from 'express';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

// Generic validation middleware
function validateRequest(schema: any, target: 'body' | 'query' | 'params' = 'body') {
  const validate = ajv.compile(schema);
  
  return (req: any, res: any, next: any) => {
    const dataToValidate = req[target];
    
    if (!validate(dataToValidate)) {
      return res.status(400).json({
        error: 'Validation failed',
        details: validate.errors?.map(err => ({
          field: err.instancePath || err.params?.missingProperty,
          message: err.message,
          value: err.data
        }))
      });
    }
    
    // Store validated data (with defaults applied!)
    req.validatedData = dataToValidate;
    next();
  };
}

// Define your schemas
const createUserSchema = {
  type: "object",
  properties: {
    name: { type: "string", minLength: 1, maxLength: 100 },
    email: { type: "string", format: "email" },
    age: { type: "number", minimum: 13, maximum: 120 },
    role: { enum: ["user", "admin"], default: "user" }
  },
  required: ["name", "email", "age"],
  additionalProperties: false
};

const updateUserSchema = {
  type: "object",
  properties: {
    name: { type: "string", minLength: 1, maxLength: 100 },
    email: { type: "string", format: "email" },
    age: { type: "number", minimum: 13, maximum: 120 }
  },
  minProperties: 1, // At least one field must be provided
  additionalProperties: false
};

// Use in your routes
const app = express();
app.use(express.json());

app.post('/users', 
  validateRequest(createUserSchema, 'body'),
  (req, res) => {
    // req.validatedData contains clean, validated data
    const user = createUser(req.validatedData);
    res.json(user);
  }
);

app.patch('/users/:id', 
  validateRequest(updateUserSchema, 'body'),
  (req, res) => {
    const userId = req.params.id;
    const updates = req.validatedData;
    const user = updateUser(userId, updates);
    res.json(user);
  }
);

// Query parameter validation too!
const searchSchema = {
  type: "object",
  properties: {
    q: { type: "string", minLength: 1 },
    page: { type: "string", pattern: "^[1-9]\\d*$", default: "1" },
    limit: { type: "string", pattern: "^(10|25|50|100)$", default: "25" }
  },
  required: ["q"],
  additionalProperties: false
};

app.get('/search', 
  validateRequest(searchSchema, 'query'),
  (req, res) => {
    const { q, page, limit } = req.validatedData;
    const results = searchUsers(q, parseInt(page), parseInt(limit));
    res.json(results);
  }
);

2. Data Pipeline Validation (ETL with Confidence)

When processing large datasets, catching bad data early saves hours of debugging:

// data-pipeline.ts
import Ajv from 'ajv';
import addFormats from 'ajv-formats';

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

// Schema for incoming data records
const dataRecordSchema = {
  type: "object",
  properties: {
    id: { 
      type: "string", 
      pattern: "^[A-Z]{2}[0-9]{6}$" // e.g., "AB123456"
    },
    timestamp: { 
      type: "string", 
      format: "date-time" 
    },
    value: { 
      type: "number",
      minimum: 0
    },
    category: { 
      enum: ["sales", "marketing", "support", "development"] 
    },
    metadata: {
      type: "object",
      properties: {
        source: { type: "string" },
        confidence: { type: "number", minimum: 0, maximum: 1 }
      },
      required: ["source"],
      additionalProperties: true // Allow extra metadata
    }
  },
  required: ["id", "timestamp", "value", "category"],
  additionalProperties: false
};

const validateRecord = ajv.compile(dataRecordSchema);

interface ProcessingResult {
  validRecords: any[];
  invalidRecords: Array<{
    record: any;
    errors: string[];
  }>;
  stats: {
    total: number;
    valid: number;
    invalid: number;
    validationRate: number;
  };
}

export function processDataBatch(records: any[]): ProcessingResult {
  const validRecords: any[] = [];
  const invalidRecords: any[] = [];
  
  records.forEach((record, index) => {
    if (validateRecord(record)) {
      validRecords.push(record);
    } else {
      invalidRecords.push({
        record,
        errors: validateRecord.errors?.map(err => 
          `${err.instancePath || 'root'}: ${err.message}`
        ) || []
      });
    }
  });
  
  const total = records.length;
  const valid = validRecords.length;
  const invalid = invalidRecords.length;
  
  return {
    validRecords,
    invalidRecords,
    stats: {
      total,
      valid,
      invalid,
      validationRate: (valid / total) * 100
    }
  };
}

// Usage in your ETL process
async function runETL(inputFile: string) {
  const rawData = await loadDataFromFile(inputFile);
  const result = processDataBatch(rawData);
  
  console.log(`Processed ${result.stats.total} records:`);
  console.log(`✅ Valid: ${result.stats.valid} (${result.stats.validationRate.toFixed(1)}%)`);
  console.log(`❌ Invalid: ${result.stats.invalid}`);
  
  if (result.invalidRecords.length > 0) {
    console.log('\nInvalid records:');
    result.invalidRecords.slice(0, 5).forEach((invalid, i) => {
      console.log(`Record ${i + 1}:`, invalid.errors.join(', '));
    });
  }
  
  // Process only valid records
  await saveToDatabase(result.validRecords);
  
  // Log invalid records for investigation
  if (result.invalidRecords.length > 0) {
    await saveInvalidRecords(result.invalidRecords);
  }
}

3. HAL (Hypermedia Application Language) Schemas

HAL makes your APIs self-describing with built-in navigation. Think JSON with links that tell clients what actions they can take next.

Basic HAL Structure & Schema

// HAL link schema
const halLinkSchema = {
  type: "object",
  properties: {
    href: { type: "string", format: "uri-reference" },
    templated: { type: "boolean" },
    type: { type: "string" }
  },
  required: ["href"],
  additionalProperties: false
};

// Complete HAL resource schema
const halUserSchema = {
  type: "object",
  properties: {
    // Resource data
    id: { type: "number" },
    name: { type: "string" },
    email: { type: "string", format: "email" },
    
    // HAL links (required)
    _links: {
      type: "object",
      properties: {
        self: halLinkSchema,
        edit: halLinkSchema,
        delete: halLinkSchema
      },
      required: ["self"],
      additionalProperties: halLinkSchema
    },
    
    // HAL embedded resources (optional)
    _embedded: {
      type: "object",
      properties: {
        posts: {
          type: "array",
          items: {
            type: "object",
            properties: {
              id: { type: "number" },
              title: { type: "string" },
              _links: {
                type: "object",
                properties: { self: halLinkSchema },
                required: ["self"]
              }
            },
            required: ["id", "title", "_links"]
          }
        }
      }
    }
  },
  required: ["id", "name", "_links"],
  additionalProperties: false
};

HAL Response Builder

import Ajv from 'ajv';
const ajv = new Ajv();
const validateHalUser = ajv.compile(halUserSchema);

class HalBuilder {
  static user(user: any, baseUrl: string) {
    const halUser = {
      ...user,
      _links: {
        self: { href: `${baseUrl}/users/${user.id}` },
        edit: { href: `${baseUrl}/users/${user.id}` },
        posts: { href: `${baseUrl}/users/${user.id}/posts` }
      }
    };
    
    // Add embedded posts if available
    if (user.posts?.length) {
      halUser._embedded = {
        posts: user.posts.map(post => ({
          ...post,
          _links: { self: { href: `${baseUrl}/posts/${post.id}` } }
        }))
      };
    }
    
    if (!validateHalUser(halUser)) {
      throw new Error('Invalid HAL resource');
    }
    
    return halUser;
  }
}

// Usage in Express
app.get('/users/:id', async (req, res) => {
  const user = await getUserById(req.params.id);
  const baseUrl = `${req.protocol}://${req.get('host')}`;
  
  res.json(HalBuilder.user(user, baseUrl));
});

4. Testing Your Schemas (Because Bugs Hide in Edge Cases)

Don't just validate production data – test your schemas themselves:

// schema-tests.ts
import { describe, it, expect } from 'vitest';
import Ajv from 'ajv';
import addFormats from 'ajv-formats';
import { halUserSchema, userRegistrationSchema } from './schemas';

const ajv = new Ajv({ allErrors: true });
addFormats(ajv);

describe('User Registration Schema', () => {
  const validate = ajv.compile(userRegistrationSchema);
  
  it('should accept valid user data', () => {
    const validUser = {
      username: "johndoe123",
      email: "*Emails are not allowed*",
      password: "SecurePass123!",
      age: 25
    };
    
    expect(validate(validUser)).toBe(true);
  });
  
  it('should reject invalid email', () => {
    const invalidUser = {
      username: "johndoe123",
      email: "not-an-email",
      password: "SecurePass123!",
      age: 25
    };
    
    expect(validate(invalidUser)).toBe(false);
    expect(validate.errors).toContainEqual(
      expect.objectContaining({
        instancePath: '/email',
        message: 'must match format "email"'
      })
    );
  });
  
  it('should reject weak password', () => {
    const invalidUser = {
      username: "johndoe123",
      email: "*Emails are not allowed*",
      password: "weak",
      age: 25
    };
    
    expect(validate(invalidUser)).toBe(false);
  });
  
  it('should apply defaults', () => {
    const userData = {
      username: "johndoe123",
      email: "*Emails are not allowed*",
      password: "SecurePass123!",
      age: 25
    };
    
    validate(userData);
    expect(userData.preferences?.newsletter).toBe(false);
    expect(userData.preferences?.theme).toBe('light');
  });
});

describe('HAL User Schema', () => {
  const validate = ajv.compile(halUserSchema);
  
  it('should accept valid HAL user', () => {
    const halUser = {
      id: 123,
      name: "Alice",
      email: "*Emails are not allowed*",
      createdAt: "2023-01-01T00:00:00.000Z",
      _links: {
        self: { href: "/users/123" },
        edit: { href: "/users/123" }
      }
    };
    
    expect(validate(halUser)).toBe(true);
  });
  
  it('should require _links.self', () => {
    const invalidHalUser = {
      id: 123,
      name: "Alice",
      email: "*Emails are not allowed*",
      _links: {
        edit: { href: "/users/123" }
      }
    };
    
    expect(validate(invalidHalUser)).toBe(false);
    expect(validate.errors).toContainEqual(
      expect.objectContaining({
        instancePath: '/_links',
        message: "must have required property 'self'"
      })
    );
  });
});

5. Pro Tips for Production Success

1. Schema Versioning Strategy

// Keep schemas versioned for backward compatibility
const schemas = {
  'v1': {
    user: userSchemaV1,
    post: postSchemaV1
  },
  'v2': {
    user: userSchemaV2,
    post: postSchemaV2
  }
};

function getValidator(resource: string, version: string = 'v2') {
  const schema = schemas[version]?.[resource];
  if (!schema) {
    throw new Error(`Schema not found: ${resource} v${version}`);
  }
  return ajv.compile(schema);
}

2. Performance Monitoring

// Monitor validation performance
function createTimedValidator(schema: any, name: string) {
  const validate = ajv.compile(schema);
  
  return (data: any) => {
    const start = process.hrtime.bigint();
    const result = validate(data);
    const end = process.hrtime.bigint();
    
    const duration = Number(end - start) / 1000000; // Convert to milliseconds
    console.log(`Validation ${name}: ${duration.toFixed(2)}ms`);
    
    return result;
  };
}

3. Schema Documentation Generation

// Generate documentation from your schemas
function generateSchemaDoc(schema: any, title: string) {
  const doc = {
    title,
    properties: {},
    required: schema.required || []
  };
  
  for (const [prop, definition] of Object.entries(schema.properties || {})) {
    doc.properties[prop] = {
      type: definition.type,
      description: definition.description || `${prop} field`,
      required: schema.required?.includes(prop) || false,
      example: generateExample(definition)
    };
  }
  
  return doc;
}

Wrapping Up the Series

Congratulations! You've journeyed from JSON Schema basics to production-ready implementations. Here's what you've gained:

Part 1: Understanding JSON Schema fundamentals and YAML compatibility
Part 2: Mastering AJV implementation with advanced features and TypeScript integration
Part 3: Real-world patterns including API validation, ETL pipelines, and HAL hypermedia APIs

Your Next Steps

Start Small: Pick one use case (maybe API validation) and implement it
Build Your Schema Library: Create reusable schemas for your common data structures
Test Everything: Write tests for both your schemas and your validation logic
Monitor Performance: Keep an eye on validation performance in production
Document Your Schemas: Good schemas are self-documenting, but examples help

You're now equipped to bring order to the chaos of unvalidated data. Go forth and validate with confidence! :rocket:

Series Navigation:

Part 1: Understanding the Basics
Part 2: Implementation with AJV
Part 3: Real-World Applications & HAL ← You are here

JSON Schema with AJV: Implementation Deep Dive ⚡

Fri, 03 Oct 2025 04:08:27 +0000

Part 2 of 3: Getting Your Hands Dirty

Welcome back! In Part 1, we covered the basics of JSON Schema and why it's awesome. Now it's time to roll up our sleeves and implement some real validation with AJV (Another JSON Schema Validator) – the Swiss Army knife of JSON validation.

Why AJV Rules the Validation World

AJV isn't just another validation library – it's THE validation library. Here's why developers love it:

Blazingly Fast: Compiles schemas to optimized JavaScript functions
Fully Compliant: Supports JSON Schema draft-07 and draft 2019-09
Extensible: Custom keywords, formats, and error messages
TypeScript Ready: Excellent TypeScript support out of the box

Getting Started: Installation and Basic Setup

// The essentials
npm install ajv

// Optional but recommended additions
npm install ajv-formats ajv-errors ajv-keywords

import Ajv from 'ajv';
import addFormats from 'ajv-formats';

// Create your AJV instance
const ajv = new Ajv({ 
  allErrors: true,        // Collect all errors, not just the first
  removeAdditional: true, // Remove additional properties
  useDefaults: true       // Apply default values
});

// Add common formats (email, date, uri, etc.)
addFormats(ajv);

// Now you're ready to validate!

Your First Real Validation

Let's build something practical – a user registration validator:

const userRegistrationSchema = {
  type: "object",
  properties: {
    username: {
      type: "string",
      minLength: 3,
      maxLength: 20,
      pattern: "^[a-zA-Z0-9_]+$"
    },
    email: {
      type: "string",
      format: "email"
    },
    password: {
      type: "string",
      minLength: 8,
      pattern: "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)(?=.*[@$!%*?&])[A-Za-z\\d@$!%*?&]"
    },
    age: {
      type: "number",
      minimum: 13,
      maximum: 120
    },
    preferences: {
      type: "object",
      properties: {
        newsletter: { type: "boolean", default: false },
        theme: { enum: ["light", "dark"], default: "light" }
      },
      additionalProperties: false
    }
  },
  required: ["username", "email", "password", "age"],
  additionalProperties: false
};

// Compile the schema (do this once, reuse many times)
const validateUser = ajv.compile(userRegistrationSchema);

// Test it out
function registerUser(userData: any) {
  const valid = validateUser(userData);
  
  if (!valid) {
    console.log('Validation failed:');
    validateUser.errors?.forEach(error => {
      console.log(`- ${error.instancePath}: ${error.message}`);
    });
    return null;
  }
  
  console.log('✅ User data is valid!');
  return userData; // Now with defaults applied!
}

// Try it
const newUser = {
  username: "coolguy123",
  email: "*Emails are not allowed*",
  password: "SuperSecret123!",
  age: 25
};

registerUser(newUser);
// ✅ User data is valid!
// Note: preferences.newsletter and preferences.theme get default values

Advanced AJV Features That'll Blow Your Mind

1. Custom Keywords

Sometimes the built-in validation isn't enough. Let's create a custom keyword:

// Add a custom "isAdult" keyword
ajv.addKeyword({
  keyword: 'isAdult',
  type: 'number',
  schemaType: 'boolean',
  compile(schemaVal) {
    return function validate(data) {
      if (schemaVal) {
        return data >= 18;
      }
      return true;
    }
  },
  errors: false,
  metaSchema: {
    type: "boolean"
  }
});

// Use it in a schema
const adultSchema = {
  type: "object",
  properties: {
    age: { 
      type: "number", 
      isAdult: true 
    }
  }
};

const validateAdult = ajv.compile(adultSchema);
console.log(validateAdult({ age: 17 })); // false
console.log(validateAdult({ age: 21 })); // true

2. Conditional Validation

Real-world data often has complex relationships. AJV handles this beautifully:

const conditionalSchema = {
  type: "object",
  properties: {
    userType: { enum: ["admin", "user", "guest"] },
    permissions: { 
      type: "array",
      items: { type: "string" }
    },
    adminKey: { type: "string" }
  },
  required: ["userType"],
  
  // If user is admin, they need permissions and adminKey
  if: { 
    properties: { 
      userType: { const: "admin" } 
    } 
  },
  then: { 
    required: ["permissions", "adminKey"],
    properties: {
      permissions: { minItems: 1 }
    }
  },
  
  // If user is guest, no additional requirements
  else: {
    if: { 
      properties: { 
        userType: { const: "guest" } 
      } 
    },
    then: {
      // Guests can't have permissions
      not: {
        required: ["permissions"]
      }
    }
  }
};

3. Schema Composition with $ref

Keep your schemas DRY and maintainable:

const schemas = {
  // Base address schema
  address: {
    $id: "https://example.com/schemas/address.json",
    type: "object",
    properties: {
      street: { type: "string" },
      city: { type: "string" },
      zipCode: { 
        type: "string", 
        pattern: "^[0-9]{5}(-[0-9]{4})?$" 
      }
    },
    required: ["street", "city", "zipCode"]
  },
  
  // Person schema using address
  person: {
    $id: "https://example.com/schemas/person.json",
    type: "object",
    properties: {
      name: { type: "string" },
      homeAddress: { $ref: "address.json" },
      workAddress: { $ref: "address.json" }
    }
  }
};

// Add schemas to AJV
ajv.addSchema(schemas.address);
ajv.addSchema(schemas.person);

const validatePerson = ajv.getSchema("https://example.com/schemas/person.json");

Error Handling Like a Pro

Default AJV errors are... functional. But we can make them much better:

import addErrors from 'ajv-errors';
addErrors(ajv);

const betterUserSchema = {
  type: "object",
  properties: {
    username: {
      type: "string",
      minLength: 3,
      maxLength: 20,
      pattern: "^[a-zA-Z0-9_]+$"
    },
    password: {
      type: "string",
      minLength: 8,
      pattern: "^(?=.*[a-z])(?=.*[A-Z])(?=.*\\d)"
    }
  },
  required: ["username", "password"],
  
  // Custom error messages
  errorMessage: {
    properties: {
      username: "Username must be 3-20 characters long and contain only letters, numbers, and underscores",
      password: "Password must be at least 8 characters with uppercase, lowercase, and a number"
    },
    required: {
      username: "Username is required",
      password: "Password is required"
    }
  }
};

Performance Tips That Actually Matter

1. Compile Once, Use Many Times

// ❌ DON'T do this
function validateUserData(data: any) {
  const validate = ajv.compile(userSchema); // Compiling every time!
  return validate(data);
}

// ✅ DO this instead
const validateUserData = ajv.compile(userSchema); // Compile once

function checkUser(data: any) {
  return validateUserData(data); // Reuse compiled function
}

2. Use removeAdditional for Large Objects

const ajv = new Ajv({ 
  removeAdditional: "all" // Strip unknown properties automatically
});

// Input: { name: "Bob", age: 25, secretHackerData: "evil" }
// After validation: { name: "Bob", age: 25 }

3. Optimize for Your Use Case

// For APIs - fast validation, detailed errors
const apiAjv = new Ajv({ 
  allErrors: true,
  verbose: true 
});

// For data processing - fastest validation
const processingAjv = new Ajv({ 
  allErrors: false,
  verbose: false,
  validateSchema: false
});

TypeScript Integration (The Cherry on Top)

AJV plays beautifully with TypeScript:

import { JSONSchemaType } from 'ajv';

// Define your TypeScript interface
interface User {
  id: string;
  name: string;
  age: number;
  email?: string;
}

// Create a typed schema
const userSchema: JSONSchemaType<User> = {
  type: "object",
  properties: {
    id: { type: "string" },
    name: { type: "string" },
    age: { type: "number" },
    email: { type: "string", nullable: true }
  },
  required: ["id", "name", "age"],
  additionalProperties: false
};

// Compile with type safety
const validateUser = ajv.compile(userSchema);

// TypeScript knows the validated data structure!
function processUser(userData: unknown): User | null {
  if (validateUser(userData)) {
    // userData is now typed as User!
    return userData;
  }
  return null;
}

Common Gotchas (Learn From My Mistakes)

1. Format Validation Needs ajv-formats

// This won't work without ajv-formats
const schema = {
  type: "string",
  format: "email" // Silently ignored!
};

// Fix it
import addFormats from 'ajv-formats';
addFormats(ajv);

2. RegExp Patterns Need Double Escaping

// ❌ Wrong
pattern: "^\d{3}-\d{3}-\d{4}$"

// ✅ Correct
pattern: "^\\d{3}-\\d{3}-\\d{4}$"

3. additionalProperties vs Properties

// This allows ANY additional properties
const schema1 = {
  type: "object",
  properties: { name: { type: "string" } }
  // additionalProperties defaults to true
};

// This blocks additional properties
const schema2 = {
  type: "object",
  properties: { name: { type: "string" } },
  additionalProperties: false
};

Wrapping Up Part 2

You now have the power to implement robust, fast, and maintainable validation in your applications! AJV transforms JSON Schema from a simple concept into a validation powerhouse.

Coming Up in Part 3...

In the final part of our series, we'll explore real-world applications:

Building API validation middleware
Data pipeline validation patterns
HAL (Hypermedia) schemas for self-describing APIs
Testing strategies for schema validation
Production ready tips

Ready to put this knowledge to work in production? Part 3 is where the magic happens!

Series Navigation:

Part 1: Understanding the Basics
Part 2: Implementation with AJV ← You are here
Part 3: Real-World Applications & HAL

JSON Schema: Your Data's New Best Friend ️

Sat, 27 Sep 2025 11:49:08 +0000

Part 1 of 3: Understanding the Basics

Ever had that moment where your API returns { age: "twenty-five" } instead of { age: 25 } and your whole app breaks? Yeah, we've all been there. Let's talk about JSON Schema – your new best friend in the fight against unpredictable data.

What the Heck is JSON Schema Anyway?

JSON Schema is basically a contract for your JSON data. Think of it like TypeScript's type definitions, but for runtime validation. It tells your data: "Hey, you better look exactly like this, or we're gonna have problems."

The concept emerged around 2009-2010 when developers got tired of writing custom validation logic for every single API endpoint. Someone smart said, "What if we could describe our data structure using... more JSON?" And boom – JSON Schema was born.

// Instead of this mess:
if (!data.name || typeof data.name !== 'string') {
  throw new Error('Name is required and must be a string');
}
if (!data.age || typeof data.age !== 'number' || data.age < 0) {
  throw new Error('Age must be a positive number');
}
// ... 50 more lines of validation

// You get this beauty:
const schema = {
  type: "object",
  properties: {
    name: { type: "string" },
    age: { type: "number", minimum: 0 }
  },
  required: ["name", "age"]
};

The Anatomy of a JSON Schema

Let's break down what makes a schema tick:

const userSchema = {
  // Root type - what kind of data are we expecting?
  type: "object",
  
  // Define the shape of our object
  properties: {
    name: { 
      type: "string", 
      minLength: 1,
      maxLength: 100 
    },
    age: { 
      type: "number", 
      minimum: 0, 
      maximum: 150 
    },
    email: { 
      type: "string", 
      format: "email"  // Built-in format validation!
    },
    hobbies: {
      type: "array",
      items: { type: "string" },
      maxItems: 10,
      uniqueItems: true
    },
    isActive: { 
      type: "boolean" 
    }
  },
  
  // Which fields are mandatory?
  required: ["name", "age"],
  
  // Should we allow extra properties?
  additionalProperties: false
};

Common Schema Patterns You'll Love

1. Enums (Because Options Are Limited)

const statusSchema = {
  type: "object",
  properties: {
    status: { 
      enum: ["active", "inactive", "pending", "banned"] 
    },
    priority: {
      type: "string",
      enum: ["low", "medium", "high", "urgent"]
    }
  }
};

2. Nested Objects (Objects All the Way Down)

const addressSchema = {
  type: "object",
  properties: {
    street: { type: "string" },
    city: { type: "string" },
    country: { type: "string" },
    zipCode: { 
      type: "string", 
      pattern: "^[1-9][0-9]{5}$" // India ZIP code pattern
    }
  },
  required: ["street", "city", "country"]
};

const personSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    homeAddress: addressSchema,  // Nested schema
    workAddress: addressSchema   // Reused!
  }
};

3. Arrays with Specific Item Types

const orderSchema = {
  type: "object",
  properties: {
    orderId: { type: "string" },
    items: {
      type: "array",
      minItems: 1,
      items: {
        type: "object",
        properties: {
          productId: { type: "string" },
          quantity: { type: "number", minimum: 1 },
          price: { type: "number", minimum: 0 }
        },
        required: ["productId", "quantity", "price"]
      }
    }
  }
};

YAML Schema: JSON Schema's Chill Cousin

Here's a cool secret – JSON Schema works perfectly with YAML too! Since YAML is essentially JSON's more readable sibling, you can use the same schema definitions.

# Your YAML data
name: "Alice"
age: 30
email: "*Emails are not allowed*"
hobbies:
  - "coding"
  - "coffee"
  - "cats"

# Same schema validates both JSON and YAML!

The validation logic doesn't care if your data started as JSON or YAML – it all becomes the same object structure in memory anyway. This means you can:

Use JSON Schema to validate YAML config files
Accept both JSON and YAML in your APIs
Keep one schema definition for multiple data formats

Why Should You Care?

1. Catch Errors Early

// This will blow up at runtime somewhere deep in your code
const user = { name: "Bob", age: "thirty-five" };
calculateInsurance(user.age * 1.2); // NaN strikes again!

// This gets caught immediately with schema validation
// Error: /age: should be number

2. Self-Documenting APIs

Your schema IS your documentation. No more outdated API docs that say age is a number when it's actually a string.

3. Frontend/Backend Agreement

When both sides validate against the same schema, miscommunication becomes impossible. It's like having a peace treaty for your data structures.

4. Better Error Messages

Instead of "Something went wrong," you get "Property 'email' should match format 'email'." Your users (and your future self) will thank you.

Coming Up Next...

In Part 2, we'll dive deep into implementing JSON Schema validation with AJV, including:

Setting up AJV in your project
Advanced validation features
Custom keywords and error messages
Performance optimization tips

Ready to never debug mysterious data issues at 2 AM again? Let's make it happen!

Series Navigation:

Part 1: Understanding the Basics ← You are here
Part 2: Implementation with AJV
Part 3: Real-World Applications & HAL

Coder Legion - Recent posts tagged ajv

🧩 **Engineering a Machine-Validatable Contributor Evidence Workflow**

Why the limitations field matters

Evidence state is constrained by observation

AJV + CI integration

Testing the format across different contribution types

Current maturity

Merge result

CoderLegion #SoftwareEngineering #JSONSchema #AJV #CI #DevOps #SystemDesign #OpenSource #Reproducibility #Testing #DeveloperTools

JSON Schema in the Wild: Real World Applications & HAL

1. API Validation Middleware (Your APIs' Bodyguard)

2. Data Pipeline Validation (ETL with Confidence)

3. HAL (Hypermedia Application Language) Schemas

Basic HAL Structure & Schema

HAL Response Builder

4. Testing Your Schemas (Because Bugs Hide in Edge Cases)

5. Pro Tips for Production Success

1. Schema Versioning Strategy

2. Performance Monitoring

3. Schema Documentation Generation

Wrapping Up the Series

Your Next Steps

JSON Schema with AJV: Implementation Deep Dive ⚡

Why AJV Rules the Validation World

Getting Started: Installation and Basic Setup

Your First Real Validation

Advanced AJV Features That'll Blow Your Mind

1. Custom Keywords

2. Conditional Validation

3. Schema Composition with $ref

Error Handling Like a Pro

Performance Tips That Actually Matter

1. Compile Once, Use Many Times

2. Use removeAdditional for Large Objects

3. Optimize for Your Use Case

TypeScript Integration (The Cherry on Top)

Common Gotchas (Learn From My Mistakes)

1. Format Validation Needs ajv-formats

2. RegExp Patterns Need Double Escaping

3. additionalProperties vs Properties

Wrapping Up Part 2

Coming Up in Part 3...

JSON Schema: Your Data's New Best Friend ️

What the Heck is JSON Schema Anyway?

The Anatomy of a JSON Schema

Common Schema Patterns You'll Love

1. Enums (Because Options Are Limited)

2. Nested Objects (Objects All the Way Down)

3. Arrays with Specific Item Types

YAML Schema: JSON Schema's Chill Cousin

Why Should You Care?

1. Catch Errors Early

2. Self-Documenting APIs

3. Frontend/Backend Agreement

4. Better Error Messages

Coming Up Next...

🧩 Engineering a Machine-Validatable Contributor Evidence Workflow