Description
One of the simplest ways to use the tool is to simply compare lhs.json and rhs.json with a visual diffing tool like VSCode or Beyond Compare. However, these are text-based diffing tools and can be confused, especially when the object diff (which is what the tool relies on) has significant additions or departures.
Consider the following scenario:
model Fruit {
calories: int16;
}
model Apple is Fruit {
variety: "honeycrisp" | "grannySmith";
}
model Orange is Fruit {
variety: "navel" | "blood";
}
When Fruit is referenced in Swagger, the tool generates an $anyOf property with the expansion of all child classes (sorry for mangling TypeSpec and JSON syntax here!):
$anyOf: [
{ # Apple
calories: int16,
variety: "honeycrisp" | "grannySmith";
},
{ # Orange
calories: int16,
variety: "navel" | "blood";
}
]
Now imagine a scenario where the LHS has Apple as a child class, but the RHS does not. For small diffs, tooling will accurately be able to "align" the diffs, but you can imagine if the structure of Apple were much larger, eventually that matching capability of that text-based comparison is going to be exceeded and it's going to erroneously interpret Orange on the RHS as simply a redefinition of Apple. At that point, of all the diffing logic will be misaligned and not useful.
The best way to avoid this is to focus on resolving diffs where large objects are added or removed.