Skip to content

Document all stable GraphQL validation error markers #220

Description

@dkijania

Context

#198 adds an important schema stability policy and names Cannot query field as stable validation/error text. Luis' latest review notes that downstream compatibility actually depends on three literal markers:

  • Cannot query field
  • Unknown argument
  • Unknown type

mina-explorer-api matches all three to classify UpstreamSchemaError, drive tier fallback, and poison its capability cache. mina-explorer keys mostly on Cannot query field.

Follow-up work

  • Update the policy/docs so all three literal markers are named as stable downstream contract, not only Cannot query field.
  • Make it clear that changing any of the three messages, masking them, or replacing them with armor/cost-limit errors can be breaking.
  • Consider explicit regression tests for Unknown argument and Unknown type alongside the existing Cannot query field checks.

Acceptance criteria

  • docs/versioning.md or the schema stability policy names all three stable markers.
  • The docs state that validation/parse masking changes affecting these markers require a major release.
  • Regression coverage pins all three marker families, or the gap is explicitly accepted.

Related

Metadata

Metadata

Assignees

No one assigned

    Labels

    P2GA polish / hygienedocumentationImprovements or additions to documentationproduction-readinessWork toward making the API production-ready / publicly available

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions