[go-fan] Go Module Review: santhosh-tekuri jsonschema v6

[github-actions]

Module Overview

github.com/santhosh-tekuri/jsonschema/v6 (pinned v6.0.3) is the dependency-free JSON
Schema validator (drafts 4/6/7/2019-09/2020-12) that backs every schema-driven validation
path in gh-aw: workflow frontmatter, MCP config, repo config, aw manifest, and per-tool
samples: validation for safe-outputs.

Current Usage in gh-aw

• Files: 9 non-test .go files import it directly.
• Key call sites:
  • pkg/parser/schema_compiler.go — shared CompileSchema/compileSchema helper; compiles
    and caches (via syncutil.OnceLoader) the 4 embedded schemas (main workflow, MCP config,
    repo config, aw manifest).
  • pkg/parser/json_path_locator.go — converts *jsonschema.ValidationError causes into
    YAML source locations for compiler-style diagnostics.
  • pkg/workflow/schema_validation.go — validates parsed workflow YAML, unwraps
    *jsonschema.ValidationError via errors.As to add field-specific examples.
  • pkg/workflow/awf_config_schema.go, pkg/workflow/schema_utils.go — AWF config schema
    compile/cache and a thin re-export.
  • pkg/workflow/samples_validation.go — compiles per-MCP-tool inputSchemas from
    safe_outputs_tools.json on demand and validates samples: entries against them.
• APIs used: NewCompiler/AddResource/Compile, Schema.Validate(any) (validates
  already-decoded YAML/JSON — no marshal roundtrip), *jsonschema.ValidationError
  (.Causes, .InstanceLocation, .ErrorKind), and the jsonschema/v6/kind package
  (kind.AdditionalProperties, kind.OneOf/AnyOf/AllOf/Group) for structural error
  inspection.

Research Findings

⚠️ Network access was unavailable this run — gh api, WebFetch, and WebSearch all
failed (no outbound network / invalid GH_TOKEN in this sandbox), so I could not confirm the
latest release, changelog, or maintainer-recommended patterns for v6.0.3 against upstream.
Filed a separate missing_tool note for this. The findings below come from static analysis
of gh-aw's own usage plus documented/known behavior of the library and the JSON Schema spec.

Already-good practice: pkg/parser/json_path_locator.go prefers the structural
ErrorKind API (e.g. reading ap.Properties off a *kind.AdditionalProperties) over
regexing the error message — this is exactly the idiomatic v6 pattern and should be the
template for any new error-parsing code in this package. Schema.Validate(any) is also used
directly on decoded YAML/JSON without a round-trip, which is the efficient path the library
is designed for.

Improvement Opportunities

🏃 Quick Wins

• Declared format constraints are silently unenforced. pkg/parser/schemas/main_workflow_schema.json
  (draft-07) declares "format": "date" for the custom-agent metadata expires field and
  "format": "uri" for the docs field and two OIDC audience fields. Per JSON Schema
  semantics, format is annotation-only unless the compiler explicitly enables assertion —
  none of the compileSchema/CompileSchema call sites configure format assertion on the
  jsonschema.Compiler. In practice, expires: not-a-date or audience: "not a uri" in
  workflow frontmatter currently passes schema validation silently. Recommend either enabling
  format assertion on the compiler (confirm the exact v6 API once docs are reachable) so these
  4 fields are actually checked, or adding a short comment at the compile call sites noting
  format is intentionally advisory-only (and verifying these fields aren't hand-validated
  elsewhere, which would make the schema annotation misleading).

✨ Feature Opportunities

• additionalPropertyNamesFor in json_path_locator.go only structurally destructures
  *kind.AdditionalProperties directly; for composite kinds (OneOf/AnyOf/AllOf/Group)
  it falls back to regexing the error message. If those composite kinds expose child causes
  structurally (mirroring how ValidationError.Causes is already walked elsewhere in this
  file), recursively walking them to find a nested *kind.AdditionalProperties would let the
  regex fallback be dropped entirely — completing the fully-structural approach the file has
  already moved most of the way toward.

📐 Best Practice Alignment

• No changes needed for schema compilation/caching: every compile site goes through the
  shared helper and every compiled *Schema is cached behind a syncutil.OnceLoader, matching
  the library's guidance that compiled schemas are safe for concurrent reuse.

🔧 General Improvements

• None beyond the above — usage is otherwise clean and idiomatic.

Recommendations

1. Decide whether the 4 format-constrained fields (expires, docs, both audience
   fields) should actually be enforced at schema-validation time; if yes, enable format
   assertion on the compiler used by pkg/parser/schema_compiler.go.
2. Extend additionalPropertyNamesFor to structurally walk composite ErrorKinds instead of
   falling back to regex.
3. Re-run this review once network access is restored to confirm no new v6 release changes
   any of the above (e.g. a new opt-in for format assertion, or additional kind helpers).

Next Steps

• Small follow-up PR to enable/clarify format assertion behavior on the 4 affected fields.
• Small follow-up PR to make additionalPropertyNamesFor fully structural for composite kinds.

---

Generated by Go Fan 🐹
Module summary saved to: scratchpad/mods/jsonschema-v6.md

Generated by 🐹 Go Fan · claude · agent · 139.1 AIC · ⌖ 7.07 AIC · ⊞ 8.2K · ◷

• expires on Aug 28, 2026, 3:24 AM UTC-08:00