Skip to main content

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:

SectionDescription
idUnique semantic identifier (e.g. c4-model, enterprise-architecture)
versionSemantic version
name, description, maintainer, licenseMetadata
systemDefinitionsOptional reference to system-defined definitions (structure elements, base types, link types, organizational roles, system element/relationship types)
linkTypesList of link type definitions (e.g. documentation, repository, issue-tracker). Centrally defined.
layersList of layer definitions (e.g. business, application, data, technology, knowledge). At least one required. Customers can customize.
organizationalRolesList of organizational role definitions (e.g. watcher, owner, participant). Centrally defined.
profilesList of modeling profiles that supply element types, relationship types, properties, validations, guidelines

Layer (per entry):

FieldDescription
idUnique identifier for the layer
nameDisplay name
descriptionShort description
descriptionDetailedDetailed description (optional)

Organizational role (per entry):

FieldDescription
idUnique identifier for the role
nameDisplay name
descriptionShort description
descriptionDetailedDetailed description (optional)
multipleBoolean; whether multiple assignees are allowed

Link type (per entry):

FieldDescription
idUnique identifier for the link type
nameDisplay name
descriptionShort description
descriptionDetailedDetailed description (optional)

Modeling profile structure

A modeling profile is identified by id and version and contains:

SectionDescription
idUnique 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).
versionSemantic version of the profile (e.g. 1.0.0, 2.1.3).
nameHuman-facing name of the profile (e.g. "C4 Model", "Domain-Driven Design").
descriptionShort description of what this profile provides.
iconOptional 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.
propertyGroupsSemantic 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).
textTemplatesOptional 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.
statusEnumerationsOptional 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.
elementTypesList of element type definitions (node/concept types) in this profile. Defines the vocabulary of model elements and diagrams available when this profile is active.
relationshipTypesList of relationship type definitions (connection types) in this profile. Defines how elements can be connected and with what semantics.
ℹ️note

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.

💡tip

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.

caution

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):

FieldDescription
idTechnical identifier (e.g. c4.container, ddd.aggregate). Must be unique across all element types in a modeling configuration.
nameHuman-facing name (e.g. "Container", "Aggregate Root").
descriptionShort description for architects and modelers.
descriptionDetailedFormal, explanatory description for AI systems (what it represents, how it's used, what it must not be confused with).
tagsOptional free-form categories or profile labels.

Element-specific:

FieldDescription
baseTypeOptional. 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.
layerOptional. Reference to a layer ID from the modeling configuration.
statusEnumerationOptional. ID of a status enumeration from the same profile; defines lifecycle states for instances.
trackableOptional boolean (default false). When true, instances get system tracking fields: creationTs, creator, creatorId, lastModifiedTs, lastModifier, lastModifierId.
propertiesSchemaCustom data fields: references to property group IDs (same profile) or inline field definitions.
organizationalRolesOptional. List of organizational role IDs this element type supports (must be defined in the modeling configuration).
descriptionTextTemplateOptional. Array of text template IDs from the profile used to initialize the description when creating new instances.
managementModeOptional (default user). Who can create and manage instances: user, system, or system-user.

Style:

FieldDescription
style.iconIcon identifier or URL. Ignored when shape is set.
style.accentColorRequired accent color (hex, rgb, or named color).
style.baseColorOptional base/background color (hex, rgb, or named color).
style.defaultCanvasStyleOptional canvas style: card, container, shape, note, image, or freehand.
style.shapeOptional SVG vector or reference. When set, icon is ignored.

Canvas (optional; for element types that can contain other elements):

FieldDescription
canvasConfig.allowedElementTypesArray of element type IDs allowed on this canvas, or "*" for all. Default filter and suggestion for what can be placed.
canvasConfig.descriptionHuman-readable description of what can be placed on this canvas and why.
canvasConfig.descriptionDetailedFormal 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):

FieldDescription
idTechnical identifier (e.g. c4.uses, ddd.aggregate-contains). Must be unique across all relationship types in a modeling configuration.
nameHuman-facing name. Must be lowercase (e.g. "uses", "references").
descriptionShort description; for asymmetric types this is the forward direction.
descriptionDetailedFormal description for AI systems explaining the relationship semantics.

Constraints:

FieldDescription
typeMappingsArray 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:

FieldDescription
bidirectionalBoolean (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.
reverseOptional. 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:

FieldDescription
prefillLabelWhen true, new relationship instances get the relationship type name as the label; when false, label is left empty for the user.

Style:

FieldDescription
style.styleLine style: line (solid), doubled_line, dotted, or dashed.
style.startArrowArrow at source end: arrow, arrow_filled, diamond, diamond_filled, reverse_triangle, circle_filled, or none.
style.endArrowArrow at target end: same options as startArrow.
style.defaultColorDefault line color (hex, rgb, or named color).
style.thicknessLine thickness in pixels (number).

Properties:

FieldDescription
propertiesSchemaCustom 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):

FieldDescription
idUnique identifier for the group within the profile (e.g. technology-stack, risk-metrics). Pattern: lowercase alphanumeric and hyphens.
nameHuman-facing name (e.g. "Technology Stack", "Risk Metrics").
descriptionOptional. Short description of the purpose and usage of this group.
descriptionDetailedOptional. Formal description for AI systems: what the group represents and how its properties relate.
propertiesList of property (field) definitions belonging to this group. At least one required.

Property (field) definition — common fields:

FieldDescription
fieldNameUnique identifier for this field within the properties schema (e.g. riskLevel, technologies). Pattern: lowercase alphanumeric and hyphens.
displayNameHuman-facing name (e.g. "Risk Level", "Technologies").
descriptionOptional. Short description of the purpose and usage of this field.
descriptionDetailedOptional. Formal description for AI systems.
typeData type; see supported property types below.
requiredOptional boolean (default false). Whether the field is required. Applicable to selection, multipleSelection
defaultValueOptional. Default value; must match the field type (e.g. string for text/selection, array of strings for multipleSelection).
Reserved property names

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:

FieldApplies toDescription
optionsselection, multipleSelectionRequired. List of choices. Each option has key (semantic id), name (display name), optional description.
textTemplatesformattedTextRequired. Array of text template IDs from the profile used as initial content. At least one.
colorCoderatingOptional. Color (e.g. hex) used to display the rating in the UI.
textAttachmentFormatattachment-textOptional. Format of the text attachment: text, markdown, yaml, json, or xml.
allowedAttachmentFileExtensionsattachment-text, attachment-image, attachment-binaryOptional. Allowed file extensions when uploading (e.g. ["pdf", "doc", "docx"]). Extensions without leading dot.
Reserved property names

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:

TypeDescription
booleanTrue/false values.
textSingle-line short text.
largeTextMulti-line text.
formattedTextMarkdown-formatted text; use textTemplates for initial content.
selectionSingle choice from a predefined list (static options).
multipleSelectionMultiple choices from a predefined list (static options).
numberNumeric value (integer or decimal).
dateDate (ISO 8601).
timestampDate and time (ISO 8601).
ratingQualitative rating (e.g. 1–5).
attachment-textText-based file attachment.
attachment-imageImage file attachment.
attachment-binaryBinary file attachment.

Customization

To customize the vocabulary for your organization:

  1. Use the default configuration as a base: Reference the default OML configuration (e.g. architecture-model with its profiles) and override only what you need, or copy the profile files and adjust them.
  2. Add or remove profiles: In the main configuration profiles list, add new profile references (with id, version, and optional source) or remove ones you do not need.
  3. Extend a profile: Copy a profile file (e.g. c4-profile-1.0.0.yaml), change its id and/or version if you want a distinct artifact, then add element types, relationship types, property groups, validations, or guidelines. Reference the new profile from the main configuration.
  4. 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.
  5. 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 by id and version; optional source path 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"
💡tip

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

For a consistent look and feel, use the accent colors from the table below when styling your diagrams.

Color nameHexPreview
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