Documentation

adrs/032-unit-of-measure-system.md

ADR-032: Unit of Measure System

Status

Accepted

Context

The catalog component currently uses a simple attribute system with basic data types and units stored as simple text abbreviations. This approach has several limitations:

  1. No standardization: Units are free text with no validation
  2. No relationships: Cannot enforce which units are valid for which physical quantities
  3. No metadata: Missing important information like symbols, conversion factors
  4. Poor internationalization: No support for locale-specific unit display
  5. Industrial requirements: Need ISO 80000/SI compliance for enterprise clients

As the system scales to support industrial asset tracking, we need a robust measurement framework that ensures data integrity and supports scientific accuracy.

Decision

We will implement a comprehensive Unit of Measure (UoM) system based on ISO 80000/SI standards to replace the simple attribute type system.

Implementation Details

  • Create four new database tables: quantity_categories, quantities, units_of_measure, and quantity_units_of_measure
  • Establish many-to-many relationships between quantities and units
  • Include comprehensive reference data for common measurements
  • Support Unicode symbols for proper unit display
  • Implement validation to ensure unit-quantity compatibility

Consequences

Positive

  • Standards compliance: ISO 80000/SI alignment for industrial applications
  • Data integrity: Enforced relationships prevent invalid unit associations
  • Extensibility: Easy to add new quantities and units
  • Future-ready: Foundation for unit conversion and calculations
  • Professional: Meets enterprise requirements for measurement systems

Negative

  • Migration complexity: Existing data must be transformed
  • Increased complexity: More tables and relationships to manage
  • Performance overhead: Additional joins for unit lookups
  • Learning curve: Developers need to understand the new model

Neutral

  • Reference data must be maintained and versioned
  • UI components need updates to use the new system
  • API contracts change to support quantity/unit relationships

Decision Drivers

  1. Customer requirements for ISO standards compliance
  2. Need for scientific measurement accuracy
  3. Support for multiple industries with different unit preferences
  4. Data validation and integrity requirements
  5. Future requirements for unit conversions

Considered Options

Option 1: Keep Simple Attribute System

  • Pros: No migration needed, simpler model
  • Cons: Doesn't meet requirements, no validation

Option 2: Third-party Library

  • Pros: Pre-built functionality, tested code
  • Cons: External dependency, may not fit our model

Option 3: Custom UoM System (Selected)

  • Pros: Tailored to our needs, full control, standards-compliant
  • Cons: Development effort, maintenance responsibility
  • ADR-005: Separation of abstractions and implementations
  • ADR-024: FluentValidation for input validation
  • ADR-027: Component interaction patterns

Notes

This decision represents a significant enhancement to the catalog component's capabilities and sets the foundation for advanced measurement features in future releases.

Date: 2025-01-17
Author: Core Platform Team
Reviewed by: Pending