Open Modeling Language reference
Introduction
This reference summarizes the structure of Open Modeling Language (OML) configurations and profiles. OML defines the modeling vocabulary for projects: element types, relationship types, layers, properties, validations, and guidelines. Configurations are versioned artifacts (e.g. YAML/JSON in Git) that projects reference by id and version.
For an overview of concepts see Open Modeling Language (OML).
Modeling configuration structure
A modeling configuration is the top-level artifact. It defines:
| Section | Description |
|---|---|
id | Unique semantic identifier (e.g. c4-model, enterprise-architecture) |
version | Semantic version |
name, description, maintainer, license | Metadata |
systemDefinitions | Optional reference to system-defined definitions (structure elements, base types, link types, organizational roles, system element/relationship types) |
linkTypes | List of link type definitions (e.g. documentation, repository, issue-tracker). Centrally defined. |
layers | List of layer definitions (e.g. business, application, data, technology, knowledge). At least one required. Customers can customize. |
organizationalRoles | List of organizational role definitions (e.g. watcher, owner, participant). Centrally defined. |
profiles | List of modeling profiles that supply element types, relationship types, properties, validations, guidelines |
Layer (per entry):
| Field | Description |
|---|---|
id | Unique identifier for the layer |
name | Display name |
description | Short description |
descriptionDetailed | Detailed description (optional) |
Organizational role (per entry):
| Field | Description |
|---|---|
id | Unique identifier for the role |
name | Display name |
description | Short description |
descriptionDetailed | Detailed description (optional) |
multiple | Boolean; whether multiple assignees are allowed |
Link type (per entry):
| Field | Description |
|---|---|
id | Unique identifier for the link type |
name | Display name |
description | Short description |
descriptionDetailed | Detailed description (optional) |
Modeling profile structure
A modeling profile is identified by id and version and contains:
| Section | Description |
|---|---|
id | Unique semantic identifier of the profile (e.g. c4, ddd). Must be unique within a modeling configuration. Pattern: lowercase alphanumeric and hyphens with optional dot-separated segments (e.g. c4-system). |
version | Semantic version of the profile (e.g. 1.0.0, 2.1.3). |
name | Human-facing name of the profile (e.g. "C4 Model", "Domain-Driven Design"). |
description | Short description of what this profile provides. |
icon | Optional icon identifier from the Carbon Design System icon catalog (e.g. Application, Document, Network). Used to represent the profile in the UI. See Carbon icons. |
propertyGroups | Semantic groups of related properties used together. Element types, relationship types, and diagram types reference property groups by ID in their propertiesSchema instead of defining properties inline. Each group has id, name, description, optional descriptionDetailed, and properties (list of field definitions). |
textTemplates | Optional list of reusable markdown templates for formatted text. Each template has id, name, description, optional descriptionDetailed, and content (markdown). Referenced by formattedText properties (via textTemplates on the field) and by element types' descriptionTextTemplate to initialize content when creating new instances. Templates are static markdown without variables. |
statusEnumerations | Optional list of status enumerations for element lifecycle. Only element types in this profile can reference them; each element type references exactly one. Each enumeration has id, name, description, optional descriptionDetailed, default (key used when no status is set), and values (ordered list). Each value has key, name, description, optional descriptionDetailed, category (proposed | active | deactive), and order. |
elementTypes | List of element type definitions (node/concept types) in this profile. Defines the vocabulary of model elements and diagrams available when this profile is active. |
relationshipTypes | List of relationship type definitions (connection types) in this profile. Defines how elements can be connected and with what semantics. |
The id of the element-type als determines the folder structure for persistence in a git repository. Each . is interpreted as a /. So the segments represent the resulting folder sructure.
It is highly recommended to start every id with a profile acroynm, like e.g. c4 or ddd. This helps during definition of the profiles and also fosters uniqueness of ids.
Element type and relationship type IDs must not start with system. to avoid conflicts with the default system configuration.
Element type
Each element type extends the named modeling language item base and adds element-specific, style, and optional canvas fields.
Named item (base type, shared with relationship types):
| Field | Description |
|---|---|
id | Technical identifier (e.g. c4.container, ddd.aggregate). Must be unique across all element types in a modeling configuration. |
name | Human-facing name (e.g. "Container", "Aggregate Root"). |
description | Short description for architects and modelers. |
descriptionDetailed | Formal, explanatory description for AI systems (what it represents, how it's used, what it must not be confused with). |
tags | Optional free-form categories or profile labels. |
Element-specific:
| Field | Description |
|---|---|
baseType | Optional. Behavior of the element. default-model-element (default): persistent model elements, referenceable across diagrams. diagram: element is a diagram (diagramContent). composite-part: lives inside parent, not independently accessible. |
layer | Optional. Reference to a layer ID from the modeling configuration. |
statusEnumeration | Optional. ID of a status enumeration from the same profile; defines lifecycle states for instances. |
trackable | Optional boolean (default false). When true, instances get system tracking fields: creationTs, creator, creatorId, lastModifiedTs, lastModifier, lastModifierId. |
propertiesSchema | Custom data fields: references to property group IDs (same profile) or inline field definitions. |
organizationalRoles | Optional. List of organizational role IDs this element type supports (must be defined in the modeling configuration). |
descriptionTextTemplate | Optional. Array of text template IDs from the profile used to initialize the description when creating new instances. |
managementMode | Optional (default user). Who can create and manage instances: user, system, or system-user. |
Style:
| Field | Description |
|---|---|
style.icon | Icon identifier or URL. Ignored when shape is set. |
style.accentColor | Required accent color (hex, rgb, or named color). |
style.baseColor | Optional base/background color (hex, rgb, or named color). |
style.defaultCanvasStyle | Optional canvas style: card, container, shape, note, image, or freehand. |
style.shape | Optional SVG vector or reference. When set, icon is ignored. |
Canvas (optional; for element types that can contain other elements):
| Field | Description |
|---|---|
canvasConfig.allowedElementTypes | Array of element type IDs allowed on this canvas, or "*" for all. Default filter and suggestion for what can be placed. |
canvasConfig.description | Human-readable description of what can be placed on this canvas and why. |
canvasConfig.descriptionDetailed | Formal description for AI systems: allowed types and how the canvas should be used. |
Relationship type (summary)
Each relationship type extends the named modeling language item base and adds constraints, semantics, cardinality, behavior, style, and properties.
Named item (base type, shared with element types):
| Field | Description |
|---|---|
id | Technical identifier (e.g. c4.uses, ddd.aggregate-contains). Must be unique across all relationship types in a modeling configuration. |
name | Human-facing name. Must be lowercase (e.g. "uses", "references"). |
description | Short description; for asymmetric types this is the forward direction. |
descriptionDetailed | Formal description for AI systems explaining the relationship semantics. |
Constraints:
| Field | Description |
|---|---|
typeMappings | Array of rules defining allowed source-to-target combinations. Each rule has sourceElementTypes and targetElementTypes (arrays of element type IDs). Supports wildcards (e.g. c4.*) At least one rule is required. |
Semantics:
| Field | Description |
|---|---|
bidirectional | Boolean (default false). When true, relationship is symmetric and the same name is used both ways; reverse must not be set. When false, can be one-directional or asymmetric; use reverse for asymmetric. |
reverse | Optional. For asymmetric bidirectional only (bidirectional must be false). Defines reverse direction: name (must be lowercase), description, optional descriptionDetailed. Reverse source/target are inferred from the forward type. |
Behavior:
| Field | Description |
|---|---|
prefillLabel | When true, new relationship instances get the relationship type name as the label; when false, label is left empty for the user. |
Style:
| Field | Description |
|---|---|
style.style | Line style: line (solid), doubled_line, dotted, or dashed. |
style.startArrow | Arrow at source end: arrow, arrow_filled, diamond, diamond_filled, reverse_triangle, circle_filled, or none. |
style.endArrow | Arrow at target end: same options as startArrow. |
style.defaultColor | Default line color (hex, rgb, or named color). |
style.thickness | Line thickness in pixels (number). |
Properties:
| Field | Description |
|---|---|
propertiesSchema | Custom data fields: references to property group IDs from the same profile. Relationship instances can carry instance data for those groups. |
Property groups and property types
Property groups are defined at the modeling profile level. Element types, relationship types, and diagram types reference property groups by ID in their propertiesSchema; they do not define individual properties inline. Groups bundle related properties (e.g. risk level and impact) for reuse across types.
Property group (per entry):
| Field | Description |
|---|---|
id | Unique identifier for the group within the profile (e.g. technology-stack, risk-metrics). Pattern: lowercase alphanumeric and hyphens. |
name | Human-facing name (e.g. "Technology Stack", "Risk Metrics"). |
description | Optional. Short description of the purpose and usage of this group. |
descriptionDetailed | Optional. Formal description for AI systems: what the group represents and how its properties relate. |
properties | List of property (field) definitions belonging to this group. At least one required. |
Property (field) definition — common fields:
| Field | Description |
|---|---|
fieldName | Unique identifier for this field within the properties schema (e.g. riskLevel, technologies). Pattern: lowercase alphanumeric and hyphens. |
displayName | Human-facing name (e.g. "Risk Level", "Technologies"). |
description | Optional. Short description of the purpose and usage of this field. |
descriptionDetailed | Optional. Formal description for AI systems. |
type | Data type; see supported property types below. |
required | Optional boolean (default false). Whether the field is required. Applicable to selection, multipleSelection |
defaultValue | Optional. Default value; must match the field type (e.g. string for text/selection, array of strings for multipleSelection). |
The following names are reserved and must not be used for custom property fieldNames: uuid, label, type, description, summary, icon, creationTs, creator, creatorId, lastModifiedTs, lastModifier, lastModifierId, profileId, profileVersion, serializationVersion, tags, identifier.
Property (field) definition — type-specific fields:
| Field | Applies to | Description |
|---|---|---|
options | selection, multipleSelection | Required. List of choices. Each option has key (semantic id), name (display name), optional description. |
textTemplates | formattedText | Required. Array of text template IDs from the profile used as initial content. At least one. |
colorCode | rating | Optional. Color (e.g. hex) used to display the rating in the UI. |
textAttachmentFormat | attachment-text | Optional. Format of the text attachment: text, markdown, yaml, json, or xml. |
allowedAttachmentFileExtensions | attachment-text, attachment-image, attachment-binary | Optional. Allowed file extensions when uploading (e.g. ["pdf", "doc", "docx"]). Extensions without leading dot. |
The following names are reserved and must not be used for property fieldName for relationships: uuid, label, type, description, summary, icon, creationTs, creator, creatorId, lastModifiedTs, lastModifier, lastModifierId, profileId, profileVersion, serializationVersion, tags, identifier, destinationIdentifier, sourceIdentifier, longDescription.
Supported property types:
| Type | Description |
|---|---|
boolean | True/false values. |
text | Single-line short text. |
largeText | Multi-line text. |
formattedText | Markdown-formatted text; use textTemplates for initial content. |
selection | Single choice from a predefined list (static options). |
multipleSelection | Multiple choices from a predefined list (static options). |
number | Numeric value (integer or decimal). |
date | Date (ISO 8601). |
timestamp | Date and time (ISO 8601). |
rating | Qualitative rating (e.g. 1–5). |
attachment-text | Text-based file attachment. |
attachment-image | Image file attachment. |
attachment-binary | Binary file attachment. |
Customization
To customize the vocabulary for your organization:
- Use the default configuration as a base: Reference the default OML configuration (e.g.
architecture-modelwith its profiles) and override only what you need, or copy the profile files and adjust them. - Add or remove profiles: In the main configuration
profileslist, add new profile references (withid,version, and optionalsource) or remove ones you do not need. - Extend a profile: Copy a profile file (e.g.
c4-profile-1.0.0.yaml), change itsidand/orversionif you want a distinct artifact, then add element types, relationship types, property groups, validations, or guidelines. Reference the new profile from the main configuration. - Add layers or rely on system definitions: Layers are defined in the main configuration and can be customized there. Link types and organizational roles typically come from system definitions; do not redefine those in profile files unless your product allows it.
- Version and share: Use semantic versioning for the main configuration and for each profile. Store the folder in Git so configurations can be shared and evolved across projects.
Folder structure
A typical OML configuration is stored in a a folder named .k5 with this structure:
.k5/
├── k5-oml.yaml # Main modeling configuration (id, version, layers, systemDefinitions, profiles)
├── k5-oml-system-1.0.0.yaml # System definitions (link types, organizational roles) – optional if using default
├── c4-profile-1.0.0.yaml # C4 Model profile
└── ddd-profile-1.0.0.yaml # Domain-Driven Design profile
-
Main configuration (
k5-oml.yaml): Defines the configuration id, version, layers, and the list of profiles (each byidandversion; optionalsourcepath if the profile is in a separate file). -
Profile files (e.g.
c4-profile-1.0.0.yaml,ddd-profile-1.0.0.yaml): One file per profile, named by profile id and version.
Main configuration
The main configuration file k5-oml.yaml defines layers, references system definitions, and lists the profiles to include.
The systemDefinitions cannot be customized and must be reference like in the example.
id: "my-custom-model"
version: "1.0.0"
name: "Custom Modeling"
description: "A modeling configuration supporting the C4 Model and Architecture Governance"
layers:
- id: "business"
name: "Business Layer"
description: "Business processes, actors, and value streams"
- id: "application"
name: "Application Layer"
description: "Software applications and services"
- id: "data"
name: "Data Layer"
description: "Data structures, schemas, and storage"
- id: "technology"
name: "Technology Layer"
description: "Infrastructure, platforms, and technology components"
- id: "organization"
name: "Organization Layer"
description: "Organizational structure, teams, and locations"
- id: "knowledge"
name: "Knowledge Layer"
description: "Decisions, assumptions, requirements, and learnings"
systemDefinitions:
- id: "k5-oml-system"
version: "1.0.0"
profiles:
- id: "basic-shapes-profile"
version: "1.0.0"
- id: "my-profile"
version: "1.0.0"
source: "./my-profile-1.0.0.yaml"
- id: "ddd-profile"
version: "1.0.0"
# ... other profiles, optionally with source: "./profile-name-1.0.0.yaml"
Use the profile-id-version (e.g. my-profile-1.0.0.yaml) pattern for naming the profile files.
Example: C4 profile
The C4 profile provides element types and diagram types for C4 Model (Person, System, Container, Component, Database, infrastructure and deployment nodes, and System Context / Container / Component / Deployment diagrams). Relationship types include uses, hosts/deployed on, and contains/contained in. Status enumerations and property groups define lifecycle and relationship details.
Profile metadata and status enumeration:
id: "c4-profile"
version: "1.0.0"
name: "C4 Model Profile"
description: "C4 Model profile for software architecture visualization at multiple levels of abstraction"
icon: "Application"
statusEnumerations:
- id: "c4.default-lifecycle"
name: "Standard Lifecycle"
description: "Standard lifecycle status for architectural elements"
default: "draft"
values:
- key: "new"
displayName: "New"
category: "proposed"
order: 1
- key: "draft"
displayName: "Draft"
category: "proposed"
order: 2
- key: "confirmed"
displayName: "Confirmed"
category: "active"
order: 3
- key: "in-production"
displayName: "In Production"
category: "active"
order: 4
- key: "deprecated"
displayName: "Deprecated"
category: "active"
order: 5
- key: "decommissioned"
displayName: "Decommissioned"
category: "deactive"
order: 6
Selected element types (Person, System, Container, diagram type):
elementTypes:
- id: "c4.person"
name: "Person"
description: "A person who uses the software system"
baseType: "default-model-element"
layer: "business"
statusEnumeration: "c4.default-lifecycle"
organizationalRoles: ["watcher", "owner"]
propertiesSchema:
- "c4-element-common"
style:
icon: "User"
accentColor: "blue"
defaultCanvasStyle: "shape"
- id: "c4.system"
name: "System"
description: "A software system that delivers value to its users"
baseType: "default-model-element"
layer: "application"
statusEnumeration: "c4.default-lifecycle"
organizationalRoles: ["watcher", "domain-expert", "owner"]
propertiesSchema:
- "c4-element-common"
style:
icon: "ContainerServices"
accentColor: "green"
defaultCanvasStyle: "card"
- id: "c4.container"
name: "Container"
description: "A deployable unit within a system that can run independently"
baseType: "default-model-element"
layer: "application"
statusEnumeration: "c4.default-lifecycle"
organizationalRoles: ["watcher", "domain-expert", "owner"]
propertiesSchema:
- "c4-element-common"
- "c4-container-deployment"
style:
icon: "Box"
accentColor: "cyan"
defaultCanvasStyle: "container"
- id: "c4.system-context-diagram"
name: "C4 System Context Diagram (Level 1)"
description: "High-level view showing the system and its users"
baseType: "diagram"
layer: "application"
canvasConfig:
allowedElementTypes: ["c4.person", "c4.system"]
description: "System Context diagrams show the system and its users. Only Person and System elements can be placed on this diagram."
style:
icon: "Diagram"
accentColor: "blue"
defaultCanvasStyle: "card"
Relationship types (uses, contains):
relationshipTypes:
- id: "c4.uses"
name: "uses"
description: "Indicates that one element uses another"
typeMappings:
- sourceElementTypes: ["c4.person", "c4.system", "c4.container", "c4.component"]
targetElementTypes: ["c4.system", "c4.container", "c4.component", "c4.database"]
bidirectional: false
relationshipType: "default"
prefillLabel: true
reverse:
name: "used by"
description: "Elements that use this element"
propertiesSchema:
details: "c4-uses-details"
style:
style: "line"
startArrow: "none"
endArrow: "arrow"
defaultColor: "gray"
thickness: 1
- id: "c4.contains"
name: "contains"
description: "Indicates that an element is contained within an environment"
typeMappings:
- sourceElementTypes: ["c4.environment"]
targetElementTypes: ["c4.container", "c4.database", "c4.infrastructure-node", "c4.deployment-node", "c4.environment"]
- sourceElementTypes: ["c4.system"]
targetElementTypes: ["c4.container"]
- sourceElementTypes: ["c4.container"]
targetElementTypes: ["c4.component"]
bidirectional: false
relationshipType: "aggregation"
prefillLabel: true
reverse:
name: "contained in"
style:
style: "dashed"
startArrow: "none"
endArrow: "arrow"
defaultColor: "teal"
thickness: 2
Property groups (C4):
propertyGroups:
- id: "c4-element-common"
name: "Common Element Properties"
description: "Common properties for C4 elements including technologies"
properties:
- fieldName: "element-technologies"
displayName: "Technologies"
description: "Technologies, frameworks, and tools used by this element"
type: "multipleSelection"
required: false
options:
- key: "java"
displayName: "Java"
- key: "python"
displayName: "Python"
- key: "spring-boot"
displayName: "Spring Boot"
- key: "react"
displayName: "React"
- id: "c4-uses-details"
name: "C4 Uses Relationship Details"
description: "Technical and communication details for C4 'uses' relationships"
properties:
- fieldName: "interactionStyle"
displayName: "Communication Scope"
description: "Whether the communication is synchronous or asynchronous"
type: "selection"
required: false
defaultValue: "sync"
options:
- key: "sync"
displayName: "Synchronous"
- key: "async"
displayName: "Asynchronous"
- fieldName: "uses-protocol"
displayName: "Protocol"
description: "The communication protocol (e.g., HTTP, gRPC, WebSocket)"
type: "selection"
required: false
defaultValue: "http"
options:
- key: "http"
displayName: "HTTP"
- key: "https"
displayName: "HTTPS"
- key: "grpc"
displayName: "gRPC"
- key: "amqp"
displayName: "AMQP"
The C4 profile defines additional property groups (e.g. c4-container-deployment, c4-database-details) that are referenced by element types and relationship types via propertiesSchema.
Example: DDD profile
The Domain-Driven Design profile defines aggregates, entities, value objects, commands, domain services, business events, and business errors, with a contains relationship (composition) and optional property groups and guidelines.
Profile metadata and element types:
id: "ddd-profile"
version: "1.0.0"
name: "Domain-Driven Design Profile"
description: "Domain Driven Design (DDD) is a software development approach that focuses on modeling complex business domains"
icon: "Cube"
elementTypes:
- id: "ddd.aggregate"
name: "Aggregate"
description: "A domain aggregate that groups related entities and value objects"
baseType: "default-model-element"
layer: "application"
trackable: true
style:
icon: "DataConnected"
accentColor: "cool-gray"
defaultCanvasStyle: "card"
- id: "ddd.entity"
name: "Entity"
description: "A domain entity with a unique identity"
baseType: "default-model-element"
layer: "application"
trackable: true
propertiesSchema:
- "ddd-entity-properties"
style:
icon: "Data_1"
accentColor: "teal"
defaultCanvasStyle: "card"
- id: "ddd.value-object"
name: "ValueObject"
description: "A value object without identity, defined by its attributes"
baseType: "default-model-element"
layer: "application"
trackable: true
style:
icon: "Object"
accentColor: "green"
defaultCanvasStyle: "card"
- id: "ddd.command"
name: "Command"
description: "A command that triggers an action or process in the domain"
baseType: "default-model-element"
layer: "business"
trackable: true
propertiesSchema:
- "ddd-command-properties"
style:
icon: "Function_2"
accentColor: "cyan"
defaultCanvasStyle: "card"
- id: "ddd.domain-service"
name: "Domain service"
description: "A domain service that performs domain operations"
baseType: "default-model-element"
layer: "application"
trackable: true
style:
icon: "FlowModeler"
accentColor: "blue"
defaultCanvasStyle: "card"
- id: "ddd.business-event"
name: "Business event"
description: "A business event that represents something that happened in the domain"
baseType: "default-model-element"
layer: "business"
trackable: true
style:
icon: "Trigger"
accentColor: "yellow"
defaultCanvasStyle: "card"
- id: "ddd.business-error"
name: "Business error"
description: "A business error or exception in the domain"
baseType: "default-model-element"
layer: "business"
trackable: true
style:
icon: "IncompleteError"
accentColor: "red"
defaultCanvasStyle: "card"
Relationship type and property groups:
relationshipTypes:
- id: "ddd.contains"
name: "contains"
description: "Indicates that an element contains another element"
typeMappings:
- sourceElementTypes: ["ddd.aggregate"]
targetElementTypes: ["ddd.entity", "ddd.value-object", "ddd.command"]
- sourceElementTypes: ["ddd.entity"]
targetElementTypes: ["ddd.entity", "ddd.value-object"]
- sourceElementTypes: ["ddd.value-object"]
targetElementTypes: ["ddd.value-object"]
bidirectional: false
relationshipType: "composition"
prefillLabel: true
reverse:
name: "contained in"
style:
style: "dashed"
startArrow: "none"
endArrow: "arrow"
defaultColor: "cool-gray"
thickness: 2
propertyGroups:
- id: "ddd-entity-properties"
name: "Entity Properties"
description: "Properties for domain entities"
properties:
- fieldName: "is-root"
displayName: "Root Entity"
description: "Indicates if entity is the root entity of the aggregate"
type: "boolean"
required: false
defaultValue: false
- fieldName: "is-abstract"
displayName: "Abstract"
description: "Indicates if entity is abstract (no instance can be created)"
type: "boolean"
required: false
- id: "ddd-command-properties"
name: "Command Properties"
description: "Properties for domain commands"
properties:
- fieldName: "is-factory"
displayName: "FactoryCommand"
description: "Indicates if command is a factory command for creating root entity instances"
type: "boolean"
required: false
Recommended color scheme
For a consistent look and feel, use the accent colors from the table below when styling your diagrams.
| Color name | Hex | Preview |
|---|---|---|
pure black | #000000 | |
black | #6f6f6f | |
orange | #ba4e00 | |
blue | #0f62fe | |
green | #198038 | |
red | #da1e28 | |
purple | #8a3ffc | |
cyan | #0072c3 | |
teal | #007d79 | |
magenta | #d02670 | |
yellow | #8e6a00 | |
cool-gray | #697077 | |
warm-gray | #726e6e | |
white | #ffffff |