Open Modeling Language (OML) Reference

Introduction

This reference provides the technical specification for Open Modeling Language (OML) configurations and profiles. OML defines the modeling vocabulary for projects: element types, relationship types, layers, properties, and validations. Configurations are versioned artifacts (typically YAML files in Git) that projects reference by id and version.

For an overview of OML concepts, see Open Modeling Language (OML).

For examples of profiles and how to use them, see Profiles.

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

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.

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

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, freehand, or none.
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.
array	Optional boolean (default false). When true, the field holds multiple values. For elementReference, use array: true to allow multiple element references.
isDraggable	Optional boolean (default false). When true, values can be reordered by dragging in the UI (e.g. for ordered lists).
required	Optional boolean (default false). Whether the field is required. Applicable to selection, multipleSelection, elementReference, and elementReferenceSelection.
deprecated	Optional boolean (default false). Whether the field is deprecated and only shown for compatibility reasons.
defaultValue	Optional. Default value; must match the field type (e.g. string for text/selection, array of strings for multipleSelection or for elementReference when array is true).

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

Field	Applies to	Description
options	selection, multipleSelection, elementReferenceSelection	Required for selection types. List of choices. Each option has key (semantic id), name (display name), optional description.
allowedElementTypes	elementReference, elementReferenceSelection	For elementReference: required. Array of element type IDs that can be referenced.
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.

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

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).
elementReference	Reference to one or more model elements. Requires allowedElementTypes. Use array: true to allow multiple element references.
elementReferenceSelection	Single value that can be either a choice from options or a reference to an element type from allowedElementTypes.
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.