jspg/GEMINI.md

Gemini Project Overview: jspg

This document outlines the purpose of the jspg project and the specific modifications made to the vendored boon JSON schema validator crate.

What is jspg?

jspg is a PostgreSQL extension written in Rust using the pgrx framework. Its primary function is to provide fast, in-database JSON schema validation against the 2020-12 draft of the JSON Schema specification.

It works by:

1. Exposing a SQL function, cache_json_schemas(...), which takes arrays of schema objects, compiles them, and caches them in memory.
2. Exposing a SQL validation function, validate_json_schema(schema_id, instance), which validates a JSONB instance against one of the pre-cached schemas.
3. Using a locally modified (vendored) version of the boon crate to perform the validation, allowing for custom enhancements to its core logic.

boon Crate Modifications

The version of boon located in the validator/ directory has been modified to address specific requirements of the jspg project. The key deviations from the upstream boon crate are as follows:

1. Recursive Runtime Strictness Control

• Problem: The jspg project requires that certain schemas enforce a strict "no extra properties" policy (specifically, schemas for public puncs and global types). This strictness needs to cascade through the entire validation hierarchy, including all nested objects and $ref chains. A compile-time flag was unsuitable because it would incorrectly apply strictness to shared, reusable schemas.

• Solution: A runtime validation option was implemented to enforce strictness recursively.

  1. A ValidationOptions { be_strict: bool } struct was added. The jspg code in src/lib.rs determines whether a validation run should be strict (based on the punc's public flag or if validating a global type) and passes the appropriate option to the validator.
  2. The be_strict option is propagated through the entire recursive validation process. A bug was fixed in _validate_self (which handles $refs) to ensure that the sub-validator is always initialized to track unevaluated properties when be_strict is enabled. Previously, tracking was only initiated if the parent was already tracking unevaluated properties, causing strictness to be dropped across certain $ref boundaries.
  3. At any time, if unevaluatedProperties or additionalProperties is found in the schema, it should override the strict (or non-strict) validation at that level.