Canonical Identity¶

Status¶

Normative Architecture Concept

Purpose¶

This document defines the Canonical Product Identity, the central business reference of the CMonChoix Platform.

The Canonical Identity represents a product independently of merchants, feeds, identifiers, projections and presentation formats.

All Platform capabilities must consume this shared identity instead of redefining product truth locally.

Scope¶

This concept applies to:

Domain Core;
Identifier First;
Identity Resolution;
Vertical Modules;
Projection;
Read Services;
Write Services;
Runtime;
Adapters.

Motivation¶

Merchant catalogs often describe the same product in different ways.

Typical variations include:

short titles;
marketing titles;
SEO titles;
marketplace titles;
refurbished titles;
localized titles;
incomplete or conflicting identifiers.

Despite these differences, the Platform must determine whether observations describe the same real-world product.

The Canonical Identity provides that stable business reference.

Definition¶

A Canonical Identity is the authoritative business representation of a product after identity resolution.

It is independent from:

merchants;
feeds;
merchant product identifiers;
EAN or GTIN values considered in isolation;
marketplace identifiers;
commercial titles;
frontend formats;
projection storage.

Identifiers and merchant fields are evidence. They do not become canonical truth merely because they are present.

Identity Resolution Boundary¶

The Canonical Identity is produced through an explicit resolution process.

Observations
    │
    ▼
Evidence and identifiers
    │
    ▼
Candidates
    │
    ▼
Resolver + Conflict Policy
    │
    ▼
Resolution Result
    │
    ├── resolved
    ├── unknown
    ├── ambiguous
    └── conflict

Only a resolved result may designate a canonical identity with sufficient confidence.

unknown, ambiguous and conflict are first-class outcomes. They must remain visible and must never be silently converted into a forced identity.

Resolution Result¶

A resolution result should expose at least:

status;
canonical identity when resolved;
confidence or decision level;
reason codes;
supporting evidence;
detected conflicts;
resolver and rule versions;
audit metadata.

Equivalent inputs, rule versions and configuration must produce equivalent results.

Objectives¶

Single Business Truth¶

A resolved product must have one authoritative Canonical Identity within the applicable identity scope.

Duplicate identities for the same product are defects unless an explicit migration or split operation is documented.

Stability¶

Merchant changes, title changes and projection changes must not alter Canonical Identity without new business evidence and an explicit resolution decision.

Shared Reference¶

Every Business Capability and Vertical Module consumes the same Canonical Identity contract.

A capability may enrich domain knowledge but must not create a parallel identity system.

Technology Independence¶

Canonical Identity must not depend on:

WordPress;
SQL schemas;
Frontend rendering;
Pipeline implementation details;
Runtime orchestration;
adapter-specific DTOs.

Canonical Components¶

A Canonical Identity contains stable business information only.

Typical components may include:

brand;
product family;
series;
model;
generation;
canonical product type;
stable normalized reference.

The exact components depend on the domain contract and validated Vertical Module rules.

Merchant-specific metadata never belongs to Canonical Identity.

Variants¶

Variants describe meaningful versions attached to a canonical product.

Examples may include:

color;
storage capacity;
memory configuration;
network configuration;
finish;
size.

A variant must not automatically create a new Canonical Identity.

Whether an attribute belongs to identity or variant semantics is defined by the relevant domain and Vertical Module contract, not by the frontend or a merchant feed.

Projections¶

A Projection is a consumer-specific representation derived from resolved business data.

Examples include:

frontend display;
SEO;
comparison;
search;
export;
audit views.

A Projection:

never creates a new identity;
never repairs identity implicitly;
never hides unresolved or conflicting states without an explicit consumer policy;
remains rebuildable from authoritative inputs.

Projection persistence is a Write Service responsibility. Projection construction itself must remain deterministic and side-effect free.

Responsibilities¶

Canonical Identity is responsible for:

providing the stable product reference;
supporting grouping of compatible observations;
organizing variant relationships;
serving as input to projections and downstream capabilities;
preserving traceability to the decision that produced it.

It is not responsible for:

pricing;
promotions;
stock;
merchant offers;
frontend rendering;
Media Quality decisions;
pipeline orchestration;
database writes.

Vertical Module Boundary¶

Vertical Modules provide domain-specific evidence interpretation and conflict rules.

They may define, for example:

smartphone model and storage semantics;
photo mount and focal semantics;
television series and size semantics.

They must not:

modify Canonical Identity directly;
bypass the Resolver;
force a resolution in case of blocking conflict;
depend on another Vertical Module;
store a second source of product truth.

Media Quality Boundary¶

Media Quality evaluates media consistency against already resolved and projected business data.

It is not an identity source.

Media Quality must therefore:

consume authoritative identity, variant and projection fields;
produce audit evidence and reason codes;
remain non-destructive by default;
never rewrite Canonical Identity;
never infer a new Canonical Identity from an image alone;
route any approved correction through an explicit Write Service.

An image mismatch may reveal a data-quality problem, but it does not itself authorize an identity mutation.

Examples¶

Smartphone¶

Canonical identity
- brand: Apple
- family: iPhone
- model: iPhone 16 Pro

Variant
- storage: 256 GB
- color: Black Titanium

Camera Lens¶

Canonical identity
- brand: Canon
- family: lens
- model: EF-S 55-250 mm f/4-5.6 IS STM

Variant or compatibility attributes
- mount: EF-S

Television¶

Canonical identity
- brand: Samsung
- family: Neo QLED
- model: QN90D

Variant
- size: 65 inch

These examples are illustrative. The authoritative field semantics belong to the corresponding Vertical Module contracts.

Prohibited Practices¶

The following practices are forbidden:

recalculating Canonical Identity inside the Frontend;
bypassing the Identity Resolver;
forcing unknown, ambiguous or conflict into resolved;
creating multiple authoritative identities for the same product without an explicit split decision;
embedding merchant-specific fields into Canonical Identity;
storing vertical-specific rules inside the generic Core;
modifying identity directly from a Vertical Module;
mutating identity from Media Quality or a Read Service;
treating a projection as the source of identity truth.

Invariants¶

The following invariants must always remain true.

Canonical Identity is authoritative only when produced by the certified resolution boundary.
Resolution states remain explicit and auditable.
Equivalent inputs and versions produce equivalent results.
Merchant data remains evidence, not truth by itself.
Variants do not silently create new identities.
Projections remain derived and rebuildable.
Read Services and Media Quality do not mutate identity.
Identity writes are explicit, auditable and owned by Write Services.

Observability¶

Identity resolution and subsequent writes should expose metrics such as:

observations processed;
candidates generated;
resolved count;
unknown count;
ambiguous count;
conflict count;
duplicate identity detections;
resolver version;
rule version;
write count;
skipped write count;
failure count.

Reason codes must be stable enough for audits, comparisons and regression tests.

Testing Expectations¶

Tests should cover:

deterministic resolution;
explicit unresolved states;
conflict preservation;
duplicate prevention;
variant attachment rules;
projection rebuildability;
Vertical Module isolation;
non-destructive Read Services;
Media Quality non-mutation;
explicit Write Service ownership;
compatibility behavior during migrations.

Future Evolution¶

The Canonical Identity model may evolve provided that identity stability, determinism, traceability and layer boundaries remain preserved.

Future Business Capabilities must consume the Canonical Identity instead of redefining product identity.