JSON Schema

JSON Schema defines the allowed structure of a JSON document and the data types for each value. This is the foundation of contract validation.

• type Keyword: Specifies allowed types: string, number, integer, boolean, array, object, or null.
• Nested Object Validation: The properties keyword validates each field within an object, allowing for complex, nested data structures.
• Array Validation: The items keyword validates all elements within an array, which can be a single schema or a list of schemas for tuple-like data.

Example: A schema requiring an id of type integer and a name of type string will reject {"id": "abc", "name": 123}.

Beyond basic types, JSON Schema enforces detailed constraints on values to match business logic and real-world formats.

• Numeric Ranges: Use minimum, maximum, exclusiveMinimum, and exclusiveMaximum.
• String Patterns: The pattern keyword uses regular expressions (e.g., for phone numbers, IDs).
• Built-in Formats: The format keyword validates common patterns like email, uri, date-time, uuid, and hostname.
• Length Control: minLength, maxLength for strings; minItems, maxItems for arrays.

Example: {"type": "string", "format": "email", "maxLength": 254} validates a standard email address.

Schemas can be combined and made conditional using logical keywords, enabling sophisticated validation rules.

• Logical Composition: allOf (must match all schemas), anyOf (must match at least one), oneOf (must match exactly one), not (must not match).
• Conditional Schemas: The if, then, else keywords apply subschemas based on conditions.
• Schema Reuse: The $defs (definitions) section allows for reusable schema components referenced with $ref.

Example: A discount field might be required (then) only if customerType is "premium" (if).

JSON Schema can enforce relationships between data points and guarantee uniqueness within a dataset.

• Required Properties: The required keyword lists object keys that must be present.
• Property Dependencies: dependentRequired makes certain properties required if a given property is present.
• Uniqueness: The uniqueItems keyword, when true, ensures all values in an array are distinct.
• Constant Values: The const keyword requires a field to match exactly one value.

Example: {"required": ["username", "email"], "dependentRequired": {"billing_address": ["zip_code"]}} ensures critical fields exist.

JSON Schema includes keywords that don't validate but provide human-readable documentation and processing instructions.

• Title and Description: title and description provide labels and explanatory text for tools and documentation.
• Examples: The examples keyword provides sample valid values.
• Read/Write Only: readOnly and writeOnly hints for API usage (e.g., id is read-only, password is write-only).
• Default Values: The default keyword suggests a value used if the property is absent.

These annotations are crucial for generating accurate API documentation and client libraries.

Schema enforcement is the runtime application of validation rules to guarantee data structures strictly conform to a predefined model. It is the active process triggered by a validation middleware component. Key aspects include:

• Static Validation: Checking a schema or configuration file for correctness before runtime.
• Dynamic Validation: Runtime verification of incoming/outgoing data against the schema.
• Constraint Checking: Enforcing rules on value ranges, string patterns, and array sizes.

Contract testing is a methodology for verifying that two separate systems (e.g., a client and a server) adhere to a shared API contract, such as an OpenAPI document. It ensures compatibility without full integration. Tools like Pact or Spring Cloud Contract use the schema to generate and verify mock requests and responses, catching breaking changes in API structure before deployment.

These are complementary validation layers:

• Syntactic Validation: Verifies data conforms to format and grammar rules (e.g., is this a valid JSON object? Does this string match the email regex pattern?). JSON Schema excels at this.
• Semantic Validation: Checks that data is meaningful within its business context (e.g., is the start_date before the end_date? Does the product_id exist in the inventory database?). This often requires custom business logic beyond the schema.

Payload verification is the comprehensive validation of an HTTP request or response body. It encompasses:

• Structure & Schema Conformance: Validating against a JSON Schema.
• Content-Type: Ensuring the payload matches the declared media type (e.g., application/json).
• Encoding: Checking for correct character encoding.
• Size Limits: Enforcing maximum payload sizes to prevent denial-of-service attacks. This holistic check is a primary defense against malformed or malicious data.

Validation middleware is a software component inserted into an API request/response pipeline that automatically performs input and output validation. For example, in a Node.js/Express app, middleware like express-json-validator-middleware can automatically validate every incoming request body against a provided JSON Schema before the request reaches the route handler, rejecting invalid payloads with detailed error messages.