Part 010 — Characteristic Definitions, Values, Cardinality, Units, and Defaults

Positioning

Characteristics adalah salah satu mekanisme utama untuk membuat product model configurable.

Namun characteristic yang hanya direpresentasikan sebagai:

name = "speed"
value = "100"

akan menghasilkan ambiguity pada:

• type;
• unit;
• cardinality;
• default;
• validation;
• pricing;
• and downstream mapping.

Core thesis: characteristic model harus strongly semantic. Definition, selected value, source, type, unit, cardinality, validity, dan lifecycle harus dipisahkan agar configuration dapat diuji, dijelaskan, dan berevolusi.

1. What a Characteristic Is

A characteristic describes an attribute of a:

• specification;
• offering;
• configured selection;
• order item;
• service;
• resource;
• or inventory product.

Context determines meaning.

2. Characteristic Definition versus Value

Definition

Describes what values are allowed.

Value

Represents actual selected or realized data.

Example:

Definition:
Bandwidth, Integer, Mbps, allowed 100–1000

Value:
500 Mbps

3. Specification Characteristic

Defines broad reusable capability.

Example:

• Bandwidth range 100–10000 Mbps.

4. Offering Characteristic

May constrain specification.

Example:

• Premium Offering allows 500, 1000, 2000 Mbps.

5. Configuration Value

Customer/context-specific selected value.

Example:

• 1000 Mbps.

6. Order Value

Requested target value.

May include:

• action;
• current value;
• target value.

7. Inventory Value

Realized actual value.

Example:

• provisioned profile 1000 Mbps.

8. Characteristic Identity

A definition should have stable identity.

Do not rely only on display name.

Example:

Characteristic ID: bandwidth
Version: 3
Display Name: Bandwidth

9. Namespacing

Use namespace when names may collide.

Example:

commercial.bandwidth
network.vlanId
billing.commitmentTerm

10. Display Name versus Semantic Name

Display name may be localized and mutable.

Semantic name/ID should remain stable.

11. Data Types

Common types:

• String;
• Integer;
• Decimal;
• Boolean;
• Enumeration;
• Date;
• DateTime;
• Duration;
• Money;
• Quantity;
• Reference;
• Object;
• Collection.

12. String

Use for true text.

Do not use String for:

• numbers;
• dates;
• booleans;
• and structured references.

13. Integer

Use when fractional value is invalid.

Examples:

• number of users;
• site count;
• quantity.

14. Decimal

Use for:

• rates;
• capacity;
• ratios;
• and measured values.

Specify scale and rounding.

15. Boolean

Useful for binary fact.

But avoid boolean when domain has more states.

Example:

managed = true/false may be insufficient if states include:

• unmanaged;
• partially managed;
• customer-managed;
• partner-managed.

16. Enumeration

Use a controlled set of values.

Need:

• stable codes;
• labels;
• lifecycle;
• unknown handling;
• and compatibility.

17. Date

Represents business date without time.

Do not convert blindly to midnight UTC.

18. DateTime

Use instant or zoned date-time depending on semantics.

19. Duration

Examples:

• 24 months;
• 30 days;
• 4 hours.

Duration may require unit and calendar semantics.

20. Money

Should contain:

• amount;
• currency;
• and precision policy.

21. Quantity

Should contain:

• value;
• unit;
• and possibly dimension.

22. Reference

A reference points to another entity.

Example:

• selected site;
• billing account;
• product instance.

Use ID plus namespace/type.

23. Object Type

Structured characteristic can group subfields.

Use when semantic unit is cohesive.

Avoid arbitrary JSON blobs.

24. Collection Type

A multi-value characteristic should define:

• item type;
• min/max cardinality;
• order significance;
• uniqueness;
• and duplicate behavior.

25. Union Type

Sometimes one of several structured forms is allowed.

Example:

• static IP configuration;
• or managed pool reference.

Use explicit discriminator.

26. Stringly Typed Anti-Pattern

Everything stored as string.

Consequences:

• runtime parsing;
• locale bugs;
• weak validation;
• and hidden compatibility issues.

27. Generic JSON Anti-Pattern

Map<String, Object> increases flexibility but reduces:

• discoverability;
• validation;
• and contract stability.

28. Unit of Measure

Unit gives meaning to numeric value.

Examples:

• Mbps;
• GB;
• users;
• sites;
• months;
• requests/second.

29. Dimension

A dimension groups compatible units.

Example:

Data Rate:
- Mbps
- Gbps

30. Unit Conversion

Conversion should be:

• deterministic;
• precise;
• and explicit.

Example:

1 Gbps = 1000 Mbps

Confirm decimal/binary conventions.

31. Canonical Unit

A system may normalize to canonical unit.

Example:

• store Mbps;
• display Gbps.

Preserve original input if needed.

32. Display Unit

Display unit may depend on:

• locale;
• scale;
• and user preference.

Do not change domain meaning.

33. Unitless Value

Some numbers are dimensionless.

Examples:

• ratio;
• percentage;
• count.

Still define semantics.

34. Percentage

Represent percentage consistently.

Is 15% stored as:

• 15;
• or 0.15?

Define contract explicitly.

35. Currency Is Not Generic Unit

Currency has monetary semantics, rounding, and exchange-rate concerns.

Use Money.

36. Cardinality

Cardinality defines number of values or occurrences.

Common form:

minCardinality
maxCardinality

37. Single-Valued

Example:

• one contract term.

38. Optional Single-Valued

min = 0
max = 1

39. Required Single-Valued

min = 1
max = 1

40. Multi-Valued

Example:

• list of sites;
• allowed IP addresses;
• contact persons.

41. Bounded Collection

Example:

min = 1
max = 5

42. Unbounded Collection Risk

Unbounded values can cause:

• performance;
• payload;
• and UI problems.

Use explicit practical limit.

43. Collection Ordering

Ask whether order matters.

Examples:

• priority list;
• routing sequence;
• display only.

44. Uniqueness

A multi-value characteristic may require unique values.

Example:

• site codes.

45. Duplicate Semantics

Two identical values may represent:

• duplicate error;
• or two occurrences.

Define explicitly.

46. Characteristic Cardinality versus Component Cardinality

Characteristic cardinality:

• number of values.

Component cardinality:

• number of child product occurrences.

Do not conflate.

47. Range

Numeric definition may include:

• minimum;
• maximum;
• step;
• inclusivity;
• and unit.

48. Step

Example:

100, 200, 300 Mbps

Step = 100 Mbps.

49. Precision

Decimal characteristic needs:

• scale;
• precision;
• rounding.

50. Pattern

String may use regex/pattern.

Avoid overly technical validation without business explanation.

51. Length

Define:

• min length;
• max length;
• normalization.

52. Enumeration Value

Each enum should have:

• stable code;
• display label;
• status;
• and possibly effective period.

53. Enum Evolution

Adding value can break strict consumers.

Need unknown-value behavior.

54. Deprecating Enum Value

Keep historical readability.

Do not delete value used by quotes/orders/inventory.

55. Allowed Values

Allowed set may come from:

• static catalog;
• external reference data;
• dynamic query;
• or context rule.

56. Dynamic Allowed Values

Example:

• available sites;
• network zones;
• existing products.

Need:

• freshness;
• cache;
• and failure behavior.

57. Default Value

A default is a proposed value when user has not selected one.

It is not automatically authoritative input.

58. Explicit versus Implicit Default

Explicit

Stored in definition and visible.

Implicit

Hidden in code.

Prefer explicit defaults.

59. Default Provenance

Store whether value was:

• user-selected;
• defaulted;
• inherited;
• calculated;
• imported;
• or corrected.

60. Conditional Default

Default may depend on context.

Example:

• standard support for SMB;
• premium support for enterprise contract.

Need explanation and version.

61. Default Recalculation

When context changes, decide whether:

• recompute;
• preserve user override;
• or mark stale.

62. User Override

A user-selected value should not be overwritten silently by new default.

63. Inherited Value

Value may come from:

• parent bundle;
• account;
• contract;
• tenant;
• or installed product.

64. Inheritance Precedence

Example:

Global default
< Tenant default
< Contract default
< User selection

65. Calculated Value

A calculated value is derived.

Example:

• total bandwidth;
• site count;
• aggregate capacity.

Should include calculation provenance.

66. Read-Only Calculated Value

Users can view but not edit.

67. Editable Suggested Value

System suggests but user may override.

Do not call it calculated if editable.

68. Formula

Formula should be:

• versioned;
• deterministic;
• and tested.

Avoid arbitrary script execution.

69. Dependency

A characteristic may depend on another.

Example:

• router model options depend on bandwidth.

70. Visibility Rule

A characteristic may appear only when condition holds.

Visibility is UI concern unless hidden value is also semantically invalid.

71. Applicability Rule

Determines whether characteristic applies to current configuration.

72. Mandatory Rule

Characteristic may become required conditionally.

73. Allowed-Value Rule

Allowed values may narrow based on context.

74. Cross-Characteristic Constraint

Example:

If resilience = dual
then accessCount >= 2

75. Cross-Item Constraint

Example:

• all site bandwidth values must be equal under one package.

76. Validation Result

Should include:

• characteristic ID;
• invalid value;
• rule;
• reason;
• severity;
• and suggested correction.

77. Validation Severity

Possible:

• error;
• warning;
• information;
• recommendation.

78. Blocking versus Non-Blocking

A warning may allow progression.

A blocking error prevents transition.

79. Normalization

Normalize:

• casing;
• whitespace;
• units;
• formatting;
• and codes.

Preserve raw input if audit requires.

80. Canonicalization

Convert semantically equivalent values to canonical form.

Example:

1 Gbps
1000 Mbps

81. Locale

Parsing and display may depend on locale.

Examples:

• decimal separator;
• date format;
• and label.

Internal representation should remain locale-neutral.

82. Timezone

DateTime characteristic should specify:

• UTC instant;
• local date-time;
• or timezone-aware business time.

83. Null versus Missing

Missing

No value supplied.

Null

Explicit absence.

Some APIs distinguish them.

84. Empty String

Do not use empty string as universal absence.

85. Unknown

Unknown can be a legitimate state distinct from missing.

Example:

• installation date not yet known.

86. Not Applicable

A characteristic may be not applicable due to context.

Do not confuse with missing required value.

87. Value State

A value can have status:

• selected;
• defaulted;
• calculated;
• invalid;
• stale;
• and confirmed.

88. Characteristic Lifecycle

Definition may be:

• draft;
• active;
• deprecated;
• retired.

89. Value Lifecycle

Configured value may change during:

• draft;
• quote revision;
• order;
• and fulfillment.

Accepted historical value should be preserved.

90. Versioning Characteristic Definition

Version when changing:

• type;
• allowed values;
• unit;
• cardinality;
• or semantics.

91. Additive Change

Examples:

• add optional characteristic;
• add enum value with tolerant consumers.

Still assess downstream compatibility.

92. Breaking Change

Examples:

• String to Integer;
• single to multi-value;
• Mbps to Gbps semantics;
• required field added;
• enum removed.

93. Semantic Breaking Change

Example:

term = 12 changes from months to billing cycles.

Schema unchanged, meaning broken.

94. Migration

Migration may:

• convert values;
• preserve old definition;
• or create new configuration revision.

95. Historical Resolution

Quote and inventory should resolve old characteristic definition/version.

96. Type Widening

Integer to Decimal may be backward compatible for some consumers.

Validate all contracts.

97. Type Narrowing

Decimal to Integer is usually breaking.

98. Unit Change

Changing display unit can be safe.

Changing canonical unit requires conversion and compatibility policy.

99. Cardinality Change

Single to multi-value can break:

• APIs;
• UI;
• persistence;
• pricing;
• and downstream mapping.

100. Default Change

Changing default affects new configurations.

It should not silently alter existing user selections.

101. Allowed-Value Removal

Existing quotes/inventory may still use removed value.

Use deprecation rather than deletion.

102. Characteristic Mapping

A commercial characteristic may map to:

• order field;
• service characteristic;
• resource characteristic;
• billing parameter.

103. One-to-One Mapping

Example:

• commercial bandwidth -> service bandwidth.

104. One-to-Many Mapping

Example:

• premium support -> support tier + monitoring flag + response SLA.

105. Many-to-One Mapping

Example:

• several UI selections combine into one service profile.

106. Transformation

Mapping may include:

• unit conversion;
• enum translation;
• normalization;
• and derived values.

107. Mapping Version

Store version when transformation affects execution.

108. Lossy Mapping

Downstream may not need every commercial characteristic.

Document intentional loss.

109. Reverse Mapping

Modification flow may need inventory values mapped back to commercial configuration.

This is not always perfectly reversible.

110. Drift Detection

Compare:

• quoted;
• ordered;
• and realized characteristic values.

Classify variance.

111. Pricing Dependency

A characteristic can influence:

• price;
• discount;
• tax;
• and approval.

112. Price-Relevant Marker

Mark price-relevant characteristics explicitly.

This helps reprice triggers.

113. Approval-Relevant Marker

Changes to certain values should invalidate approval.

114. Fulfillment-Relevant Marker

Changes affect technical realization.

115. Document-Relevant Marker

Controls customer-facing proposal.

Avoid duplicated metadata flags without governance.

116. Sensitive Characteristic

Examples:

• credentials;
• personal data;
• internal margin class.

Need visibility policy.

117. Secret Value

Secrets should not be stored as ordinary catalog characteristic values.

Use secure secret management.

118. Customer-Visible Value

Ensure label, unit, and formatting are understandable.

119. Internal-Only Value

Should not leak to proposal or customer APIs.

120. Characteristic UI

UI may render based on:

• type;
• allowed values;
• cardinality;
• and display metadata.

121. Generic UI Risk

Metadata-driven forms can become unusable for complex products.

Use custom UX where it adds value.

122. Conditional Rendering

Ensure hidden fields do not retain invalid stale values silently.

123. Multi-Value UI

Need:

• add/remove;
• reorder;
• duplicate prevention;
• and validation.

124. API Representation

Prefer typed JSON.

Example:

{
  "id": "bandwidth",
  "value": 1000,
  "unit": "Mbps",
  "source": "USER_SELECTED"
}

125. Polymorphic API Risk

Generic value fields require strong discriminator and schema.

126. Persistence Model

Options:

• typed columns;
• EAV;
• JSON;
• document;
• normalized value tables.

127. EAV

Entity-Attribute-Value offers flexibility.

Risks:

• weak type enforcement;
• difficult query;
• and poor constraints.

128. JSON Storage

Useful for snapshots.

Need:

• schema version;
• validation;
• and indexing.

129. Typed Table

Strong constraints.

Less flexible for many dynamic characteristics.

130. Hybrid Persistence

Definitions normalized; configured values stored as versioned document plus indexed selected fields.

131. Query Patterns

Understand needs:

• find all quotes with bandwidth > 1 Gbps;
• validate one configuration;
• display one quote;
• compare revisions;
• reconcile inventory.

Persistence should support real queries.

132. Indexing

Index only characteristics used for:

• search;
• eligibility;
• and operations.

Avoid indexing every dynamic field.

133. Performance

Large configurations may contain thousands of values.

Need:

• incremental validation;
• compact payload;
• and selective loading.

134. Caching

Cache definition by:

• characteristic ID/version;
• catalog publication;
• and tenant scope.

135. Definition Drift

Runtime engine and cached definitions must agree on schema/version.

136. Validation Engine

A validation engine should understand:

• types;
• units;
• cardinality;
• dependencies;
• and context.

137. Explainability

For a value, explain:

Why is it present?
Where did it come from?
Why is it allowed?
Why is it required?
What does changing it affect?

138. Characteristic Diff

A semantic diff should show:

• value changed;
• source changed;
• unit changed;
• definition version changed;
• and downstream impact.

139. Quote Revision Diff

Useful for:

• approval;
• customer negotiation;
• and audit.

140. Test Categories

• type tests;
• boundary tests;
• cardinality tests;
• unit conversion tests;
• default tests;
• dependency tests;
• migration tests;
• and compatibility tests.

141. Property-Based Testing

Properties:

• values always satisfy type;
• conversions round-trip within tolerance;
• cardinality never exceeds max;
• defaulted value is allowed;
• stale value is detected after definition change.

142. Boundary Testing

Test:

• min;
• max;
• just below;
• exactly;
• just above.

143. Enum Testing

Test:

• known;
• unknown;
• deprecated;
• and removed values.

144. Unit Testing

Test:

• conversion;
• precision;
• and display.

145. Migration Testing

Test old quote/order/inventory values against new definition.

146. Characteristic Incidents

Examples:

• wrong unit;
• hidden default;
• enum mismatch;
• cardinality overflow;
• and stale mapping.

147. Observability

Track:

• validation failures by characteristic;
• default usage;
• stale values;
• unknown enum;
• mapping errors;
• and unit conversion failures.

148. Characteristic Smells

• everything String;
• display name as ID;
• no unit;
• hidden default;
• no provenance;
• single/multi ambiguity;
• and values stored without definition version.

149. Anti-Patterns

Universal characteristic bag

Every entity has arbitrary key/value pairs.

Hidden code type

Catalog says String; code assumes Integer.

Mutable historical definition

Old quote reinterpreted with new semantics.

Unit in label only

Bandwidth (Mbps) without machine-readable unit.

Default as user choice

System cannot tell whether customer selected it.

150. Characteristic Definition Template

## ID and Version

## Semantic Name

## Display Labels

## Type

## Unit / Dimension

## Cardinality

## Allowed Values / Range

## Default

## Source Rules

## Dependencies

## Validation

## Sensitivity

## Lifecycle

## Mapping

## Tests

151. Value Record Template

Characteristic ID:
Definition version:
Value:
Unit:
Source:
Selected by:
Calculated by:
Captured at:
Validation status:
Original input:

152. Migration Template

Old definition:
New definition:
Breaking aspect:
Value conversion:
Historical behavior:
Open quote behavior:
Order/inventory behavior:
Rollback:

153. Worked Example: Bandwidth

Definition

• type: Integer;
• unit: Mbps;
• min: 100;
• max: 10000;
• allowed: 100, 500, 1000, 10000.

Offering restriction

Premium allows 500–10000.

Selected value

1000 Mbps.

Mapping

Service profile BW_1G.

154. Worked Example: Contract Term

Definition

• type: Duration;
• unit: month;
• allowed: 12, 24, 36.

Impacts

• price;
• discount;
• approval;
• and agreement terms.

155. Worked Example: Site List

Definition

• type: Reference collection;
• item type: Site;
• min: 1;
• max: 1000;
• unique: true.

Risks

• large payload;
• per-site configuration;
• and partial qualification.

156. Worked Example: Resilience

Definition

Enum:

• STANDARD;
• DUAL_ACCESS;
• GEO_REDUNDANT.

Rule

GEO_REDUNDANT requires at least two regions.

157. Worked Example: Default Change

Old default:

• Standard Support.

New default:

• Premium Support for enterprise customers.

Existing configurations preserve old selected/defaulted value unless explicit migration.

158. Worked Example: Single to Multi-Value

Characteristic cloudProvider changes to multiple providers.

Impact:

• API;
• UI;
• pricing;
• order mapping;
• and document.

Create new definition/version rather than silent cardinality mutation.

159. Worked Example: Unit Migration

Old:

• Gbps decimal.

New internal canonical:

• Mbps.

Migration:

• convert values;
• preserve display unit;
• test quote totals and downstream mapping.

160. Senior Engineer Operating Model

Require strong semantics

Type, unit, cardinality, source.

Preserve provenance

User, default, inherited, calculated.

Treat definition change as contract change

Assess compatibility.

Keep units machine-readable

Not only labels.

Separate missing, unknown, and not applicable

Avoid null ambiguity.

Version mappings

Commercial-to-technical transformations.

Test boundaries and migration

Not only happy path.

Avoid arbitrary bags

Use constrained extensibility.

161. Internal Verification Checklist

Definition model

• Are characteristic IDs stable?
• Are definitions versioned?
• What types are supported?
• Are units machine-readable?

Values

• Is source/provenance stored?
• Are defaulted and user-selected values distinguishable?
• Are calculated values read-only?
• Are original inputs preserved?

Cardinality

• How are single and multi-value represented?
• Are min/max enforced?
• Is ordering meaningful?
• Are duplicates allowed?

Rules

• How are conditional mandatory/visibility/allowed values modeled?
• Are cross-characteristic constraints supported?
• Are reasons explainable?

Evolution

• What changes are considered breaking?
• How are enum values deprecated?
• How are old quotes/inventory resolved?
• How are migrations executed?

Mapping

• Which values affect price?
• Which affect approval?
• Which affect fulfillment?
• Are mapping versions stored?

Persistence and APIs

• EAV, JSON, typed tables, or hybrid?
• How are schemas validated?
• How are dynamic fields indexed?
• How are unknown values handled?

162. Practical Exercises

Exercise 1 — Definition design

Model bandwidth, contract term, and site list characteristics.

Exercise 2 — Provenance

Distinguish user-selected, defaulted, inherited, and calculated values.

Exercise 3 — Cardinality migration

Design a safe single-to-multi-value migration.

Exercise 4 — Unit policy

Define canonical and display units for capacity and duration.

Exercise 5 — Compatibility review

Assess impact of adding/removing enum values.

Exercise 6 — Persistence evaluation

Compare EAV, JSON, typed, and hybrid models for actual query patterns.

163. Part Completion Checklist

You are done if you can:

• distinguish characteristic definition and value;
• model strong data types;
• represent units and dimensions;
• define cardinality;
• preserve value provenance;
• distinguish missing, null, unknown, and not applicable;
• model defaults and inheritance;
• evolve enums, types, units, and cardinality safely;
• map commercial values downstream;
• and create an internal characteristic-model verification backlog.

164. Key Takeaways

1. Characteristic values need definitions.
2. Strings are not a universal type.
3. Units are part of domain meaning.
4. Cardinality must be explicit.
5. Defaulted and user-selected values are different.
6. Missing, unknown, and not applicable are distinct.
7. Definition changes are contract changes.
8. Historical values need versioned interpretation.
9. Mapping and provenance must be preserved.
10. Internal characteristic semantics must be verified.

165. References

Conceptual baseline:

• General CPQ characteristic, attribute, configuration, and product-modeling practices.
• Domain-Driven Design value objects and semantic modeling.
• Schema evolution, data contracts, type systems, units of measure, and compatibility practices.
• TM Forum ProductSpecificationCharacteristic and characteristic-value vocabulary.

These references do not define internal CSG characteristic storage or rule semantics.