Skip to main content

Customization

Open Modeling Language (OML)​

The modeling vocabulary (element types, relationship types, properties, layers, and validations) is defined by the Open Modeling Language (OML). OML uses modeling configurations composed of modeling profiles: versioned, shareable artifacts that define what can be modeled in a project. Projects reference a modeling configuration (by id and version).

Customization is done by providing own baselines and profiles via admin-settings.

To understand how modeling languages are defined and how to use or compose configurations and profiles, see Open Modeling Language (OML) and the OML configuration reference with its examples. As starting point you can use OML examples.

💡tip

For troubleshooting during customization you may find helpful the log outputs of the pods k5-designer-backend and k5-diagram-modeler-sevice. The names may differ for your installation from the standard.

Profiles​

Creating Custom Profiles​

To create a custom profile for your organization:

  1. Start with a template: Copy an existing profile YAML file from (profiles/profiles.md)
  2. Update metadata: Change the id, version, name, and description
  3. Define element types: Add your custom element types with properties and styles
  4. Define relationship types: Specify how elements can be connected
  5. Add property groups: Create reusable property groups for your elements
  6. Set up validations: Add rules to enforce consistency (optional)
  7. Reference in configuration: Add your profile to the main k5-oml.yaml configuration

For detailed technical specifications, see the Open Modeling Language Reference.

💡tip

Use the profile-id-version (e.g. my-profile-1.0.0.yaml) pattern for naming the profile files.

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

Recipes​

Recipes are reusable artifacts that can be included in baselines and copied to project repositories. They consist of skills, commands, and rules that help guide implementation and enforce standards.

Creating Custom Recipes​

To create custom recipes for your baseline:

  1. Create the recipes folder structure: Set up recipes/skills/, recipes/commands/, and recipes/rules/ directories within your baseline
  2. Add skills: Create markdown files (e.g., recipe-1.md) in the skills folder that describe how implementation should be generated
  3. Add commands: Create markdown files in the commands folder that define commands triggered in the prompt window
  4. Add rules: Create markdown files in the rules folder that define rules for validation and enforcement
  5. Use naming conventions:
    • All skills and those commands and rules, which are prefixed with k5- (e.g., k5-command-1.md, k5-rule-1.md), are automatically managed by the workbench
    • Non-prefixed files are user-managed
💡tip

Commands and rules prefixed with k5- will be automatically managed by the workbench, ensuring they stay synchronized with baseline updates.

Baselines​

Creating Custom Baselines​

To create a custom baseline for your organization:

  1. Start with a template: Copy an existing baseline folder structure or use the structure shown below
  2. Update metadata: Change the id, version, name, and description in the main k5-baseline.yaml configuration file
  3. Update metadata: Change the id, version, name, and description in the main k5-oml.yaml configuration file or use an existing one
  4. Define layers: Add your custom layers in the k5-oml.yaml file (business, application, data, technology, organization, knowledge)
  5. Reference profiles: Specify which profiles to include in your baseline by listing them in the profiles section
  6. Create recipes: Add, remove, alter skills, commands, and rules in the recipes folder structure (optional)
  7. Add documentation: Create a README.md file that describes the baseline and serves as a template for projects
💡tip

Use the baseline-name-VERSION (e.g., my-baseline-1.0.0) pattern for naming the baseline folders.

Default profiles configuration​

You can directly donwload the k5-oml.yaml for further customization. This file represents the included default configuration for OML.

Folder structure​

A typical baseline is outlined in the following showing the folder structure:

baseline-name-VERSION/
├── k5-oml.yaml                    # Main modeling configuration (defines id, version, layers), references the profiles and systemDefinitions
├── k5-baseline.yaml               # System definitions (link types, organizational roles) – optional if using default
├── recipes                        # Folder for the recipes, that are copied to the repository
│   └── skills                     # A folder containing skills
│       └── recipe-1.md            # A skill / recipe that describes how implementation is generated
│   ├── commands                   # A folder containing commands
│   │   └── k5-command-1.md        # A command that is triggered in the prompt window
│   └── rules                      # A folder containing rules
│       └── k5-rule-1.md           # A command that is triggered in the prompt window
└── README.md                      # A readme file, that describes the baseline and is used for the project as template

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"
  - id: "ddd-profile"
    version: "1.0.0"
  # ... other profiles