Skip to content

Update Component/Trait documentation to match current schema and patch semantics #134

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ChathurangaKCD merged 2 commits into from
Nov 27, 2025
Merged

Update Component/Trait documentation to match current schema and patch semantics #134

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f8d1b09
Fix TraitSchema table formatting
ChathurangaKCD Nov 26, 2025
feaca92
Update componenttype examples to match current state
ChathurangaKCD Nov 26, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 10 additions & 14 deletions docs/reference/api/application/component.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,9 @@ title: Component API Reference
# Component

A Component represents a deployable unit of an application in OpenChoreo. It serves as the core abstraction that
defines the component type (Service, WebApplication, ScheduledTask, etc.) and optionally includes build configuration
when using OpenChoreo's CI system to build from source. Components are the primary building blocks used to define
applications within a Project.
references a platform-defined ComponentType (in `{workloadType}/{componentTypeName}` format) and optionally includes
build configuration when using OpenChoreo's CI system to build from source. Components are the primary building blocks
used to define applications within a Project.

## API Version

Expand All @@ -33,7 +33,7 @@ metadata:
| Field | Type | Required | Default | Description |
|---------|-----------------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------|
| `owner` | [ComponentOwner](#componentowner) | Yes | - | Ownership information linking the component to a project |
| `type` | [ComponentType](#componenttype) | Yes | - | Specifies the component type (Service, WebApplication, ScheduledTask, etc.) |
| `componentType` | string | Yes | - | componentType in the format `{workloadType}/{componentTypeName}` (e.g., `deployment/web-app`). See [ComponentType](#componenttype-reference). |
| `build` | [BuildSpecInComponent](#buildspecincomponent) | No | - | Optional build configuration when using OpenChoreo CI to build from source (omit for pre-built images) |

### ComponentOwner
Expand All @@ -42,15 +42,11 @@ metadata:
|---------------|--------|----------|---------|-------------------------------------------------------|
| `projectName` | string | Yes | - | Name of the project that owns this component (min: 1) |

### ComponentType
### ComponentType Reference

The component type determines how the component will be deployed and what resources it can create.

| Value | Description |
|------------------|-------------------------------------|
| `Service` | Long-running service component |
| `WebApplication` | Web application with HTTP endpoints |
| `ScheduledTask` | Scheduled/cron job component |
The `componentType` string points to a platform-defined ComponentType using the format `{workloadType}/{componentTypeName}`.
Examples: `deployment/service`, `cronjob/scheduled-task`, `deployment/web-application`. See [ComponentType](../platform/componenttype.md)
for details.

### BuildSpecInComponent

Expand Down Expand Up @@ -115,7 +111,7 @@ metadata:
spec:
owner:
projectName: my-project
type: Service
componentType: deployment/service
build:
repository:
url: https://github.com/myorg/customer-service
Expand All @@ -142,7 +138,7 @@ metadata:
spec:
owner:
projectName: my-project
type: WebApplication
componentType: deployment/web-app
build:
repository:
url: https://github.com/myorg/frontend
Expand Down
6 changes: 3 additions & 3 deletions docs/reference/api/platform/componenttype.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,10 +53,10 @@ Defines the configurable parameters that developers can set when creating compon

#### Parameter Schema Syntax

Parameters use inline schema syntax with pipe-separated modifiers:
Parameters use inline schema syntax with a single pipe after the type; constraints are space-separated:

```
fieldName: "type | default=value | required=true | enum=val1,val2"
fieldName: "type | default=value enum=val1,val2"
```

Supported types: `string`, `integer`, `boolean`, `array<type>`, custom type references
Expand Down Expand Up @@ -203,7 +203,7 @@ spec:

schema:
parameters:
schedule: "string | required=true"
schedule: string
concurrencyPolicy: "string | default=Forbid | enum=Allow,Forbid,Replace"

resources:
Expand Down
49 changes: 26 additions & 23 deletions docs/reference/api/platform/trait.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,27 +39,27 @@ metadata:

Defines the configurable parameters that developers can set when attaching this trait to a component.

| Field | Type | Required | Default | Description |
|----------------|--------|----------|------------------------------------------------------------|
| `types` | object | No | - | Reusable type definitions referenced in parameters |
| `parameters` | object | No | - | Developer-facing configuration options |
| `envOverrides` | object | No | - | Parameters that can be overridden per environment |
| Field | Type | Required | Default | Description |
|----------------|--------|----------|---------|---------------------------------------------------|
| `types` | object | No | - | Reusable type definitions referenced in parameters|
| `parameters` | object | No | - | Developer-facing configuration options |
| `envOverrides` | object | No | - | Parameters that can be overridden per environment |

#### Parameter Schema Syntax

Uses the same inline schema syntax as ComponentType:
Uses the same inline schema syntax as ComponentType: a single pipe after the type, then space-separated constraints:

```
fieldName: "type | default=value | required=true | enum=val1,val2"
fieldName: "type | default=value enum=val1,val2"
```

**Example:**

```yaml
schema:
parameters:
volumeName: "string | required=true"
mountPath: "string | required=true"
volumeName: string
mountPath: string
containerName: "string | default=app"

envOverrides:
Expand Down Expand Up @@ -110,7 +110,7 @@ Defines a modification using JSONPatch format (RFC 6902) with OpenChoreo extensi

| Field | Type | Required | Description |
|---------|--------|----------|-------------------------------------------------------|
| `op` | string | Yes | Operation: `add`, `replace`, `remove`, `mergeShallow` |
| `op` | string | Yes | Operation: `add`, `replace`, `remove` |
| `path` | string | Yes | JSON Pointer to the field (RFC 6901) |
| `value` | any | No | Value to set (not used for `remove`) |

Expand All @@ -119,14 +119,13 @@ Defines a modification using JSONPatch format (RFC 6902) with OpenChoreo extensi
- **add**: Add a new field or array element
- **replace**: Replace an existing field value
- **remove**: Delete a field
- **mergeShallow**: OpenChoreo extension for overlaying map keys

#### Path Syntax

Supports array filters for targeting specific elements:

```
/spec/containers/[?(@.name=='app')]/volumeMounts/-
/spec/containers[?(@.name=='app')]/volumeMounts/-
```

## Examples
Expand All @@ -142,8 +141,8 @@ metadata:
spec:
schema:
parameters:
volumeName: "string | required=true"
mountPath: "string | required=true"
volumeName: string
mountPath: string
containerName: "string | default=app"

envOverrides:
Expand Down Expand Up @@ -172,7 +171,7 @@ spec:
kind: Deployment
operations:
- op: add
path: /spec/template/spec/containers/[?(@.name=='${trait.parameters.containerName}')]/volumeMounts/-
path: /spec/template/spec/containers[?(@.name=='${trait.parameters.containerName}')]/volumeMounts/-
value:
name: ${trait.parameters.volumeName}
mountPath: ${trait.parameters.mountPath}
Expand Down Expand Up @@ -239,12 +238,12 @@ spec:
version: v1
kind: Deployment
operations:
- op: mergeShallow
path: /spec/template/spec/containers/[?(@.name=='main')]/resources
value:
limits:
cpu: ${trait.parameters.cpuLimit}
memory: ${trait.parameters.memoryLimit}
- op: add
path: /spec/template/spec/containers[?(@.name=='main')]/resources/limits/cpu
value: ${trait.parameters.cpuLimit}
- op: add
path: /spec/template/spec/containers[?(@.name=='main')]/resources/limits/memory
value: ${trait.parameters.memoryLimit}
```

### Multi-Container Trait with forEach
Expand All @@ -257,8 +256,12 @@ metadata:
namespace: default
spec:
schema:
types:
Mount:
name: string
path: string
parameters:
mounts: "array<object> | required=true"
mounts: "[]Mount"

patches:
- target:
Expand All @@ -274,7 +277,7 @@ spec:
name: ${mount.name}
emptyDir: {}
- op: add
path: /spec/template/spec/containers/[?(@.name=='app')]/volumeMounts/-
path: /spec/template/spec/containers[?(@.name=='app')]/volumeMounts/-
value:
name: ${mount.name}
mountPath: ${mount.path}
Expand Down