[daveshanley]

Problem

Consumers need static Arazzo 1.0/1.1 validation with useful source locations and clear evidence when linked checks cannot run. The existing OpenAPI and HTTP APIs do not provide this.

Solution

Add arazzo.Validate for existing nodes and arazzo.ValidateBytes for exactly one YAML/JSON document. Return detached diagnostics, typed tool errors and check records. Every error returns a non-nil incomplete result. Callers check the error, Valid() and Complete.

What changes

• Embed the official dated schemas with provenance, checksums and license notices; document narrow compiler-view corrections against normative text.
• Validate structure, identities, reusable objects, inheritance, input schemas, runtime expressions, selectors and document-qualified prerequisite graphs.
• Use caller-supplied OpenAPI, AsyncAPI and Arazzo sources for target and metadata checks. Validation performs no default file/network retrieval or workflow execution.
• Preserve caller nodes/models and bound source loads, alias expansion, graph work, diagnostics and parser input. Share resource totals and caches across document-local source scopes.
• Check authored inline expressions once; check inherited and reusable values at their consuming scope. Conflicting targets produce one cause while preserving independent common-field errors.
• Reuse one subschema walker, JSON Pointer parser and dependency-graph check. Remove the duplicate input metaschema pass and unused general ECMAScript fallback for embedded schema patterns.
• Add behavioral and resource-boundary tests, exported-API semantic fixtures and a mixed-source example. Keep usage guidance concise; the clause table is in arazzo/REQUIREMENTS.md.

Existing OpenAPI/HTTP behavior, dependencies, coverage configuration and thresholds are unchanged. Vacuum integration is separate.

Risk

High: this adds a public validation boundary with substantial semantic and source-resolution logic. A defect can accept an invalid document or reject a valid one. Detached results, resource limits, regression tests and independent review cover the new boundary.

Complete describes implemented static checks, not workflow execution. XPath, legacy JSONPath, runtime-substituted conditions, missing sources and partial adapters produce explicit incomplete check records. External input schemas are not retrieved.

Verification and rollout

Local verification on the published code, using Go 1.26.8 with GOWORK=off:

• Full module tests pass: 99.1% Go statement coverage overall, 100.0% in Arazzo. No coverage exclusions or threshold changes.
• Arazzo race tests, build, vet, package lint (zero issues) and go mod tidy -diff pass.
• Public regressions cover non-nil error results, target-union fallout plus independent errors, reusable override diagnostic limits, consuming input scopes, malformed referenced schema annotations, external Arazzo input schemas and shared sibling source budgets.
• Existing tests cover caller-node preservation under concurrent validation, retained-result collection, no default retrieval, alias and source limits, cross-document dependencies, source identity and cancellation.
• Independent reviews examined security, performance and memory/resource use. Reported defects were repaired and independently verified; no remaining P0-P2 findings in the reviewed scopes.

BenchmarkValidateInputs uses a supplied OpenAPI source and a closed workflow input schema. Three local samples before/after removal of duplicated validation work: median 633,243 ns/op → 69,336 ns/op, 582,025 → 85,951 B/op, and 7,540 → 1,104 allocs/op. These are fixture measurements, not a production latency claim.

Hosted verification on d80b603cbfad6ce75ec8d507205a34a7393814c3:

• Build, lint, Codecov patch and Codecov project checks pass.
• 100% patch coverage: Codecov confirms all modified and coverable lines are covered.
• Repository line coverage increased from 98.27% to 98.66% (+0.39 percentage points).
• All 14 inline review threads have evidence replies and are resolved. The overall review is addressed in the PR discussion.
• No coverage exclusions or thresholds changed. Removed unreachable guards instead of adding artificial reachability; malformed-bundle and ordering tests cover the remaining boundaries. The independent reviewer verified the dependency contracts and a mutation that removes compilation-error handling fails the regression.

See hosted checks and Codecov.

Rollout: consumers opt into the package after release; no migration or environment change. Revert the new package to remove the feature. Workflow execution and Vacuum integration remain separate work.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 98.66%. Comparing base (b1808fe) to head (d80b603).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #333      +/-   ##
==========================================
+ Coverage   98.27%   98.66%   +0.39%     
==========================================
  Files          80       94      +14     
  Lines        9481    12284    +2803     
==========================================
+ Hits         9317    12120    +2803     
  Misses        139      139              
  Partials       25       25              

Flag	Coverage Δ
unittests	98.66% <100.00%> (+0.39%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[daveshanley]

Overall

The core of this is good. The normalizer handles merge keys, recursive aliases and big numbers properly without touching the caller's nodes. The prerequisite graph is an iterative DFS. Every expansion is budgeted. The retention test with weak pointers is a nice touch, and the schema snapshots ship with provenance and checksums. That's the hard part, and it's done.

Three things before this merges.

Coverage. 77% on the package and 68% on the patch drops the module from 98% to 91%. This repo runs at 100% and the rule is simple: if a line can't be hit, it doesn't ship. Eight functions sit at 0%: inputSchemaFindings, ecmaPattern.String and MatchString, denyLoader.Load, externalResourceError.Error, inputResourceUnavailable.Error, inputRegexp.String, sourceQualified. Most of those are unreachable defensive branches (details inline), so most of this is deletion.

Duplicated work. Inline parameter expressions are recorded twice. The 2020-12 metaschema is validated against inputs twice (the official schema already does it) and compiled fresh on every call. The subschema keyword walk is copy-pasted three times. checkDependencyGraph has an inline twin in validate(). The semantic test helper runs a pipeline production never runs. Each is small. Together they make the package harder to trust than it deserves to be.

Docs. VALIDATION.md is a snapshot of one local run and belongs in the PR description, where it can't rot. README.md needs rewriting for a human: what it does, one example, what Complete means, what it won't do. Half a page.

The design choices are right: static only, no I/O without a resolver, detached results, explicit coverage records. Fix the above and this is a good package.

[daveshanley]

Addressed the overall review and all 14 inline threads. Each thread has an evidence reply and is resolved.

Final head: d80b603cbfad6ce75ec8d507205a34a7393814c3.

• Codecov patch: 100%. All modified and coverable lines are covered.
• Repository coverage: 98.27% → 98.66% (+0.39 percentage points). Coverage settings and thresholds are unchanged.
• Arazzo Go statement coverage: 100%. Full module tests, Arazzo race checks, build, vet, lint and dependency checks pass. Hosted Build, lint and both Codecov checks pass on this head.
• Removed redundant schema validation, repeated expression recording, copied schema walks, duplicate graph/pointer logic and unused fallback/guard code. Shared source totals have one owner. Semantic integration fixtures run exported Validate; explicit internal boundary tests are named and documented.
• Deleted VALIDATION.md, simplified the READMEs and put run/benchmark evidence in the PR description. The input-schema benchmark median fell from 633 us to 69 us with the same supplied-source fixture.

Two qualified points are explained in their threads: an input reference into malformed annotation data could reach the compiler-error site, so that behavior retains a public regression; deliberate schema-invalid/cancellation/limit unit tests still need direct internal boundaries. Required adapter methods and deny-load behavior remain and have meaningful boundary tests.

Independent review verified the repairs and the final dead-guard cleanup. No open findings remain in the reviewed scopes.

CI · Codecov