Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Define the review and annotation experience for transformed comparisons (--flatten-allof and friends)

Open
  • Is something wrong?
#1,247 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
20/100
Issue type
Feature
Clarity
Needs clarification
Activity status
Active
Tech stack
go, openapi
Domain
design

Research direction

Start by reading #1246 (the candidate implementation) and this issue's four candidate behaviors A-D plus the per-scenario objectives, since the issue explicitly defers the decision. Map where each consumer reads coordinates: the --open review upload path, the --format githubactions annotation emitter, and the review page's block slicing/highlighting code. Done means a written decision per scenario with rationale and a chosen default, not a patch; the related merge origin-retention problem is explicitly separable.

Written by the indexing model from the issue text.

Description

#1246 fixes a real mismatch, but review discussion concluded the behavior should be derived from per-scenario user objectives before we commit to one answer. This issue is the design decision; #1246 stays open as one candidate implementation. Target: the release after the current one.

Agreed facts

  1. Console locations are always in the original files' coordinate system. Without transformations they are exact; under a transformation, a change at a synthesized or merged node degrades to the enclosing structure (measured: an edit at line 30 reported at line 5, the operation, under --flatten-allof).
  2. The review today displays the original files with original-file coordinates: text and coordinates are consistent with each other, but the change content (paths like tree/child/allOf[subschema #2]/leaf, names like AllOfMerged_NodeA_NodeB) describes the transformed document the displayed text does not contain.
  3. Default text/html output shows no line numbers, so precision there is mostly invisible to direct CLI users. The big line-number consumer is --format githubactions: the action's annotations pin to file + line on the PR's Files Changed tab, where only original-file coordinates are meaningful.
  4. On the review page, locations are consumed mechanically: block slicing and highlighting are the page's core value, so line numbers must exactly match whatever text is displayed.

The underlying trade

Displaying the original files is familiar (the user's own text and formatting) but incoherent with the changes under a transformation. Displaying the rendered compared document (#1246) is coherent (text, paths, names, locations, and blocks describe one document) but shows generated text the user did not author. Untransformed runs, the vast majority, are unaffected either way.

Scenarios to define objectives for

  • CLI user, no transformation, --open: wants their own files side by side. Status quo is right; any design must preserve it.
  • CLI user with a transformation, --open: is the objective to understand their files (favoring original text with changes translated back to source terms where possible) or to understand the compared contract (favoring the rendered document)? Possibly both, per moment.
  • Action user with a transformation: annotations must stay in original-file coordinates regardless of any review decision.
  • Review reviewer: needs location and displayed text to agree exactly, whichever text is chosen.

Candidate behaviors

A. Upload the rendered document with recomputed coordinates (#1246 as written).
B. Status quo: original text and coordinates, accepting the content mismatch and the degraded precision.
C. Upload both representations and let the review page toggle between "as authored" and "as compared" views, each with its own coordinates.
D. Make it a flag and pick a default after usage data.

Related but separable

Origin precision under flattening is its own problem: the merge does not preserve per-field origins for merged nodes, which degrades the console and the action annotations today, independent of any review decision. Improving origin retention in the merge would benefit every scenario that favors original coordinates.

Dominant language
Go
Stars
1.4k
Forks
109
Avg merge
12h 11m
Merged PRs (30d)
35

Getting set up

This project ships no dev container, Dockerfile or contributing guide, so setting up is up to you: start from its README, and see our first-contribution guide for the general steps.

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.

More from oasdiff/oasdiff

All issues in oasdiff/oasdiff

Similar issues

More Go issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.