Models
1. Overview / Introduction
Models are lifecycle-managed objects that serve as the core data units in the digital thread. Each model represents an instance of a class defined in the ontology, complete with its own property values and links to other models. In SBE, models are primarily created and propagated via publishing and subscriptions, although direct interaction is also possible through a REST API.
They act as structured containers of engineering knowledge, ingesting data from external tools and transforming it into a standardized, ontologically aligned form. This enables traceability, interoperability, and lifecycle control across diverse systems.
2. Conceptual Role
Models solve the problem of data heterogeneity across engineering tools by serving as a normalized representation of externally created objects (e.g., requirements, ports, diagrams). Without models, it would be impossible to maintain a coherent digital thread or perform cross-tool analysis and traceability.
They abstract tool-specific details into unified schema-backed objects. In practice, this allows SBE to function as an integration hub — consolidating siloed data into a semantically connected environment.
3. Design Rationale
Models are tightly coupled to classes in the ontology through an origin reference. This reference determines the model's schema — including valid properties and relations — and ensures ontological consistency.
Design decisions include:
Schema enforcement via classes: Ensures uniformity in how data is represented.
Link-based relationships: Connections between models preserve traceability across systems and lifecycles.
Publishing/subscription workflows were prioritized due to the volume of data exchange from external tools. REST APIs are available for fine-grained control, but rarely used for bulk operations.
4. Relationship to Other Resources
Classes: Define the schema (structure and semantics) that each model must follow.
Mappings: Convert external tool data into model-compatible property and relation values. Mappings are also used to refresh models into universal items to be interpreted by the adapter and external tool.
Links: Capture and persist model-to-model relationships in the digital thread.
Subscriptions: Allow models to be shared across channels.
The model sits at the center of SBE’s architecture, acting as a consumer of mappings, instance of classes, and anchor point for relationships.
5. Conceptual Usage Patterns
Models typically go through the following stages:
Created: Triggered via publish, subscription, or API call.
Validated: Checked against schema rules.
Versioned: Stored as new variants if modified.
Linked: Connected to other models via defined relationships.
Consumed: Retrieved for visualization, diffing, or merging.
Models are often the subject of operations like sync, diff, refresh, and archive — all of which interact with their lifecycle state and relationships.
6. Common Pitfalls, Misunderstandings, and Troubleshooting
Subscription Models: When a model is subscribed to, a copy of the authoritative model is created and stored in a clone branch. This copy for the subscribed model is independently managed and versioned from the authoritative model. If a channel subscribes to a set of models and makes a set of links between their authoritative models and the subscribed models, the authoritative models that were originally subscribed to are unaffected by these changes until a diff is applied between the subscribed models and the authoritative models.
7. Model Relationship to Links
Models are tightly integrated with the link system. A model owns all outbound links where it is the source. This ownership determines critical behaviors:
When saving a new version of a model, any outbound links not included in the save request are treated as deleted.
The link service updates outbound links accordingly, but not inbound ones.
When a model is the destination of a link, that link persists through version changes and always targets the latest version. Inbound links remain active, in context, and visible.
Link data appears in two structured areas:
Inbound links: Shown as a flat list at the top level. These represent links where the current model is the destination. They are not organized by relationship name, as the model does not control or validate who links to it.
Outbound links: Structured by relationship name, defined and validated by the model's class (via its origin reference). Only relationships declared in the class can be used to create outbound links from a model.
This distinction ensures data integrity, clear traceability, and schema adherence within the system.
8. Model Comparisons
Model comparison is a core feature of the SBE system, supported through two main operations: diff get and diff apply.
When a model is subscribed, a clone of the original model is created in a new branch (commonly called a clone set). This clone model maintains a relationship to the original authoritative model it was derived from. This structure allows the subscribed (clone) model and the original model to evolve independently over time.
When a user wants to inspect changes between the authoritative model and its clone, the system compares these two versions. The diff process is directional, with a defined source and destination branch, and computes changes to apply from one branch to the other.
The following resources within a model can be diffed:
Origin reference (the class the model is based on)
Property values
Outbound links
Inbound links cannot be diffed from the current model. To view differences in inbound links, the diff must be performed from the source model of those links.
When comparing links during a diff operation, only creates and deletes are supported — updates are not. If a link's destination changes, the system treats this as a deletion of the old link and a creation of a new one.
To determine if a link has been created or deleted, the system compares all outbound links from the source model with those in the destination. A link is considered matching if it connects to the same logical model, even if the version is different (e.g., authoritative vs. subscribed copy). This approach supports context-aware diffing, ensuring semantic matches even across versioned environments.
Additionally, if a link in the source model points to a model that does not exist in the destination branch (i.e., is out-of-context), it will be filtered out of the diff. This prevents applying links that would be invisible to the user, and avoids repeatedly surfacing the same out-of-context link in future diffs.
Three-Way Diffs
The SBE platform supports three-way diffs during model comparisons. In addition to the source and destination models, the system retains the state of the model at the time the last merge was applied (or when the subscription was initially created). This enables comparison of three versions:
The current source model
The current destination model
The last common ancestor (baseline)
This capability is essential when both the source and destination have been independently updated. For instance, a property value might be changed in both branches. During such a diff, the system offers users options to accept, reject, or revert changes:
Accept: Apply the change from the source.
Reject: Retain the current destination value.
Revert: Roll back to the value from the last applied diff or original subscription (baseline).
Three-way diffs are crucial for managing collaboration and maintaining consistency across divergent versions.
Ignoring Unmapped Properties and Relations
To improve diff clarity, the system supports an option to ignore unmapped properties and relations. This feature is available through both the DiffUI and the REST API.
When enabled, the diffing engine identifies properties and relations that are mapped in both the source and destination branches. It does this by evaluating the channel, data source, and data source type associated with each branch, then cross-referencing the mappings for each class.
Only those properties and relations that are commonly mapped on both ends will be included in the diff. This prevents noise in the output caused by schema differences across tools. For example, if a model is published from Tool A and later subscribed to, refreshed and re-published by Tool B (which uses a different mapping set), unmapped properties and links would normally surface in diffs. Enabling this filter hides those differences, resulting in a cleaner and more meaningful comparison.
9. Subscriptions
Subscriptions are mechanisms for bringing models from one channel or branch into another. SBE supports three types of subscriptions, each suited to different use cases:
Manual Subscriptions
With manual subscriptions, users explicitly select individual models they want to subscribe to. This is a static form of subscription that requires manual updates if additional models need to be added or removed later.
Branch-Based Subscriptions
In branch-based subscriptions, users subscribe to all models in the authoritative branch of a channel. This subscription type reflects the current set of authoritative models dynamically:
If models are removed from the authoritative branch, they are surfaced as deletes in the diff.
If new models are added, they appear as creates when comparing authoritative to subscription branches.
This type of subscription provides a comprehensive and up-to-date view of all models from the source branch.
Search-Based Subscriptions
Search-based subscriptions allow users to define dynamic criteria for selecting models. Models are searchable by:
Name
Property values
Relationships
The search is scoped to a specific partition and branch, and it is used by both the model browser UI and the subscription engine.
At subscription creation time, all models matching the criteria are cloned into the subscription's clone set. These search criteria are re-evaluated whenever a user performs a diff. During the diff:
Models no longer matching the criteria are marked for removal.
Newly matching models are marked for addition.
These changes are only enacted when the user explicitly applies the diff, ensuring user control over updates.