Skip to content

Add @stdlib/json_schema module for JSON Schema validation#443

Open
nbeerbower wants to merge 1 commit into
mainfrom
claude/json-schema-validation-Z1pVo
Open

Add @stdlib/json_schema module for JSON Schema validation#443
nbeerbower wants to merge 1 commit into
mainfrom
claude/json-schema-validation-Z1pVo

Conversation

@nbeerbower

Copy link
Copy Markdown
Collaborator

Summary

Adds a new @stdlib/json_schema module to the standard library, bringing JSON Schema validation capabilities to Hemlock. This is particularly useful for validating structured output from LLMs, API responses, configuration files, and user input.

Key Changes

  • New module: stdlib/json_schema.hml - Pure Hemlock implementation of JSON Schema Draft 7 validation (400+ lines)
  • Comprehensive documentation: stdlib/docs/json_schema.md with API reference, examples, and use cases
  • Schema builders: Helper functions for constructing schemas programmatically (string_type, object_type, array_type, nullable, enum_type, etc.)
  • Core validation functions:
    • validate(value, schema) - Returns detailed error information with paths
    • is_valid(value, schema) - Boolean-only check
    • validate_json(json_str, schema) - Parse and validate in one call
    • format_errors(errors) - Human-readable error formatting
  • Supported schema keywords: type, enum, const, required, properties, items, additionalProperties, minimum/maximum, minLength/maxLength, minItems/maxItems, uniqueItems, allOf, anyOf, oneOf, not, if/then/else
  • Comprehensive test suite: 8 test files covering arrays, objects, numbers, strings, composition, conditionals, and error reporting
  • Updated documentation: CLAUDE.md and stdlib/README.md reflect the new 43rd module

Implementation Details

  • Built as a pure Hemlock module on top of @stdlib/json with no external dependencies
  • Deep equality comparison for enum/const validation
  • Detailed error paths using dot notation (e.g., users[1].name)
  • Type checking that handles Hemlock's numeric type variants
  • Composition keywords (allOf/anyOf/oneOf/not) with proper short-circuit evaluation
  • Conditional schemas (if/then/else) for advanced validation logic

Use Cases

  • LLM structured output validation - Ensure LLM responses match expected JSON shapes
  • API response validation - Verify third-party API responses conform to contracts
  • Configuration validation - Validate config files at load time
  • Tool call argument validation - Validate arguments passed to tool functions

https://claude.ai/code/session_01Vrk4CoN6sAZBCRxvzyuBpY

Pure Hemlock module built on @stdlib/json that validates values against
JSON Schema-like definitions. Designed for validating LLM responses,
API payloads, and configuration data.

Supported schema keywords:
- Type: type (with union types), enum, const
- Numbers: minimum, maximum, exclusiveMinimum, exclusiveMaximum, multipleOf
- Strings: minLength, maxLength
- Arrays: items, minItems, maxItems, uniqueItems
- Objects: properties, required, additionalProperties, minProperties, maxProperties
- Composition: allOf, anyOf, oneOf, not, if/then/else

Includes builder helpers (string_type, object_type, nullable, etc.),
validate_json for direct string input, and format_errors for display.

8 test files covering types, numbers, strings, arrays, objects,
composition, builders, and JSON string validation.

https://claude.ai/code/session_01Vrk4CoN6sAZBCRxvzyuBpY
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants