JSON Schema

JSON Schema uses a declarative rather than imperative approach. You define what the data should look like, not how to check it. The schema itself is a JSON document that specifies:

• Required properties and their expected data types (string, number, boolean, array, object, null).
• Constraints like minimum/maximum values, string patterns (regex), and array lengths.
• Nested structures for complex objects. This allows validation engines in any programming language to interpret and enforce the same rules consistently.

A key feature for maintainability is the $ref (reference) keyword. It allows you to define common schemas once and reference them, preventing duplication and enabling modular design.

Example:

jsonCopy
{
  "definitions": {
    "address": {
      "type": "object",
      "properties": {
        "street": { "type": "string" },
        "city": { "type": "string" }
      }
    }
  },
  "type": "object",
  "properties": {
    "billingAddress": { "$ref": "#/definitions/address" },
    "shippingAddress": { "$ref": "#/definitions/address" }
  }
}

This ensures both addresses follow the exact same structure.

JSON Schema provides a rich set of keywords for precise control over validation logic. Core keywords include:

• type: The fundamental data type.
• properties, required: For object validation.
• items, minItems, maxItems: For array validation.
• enum: Restricts value to a fixed set.
• allOf, anyOf, oneOf, not: For combining schemas with boolean logic.
• format: For semantic validation of strings (e.g., date-time, email, uri). This vocabulary allows the schema to express complex business logic and data quality rules.

JSON Schema is developed through IETF drafts. The most widely implemented versions are Draft-07, 2019-09, and 2020-12. Each draft adds new keywords and refines behavior. A schema must declare its $schema keyword (e.g., https://json-schema.org/draft/2020-12/schema) to indicate which set of rules validators should apply. This ensures consistent interpretation across different tools and libraries.

A JSON Schema serves a dual purpose:

1. Machine Readable: Validation libraries (like jsonschema in Python or ajv in JavaScript) can automatically test data compliance.
2. Human Readable: The schema acts as living documentation. Developers and API consumers can read the schema to understand exactly what data is expected without consulting separate, potentially outdated, documentation. This characteristic is fundamental to its role in data contracts and API specifications.

Type enforcement is the verification that data values conform to declared type definitions (e.g., string, integer, boolean). This can occur at compile-time (static) or runtime (dynamic).

• Static Checking: Catches type errors before code execution, common in languages like TypeScript.
• Dynamic Validation: Checks types during program runtime, as performed by Pydantic or JSON Schema validators.
• Purpose: Prevents runtime errors and ensures data integrity when AI models interact with strictly-typed APIs and databases.

Output parsing is the process of converting the raw, unstructured text from a language model into a structured, machine-readable format like a Python object or JSON dictionary.

• Challenge: LLMs naturally produce free-form text, which is unreliable for direct code integration.
• Solution: Parsing libraries use techniques like guided generation or regex extraction to map text to a schema.
• Result: Enables the direct use of LLM outputs in software logic, such as populating function arguments or database records.

JSON Mode is a configuration option for language model APIs (e.g., OpenAI's GPT-4) that instructs the model to guarantee its response will be valid, parseable JSON.

• Guarantee: The model is constrained to output only JSON, significantly reducing the chance of malformed responses.
• Usage: Typically paired with a JSON Schema provided in the system prompt to define the exact structure.
• Benefit: Eliminates the need for complex, error-prone post-processing to extract structured data from text blocks.

Schema-guided generation is a technique where a language model's output is constrained and directed by a formal schema definition, such as JSON Schema or a Pydantic model.

• Mechanism: The schema is provided to the model as part of the prompt or via a specialized API parameter, acting as a blueprint for the response.
• Contrasts with post-hoc parsing by ensuring the model's reasoning process aligns with the required structure from the start.
• Application: Critical for generating type-safe API calls and database queries where format is non-negotiable.

A data contract is a formal specification that defines the structure, semantics, and quality requirements for data exchanged between systems, such as between an AI agent and an API.

• Formats: Often implemented using JSON Schema, Protobuf, or OpenAPI specifications.
• Components: Includes type definitions, allowed value ranges, required fields, and documentation.
• Role: Serves as a single source of truth for both producers (the AI) and consumers (backend services), enabling contract enforcement and reducing integration errors.