Skip to content

Add supersedes tag and SHOULD-level guidance for product identity changes #8

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
ericfj2140 wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Add supersedes tag and SHOULD-level guidance for product identity changes #8

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3f39156
Clarify product identity mutability and add supersedes tag
ericfj2140 Dec 6, 2025
929efe9
Clarify product supersession semantics and make supersedes addressable
ericfj2140 Jan 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 12 additions & 0 deletions spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,9 @@ Products are the core element in a marketplace. Each product listing MUST contai
- `summary`: Short product description
- `spec`: Product specifications `[<key>, <value>]`, can appear multiple times

- Versioning:
- `supersedes`: Product version reference `"30402:<pubkey>:<d>"` indicating that this product is intended to replace a previous product listing. MAY appear at most once.

- Media:
- `image`: Product images `[<url>, <dimensions>, <sorting-order>]`, MAY appear multiple times
- url: Direct image URL
Expand Down Expand Up @@ -183,6 +186,7 @@ Products are the core element in a marketplace. Each product listing MUST contai
// References
["shipping_option", "<30406|30405>:<pubkey>:<d-tag>", "<extra-cost>"], // Shipping options or collection, MAY appear multiple times
["a", "30405:<pubkey>:<d-tag>"] // Product collection
["supersedes", "30402:<pubkey>:<d>"] // optional: previous product listing address
]
}
```
Expand All @@ -209,6 +213,12 @@ Products are the core element in a marketplace. Each product listing MUST contai
4. Location Support:
- Optional location data aids in local marketplace features, they can point to a collection event to inherit it's value
- Geohash enables precise location-based searches, they can point to a collection event to inherit it's value

#### Product identity and mutability

Clients MAY apply their own policies to determine when a listing update should be treated as a new product versus an in-place update. As a general guideline, if the underlying item/service being sold materially changes (e.g., a different item, variant, ingredients, or core specifications), merchants SHOULD publish a new product listing with a new `d` tag.

When publishing a new listing intended to replace a prior one, merchants MAY include a `supersedes` tag referencing the prior listing address (`"30402:<pubkey>:<d>"`). Clients MAY use `supersedes` as an advisory signal to manage deprecation, continuity, and display (including optional review/history roll-ups). This specification does not define enforcement or validation requirements for supersession chains.

### Product Collection (Kind: 30405)
A specialized event type using [NIP-51](51.md) like list format to organize related products into groups. Collections allow merchants or any user to create meaningful product groupings and share common attributes that products can also reference, establishing one-to-many relationships.
Expand Down Expand Up @@ -768,6 +778,8 @@ Total Score = (Thumb × 0.5) + (0.5 × (∑(Category Ratings) ÷ Number of Categ
- Additional categories are optional
- Scores support fractional values between 0-1
- Custom categories can be added
2. Versioned Products:
- When a product listing supersedes another via a `supersedes` tag, clients MAY display review and rating history from previous versions alongside the current listing. Review events SHOULD remain logically attached to the specific product reference they were created for. Any roll-up or aggregation behavior is client-defined.

## 6. Implementation Guidelines

Expand Down