From 3f391562584d3a3fa97a9fc6d19b5dcbac7cce86 Mon Sep 17 00:00:00 2001 From: Eric FJ Date: Sat, 6 Dec 2025 15:09:43 -0800 Subject: [PATCH 1/2] Clarify product identity mutability and add supersedes tag --- spec.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) diff --git a/spec.md b/spec.md index 2ba8eba..d632fbd 100644 --- a/spec.md +++ b/spec.md @@ -125,6 +125,9 @@ Products are the core element in a marketplace. Each product listing MUST contai - `summary`: Short product description - `spec`: Product specifications `[, ]`, can appear multiple times +- Versioning: + - `supersedes`: Product version reference `"30402::"` indicating that this product replaces a previous product listing. MAY appear at most once. + - Media: - `image`: Product images `[, , ]`, MAY appear multiple times - url: Direct image URL @@ -183,6 +186,7 @@ Products are the core element in a marketplace. Each product listing MUST contai // References ["shipping_option", "<30406|30405>::", ""], // Shipping options or collection, MAY appear multiple times ["a", "30405::"] // Product collection + ["supersedes", "30402::"] // optional: previous product identifier ] } ``` @@ -209,6 +213,19 @@ 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 + +Implementations SHOULD treat the following as identity-defining aspects of a product listing: + +- The human-readable product description in `content` +- The `title` tag +- The `summary` tag, when present +- The primary `image` tags used to render the product + +Substantial changes to these identity-defining fields (for example, replacing the product with a different item, or completely changing its core description and imagery) SHOULD be published as a new product listing event with a new `d` tag. + +When a new listing replaces a previous one, clients SHOULD include a `supersedes` tag pointing to the prior product identifier (`"30402::"`). Operational fields such as `price`, `stock`, shipping-related tags, and other non-identity metadata MAY be updated in place on the same product listing without resetting social context. ### 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. @@ -768,6 +785,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, but review events SHOULD remain logically attached to the specific product reference they were created for. ## 6. Implementation Guidelines From 929efe90f5785e91ea7080f8058c178dba8a7d7d Mon Sep 17 00:00:00 2001 From: Eric FJ Date: Wed, 14 Jan 2026 14:09:48 -0800 Subject: [PATCH 2/2] Clarify product supersession semantics and make supersedes addressable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit This change tightens the optional product versioning mechanism without adding enforcement requirements. - Fix `supersedes` reference format to use an unambiguous address (`30402::`) rather than `d` alone. - Reframe “product identity and mutability” as non-normative guidance: clients define policy; merchants MAY publish a new listing when the underlying item materially changes. - Clarify that `supersedes` is an advisory signal for deprecation/continuity UX (including optional review/history roll-ups), and that reviews remain attached to the specific product reference they were created for. --- spec.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/spec.md b/spec.md index d632fbd..d65da53 100644 --- a/spec.md +++ b/spec.md @@ -126,7 +126,7 @@ Products are the core element in a marketplace. Each product listing MUST contai - `spec`: Product specifications `[, ]`, can appear multiple times - Versioning: - - `supersedes`: Product version reference `"30402::"` indicating that this product replaces a previous product listing. MAY appear at most once. + - `supersedes`: Product version reference `"30402::"` indicating that this product is intended to replace a previous product listing. MAY appear at most once. - Media: - `image`: Product images `[, , ]`, MAY appear multiple times @@ -186,7 +186,7 @@ Products are the core element in a marketplace. Each product listing MUST contai // References ["shipping_option", "<30406|30405>::", ""], // Shipping options or collection, MAY appear multiple times ["a", "30405::"] // Product collection - ["supersedes", "30402::"] // optional: previous product identifier + ["supersedes", "30402::"] // optional: previous product listing address ] } ``` @@ -216,16 +216,9 @@ Products are the core element in a marketplace. Each product listing MUST contai #### Product identity and mutability -Implementations SHOULD treat the following as identity-defining aspects of a product listing: +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. -- The human-readable product description in `content` -- The `title` tag -- The `summary` tag, when present -- The primary `image` tags used to render the product - -Substantial changes to these identity-defining fields (for example, replacing the product with a different item, or completely changing its core description and imagery) SHOULD be published as a new product listing event with a new `d` tag. - -When a new listing replaces a previous one, clients SHOULD include a `supersedes` tag pointing to the prior product identifier (`"30402::"`). Operational fields such as `price`, `stock`, shipping-related tags, and other non-identity metadata MAY be updated in place on the same product listing without resetting social context. +When publishing a new listing intended to replace a prior one, merchants MAY include a `supersedes` tag referencing the prior listing address (`"30402::"`). 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. @@ -786,7 +779,7 @@ Total Score = (Thumb × 0.5) + (0.5 × (∑(Category Ratings) ÷ Number of Categ - 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, but review events SHOULD remain logically attached to the specific product reference they were created for. + - 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