Skip to main content

Open Modeling Language (OML)

Available in product editions: ArchitectProfessional

Introduction​

The Open Modeling Language (OML) is a flexible, extensible meta-modeling system that defines the modeling vocabulary available in your projects. The workbench comes with a profile-based approach: you choose or compose project baselines built from reusable OML profiles, so your projects can adopt industry-standard or custom vocabularies while keeping type safety and consistency.

With OML you can:

  • Use and combine standard or custom modeling languages (e.g. C4, DDD, BPMN, knowledge/ADR profiles).
  • Define element types (nodes/concepts) and relationship types (connections) with clear semantics, validation, and styling.
  • Organize elements by layers, status enumerations, and organizational roles.
  • Attach properties (custom fields), links to external resources, and validations for modeling and AI assistance.

Modeling configurations in form of project baselines are versioned artifacts (e.g. stored in Git) and can be shared across projects for consistent vocabulary and governance.

Key concepts​

Project baselines​

A project baseline (also called "modeling language" or "project configuration") defines everything that can be modeled in a project. It has a unique identifier, a version, and includes:

  • System definitions (optional): Central, immutable building blocks (structure elements, base types, link types, organizational roles, and optionally system element/relationship types).
  • Link types: Types of external links that can be attached to elements (e.g. documentation, repository, issue-tracker).
  • Layers: Architectural or conceptual layers (e.g. business, application, data, technology, knowledge) that element types can reference.
  • Organizational roles: Roles used for collaboration (e.g. watcher, owner, participant) that element types can support.
  • OML profiles: One or more profiles that supply the actual element types, relationship types, and properties.

Projects reference a project baseline (by id and version). The baseline is the single source of truth for the project’s modeling language.

ℹ️note

While the workbench comes with several system baselines that can be used right away, it is advised to create your own baseline and corresponding OML profiles tailored to your project and its requirements. Read more about system baselines, and base your own configurations on one of our references. You can also find information on the customization of project baselines here.

OML profiles​

An OML profile is a cohesive set of vocabulary for a specific concern or domain (e.g. C4, DDD, knowledge/ADRs). Each profile defines:

  • Element types: The node/concept types (e.g. container, aggregate, decision) with base type (default model element, diagram, composite-part, document, or external proxy element), layer, status enumeration, properties schema, allowed relationships, and style.
  • Relationship types: The connection types (e.g. uses, contains) with type mappings (allowed source/target element types), cardinality, composition/aggregation semantics, and style.
  • Property groups and property definitions: Reusable groups of fields (text, selection, element references, dates, ratings, attachments, links, etc.) that element and relationship types reference in their propertiesSchema.
  • Text templates: Reusable markdown templates for formatted-text properties.
  • Status enumerations: Lifecycle states (e.g. draft, in-production, archived) shared by element types.

Profiles are composed into a modeling configuration; the configuration’s layers and organizational roles apply across all profiles.

ℹ️note

While the workbench comes with several useful OML profiles that can be used right away, it is advised to create your own profiles corresponding to your project and its vocabulary. Read more about OML profiles, and base your own configurations on one of our references. You can also find information on the customization of OML profiles here.

Model element types​

Model element types are the main building blocks of the model. Each type has:

  • id, name, description (and optional descriptionDetailed for AI).
  • baseType: default-model-element (persistent concepts), diagram, composite-part, document, or external-proxy-element (representation of an object whose original data is managed in an external system).
  • layer: Reference to a layer in the configuration.
  • statusEnumeration: Optional reference to a status enumeration in the same profile.
  • propertiesSchema: References to property groups (and thus the fields shown on instances).
  • allowedRelationshipsIn / allowedRelationshipsOut: Optional documentation/validation of allowed relationships.
  • style: Icon, colors, shape, default canvas style.
  • canvasConfig: For types that contain a canvas (e.g. diagram, composite-part), which element types are allowed inside.
  • managementMode: user, system, or system-user (who can create/manage instances).

Element and relationship type IDs
IDs must not start with system. to avoid conflicts with the default system configuration.

Diagrams are element types with baseType: "diagram"; documents are element types with baseType: "document".

External proxy elements use baseType: "external-proxy-element". They are persistent, referenceable model elements like default-model-element, but they stand for an object that continues to be managed outside the workbench. You define the types, properties, and allowed relationships in the OML profile — as close to the source as you need, or more abstract. Instances are stored in Git with those properties and are available to the Design Assistant. See External proxy elements for capability and boundaries.

Relationship types​

Relationship types define how elements can be connected. Each type has:

  • id, name, description (and optional descriptionDetailed), and optional reverse name/descriptions for asymmetric bidirectional relationships.
  • typeMappings: Allowed source and target element type combinations (supports wildcards, e.g. c4.*).
  • bidirectional / reverse: Symmetric vs asymmetric bidirectional relationships.
  • relationshipType: default, composition (targets deleted with source), or aggregation (logical grouping only).
  • maxSourceCardinality / maxTargetCardinality: Optional cardinality limits.
  • propertiesSchema and style (line style, arrows, color).

Relationship type names use lowercase (e.g. "uses", "used by").

Layers, status, and organizational roles​

  • Layers are defined once per modeling configuration and referenced by element types. They represent architectural or conceptual views (e.g. business, application, data, knowledge).
  • Status enumerations are defined in an OML profile and define lifecycle states (proposed, active, deactive) with a default value; element types reference one status enumeration.
  • Organizational roles are defined once per configuration; element types declare which roles they support. Instances store role assignments (roleId, userId, userDisplayName) for collaboration and ownership.

Properties schema​

Properties are defined inside property groups in an OML profile. Element types and relationship types reference these groups in their propertiesSchema. Supported property types include: boolean, text, largeText, formattedText, selection, multipleSelection, elementReference, elementReferenceList, number, date, timestamp, rating, user, attachment types, and link. Formatted-text fields can reference text templates for initial content. See Link properties for the link type.

Reserved property names
The following names are reserved and must not be used for custom properties: uuid, label, type, description, summary, icon, creationTs, creator, creatorId, lastModifiedTs, lastModifier, lastModifierId, profileId, profileVersion, serializationVersion.

A link property holds a URL and, optionally, a label. In the workbench the field is shown as a clickable link: the label is the text you see, and the URL is the destination. If no label is set, the URL itself is shown.

Declare it in a property group like any other type. Link properties are a good fit on external proxy elements for fields that point to the original source of the proxy — for example a source property with the URL of the work item or page in the other system. You can also add link properties to other element or relationship types.

- fieldName: "source"
  displayName: "Source"
  description: "The original work item in the issue tracker."
  type: "link"

Set array: true if the field should hold several links. For the type list and other field options, see the OML configuration reference.

What you can do

  • Store a URL on a model element or relationship, with an optional label for display. The value is persisted in Git with the instance.
  • Open the target from details: the field is a real hyperlink, not plain text.
  • On external proxy elements, use a link property for fields that point to the original source of the proxy.
  • Use it anywhere you would use another OML property type — not only on external proxy elements.

Boundaries

  • The stored value is the URL plus the optional label. The workbench does not fetch, preview, or keep the target in sync.
  • Changing the property changes only the model. It does not update the linked system.
  • A link property is a named field of the type. It is not a reference to another model element (elementReference), and it is not the same as an ad-hoc URL in the Loop tab. Loop links are extras on a single instance; a link property appears on every instance of the type.
  • The label is display only. The destination of the click is always the URL.

How OML relates to custom models​

OML replaces the previous custom model approach:

  • Before (custom models): A single project-level file .k5/modelling-config.yaml defined structure elements, element types, and behavior in one place. Customization was limited to that file’s schema.
  • With OML: Modeling is driven by project baselines referencing OML profiles. Configurations are versioned, shareable artifacts. You reference a configuration (by id and version) in the project; the configuration defines layers, link types, organizational roles, and one or more profiles that define element types, relationship types, and properties.

If you used custom model elements or the old modelling config, you should migrate to a project baseline and profiles that define the same (or improved) vocabulary. See the OML configuration reference for structure and examples, and your product or specification documents for migration guidance.

Where to go next​