Naming & Conventions Guide

Audience: Integrators, schema owners, operators. Use: Apply canonical naming rules for subjects, predicates, schemas, streams, and zone identities.

Overview

BSFG integrations span multiple systems, zones, and teams. Without consistent naming conventions, systems quickly accumulate semantic drift:

OrderCreated (PascalCase) order_created (snake_case) ← standard order-created (kebab-case) order.created (dotted) orderCreated (camelCase)

This multiplicity breaks integration consistency and makes the fact vocabulary fragile.

This guide defines the canonical naming grammar for all identifiers used in BSFG systems:

• Subjects: Entity identifiers (what the fact is about)
• Predicates: State transitions and events (what happened)
• Schemas: Object structure versions
• Streams: JetStream channels organizing facts
• Artifacts: Binary files referenced by facts
• Identities: BSFG node and zone names

Identifier Principles

All BSFG identifiers follow these principles:

Canonical case: lower_snake_case (no spaces, no special characters except underscore)

Readability: Names should be self-documenting and pronounceable

Stability: Identifiers are immutable once deployed. Never rename or reuse.

Domain-oriented: Use domain vocabulary, not generic system terms

ASCII only: No Unicode, no accents, no emoji (for compatibility)

What to Use

What to Avoid

Subject Naming

Subjects identify the entities that facts describe. A subject is a unique reference to something in the world.

Format:

subject := <entity_type>:

Entity types: Lowercase entity kind (what is this subject?)

batch (a production batch) order (a sales or production order) device (equipment or sensor) recipe (a process recipe) lot (a material lot) container (shipping or storage container)

Identifiers: Unique reference within the entity type

batch:B1042 (simple ID) batch:PlantA/B1042 (hierarchical: plant/batch) device:reactor_7 (device with underscore) order:ENT-12345 (order with dash)

Hierarchical Subjects

Use forward slashes (/) to denote hierarchy when an identifier is scoped to a parent entity:

Subject Naming Rules

Entity types are lowercase: batch, order, not Batch or Order

Identifiers can contain alphanumerics, dashes, and slashes: PlantA/B1042, ENT-12345, reactor_7

Use forward slash (/) for hierarchies, never backslash or dot: PlantA/B1042 not PlantA.B1042 or PlantA\B1042

Identifiers must be stable: Once a subject is used in a fact, it never changes. If you need a different identifier, create a new subject.

Predicate Naming

Predicates express semantic meaning — what happened or what state changed.

Format:

predicate := _