ABS Platform Messaging Convention Dictionary¶

Purpose & Authority¶

This document establishes the unified semantic structure for ALL messaging across the ABS Platform ecosystem. Every topic MUST follow these segment-semantic conventions to ensure consistent interpretation by all sending and receiving parties.

🎯 Goal: Create consistent segment-semantic structures for all future conventions while remaining inclusively tolerant of existing IoT/GATT patterns.

Section 1: High-Level Semantic Framework¶

1.1 Universal Topic Structure¶

All MQTT topics follow a 5-segment semantic structure:

{msg-direction}/{domain}/{context}/{resource}/{identifier}/{action}

1.2 Semantic Consistency Goals¶

1.2.1 Consistent Interpretation¶

Each segment position has fixed semantic meaning
Same segment = same interpretation across ALL topics
Predictable topic construction and parsing

1.2.2 Future-Proof Extensibility¶

New domains/contexts can be added without breaking existing patterns
Clear expansion rules for new business domains
Backward compatibility with existing IoT/GATT patterns

1.2.3 Cross-Platform Tolerance¶

IoT legacy patterns (dt/, cmd/) preserved and integrated
Service patterns (emit/, echo/) follow same semantic rules
Unified parsing logic handles both IoT and service messages

Section 2: Segment Semantic Definitions¶

2.1 Complete Segment Semantics Table¶

📋 Foundation vs Extension: The 6-segment position semantics ({msg_dir}, {domain}, {context}, {resource}, {identifier}, {payload}) are foundational and fixed. However, the actual dictionary entries for each segment are extensible and flexible to accommodate diverse protocols including sender-receiver patterns, custom domains, specialized contexts, and emerging communication needs.

Seg. 1	Seg. 2	Seg. 3	Seg. 4	Seg. 5	Seg. 6	Payload
{msg_dir}	{domain}	{context}	{resource}	{identifier}	{payload}	message_data
`dt`	`arm`	`bms/ph-mnl1`	`fleet_id`	`item_id`	`sensor_data`	Telemetry JSON
`cmd`	`arm`	`bms/ph-mnl1`	`fleet_id`	`item_id`	`lock`	Command JSON
`emit`	`abs`	`payment`	`plan`	`BSS-001`	`deposit_received`	Event JSON
`echo`	`abs`	`payment`	`plan`	`BSS-001`	`deposit_confirmed`	Response JSON
`call`	`abs`	`service`	`plan`	`BSS-001`	`validate_access`	Request JSON
`rtrn`	`abs`	`service`	`plan`	`BSS-001`	`access_validated`	Response JSON
`meta`	`arm`	`bms`	`device_class`	`schema_v1`	`schema`	Schema JSON
`stat`	`arm`	`bms`	`device_class`	`temp_sensor`	`data_broadcast`	Status JSON

Section 3: Segment Dictionaries¶

📚 Critical: For semantic interpretation to work, each segment position has an agreed-upon dictionary of specific phrases. These dictionaries define the exact meaning and interpretation contracts.

🔄 Extensibility Principle: While the 6-segment semantic structure is foundational, the dictionary entries are designed for extension. Teams can add new message directions, domains, contexts, and other segment values to accommodate: - Sender-Receiver Protocols: Custom message flows between specific systems - Specialized Domains: New business areas or external system integrations
- Custom Contexts: Domain-specific functional areas or routing requirements - Protocol Variants: Alternative communication patterns beyond IoT and Service messaging

The semantic positions remain consistent, but the vocabulary adapts to evolving requirements.

3.1 Message Direction Dictionary (Segment 1)¶

Direction	Meaning	Flow	Response	Legacy Compatible
dt	Device Telemetry	Device → Cloud	None	✓ GATT/IoT
cmd	Command/Control	Cloud → Device	Acknowledgment	✓ GATT/IoT
emit	Event Emission	Service → Service	Optional Echo	✓ DIRAC-BRO
echo	Response Confirmation	Service → Service	None (Terminal)	✓ DIRAC-BRO
call	RPC Request	Service → Service	MQTT v5 Response	✓ RPC Extension
rtrn	RPC Response	Service → Service	None (Terminal)	✓ RPC Extension
meta	Metadata/Schema Definitions	Any → Any	None (Retained)	✓ Semantic definitions, "by abcd we mean..."
stat	Status/Data Broadcasts	Any → Any	None (Retained)	✓ Actual data, {"abcd": 1000}

3.2 Domain Dictionary (Segment 2)¶

Domain	Full Name	Responsibility	System Boundary	Owner
abs	Asset-Based Services	Core service platform	ABS Microservice	Platform Team
arm	Asset Relations Management	IoT asset management	ARM Microservice	Asset Team
odo	Odoo ERP Platform	Business operations	External ERP	Business Team
bia	Business Intelligence	Analytics & AI	BIA Microservice	Analytics Team
uxi	User Experience Interface	Frontend applications	UXI Layer	Frontend Team
fed	Federated API	API coordination	FED Gateway	Platform Team
bro	Messaging Broker	Message routing	MQTT Infrastructure	DevOps Team

Domain Addition Rules:¶

3-4 characters: Lowercase, descriptive abbreviation
Unique responsibility: No overlapping system boundaries
Clear ownership: Designated team maintains the domain
Documentation required: Full name and responsibility defined

3.3 Context Dictionary (Segment 3)¶

3.3.1 Service Contexts (for emit/echo messages)¶

Context	Scope	Resource Types	Common Actions	Description
payment	Financial operations	plan, invoice, transaction	received, failed, overdue	Payment processing
asset	Physical/digital assets	battery, device, station	allocated, returned, lost	Asset management
service	Service delivery	plan, access, usage, quota	activated, suspended, expired	Service operations
customer	Customer management	customer, account, profile	registered, verified, updated	Customer lifecycle
iot	IoT device operations	device, sensor, gateway	connected, updated, failed	Device communication
fleet	Fleet coordination	fleet, vehicle, route	dispatched, arrived, completed	Fleet management
maintenance	Asset maintenance	schedule, task, report	created, completed, failed	Maintenance operations
analytics	Data & insights	report, metric, alert	generated, processed, sent	Business intelligence

3.3.2 IoT Contexts (for dt/cmd messages)¶

Context	Device Type	Capabilities	Data Types	Description
bms	Battery Management	Voltage, current, temp monitoring	telemetry, alarms, config	Battery systems
ssc	Swap Station Controller	Door control, safety systems	status, commands, logs	Station operations
gps	GPS Tracker	Location, movement tracking	coordinates, speed, heading	Vehicle tracking
env	Environmental Sensor	Weather, air quality	temperature, humidity, pollution	Environmental monitoring
gateway	IoT Gateway	Data aggregation, connectivity	device_status, network_health	Network coordination

Context Addition Rules:¶

Descriptive nouns: Clear functional area identification
Non-overlapping scope: Each context has distinct responsibility
Resource alignment: Context matches expected resource types
Action compatibility: Context supports logical action types

3.4 Resource Dictionary (Segment 4)¶

3.4.1 Business Resources¶

Resource	ID Format	Scope	Valid Events	Valid Contexts	Description
plan	`{plan-id}`	Service plan instances	created, activated, suspended	payment, service, customer	Service subscriptions
battery	`BAT-{num}`	Battery assets	allocated, returned, charged	asset, iot, fleet	Physical batteries
customer	`cust-{id}`	Customer entities	registered, verified, suspended	customer, payment, service	Customer accounts
invoice	`INV-{num}`	Financial invoices	created, sent, paid, overdue	payment, finance, billing	Billing documents
station	`STATION-{id}`	Swap stations	online, offline, maintenance	asset, iot, maintenance	Physical locations
device	`DEV-{id}`	IoT devices	connected, updated, failed	iot, asset, maintenance	Connected devices
fleet	`FLEET-{id}`	Vehicle fleets	dispatched, arrived, returned	fleet, asset, iot	Vehicle groups
subscription	`SUB-{id}`	Active subscriptions	renewed, expired, cancelled	payment, service, customer	Ongoing services

Resource Addition Rules:¶

Noun-based naming: Clear entity identification
Consistent ID format: Predictable identifier patterns
Event compatibility: Resource supports logical event types
Context alignment: Resource fits within expected contexts

3.5 Action/Event Dictionary (Segment 6)¶

3.5.1 Lifecycle Events¶

Action	Meaning	Applicable Resources	Payload Requirements	Response Expected
created	New entity created	All resources	entity_id, timestamp, initial_state	creation_confirmed
updated	Entity modified	All resources	entity_id, changed_fields, timestamp	update_confirmed
deleted	Entity removed	All resources	entity_id, timestamp, reason	deletion_confirmed
activated	Entity made active	plan, service, device, station	entity_id, timestamp, context	activation_confirmed
suspended	Entity temporarily inactive	plan, service, customer, device	entity_id, reason, timestamp	suspension_confirmed
expired	Entity reached end-of-life	plan, subscription, session	entity_id, timestamp, renewal_options	expiration_acknowledged

3.5.2 Operational Events¶

Action	Meaning	Applicable Resources	Payload Requirements	Response Expected
allocated	Resource assigned	battery, device, service, quota	resource_id, target, timestamp	allocation_confirmed
returned	Resource released	battery, device, asset, service	resource_id, condition, timestamp	return_confirmed
failed	Operation failed	All resources	entity_id, error_code, reason, retry_info	failure_acknowledged
completed	Process finished	task, transaction, service	entity_id, result, timestamp	completion_confirmed
requested	Action requested	All resources	entity_id, request_type, parameters	request_acknowledged

3.5.3 IoT-Specific Actions¶

Action	Meaning	IoT Context	Data Format	Description
sensor_data	Periodic telemetry	All device types	JSON with measurements	Regular data transmission
alarm	Alert condition	bms, ssc, env	Alert code and severity	Emergency notifications
config_update	Configuration change	All device types	Configuration parameters	Device reconfiguration
heartbeat	Connectivity check	All device types	Timestamp and status	Connection monitoring
firmware_update	Software update	All device types	Version and status	Device maintenance

Action Addition Rules:¶

Past tense verbs: Events describe completed actions
Clear semantics: Unambiguous meaning and interpretation
Resource compatibility: Action makes sense for target resource
Payload specification: Required data clearly defined

3.6 Special Pattern Recognition¶

3.6.1 Legacy IoT Pattern Support¶

For backward compatibility with existing GATT/IoT implementations:

# Legacy GATT Pattern:
dt/ov01/GPRSV2/60b032fa3711d64a5c6c22a7/ovPump1900000300/metadata

# Semantic Interpretation:
Direction: dt (device telemetry)
Domain: ov01 (legacy Omnivoltaic)
Context: GPRSV2 (communication technology)
Resource: 60b032fa3711d64a5c6c22a7 (fleet/network ID)
Identifier: ovPump1900000300 (device serial)
Action: metadata (device information)

3.6.2 Service Pattern Standard¶

For new service implementations:

# Standard Service Pattern:
emit/abs/payment/plan/BSS-001/deposit_received

# Semantic Interpretation:
Direction: emit (service event)
Domain: abs (ABS platform)
Context: payment (financial operations)
Resource: plan (service plan entity)
Identifier: BSS-001 (specific plan)
Action: deposit_received (financial event)

Section 4: Implementation & Usage¶

4.1 Topic Construction Algorithm¶

Step-by-Step Topic Building:¶

Choose Message Direction: Select from Direction Dictionary (Section 3.1)
Identify Domain: Select from Domain Dictionary (Section 3.2)
Determine Context: Select from Context Dictionary (Section 3.3)
Specify Resource: Select from Resource Dictionary (Section 3.4)
Provide Identifier: Use resource-specific ID format
Define Action: Select from Action Dictionary (Section 3.5)

Validation Rules:¶

Each segment MUST exist in its respective dictionary
ID format MUST match resource specification
Action MUST be compatible with resource type
Context MUST support the intended action

4.2 Message Payload Requirements¶

Universal Envelope (All Messages):¶

{
  "sid": "schema.v1",           // REQUIRED: Schema identifier
  "ts": 1730182103,             // REQUIRED: Unix timestamp  
  "correlation_id": "uuid-123", // REQUIRED: Unique correlation
  "d": { /* content */ }        // REQUIRED: Message data
}

Optional Envelope Fields:¶

{
  "plan_id": "BSS-001",         // Service plan context
  "tenant_id": "tenant-xyz",    // Multi-tenancy support
  "trace": "trace-abc",         // Distributed tracing
  "actor": {                    // Action context
    "type": "customer|agent|system",
    "id": "actor-identifier"
  }
}

4.3 Subscription Patterns¶

Pattern Construction:¶

Use MQTT wildcards based on semantic segments:

# Monitor all events for specific resource type
emit/+/+/{resource}/+/+

# Monitor specific domain events
emit/{domain}/+/+/+/+

# Monitor specific context across domains
emit/+/{context}/+/+/+

# Load balancing for specific operations
$share/{worker-group}/emit/+/{context}/+/+/+

Common Subscription Examples:¶

# All service plan events
emit/+/+/plan/+/+

# All ABS platform events  
emit/abs/+/+/+/+

# All payment operations
emit/+/payment/+/+/+

# Battery asset tracking
emit/+/asset/battery/+/+

# IoT device telemetry
dt/+/+/+/+/+

4.4 Error Handling Standards¶

Error Response Topics:¶

echo/{domain}/{context}/{resource}/{id}/error

Standard Error Payload:¶

{
  "sid": "error.v1",
  "ts": 1730182103,
  "correlation_id": "original-correlation-id",
  "d": {
    "error_type": "validation_error|resource_error|service_error",
    "error_code": "SPECIFIC_ERROR_CODE",
    "error_message": "Human readable description",
    "retry_after": 300,  // Optional: seconds to wait before retry
    "details": {}        // Optional: error-specific details
  }
}

4.5 Testing Requirements¶

MQTT Emit/Echo Test Pattern:¶

describe('Messaging Integration Test', () => {
  test('should handle payment processing', async () => {
    // 1. EMIT: Send test message
    const emitTopic = 'emit/abs/payment/plan/TEST-001/deposit_received';
    const message = {
      sid: 'evt.v1',
      ts: Date.now(),
      correlation_id: 'test-12345',
      d: { amount: 100, currency: 'USD' }
    };

    await publishMessage(emitTopic, message);

    // 2. ECHO: Validate response
    const echoTopic = 'echo/abs/payment/plan/TEST-001/deposit_confirmed';
    const response = await waitForEcho(echoTopic, 5000);

    expect(response.correlation_id).toBe('test-12345');
    expect(response.d.status).toBe('confirmed');

    // 3. VERIFY: Check system state
    // Additional validation logic
  });
});

Section 5: Dictionary Compliance¶

5.1 Developer Checklist¶

Before implementing any messaging functionality:

[ ] Topic Structure: Follows 6-segment semantic pattern
[ ] Direction: Selected from Dictionary Section 3.1
[ ] Domain: Selected from Dictionary Section 3.2
[ ] Context: Selected from Dictionary Section 3.3
[ ] Resource: Selected from Dictionary Section 3.4
[ ] Identifier: Follows resource ID format specification
[ ] Action: Selected from Dictionary Section 3.5
[ ] Payload: Includes required envelope fields
[ ] Error Handling: Implements standard error responses
[ ] Testing: Follows emit/echo validation pattern

5.2 Code Review Checklist¶

[ ] Dictionary Compliance: All segments exist in dictionaries
[ ] Semantic Consistency: Topic meaning is clear and unambiguous
[ ] ID Format Validation: Identifiers follow specified patterns
[ ] Correlation IDs: Properly implemented for emit/echo pairing
[ ] Error Responses: Follow standard error format
[ ] Documentation: New patterns documented with examples

5.3 Dictionary Extension Process¶

When adding new entries to any dictionary:

Proposal: Create RFC with semantic definition
Review: Technical review for consistency
Approval: Architecture team approval required
Documentation: Update dictionary with examples
Implementation: Code examples and test cases
Communication: Team notification of new entries

Section 6: Quick Reference¶

6.1 Topic Templates¶

# Service Events
emit/{domain}/{context}/{resource}/{id}/{action}

# Service Responses  
echo/{domain}/{context}/{resource}/{id}/{action}

# RPC Requests
call/{domain}/{context}/{resource}/{id}/{verb}

# IoT Telemetry
dt/{domain}/{device-type}/{region}/{fleet_id}/{item_id}/{data-type}

# IoT Commands
cmd/{domain}/{device-type}/{region}/{fleet_id}/{item_id}/{command}

6.2 Common Examples¶

# Payment processing
emit/abs/payment/plan/BSS-001/deposit_received
echo/abs/payment/plan/BSS-001/deposit_confirmed

# Asset allocation
emit/arm/asset/battery/BAT-456/allocated
echo/arm/asset/battery/BAT-456/allocation_confirmed

# IoT telemetry
dt/arm/bms/ph-mnl1/F7/DEV42/sensor_data
dt/arm/ssc/ke-nai1/FLEET-KE/CTRL01/status_update

# RPC requests
call/abs/service/plan/BSS-001/validate_access
call/crm/odoo/customer/C456/sync

# Error responses
echo/abs/payment/plan/BSS-001/error
echo/arm/asset/battery/BAT-456/error

6.3 Dictionary Summary¶

Segment	Purpose	Dictionary Section	Key Examples
1	Message Direction	3.1	dt, cmd, emit, echo
2	Domain	3.2	abs, arm, bss, odoo
3	Context	3.3	payment, asset, service, iot
4	Resource	3.4	plan, battery, customer, station
5	Identifier	Resource-specific	BSS-001, BAT-456, cust-123
6	Action	3.5	created, allocated, failed, received

Conclusion¶

This dictionary establishes semantic consistency across all ABS Platform messaging through:

🎯 Clear Segment Semantics: Each position has fixed meaning
📚 Specific Dictionaries: Agreed-upon vocabulary for each segment
🔄 Legacy Compatibility: Inclusive tolerance for existing IoT/GATT patterns
🚀 Future Extensibility: Clear rules for adding new entries
⚙️ Implementation Ready: Concrete examples and validation rules

Remember: All messaging MUST follow these semantic conventions. When in doubt, consult the dictionaries!

This dictionary is the authoritative source for all messaging conventions. Updates require architecture team approval and must maintain semantic consistency.**