@texaryn/schema-json 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @texaryn/schema-json
 
+## 0.8.0
+
+### Minor Changes
+
+- 8605d64: Adds opt-in projected submissions and rejects reference scope collisions that give validation and projection different assertions. The runtime validates and submits the same independent snapshot while retaining live form data.
+- 82f38e9: Add explicit view expansion for recursion and budget boundaries.
+- 8605d64: Adds host supplied external schema resolution with a configurable resource limit.
+- 82f38e9: Adds opt in dynamic scope projection for supported local references and host supplied external resources.
+
+### Patch Changes
+
+- 1adb31d: Patches dependent schema reduction and includes the fixed runtime in published adapter builds, so invalid `oneOf` dependencies remain projectable for installed consumers.
+- 8605d64: Corrects projection through `allOf` references and applies dialect-specific defaults beside `$ref`.
+- 8605d64: Preserves inherited dialects and Draft 7 identifiers when compiling retrieved schemas.
+- 6f6bd70: Projects fields from retained inactive conditional branches and keeps them aligned with Hyperjump.
+- 8605d64: Projects fields from the selected Draft 7 `then` or `else` reference.
+- 82f38e9: Reuse static property candidates across data projections and skip reductions that cannot change an object's projected shape.
+- 82f38e9: Avoid repeated branch validation for missing values during a single schema projection.
+- 8605d64: Projects existing and required fields governed by `additionalProperties`.
+- Updated dependencies [8605d64]
+- Updated dependencies [82f38e9]
+- Updated dependencies [8605d64]
+  - @texaryn/core@0.14.0
+
+## 0.7.1
+
+### Patch Changes
+
+- 3af1cf7: Projecting a schema whose `items` is the boolean `false` no longer throws in 2020-12. A tuple closed with `prefixItems` and `items: false` projects as an array.
+- d959520: Validation and projection no longer throw for a data key named like an `Object.prototype` member, such as `__proto__`, `constructor` or `toString`. The key is validated like any other key.
+- eab920a: Validation errors report RFC 6901 pointers for property names that contain `/` or `~`. A missing required field named `a/b` is reported at `/a~1b`, so `validateAt` and the association of an error with its field find it.
+
 ## 0.7.0
 
 ### Minor Changes

package/README.md

@@ -85,6 +85,7 @@ The adapter currently handles the schema features required by Texaryn's runtime
 - arrays
 - enums
 - local `$ref`, including recursive references
+- opt-in dynamic scope projection for supported `$dynamicRef` and `$recursiveRef` paths
 - `if` / `then` / `else`
 - `oneOf`
 - `anyOf`
@@ -101,13 +102,32 @@ A local `$ref` may point back to a schema that contains it, such as `{ propertie
 
 `boundaries` on an object's `NodeProjection` says why the projection withheld something beneath it: `recursion` when a descendant would repeat the object's schemas, `budget` when a fixed per-projection limit withheld members. The limits are 16 objects and 512 nodes, counted only over locations that exist because of the recursion, two or more levels below the data; they never cut a member of a location that holds data. A node the projection reached only by expanding the recursion carries `recursiveExpansion`, and `schema-defaults` initialization never writes there.
 
+`boundaryTargets` has the next withheld instance pointer for each boundary reason, with a generation scoped token. Pass selected tokens to `project(data, { expandedBoundaryTokens })` to reveal those locations. The runtime also supplies `boundaryGeneration`; direct adapter callers can leave it at zero or increment it whenever replacing a container changes pointer ownership. Each token admits one target. The built in renderers show one action per boundary reason on an object and advance one target per click, so a large budget boundary does not create a button for every withheld field. Expansion changes the view only. It does not write form data, affect validation, or change initialization. React, React Bootstrap, React MUI, Vue, and Web Components provide these actions by default.
+
 A schema that applies itself at one instance location without crossing into a property or item, such as `{ allOf: [{ $ref: '#' }] }`, makes the evaluator recurse without end, so `createJsonSchemaAdapter` rejects it with `SameLocationCycleError`. Its `positions` field lists the schema positions of each cycle, and the message names one of them and the path through the cycle. The check reads the schema, not the data: a cycle behind an `if` is rejected even while the `if` does not hold, except the branches the specification never evaluates. It is conservative for dynamic references, treating a `$dynamicRef` to a `$dynamicAnchor` as reaching every `$dynamicAnchor` of that name and a `$recursiveRef` as reaching every schema that declares `$recursiveAnchor: true`, so a schema whose dynamic references could close such a cycle is rejected even when no evaluation selects it.
 
 The [JSON Schema support guide](https://texaryn.github.io/texaryn/guides/json-schema-support/#recursive-references) has the details, and ADR-007 records the decision.
 
+## Dynamic reference projection
+
+Dynamic scope aware form projection is opt in with `dynamicReferenceProjection: 'local'`. It supports Draft 2020-12 `$dynamicRef` and Draft 2019-09 `$recursiveRef: '#'` under object properties or homogeneous array items, including references reached through `allOf`, `anyOf`, `oneOf`, conditionals and `dependentSchemas`.
+
+External dynamic references use the host supplied `resolveResource` callback. The adapter does not fetch schemas. Without the option, the projector does not follow the active dynamic scope. The option rejects references below unsupported applicators and array keywords, root relative resource identifiers, and unsupported reference siblings. See [ADR-010](../../docs/adr/010-local-dynamic-reference-projection.md) for the exact boundaries.
+
+```ts
+const adapter = await createJsonSchemaAdapter(schema, {
+  dynamicReferenceProjection: 'local',
+  resolveResource: (uri) => schemaResources.get(uri),
+})
+```
+
+Adapter creation also rejects a retained static `$ref` when json-schema-library resolves it to different declarations with different validation assertions in the validation tree and the normalised projection tree. The check covers the dialect's supported assertions, including boolean subschemas. The error is `ProjectionValidationDivergenceError`.
+
+The adapter exposes `projectSubmission(data)` for supported schemas. It removes values declared only by inactive branches, keeps provisional fields, and preserves undeclared data so validation can still reject it. This opt-in treats an inactive declaration as form data to omit even when an enclosing object allows additional properties. `createFormRuntime` selects the mode with `submission: 'projected'`; it validates and submits the same independent snapshot, while the form's live data stays unchanged. Schemas with dynamic references or `unevaluatedProperties` or `unevaluatedItems` do not expose this capability yet. The private Hyperjump adapter also does not expose it. Runtime creation fails if projected submission is requested without the capability.
+
 ## json-schema-library version
 
-The dependency range is `~11.6.2`. In Draft 7, json-schema-library 11.6.2 overwrites the registry entry that `"$ref": "#"` resolves through, so without a fix the reference reaches another node and validation is wrong. The adapter pins that entry to the document root, and every other entry the library files for its own location to the node compiled there, so a reduction during projection cannot replace a definition with a reduced copy. Because the fix depends on the library's internal registry, adapter creation throws an error naming json-schema-library 11.6.2 when the registry is shaped differently, or when a self-test on two probe schemas shows the fix no longer repairs validation. A new json-schema-library minor needs a Texaryn release that verifies the internal again.
+The dependency is pinned to exactly `11.6.2`. In Draft 7, json-schema-library 11.6.2 overwrites the registry entry that `"$ref": "#"` resolves through, so without a fix the reference reaches another node and validation is wrong. The adapter pins that entry to the document root, and every other entry the library files for its own location to the node compiled there, so a reduction during projection cannot replace a definition with a reduced copy. Because the fix depends on the library's internal registry, adapter creation throws an error naming json-schema-library 11.6.2 when the registry is shaped differently, or when a self-test on two probe schemas shows the fix no longer repairs validation. A newer json-schema-library release is not installed until a Texaryn release raises the pin after the registry fix and its self-test pass against it.
 
 ## Validation
 
@@ -134,6 +154,10 @@ interface ValidationError {
 
 Required-property errors are located at the missing property pointer rather than only at the parent object.
 
+`instancePointer` is an RFC 6901 pointer: a property named `a/b` is `/a~1b`, and `a~b` is `/a~0b`. json-schema-library joins property names into its own error pointers without escaping, so the adapter recovers the real keys from the validated data. Two locations whose keys read the same once joined, such as `a/b` holding `c` next to `a` holding `b/c`, are told apart by the value the error reports. When both hold equal values and only one fails, the error is located at the first of them in key order, until json-schema-library escapes at the source (sagold/json-schema-library#130). `params` is json-schema-library's raw error data, and its pointers are not escaped.
+
+A data key named like an `Object.prototype` member (`__proto__`, `constructor`, `toString`) validates and projects like any other key. The one exception is a schema that combines `patternProperties` with `additionalProperties: false`: json-schema-library reads that schema's plain `properties` object, so it treats such an undeclared key as declared.
+
 ## Scoped validation
 
 This adapter also implements the optional `validateAt()` port method:
@@ -149,6 +173,7 @@ The result contains validation errors at that pointer or below it.
 ```ts
 import {
   createJsonSchemaAdapter,
+  ProjectionValidationDivergenceError,
   SameLocationCycleError,
   type AdapterConfig,
   type Dialect,
@@ -170,6 +195,9 @@ const adapter = await createJsonSchemaAdapter(schema, {
 ```ts
 interface AdapterConfig {
   defaultDialect?: Dialect
+  dynamicReferenceProjection?: 'local'
+  resolveResource?: (uri: string) => unknown | undefined | Promise<unknown | undefined>
+  maxExternalResources?: number
 }
 ```
 
@@ -194,6 +222,10 @@ try {
 }
 ```
 
+### `ProjectionValidationDivergenceError`
+
+Thrown by `createJsonSchemaAdapter` when one retained static `$ref` resolves to different declarations with different validation assertions for validation and projection. Its `reference` and `sourcePosition` identify the reference site. `validationPosition` and `projectionPosition` identify the two resolved schema positions.
+
 ## Architecture
 
 The adapter is deliberately separate from `@texaryn/core`:

package/THIRD-PARTY-NOTICES.md

@@ -1,5 +1,12 @@
 # Third-party notices
 
+## json-schema-library
+
+The ESM runtime at `dist/vendor/json-schema-library/` is adapted from
+`json-schema-library` 11.6.2 by Sascha Goldhofer and is distributed under the
+MIT License. Its full license is included at
+`dist/vendor/json-schema-library/LICENSE.md`.
+
 ## JSON Schema metaschemas
 
 `src/metaschemas/` contains the published JSON Schema metaschema documents for

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAiBA,OAAO,EAAmC,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAIxF,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAElE,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CA8B5B"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAmC,KAAK,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAQxF,OAAO,KAAK,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAElE,wBAAsB,uBAAuB,CAC3C,MAAM,EAAE,OAAO,EACf,MAAM,CAAC,EAAE,aAAa,GACrB,OAAO,CAAC,iBAAiB,CAAC,CAE5B;AAED,wBAAsB,aAAa,CACjC,MAAM,EAAE,OAAO,EACf,MAAM,EAAE,aAAa,GAAG,SAAS,EACjC,MAAM,EAAE,gBAAgB,GACvB,OAAO,CAAC,iBAAiB,CAAC,CAwF5B"}