o1-labs / o1-labs/Archive-Node-API

Document all stable GraphQL validation error markers

Open Beginner friendly
#220 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

documentation P2 production-readiness
Dominant language
TypeScript
Stars
19
Forks
9
Avg merge
14h 20m
Merged PRs (30d)
8

Description

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

  • #198
  • #183
  • #195

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with docs/versioning.md or the schema stability policy and read #198, then locate the existing checks for the Cannot query field marker. Document Cannot query field, Unknown argument, and Unknown type as stable contract markers, including the major-release rule for masking or changing them. Add regression coverage for all three families, or record an explicit decision to accept the gap.

Written by the indexing model from the issue text.

Assessment

Tech stack
graphql, typescript
Domain
api, documentation, testing
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
76/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.