Specifications, Claims, & Conversions
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Specifications, Claims, and Conversions system forms the core of the ProductCompare engine, enabling the collaborative definition and verification of product attributes. It provides a typed framework for managing product data through an append-only "claim" lifecycle, where users propose specifications that undergo moderation before becoming the "current" canonical value for a product.
This system ensures data integrity by utilizing a rigorous dimension and unit conversion layer. Every numeric specification is normalized to a base unit (e.g., converting inches to millimeters) to support accurate filtering, sorting, and side-by-side comparisons. This infrastructure allows the platform to handle complex data types—including booleans, enums, and numeric ranges—within a unified Catalog context.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:5-10, README.md:23-30
Claim Lifecycle and State Management
Specifications are managed as an append-only log of product_attribute_claims. This architecture separates the history of proposed data from the currently displayed value, ensuring that changes are traceable and reversible.
Claim Transitions
A claim moves through several states managed by the ProductCompare.Specs context. When a user submits a specification, it is created as a proposal. Moderators then transition these claims to accepted or rejected statuses. Only accepted claims are eligible to be promoted to the "current" status for a specific product attribute.
The diagram above illustrates the transition logic for product specification claims.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:154-165, 2026-03-03-product-compare-backend-mvp-plan.md:213-220
Atomic Current Selection
To prevent race conditions, the system uses a transactional select_current_claim operation. This logic locks the scope of a product-attribute pair to ensure that only one claim is marked as "current" at any given time. This "current" pointer is stored in the product_attribute_current table to optimize read performance for the frontend.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:218-223, 2026-03-03-product-compare-backend-mvp-plan.md:106-110
Unit Conversion and Normalization
To facilitate deterministic filtering across different units of measurement, the system implements a normalization layer. Numeric values are processed through a conversion helper that translates user-provided units into base units defined by the attribute's dimension.
Conversion Logic
The Specs.convert_to_base/3 function utilizes multiplier_to_base and offset_to_base constants to perform calculations. This allows for simple scaling (e.g., length) as well as complex shifts (e.g., temperature).
| Field | Description |
|---|---|
value_num | The raw numeric value provided by the user/claim. |
value_num_base | The indexed canonical numeric value used for fast filtering. |
multiplier_to_base | The factor used to scale a unit to its dimension's base unit. |
offset_to_base | The constant added to a value after scaling for non-zero-based units. |
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:205-211, 2026-03-03-product-compare-backend-mvp-plan.md:10-12
Dimension Hierarchy
Architecture of unit normalization within the Specs context.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:113-118, 2026-03-03-product-compare-backend-mvp-plan.md:267-275
Data Modeling and Schema
The specifications system relies on several interlinked tables within the ProductCompareSchemas.Specs boundary. These tables use bigint primary keys and uuidv7 entropy IDs for global identification.
Key Schema Entities
- Dimensions & Units: Defines the physical properties (e.g., Frequency, Length) and the specific units (e.g., Hz, mm) available for attributes.
- Enum Sets & Options: Provides restricted choice lists (e.g.,
panel_techoptions likeIPS,OLED). - Attributes: The definition of a specific property (e.g., "Refresh Rate") which links to a Dimension or an Enum Set.
- Product Attribute Claims: The actual values proposed for a product, containing
value_bool,value_num_base, orenum_option_id.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:135-144, backend_starting_guide.md:95-102
Indexing Strategy
To maintain high performance for product filtering, the database utilizes composite and partial indexes on the specification tables:
- Unique index on
(product_id, attribute_id)inproduct_attribute_current. - Partial numeric filter index on
product_attribute_claims(attribute_id, value_num_base)where values are not null. - Enum filter index on
(attribute_id, enum_option_id).
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:167-175
Comparison and Filtering
The comparison system utilizes the "current" claims to generate side-by-side views. The Catalog.Filtering module implements a query builder that joins products with their current attribute values.
Flow of a filtered product query using normalized specification data.
Sources: 2026-03-03-product-compare-backend-mvp-plan.md:225-231, assets/src/routes/compare/api.ts:46-52
Multi-Product Comparison
The frontend comparison route (e.g., /compare?slug=a&slug=b) leverages the loadProductDetail API to fetch specifications for up to three products simultaneously. It validates that all selected products exist and are compatible for comparison before rendering.
Sources: assets/src/routes/compare/api.ts:54-65, ARCHITECTURE.md:25-28
Summary
Specifications, Claims, & Conversions provide the technical foundation for accurate product data within the project. By using an append-only claim model and normalizing numeric data into base units, the system ensures that product comparisons remain technically accurate and high-performing, even as the taxonomy and dataset scale.