Skip to main content

OML Profiles

What are OML Profiles?​

An OML Profile is a cohesive set of vocabulary for a specific concern or domain (e.g. C4, DDD, knowledge/ADRs). Each OML 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.

OML Profiles are composed into a modeling configuration (project baseline); the configuration's layers and organizational roles apply across all profiles.

How OML Profiles work​

OML Profiles are defined in YAML files and referenced by a main project baseline. Each OML Profile is versioned independently and can be:

  • Used as-is from the default configuration
  • Customized by copying and modifying
  • Created from scratch for organization-specific needs

The project baseline combines multiple OML Profiles to create a complete modeling vocabulary for your projects.

❗️info

OML profiles are managed in the admin settings of the Workbench. Here, you can create new profiles and manage their status. For further information on the basic structure of an OML profile, view the reference section.

Available OML Profiles as examples​

OML Profiles are flexible configurations that can be created for and adapted to your project, team, use case, methodology, and vocabulary. The following profiles are shipped together with the workbench, built-in as examples and starting points:

C4 Model Profile​

Software architecture visualization at multiple levels of abstraction. Provides element types for Person, System, Container, Component, Database, and deployment infrastructure, along with diagram types for System Context, Container, Component, and Deployment views.

Use when: Developing and documenting software architecture, showing system boundaries, visualizing deployment topology.

Domain-Driven Design Profile​

Tactical DDD patterns for domain modeling. Includes Aggregates, Entities, Value Objects, Commands, Domain Services, Business Events, and Business Errors.

Use when: Modeling complex business domains, implementing DDD patterns, defining domain boundaries.

Implementation Design Profile​

Technical implementation details including classes, methods, services, REST/SOAP APIs, messaging patterns, and database structures.

Use when: Designing technical implementation, documenting APIs, modeling persistence layer, defining integration patterns.

Basic Shapes Profile​

Simple geometric and document shapes for diagrams and visualizations. Includes rectangles, circles, triangles, diamonds, documents, folders, and various other shapes.

Use when: Creating flowcharts, adding visual annotations, creating custom diagrams.

Basic Collaboration Profile​

Collaborative discussions about architecture, design, and domain topics. Provides Discussion Thread elements.

Use when: Capturing collaborative conversations, documenting exploration process, gathering stakeholder input.

Risks, Tech Debt & Health Profile​

Quality and risk tracking. Includes Risk and Tech Debt Item elements with assessment properties and lifecycle tracking.

Use when: Managing technical debt, tracking risks, assessing system health, planning remediation.

Event Storming Profile​

Collaborative domain exploration technique. Provides Domain Events, Commands, Actors, Policies, Aggregates, Systems, Problems, and Insights.

Use when: Running event storming workshops, exploring domain knowledge, discovering business processes.

Architecture Principles, Standards & Policies Profile​

Governance framework for documenting and enforcing architectural principles, standards, and policies.

Use when: Establishing governance, documenting standards, tracking compliance, managing architectural decisions.

Best Practices​

  • Use multiple OML Profiles: Combine OML Profiles to cover different aspects of your architecture
  • Version carefully: Use semantic versioning for OML Profiles and configurations
  • Document customizations: Clearly document any changes to default profiles
  • Share configurations: Store configurations in Git for team collaboration
  • Start simple: Begin with default OML Profiles and customize only when needed
  • Follow naming conventions: Use OML Profile prefixes in element type IDs (e.g., c4.container, ddd.aggregate)
ℹ️note

To learn more about creating your own baselines and OML profiles, visit the Customization overview