schema validation with jsonschema, orgs

docs/schema_validation.md

@@ -1,24 +1,29 @@
 # Schema Validation Boundary
 
 `wf_core` uses `SchemaRef` to carry JSON-schema-like shapes on workflow input,
-node input, node output, and workflow output. The current runtime does not
-implement full JSON Schema validation.
+node input, node output, and workflow output. Runtime payload validation is
+delegated to the existing `jsonschema` library.
 
 ## Current Behavior
 
-`wf_core.runtime.ops.schemas.validate_payload_against_schema` currently checks:
+`wf_core.runtime.ops.schemas.validate_payload_against_schema` currently:
 
-- if `schema.type == "object"`, the payload must be a `dict`
-- required top-level keys must be present
+- converts `SchemaRef` into a JSON Schema dictionary
+- asks `jsonschema` to validate the schema itself
+- asks `jsonschema` to validate the payload
+- wraps validation failures in `WorkflowExecutionError`
 
-It does not currently check:
+This means normal JSON Schema checks such as object shape, required fields,
+property types, nested required fields, arrays, and item types are enforced by
+the library.
 
-- property value types, such as `string`, `boolean`, `array`, or nested objects
-- array item schemas
-- `additionalProperties`
-- formats, enums, minimums, maximums, unions, discriminators, or nested required
-  fields
-- whether a schema is valid JSON Schema
+It still does not solve:
+
+- semantic compatibility between Pydantic-generated schemas and every possible
+  external JSON Schema dialect
+- typed Python object creation from arbitrary JSON Schema
+- workflow state merge behavior
+- better domain-specific error payloads beyond `WorkflowExecutionError`
 
 This means schema fields are mostly contracts for authoring, planning,
 documentation, and mapping validation today. They are not yet strong runtime
@@ -26,39 +31,34 @@ guards.
 
 ## Why This Matters
 
-The engine currently looks stricter than it is. A node can return a required
-field with the wrong type and pass runtime validation as long as the field is
-present. That is acceptable during early design work, but it is a real product
-boundary before workflows are generated by an LLM or backed by arbitrary MCP
-tools.
+Node and workflow boundaries can now reject wrong primitive/container types when
+the schema declares them. This matters before workflows are generated by an LLM
+or backed by arbitrary MCP tools.
 
 ## Intended Seam
 
-The schema adapter should live behind:
+The schema adapter lives behind:
 
 ```text
 wf_core.runtime.ops.schemas.validate_payload_against_schema
 ```
 
 Callers should not choose or invoke the validation backend directly. The runtime
-should keep one small validation interface and hide whether the implementation
-uses Pydantic, `jsonschema`, a generated model cache, or a stricter custom
-adapter.
+keeps one small validation interface and hides the validation backend.
 
 ## Future Requirements
 
 - Validate workflow input, node input, node output, and final workflow output
   with the same semantics.
 - Return errors that name the failing boundary and path.
-- Avoid silently accepting unsupported schema features once schemas are
-  user/LLM-authored.
 - Keep schema validation separate from graph structure validation.
 - Keep `wf_authoring` free to generate schemas from Pydantic models without
   making the core runtime depend on authoring internals.
+- Add targeted tests as externally sourced schemas grow more complex.
 
 ## Non-Goals For Now
 
 - Do not add ad hoc type checks throughout runtime state operations.
 - Do not let each node wrapper invent separate validation behavior.
 - Do not conflate graph validation with payload validation.
-
+- Do not hand-write a general JSON Schema implementation.

docs/wf_core_architecture.md

@@ -65,9 +65,9 @@ raising at the first failure.
 ## Schema Validation
 
 Payload schema validation is intentionally isolated behind
-`wf_core.runtime.ops.schemas.validate_payload_against_schema`. That function is
-not a full JSON Schema engine today; see `docs/schema_validation.md` for the
-current limits and intended adapter seam.
+`wf_core.runtime.ops.schemas.validate_payload_against_schema` and delegated to
+the `jsonschema` library. See `docs/schema_validation.md` for the current
+limits and intended adapter seam.
 
 ## What This Cleanup Does Not Solve Yet
 
@@ -79,5 +79,5 @@ current limits and intended adapter seam.
 - Runtime errors are still ordinary exceptions plus failed run status. A richer
   error payload can be added later, but should be designed as part of trace/run
   state rather than scattered exceptions.
-- Payload schema validation is still shallow. The runtime checks object payloads
-  and required top-level keys, not full JSON Schema semantics.
+- Payload schema validation depends on JSON Schema semantics. If external tools
+  emit unusual schema dialects, add compatibility tests before adapting them.