Context and request
The data-module verb vocabulary includes Compare-<Noun> for diffing two structures. Json has no equivalent, so a user checking whether a configuration file changed meaningfully — as opposed to changing key order or whitespace — has to compare serialized text, which reports differences that are not differences.
Acceptance criteria.
Compare-Json reports the structural differences between two JSON inputs.- It accepts both JSON strings and objects, consistent with the parameter set pattern the module already uses.
- Key ordering and formatting differences are not reported as differences.
- Output identifies each difference by path, the value on each side, and the kind of change: added, removed, or changed.
- A
-PassThru-style or boolean mode answers "are these equivalent?" without the caller having to inspect a difference collection.
- It declares
[OutputType()] with matching .OUTPUTS, and carries complete comment-based help with a .LINK to https://psmodule.io/Json/Functions/Compare-Json/.
- Tests cover added, removed, and changed values, nested differences, array differences, type changes, key-order equivalence, and
null versus absent. Coverage stays at or above the 95% target.
Technical decisions
The output shape is the main design decision and needs settling before implementation. A collection of difference objects carrying Path, Difference, Reference, and Value is more useful in a pipeline than Compare-Object-style SideIndicator output, and JSON's nesting makes a path notation such as $.database.host or database/host necessary regardless. Pick one notation and document it.
Array comparison needs an explicit rule. Positional comparison is simple and predictable; matching by content or key is more useful for arrays of objects but requires the caller to say what identifies an element. Start with positional and treat key-based matching as a follow-up rather than guessing at a heuristic.
null versus absent is a real distinction in JSON and must be reported differently, not collapsed.
Depth is a parameter from the outset, for the same reason as every other traversal in this module.
Do not shadow the built-in Compare-Object; this is a new command with a JSON-specific noun, which is exactly what the vocabulary intends.
Depends on the function-standard work landing first so this is written against the corrected patterns.
Implementation plan
Context and request
The data-module verb vocabulary includes
Compare-<Noun>for diffing two structures.Jsonhas no equivalent, so a user checking whether a configuration file changed meaningfully — as opposed to changing key order or whitespace — has to compare serialized text, which reports differences that are not differences.Acceptance criteria.
Compare-Jsonreports the structural differences between two JSON inputs.-PassThru-style or boolean mode answers "are these equivalent?" without the caller having to inspect a difference collection.[OutputType()]with matching.OUTPUTS, and carries complete comment-based help with a.LINKtohttps://psmodule.io/Json/Functions/Compare-Json/.nullversus absent. Coverage stays at or above the 95% target.Technical decisions
The output shape is the main design decision and needs settling before implementation. A collection of difference objects carrying
Path,Difference,Reference, andValueis more useful in a pipeline thanCompare-Object-styleSideIndicatoroutput, and JSON's nesting makes a path notation such as$.database.hostordatabase/hostnecessary regardless. Pick one notation and document it.Array comparison needs an explicit rule. Positional comparison is simple and predictable; matching by content or key is more useful for arrays of objects but requires the caller to say what identifies an element. Start with positional and treat key-based matching as a follow-up rather than guessing at a heuristic.
nullversus absent is a real distinction in JSON and must be reported differently, not collapsed.Depth is a parameter from the outset, for the same reason as every other traversal in this module.
Do not shadow the built-in
Compare-Object; this is a new command with a JSON-specific noun, which is exactly what the vocabulary intends.Depends on the function-standard work landing first so this is written against the corrected patterns.
Implementation plan
null-versus-absent reportingnullversus absentsrc/functions/public/Compare-Json.ps1with[OutputType()], full comment-based help, and a-DepthparameterGet-Command -Module Jsonand its reference page generates