chore: formalize validation error issues field (#3059)

[SkeletonMan2k21]

Summary

Adds issues[] to the core error schema as a formal optional field for structured validation errors.

This formalizes behavior that could already appear as an extension and aligns the schema with current buyer-facing guidance, while preserving compatibility for existing consumers.

Approach

The change is additive and compatibility-focused:

• issues[] is optional
• field remains present for existing consumers
• issues[].pointer uses JSON Pointer format, matching current documented guidance
• issues[].keyword is optional so implementations are not forced to invent placeholder values
• issues[].schemaPath is optional debug metadata, with guidance against exposing it in production responses by default

Rationale

Because the error schema already allowed additional properties, issues[] could already appear as an extension. Defining it explicitly in core/error.json makes that shape documented and interoperable for clients that want structured validation details.

The goal is to standardize the schema contract, not redesign validation behavior.

Validation

• JSON schema parses successfully
• Targeted schema/example/extensibility tests pass locally
• Full pre-commit passes locally in my current environment

Notes

Also updates buyer-facing docs/skill guidance and adds regression coverage for empty issues[], optional keyword, compatibility of field, and non-normative issue extensions.

[bokelley]

Thanks for the careful work here — the plan doc shows the right shape of analysis and most of your resolved-decisions list matches where the spec landed.

Heads up: this was superseded by #3562, which merged 2026-04-29 and closed #3059. A few places where #3562 made different calls worth knowing about for future PRs in this area:

• Versioned as minor with a changeset. New optional field on core/error.json is a published-schema change, so it needs a .changeset/ entry (adcontextprotocol: minor), not chore:.
• field ↔ issues[0].pointer is a deterministic dual-write, not two parallel encodings. When issues is present, sellers MUST set field to issues[0].pointer translated RFC 6901 → JSONPath-lite (/packages/0/targeting → packages[0].targeting). That avoids buyers carrying two decoders forever and lets field cleanly deprecate later.
• keyword kept required, matching the original issue proposal — your optional framing was defensible (non-AJV sellers), but the ecosystem already converges on JSON Schema vocabulary and required sets a higher floor for agent recovery.
• schemaPath SHOULD-NOT lives in the schema description, not just narrative docs — schema-level normative language is stronger against fingerprinting.
• variants[] was not standardized, even as a documented extension. After spec(error): standardize VALIDATION_ERROR issues[] on core/error.json (closes #3059) #3562, leaving variant guidance in calling-an-agent.mdx / SKILL.md would drift from the normative contract.

Also independent of all that: issue-3059-issues-array-plan.md at the repo root is a working doc and shouldn't be committed — convention is to keep planning files out of the tree.

Closing this one out. Appreciate the writeup either way.