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), 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, 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, or document.
  • 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".

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, and attachment types. Formatted-text fields can reference text templates for initial content.

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.

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​