Skip to content

fix(rover-ctl,rover-server): keep key order of API specifications - #871

Draft
ron96g wants to merge 1 commit into
mainfrom
agents/openapi-specs-investigation-process
Draft

ron96g wants to merge 1 commit into
mainfrom
agents/openapi-specs-investigation-process

Conversation

@ron96g

@ron96g ron96g commented Nov 17, 2026

Copy link
Copy Markdown
Member

What

API specifications now keep the author's key order end to end:

  • rover-ctl decodes YAML once in goccy's ordered mode (anchors, aliases and merge keys resolved, comments dropped) and sends the specification as JSON in source order. JSON files are sent as written.
  • rover-server receives specification as json.RawMessage (x-go-type in api/openapi.yaml, request and response). specToYAML converts it with goccy into 2-space YAML in the same order. That YAML is hashed, linted and uploaded to the file-manager. On read, specToJSON returns the stored YAML as JSON in stored order.
  • roverctl resource get / list keep responses as json.RawMessage, so their JSON and YAML output shows the server's order for every resource type.

Why

Before, both sides decoded specifications into Go maps. As a result:

  • The stored YAML had alphabetically sorted keys and 4-space indentation.
  • Integers of 1,000,000 or more were stored as 1e+06, which libopenapi reads as 0 for fields like maxLength.
  • Integers above 2^53 lost precision.
  • GET returned keys in random order, because sonic doesn't sort map keys.

What reviewers should know

  • One-time re-upload: every existing specification gets a new hash on its next apply and is uploaded once more. The file ID is reused and the Api resource is unchanged. After that, unchanged specs hit the hash shortcut again.
  • Reordering keys now changes the hash. Before, keys were sorted, so the order didn't matter.
  • Older rover-ctl versions still work, but send sorted keys. A team that mixes old and new rover-ctl on the same spec will re-upload on every apply until everyone upgrades.
  • Duplicate keys and empty, null or non-object specifications are now rejected with 400.
  • Known goccy limits (rare in OpenAPI documents):
    • 1.50 is stored as 1.5.
    • 1e+06 comes back from GET as a string, which also affects old specs until they're applied again.
    • A key literally named "<<" is read back as a merge key.
    • Control characters cause GET to fail with a 500 instead of returning invalid JSON.
  • Dependencies: none new. goccy/go-yaml moves from indirect to direct in rover-server's go.mod, at the same version.
  • Docs: user-journey/exposing-apis.mdx describes how a specification is stored and corrects the old claim that it is "stored unchanged". architecture/rover.mdx describes the format.

Verification

  • make test passes in rover-ctl and rover-server (controller suite 345/345), including new tests for both conversion helpers, the upload bytes, the read-back order, roverctl resource get output order and the anchor tests from 0cb6605b.
  • code-auditor: staged audit clean, and the pre-commit and pre-push gates pass.

API specifications were decoded into Go maps on both sides, so the stored
YAML had alphabetically sorted keys, 4-space indentation, and integers of
1,000,000 or more written as 1e+06. Reading a specification back returned
its keys in random order.

rover-ctl now decodes YAML once in ordered mode and sends the specification
as JSON in source order. rover-server keeps the specification as raw JSON
and converts it with goccy/go-yaml into 2-space YAML in the same order,
and back into JSON in stored order on read. roverctl resource get/list
keeps the server's order in its output.

Existing specifications get a new hash and are uploaded once more on their
next apply; the file ID and the Api resource stay the same.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@ron96g ron96g self-assigned this Nov 17, 2026

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant