Part 003 — Domain Vocabulary, Entity Identity, and Semantic Precision

Positioning

Banyak kegagalan architecture pada CPQ dan Quote-to-Order bukan dimulai dari database, API, atau framework.

Ia dimulai dari bahasa yang ambigu.

Contoh ambiguity:

• product digunakan untuk catalog definition, configured selection, dan installed asset;
• price digunakan untuk price rule, calculated amount, dan invoiced charge;
• order digunakan untuk customer request, fulfillment plan, dan technical work order;
• status digunakan untuk business state, processing state, dan integration state.

Core thesis: ubiquitous language yang presisi mengurangi semantic coupling. Setiap entity harus memiliki identity, lifecycle, ownership, dan meaning yang dapat dijelaskan tanpa bergantung pada nama table atau class.

1. Why Language Is Architecture

Language shapes:

• aggregate boundaries;
• API resource names;
• event contracts;
• database schemas;
• test scenarios;
• UI labels;
• and ownership.

Jika satu istilah memiliki banyak meaning, system akan mengandung translation yang tidak terlihat.

2. Ubiquitous Language

Dalam Domain-Driven Design, ubiquitous language adalah bahasa bersama antara:

• domain experts;
• product;
• engineers;
• architects;
• QA;
• support;
• and operations.

Bahasa tersebut harus muncul secara konsisten dalam:

• conversation;
• code;
• API;
• documentation;
• tests;
• dan monitoring.

3. Ubiquitous Does Not Mean Global

Satu istilah dapat memiliki meaning berbeda di bounded context berbeda.

Example:

Product in Catalog

A sellable or configurable definition.

Product in Inventory

A realized instance owned or used by customer.

The solution is not necessarily one universal object.

The solution is explicit context.

4. Canonical Model versus Ubiquitous Language

Ubiquitous language

Shared domain vocabulary within a context.

Canonical model

A normalized representation used for integration or shared interpretation.

A canonical model can help interoperability.

It can also become a giant enterprise object that obscures local semantics.

Use carefully.

5. Semantic Precision Checklist

For every term, define:

Meaning:
Context:
Identity:
Lifecycle:
Owner:
Created by:
Changed by:
Referenced by:
Historical behavior:

6. Entity, Value Object, and Aggregate

Entity

Has identity that persists through change.

Examples:

• Quote;
• Product Order;
• Agreement;
• Inventory Product.

Value Object

Defined by attributes, not identity.

Examples:

• Money;
• Address;
• Date Range;
• Quantity.

Aggregate

Consistency boundary containing one aggregate root and related entities/value objects.

7. Entity Identity

Identity should remain stable when attributes change.

Weak identity:

• display name;
• external description;
• mutable code;
• position in array.

Strong identity:

• stable domain ID;
• version-aware reference where needed;
• explicit external identifiers.

8. Business ID versus Technical ID

Technical ID

Database or platform identifier.

Business ID

Identifier meaningful in business process.

Examples:

• Quote Number;
• Order Number;
• Contract Number;
• Customer Account Number.

Both may be needed.

Do not expose random database identity as the only business reference.

9. Natural Key Risk

Natural keys can change.

Examples:

• customer name;
• product code;
• site address;
• email;
• SKU.

Use stable identity plus mutable attributes.

10. External Identifier

An entity may have multiple external identifiers.

Example:

Internal Quote ID
CRM Opportunity ID
Customer Reference
Partner Reference
Legacy Quote Number

Store:

• namespace;
• value;
• owner;
• validity;
• and source.

11. Versioned Identity

Some entities need both identity and version.

Example:

Offering ID = OFFER-123
Version = 7

A quote may reference:

• offering identity;
• exact version;
• and snapshot.

Do not assume identity alone recreates historical meaning.

12. ProductSpecification

A ProductSpecification describes reusable product characteristics and structure.

Potential responsibilities:

• characteristic definitions;
• technical or commercial semantics;
• relationships;
• constraints;
• lifecycle;
• and reusable composition.

It is a definition, not a customer-owned instance.

13. ProductOffering

A ProductOffering represents a sellable market-facing proposition.

It may include:

• market;
• channel;
• price;
• eligibility;
• validity;
• terms;
• bundling;
• and reference to ProductSpecification.

A specification can support multiple offerings.

14. ProductOffering versus ProductSpecification

Example:

ProductSpecification

Business Connectivity

Defines:

• bandwidth;
• access type;
• service tier.

ProductOffering

Business Connectivity 24-Month Premium Offer

Defines:

• term;
• price;
• market;
• discount;
• channel;
• effective period.

15. Configured Product

A configured product represents a selected and parameterized commercial solution.

It may contain:

• chosen offering;
• characteristic values;
• quantity;
• relationships;
• and calculated defaults.

It is not necessarily an inventory product.

16. Configuration Session

A Configuration Session captures an interactive working state.

Possible attributes:

• session ID;
• actor;
• customer context;
• catalog version;
• selected options;
• invalid intermediate state;
• and expiry.

This can be separate from Quote.

17. Product Instance

A Product Instance is a contextual term and must be defined carefully.

Possible meanings:

• configured commercial selection;
• ordered product;
• installed inventory product.

Avoid generic ProductInstance without context qualifier.

18. Inventory Product

An Inventory Product represents a realized product associated with customer/account.

It may include:

• status;
• effective dates;
• installed configuration;
• external realization identifiers;
• and relationships.

It is not the same as the original offering.

19. Product versus Service versus Resource

Product

Customer-facing commercial concept.

Service

Logical capability delivering value.

Resource

Technical or physical element enabling a service.

Example:

Product: Managed Connectivity
Service: WAN Access
Resource: Router, Port, Circuit

20. Offer, Offering, Package, Bundle, and Plan

These words are often overloaded.

A useful distinction:

• Offering: sellable proposition.
• Bundle: composition of offerings/components.
• Package: presentation or commercial grouping.
• Plan: recurring commercial structure.
• Offer: contextual or campaign-specific proposition.

Internal definitions must be explicit.

21. Catalog

Catalog can mean:

• complete product knowledge repository;
• publication;
• market-specific view;
• tenant-specific overlay;
• or runtime snapshot.

Use precise terms such as:

• Product Catalog;
• Catalog Version;
• Catalog Publication;
• Catalog View.

22. Catalog Version

A Catalog Version should define:

• content identity;
• effective period;
• lifecycle;
• and immutability policy.

A version is not merely updated_at.

23. Catalog Publication

A publication may represent:

• approved set;
• environment release;
• tenant/market scope;
• and activation time.

Publication semantics can differ from entity version.

24. Catalog Snapshot

A snapshot is a stable representation at a point in time.

Useful for:

• quote reproducibility;
• testing;
• and rollback.

Snapshot must include enough provenance.

25. Characteristic Specification

Defines:

• name;
• type;
• cardinality;
• allowed values;
• unit;
• default;
• and constraints.

It is not the selected value.

26. Characteristic Value

Represents actual selected or derived value.

Need to distinguish:

• user-provided;
• defaulted;
• calculated;
• inherited;
• and externally sourced.

27. Characteristic Ownership

Ask:

• Who defines it?
• Who selects it?
• Who can override it?
• Who consumes it?
• Who is authoritative after fulfillment?

A configuration characteristic may later map to service/resource attributes.

28. Relationship

A relationship should have explicit semantics.

Examples:

• contains;
• requires;
• excludes;
• substitutes;
• upgrades;
• dependsOn;
• realizes;
• supersedes.

Avoid generic relatedTo.

29. Price Definition

A Price Definition describes a commercial calculation rule.

It may include:

• type;
• amount/rate;
• currency;
• validity;
• condition;
• and precedence.

It is not the same as calculated price.

30. Calculated Price

A Calculated Price is an output for specific context.

It should include:

• component;
• amount;
• currency;
• quantity;
• basis;
• source rule;
• and calculation version.

31. Charge

A Charge is a commercial or billing obligation.

Possible types:

• one-time;
• recurring;
• usage;
• fee;
• penalty;
• credit.

A quoted charge may later become a billing charge.

Preserve lineage.

32. Adjustment

Adjustment modifies a price or charge.

Examples:

• discount;
• surcharge;
• waiver;
• credit;
• manual override.

An adjustment should include:

• reason;
• source;
• authority;
• and scope.

33. Discount versus Promotion

Discount

Reduction based on policy or negotiation.

Promotion

Time- or campaign-bound commercial incentive.

Promotion may produce one or more adjustments.

Do not use both words interchangeably without rule.

34. Quote

A Quote is a commercial proposal.

Potential properties:

• quote ID/number;
• revision;
• customer context;
• items;
• prices;
• terms;
• validity;
• state;
• approval;
• and acceptance evidence.

35. Quote Item

A Quote Item represents part of the commercial proposal.

It may be:

• product offering selection;
• configured component;
• service;
• fee;
• discount;
• or grouping.

The item taxonomy must be explicit.

36. Quote Revision

A revision represents a version of the quote over time.

Questions:

• Is every save a revision?
• Is revision immutable?
• What invalidates approval?
• Which revision is accepted?

37. Quote Version versus Revision

Possible distinction:

• Version: major commercial alternative.
• Revision: sequential change history.

Or the opposite.

The key is consistency.

38. Proposal

A Proposal is customer-facing presentation of commercial content.

It may be:

• generated document;
• structured digital view;
• or package of attachments.

Proposal is not necessarily the authoritative quote.

39. Approval Request

An Approval Request represents a decision need.

It should include:

• scope;
• trigger;
• policy;
• approver;
• status;
• decision;
• reason;
• and related quote revision.

40. Approval Decision

An Approval Decision is an immutable fact.

It should state:

• approved/rejected/conditional;
• by whom;
• under what authority;
• when;
• and for which revision/scope.

41. Agreement

An Agreement represents binding terms between parties.

Potential responsibilities:

• terms;
• signatories;
• effective dates;
• obligations;
• and amendments.

It may be separate from quote.

42. Contract

Contract is often used as legal synonym for Agreement.

In some architectures:

• Agreement is domain entity;
• Contract is document.

In others, the reverse.

Define local semantics.

43. Acceptance

Acceptance is an act and evidence.

It may include:

• actor;
• authority;
• timestamp;
• channel;
• accepted revision;
• and signature/evidence.

Do not model acceptance only as status = ACCEPTED.

44. Product Order

A Product Order is a request to initiate or change customer product state.

It contains intent such as:

• add;
• modify;
• delete;
• suspend;
• resume;
• or replace.

45. Product Order Item

An Order Item carries:

• requested action;
• product/offering reference;
• configuration;
• quantity;
• relationships;
• dates;
• and traceability.

46. Service Order

A Service Order requests service-level realization.

It is not necessarily visible to customer.

It may be derived from Product Order.

47. Resource Order

A Resource Order requests technical or physical resource actions.

Examples:

• allocate port;
• ship device;
• configure VLAN.

48. Fulfillment Plan

A Fulfillment Plan defines executable work structure.

It may contain:

• tasks;
• dependencies;
• milestones;
• assignments;
• and recovery behavior.

49. Order Decomposition

Decomposition transforms commercial order intent into fulfillment units.

It is a process, not merely a static mapping table.

50. Order Fallout

Order Fallout is a failure or exception preventing normal progression.

It should distinguish:

• business failure;
• technical failure;
• retryable;
• manual action;
• and terminal outcome.

51. Inventory

Inventory is a record of realized state.

Possible inventories:

• Product Inventory;
• Service Inventory;
• Resource Inventory.

Do not collapse them without semantic reason.

52. Installed Base

Installed Base is the set of active or historical realized customer products/services/resources.

It supports:

• modify;
• renew;
• terminate;
• support;
• and billing.

53. Asset

Asset may mean:

• physical resource;
• financial asset;
• customer-owned product;
• or installed product.

Avoid generic use.

54. Customer

Customer is a party in a commercial relationship.

Need to distinguish:

• legal customer;
• account;
• buyer;
• user;
• bill payer;
• service owner;
• and contact.

55. Account

Account may be:

• customer account;
• billing account;
• service account;
• commercial account;
• or CRM account.

Always qualify.

56. Related Party

A Related Party links an entity to a party and role.

Example:

Party: Organization X
Role: BillTo

This is more precise than customerId everywhere.

57. Site and Place

Site

Business or operational location concept.

Place

Generic location or geographic reference.

Address

Value describing location.

Do not assume one address equals one serviceable site.

58. Channel

Channel may be:

• direct sales;
• partner;
• digital;
• call center;
• marketplace.

Channel can influence:

• visibility;
• price;
• approval;
• and document.

59. Market

Market can include:

• geography;
• segment;
• regulatory context;
• brand;
• and commercial scope.

Market should not be overloaded into a free-text field.

60. Term

Term may mean:

• contract duration;
• payment term;
• renewal term;
• notice term.

Use qualified names.

61. Effective Date

Effective Date indicates when a business fact becomes valid.

Do not confuse with:

• created time;
• processed time;
• published time;
• or billing start time.

62. Validity Period

Validity period defines when an entity or decision may be used.

Examples:

• offer validity;
• quote validity;
• price validity;
• approval validity.

63. Status versus State

State

Meaningful lifecycle condition with transition semantics.

Status

Often a reporting label.

Prefer state when behavior depends on it.

64. Business State versus Processing State

Business state

Example:

• Quote Accepted.

Processing state

Example:

• Order Conversion Running.

Do not combine them into one enum if lifecycles differ.

65. Integration State

Integration state may track:

• sent;
• acknowledged;
• failed;
• replayed.

This should not replace domain state.

66. Reason Code

A reason code should be:

• stable;
• machine-readable;
• localized externally;
• and linked to business meaning.

Avoid free text as the only reason.

67. Money

Money is a value object containing:

• amount;
• currency;
• precision policy.

Do not use binary floating point.

68. Quantity

Quantity should include:

• numeric value;
• unit;
• and possibly scale.

10 without unit is ambiguous.

69. Date Range

A date range should define:

• start;
• end;
• inclusivity;
• timezone;
• and open-ended behavior.

70. Snapshot

A Snapshot preserves a historical representation.

It should state:

• captured at;
• source;
• version;
• and reason.

71. Projection

A Projection is a read model derived from authoritative events/data.

It may be stale.

Do not treat projection as command-side authority.

72. Cache

Cache is an optimization.

It must not become an accidental source of truth.

Define:

• key;
• freshness;
• invalidation;
• and fallback.

73. Translation Model

An anti-corruption layer translates between contexts.

Example:

External TM Forum ProductOffering
-> Internal CommercialOffering

Translation should be explicit and tested.

74. Canonical Model Advantages

Potential benefits:

• consistent integration;
• reusable tooling;
• simpler analytics;
• standard contracts.

75. Canonical Model Risks

Potential risks:

• lowest-common-denominator semantics;
• giant sparse object;
• ownership ambiguity;
• slow change;
• and leakage across contexts.

76. Semantic Versioning for Domain Contracts

Versioning should consider:

• structural change;
• semantic change;
• behavior;
• and temporal validity.

A field can remain structurally identical but change meaning.

That is still breaking.

77. Naming Rules

Good names are:

• context-specific;
• behaviorally meaningful;
• and stable.

Examples:

• AcceptedQuoteRevision
• ProductOrderItem
• InstalledProduct
• PricingAdjustment

Avoid:

• DataObject;
• MasterEntity;
• GenericItem;
• StatusInfo.

78. Code Smells from Language Ambiguity

• one Product class used everywhere;
• generic Item hierarchy;
• one shared enum for all states;
• Map<String, Object> for characteristics;
• field names copied from external APIs without translation;
• and type deciding multiple unrelated behaviors.

79. Database Smells

• table named product containing catalog and inventory data;
• generic entity_attribute;
• status code without lifecycle documentation;
• mutable historical rows;
• and foreign keys reused across meanings.

80. API Smells

• /products returns offering sometimes and inventory other times;
• update endpoint changes accepted quote;
• generic relatedEntity;
• unqualified accountId;
• and error messages without domain reason.

81. Event Smells

• EntityChanged;
• StatusUpdated;
• ProductUpdated;
• no context or version;
• payload contains giant canonical object;
• and event meaning changes silently.

82. UI Smells

• same label “Product” for catalog and installed asset;
• “Completed” without business meaning;
• hidden revision;
• ambiguous customer/account selector;
• and internal technical status shown to customer.

83. Test Smells

• tests use synthetic names not found in business language;
• fixtures combine catalog and inventory;
• expected status values copied without transition reason;
• and no tests for semantic translation.

84. Glossary Governance

A glossary should have:

• owner;
• context;
• definition;
• examples;
• aliases;
• deprecated terms;
• and review date.

85. Glossary Entry Template

## Term

## Context

## Definition

## Identity

## Lifecycle

## Examples

## Not the Same As

## Aliases

## Owner

## Open Questions

86. Canonical Entity Matrix

87. Identity Mapping Table

Use only after validating internal semantics.

88. Semantic Review Questions

Can two people explain this term identically?
Does the term change meaning across contexts?
Does identity survive attribute changes?
Who owns its lifecycle?
Is it definition, instance, snapshot, or projection?

89. Worked Example: Product Ambiguity

A system uses Product for:

• catalog offering;
• quote line;
• installed service.

Consequences:

• catalog update mutates quote display;
• order cannot identify selected version;
• support cannot distinguish planned from active state.

Fix:

• ProductOffering;
• QuoteProductSelection;
• InventoryProduct;
• explicit lineage.

90. Worked Example: Price Ambiguity

A field price stores:

• base amount;
• discounted amount;
• and billed amount depending on service.

Consequences:

• reconciliation impossible;
• approval reason unclear;
• and document total differs.

Fix:

• BasePrice;
• Adjustment;
• QuotedPrice;
• Charge;
• BilledAmount.

91. Worked Example: Order Ambiguity

Order is used for:

• product request;
• service order;
• work task.

Consequences:

• state semantics collide;
• cancellation authority unclear;
• and UI cannot explain progress.

Fix:

• ProductOrder;
• ServiceOrder;
• FulfillmentTask.

92. Worked Example: Customer Ambiguity

customerId refers alternately to:

• legal customer;
• billing account;
• service user;
• CRM account.

Consequences:

• authorization bug;
• wrong invoice;
• and partner leakage.

Fix:

• RelatedParty with explicit role;
• qualified account references.

93. Worked Example: Status Ambiguity

One enum:

DRAFT
APPROVED
PROCESSING
COMPLETED
FAILED

Problems:

• quote approval mixed with order processing;
• no partial state;
• no reason;
• no transition owner.

Fix:

• separate QuoteState;
• ApprovalState;
• OrderState;
• IntegrationState.

94. Semantic Refactoring Strategy

1. Map actual meanings.
2. Identify collisions.
3. Add context-qualified language.
4. Introduce translation layer.
5. Migrate contracts incrementally.
6. Preserve backward compatibility.
7. Deprecate old terms.
8. Update tests and documentation.

95. Avoiding Big-Bang Vocabulary Rewrite

A full rename across APIs, database, and customers may be risky.

Use:

• aliases;
• façade;
• adapter;
• event translation;
• and versioned contract.

96. Ubiquitous Language Workshop

Participants:

• Product;
• domain experts;
• engineering;
• support;
• operations;
• integration teams.

Activities:

• collect terms;
• define context;
• compare examples;
• identify collisions;
• map entities and lifecycle;
• record open questions.

97. Event Storming Contribution

Event Storming can reveal:

• commands;
• events;
• actors;
• policies;
• aggregates;
• and boundaries.

Use business language, not table names.

98. Example Mapping Contribution

Use examples to clarify:

• state;
• role;
• price;
• and identity.

Example:

When an accepted quote is revised, is it a new revision, a new quote, or an amendment?

99. Senior Engineer Operating Model

Listen

Capture actual language used by domain experts.

Challenge ambiguity

Ask for examples.

Separate contexts

Do not force one global meaning.

Protect identity

Avoid mutable natural keys.

Make translation explicit

Do not hide semantic mapping in random utility code.

Preserve history

Use versions and snapshots where necessary.

Teach the language

Use it in reviews, code, tests, and incidents.

100. Internal Verification Checklist

Vocabulary

• Is there an official glossary?
• Which terms differ across teams?
• Which terms differ from TM Forum vocabulary?
• Which deprecated terms remain in code or APIs?

Identity

• What is the stable ID for offering, quote, order, and inventory product?
• Are business numbers distinct from technical IDs?
• How are external IDs namespaced?
• Which entities require versioned references?

Catalog

• Is ProductSpecification distinct from ProductOffering?
• How are configured selections represented?
• How are catalog version and publication represented?

Quote

• What is quote versus proposal?
• What is version versus revision?
• Is acceptance tied to a revision?
• Is approval a separate entity?

Order and inventory

• Is ProductOrder distinct from ServiceOrder?
• Is installed product distinct from ordered product?
• How is lineage maintained?

Parties

• How are customer, account, partner, bill payer, and user represented?
• Are roles explicit?
• Is signatory authority modeled?

Money and time

• What is authoritative Money type?
• How are units represented?
• What date/time semantics exist?
• Are timezone and validity explicit?

Integration

• Is there a canonical model?
• Who owns translations?
• Which events use ambiguous generic names?
• Which APIs expose local or standard semantics?

101. Practical Exercises

Exercise 1 — Glossary audit

Collect 30 terms from UI, API, code, and documents.

Exercise 2 — Meaning collision

Identify five terms with more than one meaning.

Exercise 3 — Entity classification

Classify 20 concepts as entity, value object, aggregate, snapshot, projection, or event.

Exercise 4 — Identity map

Map technical, business, and external IDs.

Exercise 5 — Context translation

Design translation between internal offering and external ProductOffering.

Exercise 6 — Refactoring plan

Choose one ambiguous entity and create incremental semantic-refactoring steps.

102. Part Completion Checklist

You are done if you can:

• explain ubiquitous language;
• distinguish entity, value object, aggregate, snapshot, and projection;
• separate specification, offering, configured product, and inventory product;
• distinguish quote, proposal, agreement, order, fulfillment plan, and inventory;
• define stable identity and version;
• qualify customer/account/party roles;
• model money, quantity, and time precisely;
• detect semantic smells;
• and build an internal glossary verification backlog.

103. Key Takeaways

1. Language is architecture.
2. Ubiquitous language is context-specific.
3. Product definition, selection, order, and installed instance are different.
4. Identity and version are separate concerns.
5. Quote, proposal, agreement, and acceptance are not synonyms.
6. Product Order, Service Order, and fulfillment task have distinct semantics.
7. Money, quantity, and time require explicit value models.
8. Giant canonical models often hide ambiguity.
9. Translation between contexts should be explicit.
10. Internal vocabulary must be verified before applying standards terminology.

104. References

Conceptual baseline:

• Domain-Driven Design ubiquitous language, entities, value objects, aggregates, and bounded contexts.
• General CPQ, Quote-to-Order, Product Catalog, Product Order, and Inventory domain practices.
• TM Forum domain vocabulary for ProductSpecification, ProductOffering, Quote, ProductOrder, Product Inventory, Party, and Agreement.

These references do not define internal CSG entity names or implementation.