Product Ubiquitous Language¶
Status¶
Normative Business Domain Specification
Purpose¶
This document defines the official language of the Product Domain.
Every Product Domain document, contract, class, test and event must use this vocabulary consistently.
Core Terms¶
| Term | Definition |
|---|---|
| Product | Stable business representation of a real-world product |
| Canonical Product Identity | Official stable identity of a Product |
| Product Identity | Business identity currently assigned to a Product |
| Identifier | Identification signal attached to an Observation or Product |
| Identifier Type | Kind of identifier such as EAN, GTIN, MPN, SKU, model reference or merchant product id |
| Observation | Product-related information received, extracted or inferred from a source |
| Evidence | Information used to support or challenge a Product Identity |
| Variant | Version of the same Product with distinct attributes |
| Variant Attribute | Attribute that differentiates variants, such as color, storage, memory, size or network |
| Product Family | Stable family grouping similar products |
| Product Type | Generic type describing what the product is |
| Brand | Manufacturer or commercial brand |
| Model | Commercial model name |
| Series | Product line or range |
| Generation | Version generation of a model or series |
| Consistency | Coherence state between identifiers, observations and identity |
| Conflict | Explicit contradiction between evidences |
| Confidence | Trust level assigned to an identity decision |
| Resolution | Process that establishes or confirms Product Identity |
Product¶
A Product is the stable business representation of a real-world product.
A Product is not:
- an offer;
- a merchant listing;
- a feed row;
- a catalog card;
- a WordPress post;
- a projection;
- a frontend page.
A Product may be represented by many merchant offers, many observations and many identifiers.
Canonical Product Identity¶
Canonical Product Identity is the official stable identity of a Product.
It represents the product itself, not the way a merchant describes it.
Canonical Product Identity may include:
- brand;
- series;
- model;
- generation;
- product family;
- product type.
Canonical Product Identity must not include:
- price;
- stock;
- promotion;
- merchant name;
- feed name;
- frontend title;
- SEO title;
- runtime metadata.
Identifier¶
An Identifier is a signal used to support identity resolution.
Examples:
- EAN;
- GTIN;
- MPN;
- SKU;
- merchant product id;
- manufacturer reference;
- model reference.
An Identifier never defines a Product alone.
Observation¶
An Observation is product-related information coming from a source or derived from a source.
An Observation may contain:
- title;
- brand;
- identifiers;
- attributes;
- source information;
- extracted technical data;
- confidence hints.
An Observation is evidence, not final truth.
Evidence¶
Evidence is information used to support or challenge a Product Identity.
Evidence may come from:
- identifiers;
- observations;
- normalized attributes;
- trusted source data;
- previous validated decisions.
Evidence must remain traceable.
Variant¶
A Variant is a version of the same Product.
Examples:
- same smartphone with different storage;
- same console with different color;
- same printer with or without Wi-Fi;
- same laptop with different RAM.
A Variant belongs to exactly one Product.
A Variant must never create a new Product when it only represents a product option.
Product Family¶
Product Family is a stable business grouping.
Examples:
- smartphone;
- tablet;
- console;
- video game;
- printer;
- camera;
- headphone;
- toy.
Product Family is not a frontend category.
Product Type¶
Product Type describes what the Product is in generic business terms.
Product Type must remain independent from merchant taxonomy and frontend navigation.
Consistency¶
Consistency represents the coherence state of a Product.
A Product may be:
- consistent;
- incomplete;
- conflicting;
- unresolved.
Consistency is a business signal used to protect quality.
Conflict¶
A Conflict is an explicit contradiction between evidences.
Examples:
- same EAN attached to different brands;
- same model name attached to incompatible product families;
- variant attributes contradict canonical identity;
- trusted observations disagree.
A Conflict must be visible, traceable and resolvable.
Confidence¶
Confidence is the trust level assigned to an identity decision.
Confidence must never hide a conflict.
Low confidence requires explicit handling.
Resolution¶
Resolution is the process that establishes or confirms Product Identity.
Resolution must be:
- deterministic;
- traceable;
- explainable;
- reproducible.
Forbidden Vocabulary¶
The Product Domain must not use the following terms as Product Domain concepts:
| Forbidden Term | Reason |
|---|---|
| Offer price | Belongs to commercial offer concerns |
| Discount | Belongs to promotion or offer concerns |
| Stock | Belongs to availability concerns |
| Merchant ranking | Belongs to catalog or marketplace concerns |
| Frontend card | Belongs to frontend/projection concerns |
| WordPress post | Belongs to adapter concerns |
| Feed row | Belongs to pipeline concerns |
| SQL row | Belongs to infrastructure concerns |
Naming Rules¶
Product Domain naming must follow these rules:
- use Product when referring to the stable business object;
- use Offer only outside the Product Domain;
- use Observation for source-derived product data;
- use Identifier for identity signals;
- use Evidence for information used in identity decisions;
- use Variant only for versions of the same Product;
- use Conflict only for explicit contradictions;
- use Projection only outside the Product Domain.
Architecture Decision¶
Decision: CERTIFIED.
The Product Domain language is now explicitly separated from Offer, Catalog, Projection, Pipeline and Adapter language.