Subject Naming

Subject Hierarchy Design

Subject naming is the API of your messaging system. A well-designed hierarchy enables efficient routing, filtering, and access control while remaining intuitive for developers.

Design Principles

Core Subject Pattern

All fleet subjects follow this pattern:

fleet.<env>.veh.<vid>.<category>.<type>

Message Categories

State: fleet.<env>.veh.<vid>.state.*

Current vehicle state, published continuously:

Example publish:

subject := fmt.Sprintf("fleet.prod.veh.%s.state.position", vehicleID)
nc.Publish(subject, positionJSON)

Events: fleet.<env>.veh.<vid>.evt.*

Discrete occurrences, published when they happen:

Events are state transitions, not continuous data. They’re durable—stored in JetStream for audit trails.

Commands: fleet.<env>.veh.<vid>.cmd.*

Instructions sent to vehicles:

Commands flow downstream from fleet management to vehicles.

Command Acknowledgments: fleet.<env>.veh.<vid>.cmdack.*

Responses to commands:

Ack payload includes:

{
  "cmd_id": "cmd-123456",
  "status": "accepted|rejected|completed|failed",
  "error": "optional error message",
  "timestamp": "2024-01-15T10:30:00Z"
}

Wildcard Subscriptions

NATS wildcards enable flexible subscriptions:

Common Subscription Patterns

KV Stores: Digital Twin Shadow

JetStream KV stores maintain desired and reported state:

Subject Pattern (KV)

fleet/<env>/veh/<vid>/desired
fleet/<env>/veh/<vid>/reported

Note: KV uses / separator (bucket path), while pub/sub uses . separator.

Desired State

What the fleet management system wants the vehicle to do:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "geofence_enabled": true,
  "max_altitude": 120,
  "home_position": {
    "lat": 37.7749,
    "lon": -122.4194
  }
}

Reported State

What the vehicle actually reports:

{
  "mode": "AUTO",
  "mission_id": "mission-456",
  "mission_progress": 0.45,
  "geofence_enabled": true,
  "armed": true,
  "in_flight": true,
  "battery_remaining": 0.72
}

Shadow Reconciliation

The Vehicle Gateway continuously:

1. Reads desired state from KV
2. Compares with actual vehicle state
3. Issues commands to align reality with desired
4. Updates reported state

This enables declarative fleet management—set the desired state, let vehicles converge.

Access Control

NATS authorization maps users to allowed subjects:

# Vehicle can publish its own state/events
publish: fleet.prod.veh.VID-001.state.>
publish: fleet.prod.veh.VID-001.evt.>
publish: fleet.prod.veh.VID-001.cmdack.>

# Vehicle can subscribe to commands for itself
subscribe: fleet.prod.veh.VID-001.cmd.>

# Vehicle can read/write its own shadow
kv: fleet/prod/veh/VID-001/*

# Fleet operator can subscribe to all state/events
subscribe: fleet.prod.veh.*.state.>
subscribe: fleet.prod.veh.*.evt.>
subscribe: fleet.prod.veh.*.cmdack.>

# Fleet operator can publish commands
publish: fleet.prod.veh.*.cmd.>

# Fleet operator can manage shadows
kv: fleet/prod/veh/*/desired

This ensures vehicles can’t impersonate other vehicles or publish unauthorized commands.

For detailed coverage of the authorization model, including third-party grants and credential management, see Authorization & Grants.

Subject Design Tradeoffs

Why not flat subjects?

Flat subjects like vehicle-001-position don’t support:

• Wildcard subscriptions
• Hierarchical access control
• Logical grouping

Why not deeper hierarchy?

Subjects like fleet.prod.region.us-west.site.warehouse-a.veh.VID-001.state.position:

• Harder to construct programmatically
• Wildcards become complex
• Changes ripple through the system

The four-level hierarchy balances flexibility with simplicity.

Message Format

All messages use JSON with consistent structure:

{
  "vid": "VID-001",
  "timestamp": "2024-01-15T10:30:00.123Z",
  "seq": 12345,
  "data": {
    // message-specific payload
  }
}

Summary

Next

Stream Configuration →