This is the question everything else rests on. Price comparison, substitution, assortment analysis and repricing are all downstream of it, and all of them silently produce nonsense when it is answered wrong.
A score between zero and one tells an agent how close two things are and nothing about how they differ, which is exactly the information a user needs to accept or reject a recommendation. So the answer is one of five relations plus the specific attributes that differ.
| Relation | Meaning | Safe to price-compare? |
|---|---|---|
| identical | Same item, same identity, same pack. | Yes. |
| variant | Same product, different size, colour or capacity. | Only after normalising to unit price. |
| substitute | Different product, same job. | No — compare value, not price. |
| successor | One supersedes the other. | No — a lower price is clearance, not a deal. |
| unrelated | No meaningful relation. | No. |
A discontinued model is almost always cheaper than its replacement. An agent that treats them as the same product concludes the older one is a bargain, when the price is actually telling it the item is being cleared. `relation: successor` with a direction prevents that, and the `guidance` field says so in words the agent can pass on.
POST /v1/equivalence
{ "a": "sony wh-1000xm4", "b": "sony wh-1000xm5" }
{ "relation": "successor", "direction": "b_supersedes_a",
"differences": [
{ "attribute": "folding", "a": true, "b": false,
"note": "XM5 does not fold — a real regression for some buyers" } ],
"guidance": "Do not treat as a price comparison." }A twelve-pack and a twenty-four-pack are `variant`, not `identical`. Comparing their sticker prices is arithmetically valid and commercially meaningless. Normalise to unit price before ranking, always.
| Setting | Treats as identical | Use for |
|---|---|---|
| exact | Only the same pack of the same item. | Repricing. A false match moves a real price. |
| practical | 500ml and 550ml of the same product. | Most things. The default. |
| loose | Two 65-inch OLED televisions. | Discovery and substitution, never pricing. |
The same model sold in a different market may have a different plug, a different voltage, a different warranty and no local support. It resolves as a `variant`, and the difference is surfaced — a price far below every domestic seller is very often this rather than a bargain.