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. comes with a profile-based approach: you choose or compose modeling configurations built from reusable modeling 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, validations, and guidelines for modeling and AI assistance.

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

Key concepts​

Modeling configuration​

A modeling configuration (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.
  • Modeling profiles: One or more profiles that supply the actual element types, relationship types, properties, validations, and guidelines.

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

Modeling profiles​

A modeling 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.
  • Validations: Rules (with severity) to enforce consistency.
  • Guidelines: Natural-language policies for modeling and for AI/coding assistants.

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

Element types​

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.
  • organizationalRoles: Optional list of roles (from the configuration) that instances can use.
  • 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.
  • trackable: Optional flag to add system tracking fields (creation/modification user and timestamp).
  • 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 a 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 a 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.

Besides relationships between model elements, OML supports links from elements to external resources. Link types (e.g. documentation, specification, repository, issue-tracker) are defined at the configuration level. Element instances store a list of links (type, label, uri).

Validations and guidelines​

  • Validations: Profile-specific rules with severity (info, warning, error, blocking) and optional scope (element/relationship types). They use an expression language over element/relationship properties.
  • Guidelines: Natural-language policies for humans and AI; they provide proactive guidance and do not enforce or block operations.

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 modeling configurations composed of 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, properties, validations, and guidelines.

If you used custom model elements or the old modelling config, you should migrate to a modeling configuration 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​