Skip to content

Generate deterministically indented OpenAPI JSON to minimize diff churn #1685

Open

Description

Summary

The generated website OpenAPI schema (website/src/openapi/scope-openapi.json) is committed as a single minified line. Small API changes therefore replace the entire line in diffs, obscuring the actual changes and creating unnecessary diff churn.

Track a fix to generate consistently indented, deterministic JSON so future diffs change only the lines corresponding to actual schema changes.

Steps to reproduce

  1. Make a small change to an API schema and regenerate the website OpenAPI specification.
  2. Inspect the diff for website/src/openapi/scope-openapi.json.
  3. The entire single-line document is replaced, even for a small schema change. See fix(api): soft-delete reports with requests #1433 for an example.

Expected behavior

  • Generate readable JSON using a fixed indentation style (for example, two spaces), consistent line endings, and a trailing newline.
  • Preserve deterministic object-key ordering so unchanged schema content does not move between generations. Do not reorder semantically meaningful arrays.
  • Repeated generation from unchanged API definitions produces byte-identical output.
  • After the one-time formatting migration, a small schema change produces a localized diff limited to the changed schema content, rather than replacing the entire document.
  • Update the snapshot test's website-file comparison to enforce the same serialization contract, and add focused regression coverage for determinism and localized diffs.
  • Regenerate and commit the website schema without changing its parsed OpenAPI content as part of the formatting migration.

Actual behavior

apps/api/src/openapi/generate.ts writes the website file using JSON.stringify(document) without indentation. apps/api/src/openapi-snapshot.test.ts explicitly compares the website file to JSON.stringify(doc), enforcing compact output. The API's separate Vitest snapshot is already formatted, but this does not affect the website JSON.

Environment and logs

Observed at commit 29d2f0517c9b573633b661620f53975e2dc28208 in #1433. Both the base and head website schema files contain zero newlines; the formatting issue predates that PR.

The goal is smaller, more reviewable line-based changes. Pretty-printing increases the initial file size; it does not by itself guarantee smaller Git pack storage.

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

Metadata

Metadata

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions