Project Baseline Reference

This reference describes the structure and format of project baselines, including the k5-baseline.yaml configuration file, ZIP archive structure, and API operations.

Baseline ZIP Archive Structure

A project baseline is distributed as a ZIP archive with the following structure:

baseline-name-VERSION.zip
├── k5-baseline.yaml          # Baseline metadata and configuration (required)
├── k5-oml.yaml               # OML configuration (required)
├── .recipes/                 # Recipes folder (optional)
│   ├── skills/               # Skills for implementation generation
│   │   └── *.md              # Markdown files
│   ├── commands/             # Commands for prompt window
│   │   └── *.md              # Markdown files
│   └── rules/                # Validation and enforcement rules
│       └── *.md              # Markdown files
└── README.md                 # Documentation (optional)

File Requirements

Required files: k5-baseline.yaml, k5-oml.yaml
Optional files: README.md, .recipes/ folder with any structure
Allowed extensions (root level): .yaml, .yml, .txt, .md
Recipes folder: Any file types allowed under .recipes/
Maximum size: 16 MB

Excluded Files

The following files are automatically excluded during processing:

MacOS resource fork files (._ *)
__MACOSX/ folders and their contents

k5-baseline.yaml Format

The k5-baseline.yaml file defines the baseline metadata and configuration.

Required Fields

id: "baseline-identifier"           # Unique baseline identifier
version: "1.0.0"                     # Semantic version
name: "Baseline Display Name"        # Human-readable name

Optional Fields

description: "Detailed description of the baseline"
tags:
  - "domain-driven-design"
  - "microservices"
icon: "Application"                  # Icon identifier
color: "#0f62fe"                     # Hex color code

Coding Assistant Preferences

Define folder mappings for different coding assistants:

codingAssistantPreferences:
  bob:
    baseFolder: "./.bob"
  cursor:
    baseFolder: "./.cursor"
  github:
    baseFolder: "./.github"

Requirements:

Each coding assistant entry must have a baseFolder property (string)
The baseFolder specifies where the assistant's configuration is stored
Optional mapping array defines source-to-target path transformations

Complete Example

id: "ddd-quarkus-baseline"
version: "1.3.2"
name: "Domain Service based on Quarkus"
description: "A baseline configuration for implementing a domain service based on Quarkus with domain-driven-design principles"
tags:
  - "ddd"
  - "quarkus"
  - "domain-driven-design"
icon: "Application"
color: "#ca3131"
codingAssistantPreferences:
  bob:
    baseFolder: "./.bob"

k5-oml.yaml Format

The k5-oml.yaml file defines the OML configuration. See OML Configuration Reference for complete details.

Required Structure

id: "modeling-configuration-id"
version: "1.0.0"
name: "Configuration Name"
description: "Configuration description"

layers:
  - id: "layer-id"
    name: "Layer Name"
    description: "Layer description"

systemDefinitions:
  - id: "k5-oml-system"
    version: "1.0.0"

profiles:
  - id: "profile-id"
    version: "1.0.0"

Baseline Lifecycle States

Status	Description	Allowed Operations
`DRAFT`	Under development, can be modified	Upload new file, Download, Publish, Deprecate, Delete
`PUBLISHED`	Released for use, immutable	Download, Deprecate
`DEPRECATED`	No longer recommended	Download, Re-publish

State Transitions

DRAFT ──────────> PUBLISHED ──────────> DEPRECATED
  │                   │                      │
  │                   │                      │
  └───────────────────┴──────────────────────┘
           (Delete only from DRAFT)

API Operations

Upload Baseline

Endpoint: POST /api/project-baselines

Request:

Content-Type: multipart/form-data
Field: baselineFile (ZIP file, max 16 MB)
Allowed extensions: .zip
Allowed MIME types: application/zip, application/x-zip-compressed, application/octet-stream

Validation:

ZIP must contain k5-baseline.yaml and k5-oml.yaml
All referenced OML profiles must exist
Baseline ID + version combination must be unique (for new baselines)
For updates: baseline must be in DRAFT status

Response: 201 Created

{
  "baselineId": "ddd-quarkus-baseline",
  "baselineVersion": "1.3.2",
  "name": "Domain Service based on Quarkus",
  "status": "DRAFT",
  "description": "...",
  "tags": ["ddd", "quarkus"],
  "icon": "Application",
  "color": "#ca3131"
}

List Baselines

Endpoint: GET /api/project-baselines

Query Parameters:

publishedBaselineOnly: true | false (filter for published baselines only)
latestVersionOnly: true | false (show only latest version of each baseline)

Response: 200 OK

[
  {
    "baselineId": "ddd-quarkus-baseline",
    "baselineVersion": "1.3.2",
    "name": "Domain Service based on Quarkus",
    "status": "PUBLISHED",
    "k5Oml": { ... }
  }
]

Get Baseline Metadata

Endpoint: GET /api/project-baselines/:baselineId/:version

Response: 200 OK

{
  "baselineId": "ddd-quarkus-baseline",
  "baselineVersion": "1.3.2",
  "name": "Domain Service based on Quarkus",
  "status": "PUBLISHED",
  "k5Oml": {
    "id": "ddd-quarkus-config",
    "version": "1.0.0",
    "layers": [...],
    "profiles": [...]
  }
}

Download Baseline

Endpoint: GET /api/project-baselines/:baselineId/:version/download

Authorization: Requires admin privileges

Response: 200 OK

Content-Type: application/zip
Content-Disposition: attachment; filename="baseline-id-version.zip"
Body: ZIP file buffer

Update Baseline Status

Endpoint: PUT /api/project-baselines/:baselineId/:version/status

Authorization: Requires admin privileges

Request Body:

{
  "status": "PUBLISHED"
}

Allowed Transitions:

DRAFT → PUBLISHED
DRAFT → DEPRECATED
PUBLISHED → DEPRECATED
DEPRECATED → PUBLISHED

Validation for Publishing:

Baseline ZIP file must be valid
All referenced OML profiles must exist and be published

Response: 204 No Content

Delete Baseline

Endpoint: DELETE /api/project-baselines/:baselineId/:version

Authorization: Requires admin privileges

Restrictions:

Only baselines in DRAFT status can be deleted
Published and deprecated baselines cannot be deleted

Response: 204 No Content

Validation Rules

ZIP Archive Validation

Required files present: k5-baseline.yaml, k5-oml.yaml
File extensions (root level): Only .yaml, .yml, .txt, .md allowed
Recipes folder: Any file types allowed under .recipes/
Size limit: Maximum 16 MB
System files: MacOS resource forks and __MACOSX folders excluded

k5-baseline.yaml Validation

Required fields: id, version, name must be present
Version format: Must follow semantic versioning
Coding assistant preferences: If present, each assistant must have baseFolder property

k5-oml.yaml Validation

Required fields: id, version, name, layers must be present
Profile references: All referenced profiles must exist in the system
System definitions: Must reference valid system definition IDs

Status Change Validation

Publishing: All referenced profiles must be in PUBLISHED status
Deletion: Only DRAFT baselines can be deleted
Re-upload: Only DRAFT baselines can be re-uploaded

Error Codes

Error	Description
`ProjectBaselineValidationError`	ZIP structure or YAML content is invalid
`ProjectBaselineAlreadyExistsError`	Baseline with same ID and version already exists
`ProjectBaselineNotFoundError`	Baseline with specified ID and version not found
`ProjectBaselineStatusUpdateNotAllowedError`	Status transition not allowed
`ProjectBaselineDeleteNotAllowedError`	Deletion not allowed (not in DRAFT status)
`ProjectBaselineReferenceNotPublishedError`	Referenced profile not published
`ProjectBaselineVersionIsLowerThanLatestError`	New version is lower than existing latest version

Best Practices

Versioning: Use semantic versioning (MAJOR.MINOR.PATCH)
Testing: Thoroughly test baselines in DRAFT before publishing
Profile dependencies: Ensure all referenced profiles are published first
Documentation: Include comprehensive README.md in the ZIP
Recipes organization: Structure recipes logically in subdirectories
File naming: Use k5- prefix for workbench-managed files
Size optimization: Keep ZIP archives under 16 MB
Backward compatibility: Consider compatibility when creating new versions

Baseline ZIP Archive Structure​

File Requirements​

Excluded Files​

k5-baseline.yaml Format​

Required Fields​

Optional Fields​

Coding Assistant Preferences​

Complete Example​

k5-oml.yaml Format​

Required Structure​

Baseline Lifecycle States​

State Transitions​

API Operations​

Upload Baseline​

List Baselines​

Get Baseline Metadata​

Download Baseline​

Update Baseline Status​

Delete Baseline​

Validation Rules​

ZIP Archive Validation​

k5-baseline.yaml Validation​

k5-oml.yaml Validation​

Status Change Validation​

Error Codes​

Best Practices​

Related Documentation​

Baseline ZIP Archive Structure

File Requirements

Excluded Files

k5-baseline.yaml Format

Required Fields

Optional Fields

Coding Assistant Preferences

Complete Example

k5-oml.yaml Format

Required Structure

Baseline Lifecycle States

State Transitions

API Operations

Upload Baseline

List Baselines

Get Baseline Metadata

Download Baseline

Update Baseline Status

Delete Baseline

Validation Rules

ZIP Archive Validation

k5-baseline.yaml Validation

k5-oml.yaml Validation

Status Change Validation

Error Codes

Best Practices

Related Documentation