Classes

1. Overview / Introduction

Classes — internally referred to as “clazzes” — are the schema layer of SBE, defining the properties and allowable relationships for every type of model object that flows through the digital thread. They are grouped into ontologies, which represent the complete set of object types, attributes, and links across all connected tools. Unlike models, which hold actual instance data, classes are abstract templates that describe what a valid model of that type looks like.

Each SBE instance relies on a tagged ontology of clazzes to standardize representation across channels and tools. Because external tools each define objects differently, SBE classes capture the common denominators so the same concept can be managed consistently across systems.

Classes live in separate partitions from models. This separation allows any number of model entity sets to reuse the same set of clazzes and mappings, while also letting classes evolve independently of the data that references them. For the digital thread to work with a given class type, a mapping must exist for each digital tool that consumes or produces that data.

2. Conceptual Role

Classes address the problem of structural inconsistency across systems by serving as a shared schema layer. They abstract common object types — such as requirements, test cases, or components — into consistent definitions that transcend individual tools. This abstraction ensures that data exchanged through the digital thread retains meaning and integrity regardless of its source.

Conceptually, classes represent the universal vocabulary of the system: the fundamental entities and their relationships that underpin engineering data. Without classes, SBE would lack a mechanism to validate, interpret, and relate incoming model data across domains, leaving the platform fragmented and unable to maintain a coherent digital thread.

3. Design Rationale

SBE's class system is rooted in ontology-based design. Clazzes are stored in class-specific partitions, separate from model data, which allows multiple model entity sets to share the same schema and ensures lifecycle independence between schema and data. This separation supports versioning, reuse, and modularity. Clazzes are organized into entity sets that together form ontologies — self-contained, versioned schema sets that uniformly define how model data is interpreted.

A key design feature is that a class in one branch can reference classes in other branches, provided those referenced classes are accessible in the context of the class doing the referencing. This allows controlled reuse across branches while preserving context-specific consistency.

Trade-offs:

Strict partitioning and contextual referencing improve modularity and interoperability but add to the complexity of initial configuration.
Making active ontologies read-only ensures consistency and stability across the digital thread but limits flexibility and requires careful planning up front.

4. Relationship to Other Resources

Link Dictionary ↔ Classes (direct interaction): The link dictionary defines relation specs and governs the relational aspects of class definitions.
Mappings ↔ Classes (per data source/adapter): Mappings determine how a given data source is translated into SBE model data and must be maintained in conjunction with the class data.
Models (instances) ← constrained by Classes: Models are the instance data shaped/validated by a class’s property and relation specifications.

Conceptual flow:

CODE

External Tool Data
      │
      ▼
Mappings  ── consults ──  Clazzes  +  Link Dictionary
      │
      ▼
Model instances in the Digital Thread

Change/impact notes:

Classes act as dependencies in the architecture.
If a class changes, mappings may need to change:
- Removing a property/relation invalidates any mapping that referenced it.
- Adding a new property often requires a new mapping for tools that care about that property.
- Adding a new class usually requires a new mapping for that type.

4.1 Property Specifications

Property specifications define the attributes that belong to a class. Each property spec identifies a name, data type, format, and whether the property is inherited or locally defined. These specifications determine what data a model instance of that class can contain. TODO: Link to type/format docs or explain them a bit more here.

Property specs ensure that all models based on a class conform to the same structural rules. When a property spec is modified or removed, mappings that reference it must also be updated to maintain consistency across tools and channels.

4.2 Relation Specifications

Relation specifications define the types of links that models of a given type can create with other model instances. A relation spec is associated with a class but may be defined in one of its parent classes and inherited by its descendants.

Each relation spec includes:

A relation type, describing the kind of link (e.g., satisfies, verifies).
A cardinality, specifying how many relations of that type a model can have.
Optional metadata such as valid target types, directionality, or other constraints on how the relation behaves.

Relation specs define the connection rules between classes, enabling traceability and ensuring relationships remain valid and consistent across domains and tools.

Both property and relation specs can be:

Inherited – Properties defined in a parent class are automatically available to all subclasses.
Overridden – A subclass can redefine a property with a new specification, which creates an override rather than deleting the inherited version.
Local – Properties defined directly within the class and not inherited from a parent.

5. Conceptual Usage Patterns

Classes are created and maintained within partitions and versioned via branches. They typically move from definition in a draft state, through validation and tagging, to active use within a channel or multiple channels. There are standard ontologies that can be used directly or extended without modifying the base classes. Individual classes can extend classes in other branches if the parent class resides in a branch that is in the context of the branch of the child class. This ensures a stable foundation of reusable classes rather than requiring everything to be defined from scratch.

Typical usage patterns involve creating or reusing a base ontology of standard classes and extending it with domain- or customer-specific variants. Classes are then mapped to external tool data, producing models that instantiate the defined schema in the digital thread.

Update process: Making changes typically involves branching from an existing class branch, applying updates to classes (and potentially to mappings), validating the changes, and then tagging the new branch as ready for use in one or more channels. Channels must then be configured to consume the newly tagged ontology, ensuring consistency and controlled rollout of schema updates.

6. Common Pitfalls, Misunderstandings, and Troubleshooting

Misunderstanding OWL Inheritance: Developers may expect OWL-style inheritance on properties. In SBE, only class and relation inheritance are honored.
Mixing Classes and Models: Models and clazzes cannot share an entity set. Attempting to do so breaks tooling expectations and validation logic.
Improper Ontology Tagging: Using untagged or inconsistent clazz sets across publishing channels can corrupt the digital thread.
Overriding Inherited Properties: SBE allows this, but users should understand it creates overrides — not deletions — of superclass attributes.