Left open by #13, which introduced this TODO while closing the surrounding section. Issue #9 did not cover it.
specifications/listing/v1/spec.md §3:
TODO — What metadata.version agrees with in a COMPONENT item, which has no blueprint. The component documents each carry their own metadata.version and an item may hold more than one, so this is not the same rule with a different sibling.
Why it matters
§3 pins a listing's version to its sibling blueprint's with ERR_VERSION_MISMATCH, and gives the reason: "A listing whose version has moved ahead of its blueprint describes something other than what would be installed."
It then carves out the case where there is no blueprint:
An item whose listing is listingKind: COMPONENT need not contain one; where there is no sibling blueprint the rule has nothing to compare and does not apply.
So a COMPONENT item's listing version is currently unconstrained, and the argument for constraining it is untouched by the absence of a blueprint — the storefront copy can still move ahead of the thing it describes.
This is the one rule where the two families are asymmetric, and the asymmetry is not a decision anyone made.
The concrete question
An item may hold more than one component document, each with its own metadata.version, so "agrees with the sibling" has no referent. The candidates:
- The item names one primary component and the listing agrees with that. Needs a way to say which, which the contract does not currently have.
- The listing version is independent for
COMPONENT items, and the carve-out stands as a decision rather than a gap. Honest, but it makes ERR_VERSION_MISMATCH mean different things in the two item shapes.
- A
COMPONENT item holds exactly one component document. Simplest, and testable — but it narrows what an item may be, which is a bigger change than it looks.
What deciding it costs
semantic, item-scoped, therefore a case tree — expressible since ADR 0002. conformance/listing/v1/semantic/003-version-disagrees-with-blueprint/ is the fixture to copy.
Option 3 is breaking. Options 1 and 2 are not.
Refs #9
Left open by #13, which introduced this TODO while closing the surrounding section. Issue #9 did not cover it.
specifications/listing/v1/spec.md§3:Why it matters
§3 pins a listing's version to its sibling blueprint's with
ERR_VERSION_MISMATCH, and gives the reason: "A listing whose version has moved ahead of its blueprint describes something other than what would be installed."It then carves out the case where there is no blueprint:
So a
COMPONENTitem's listing version is currently unconstrained, and the argument for constraining it is untouched by the absence of a blueprint — the storefront copy can still move ahead of the thing it describes.This is the one rule where the two families are asymmetric, and the asymmetry is not a decision anyone made.
The concrete question
An item may hold more than one component document, each with its own
metadata.version, so "agrees with the sibling" has no referent. The candidates:COMPONENTitems, and the carve-out stands as a decision rather than a gap. Honest, but it makesERR_VERSION_MISMATCHmean different things in the two item shapes.COMPONENTitem holds exactly one component document. Simplest, and testable — but it narrows what an item may be, which is a bigger change than it looks.What deciding it costs
semantic, item-scoped, therefore a case tree — expressible since ADR 0002.conformance/listing/v1/semantic/003-version-disagrees-with-blueprint/is the fixture to copy.Option 3 is breaking. Options 1 and 2 are not.
Refs #9