Context and request
Three verbs in the data-module vocabulary collide with cmdlets that ship in PowerShell 7: ConvertFrom-Json, ConvertTo-Json, and Test-Json. Module types states that every conversion goes through the neutral object model and that a data module should "always ship both directions", and it names Json as a module following that pattern — but it does not say what happens when the platform already owns those names.
Right now the gap is silent. A reader comparing Json to Hashtable sees a module missing three of the eight verbs with no explanation, and a maintainer generating a new module from the archetype has no guidance on the collision. This needs a recorded position, not an assumption.
Acceptance criteria.
- A decision is recorded for each of
ConvertFrom-Json, ConvertTo-Json, and Test-Json: defer to the built-in, wrap it, or ship a differently-named command.
- The reasoning is written where a user will encounter it — the README, comment-based help, or a
docs/ page — not only in this issue.
- The decision does not shadow or override any built-in cmdlet.
- If
Json defers, the documentation says so plainly, so a user does not go looking for a command that intentionally does not exist.
- A follow-up is raised against
PSModule/docs so the archetype page covers built-in collisions for every data module, not just this one.
Technical decisions
This is a decision-and-documentation deliverable, not an implementation. If the decision turns out to require new commands, those become separate Tasks.
The strong default is to defer to the built-ins. ConvertFrom-Json, ConvertTo-Json, and Test-Json are well understood and widely used; redefining them inside a module people import for convenience would change the meaning of existing scripts the moment the module is loaded. Module command resolution favours the most recently imported module, so shipping same-named commands is not a theoretical risk — it is a live one.
Wrapping is worth considering only where the module can add something the built-in cannot. ConvertTo-Json's depth defaults and truncation warnings are a genuine sharp edge — which is exactly what the Export-Json depth defect was a symptom of — so there may be a case for a differently-named helper. That case has to be made explicitly, not assumed.
Test-Json has the weakest case for duplication: the built-in already supports schema validation.
The archetype page is the more valuable output here. Json is not the only data module that will hit this, and the guidance should live centrally rather than being rediscovered per module.
Implementation plan
Context and request
Three verbs in the data-module vocabulary collide with cmdlets that ship in PowerShell 7:
ConvertFrom-Json,ConvertTo-Json, andTest-Json. Module types states that every conversion goes through the neutral object model and that a data module should "always ship both directions", and it namesJsonas a module following that pattern — but it does not say what happens when the platform already owns those names.Right now the gap is silent. A reader comparing
JsontoHashtablesees a module missing three of the eight verbs with no explanation, and a maintainer generating a new module from the archetype has no guidance on the collision. This needs a recorded position, not an assumption.Acceptance criteria.
ConvertFrom-Json,ConvertTo-Json, andTest-Json: defer to the built-in, wrap it, or ship a differently-named command.docs/page — not only in this issue.Jsondefers, the documentation says so plainly, so a user does not go looking for a command that intentionally does not exist.PSModule/docsso the archetype page covers built-in collisions for every data module, not just this one.Technical decisions
This is a decision-and-documentation deliverable, not an implementation. If the decision turns out to require new commands, those become separate Tasks.
The strong default is to defer to the built-ins.
ConvertFrom-Json,ConvertTo-Json, andTest-Jsonare well understood and widely used; redefining them inside a module people import for convenience would change the meaning of existing scripts the moment the module is loaded. Module command resolution favours the most recently imported module, so shipping same-named commands is not a theoretical risk — it is a live one.Wrapping is worth considering only where the module can add something the built-in cannot.
ConvertTo-Json's depth defaults and truncation warnings are a genuine sharp edge — which is exactly what theExport-Jsondepth defect was a symptom of — so there may be a case for a differently-named helper. That case has to be made explicitly, not assumed.Test-Jsonhas the weakest case for duplication: the built-in already supports schema validation.The archetype page is the more valuable output here.
Jsonis not the only data module that will hit this, and the guidance should live centrally rather than being rediscovered per module.Implementation plan
ConvertFrom-Json,ConvertTo-Json, andTest-Jsonon the supported PowerShell LTSPSModule/docsto cover built-in collisions on the data-module archetype page