From d412717abfa4e60ce3e8eab103eb2a4e049ec008 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 15:10:39 +0100 Subject: [PATCH 1/2] feat: add flow template reference page and JSON schema --- .gitignore | 3 + docs.json | 12 ++++ schemas/flow-template.json | 97 +++++++++++++++++++++++++ template-reference/flow_template.md | 106 ++++++++++++++++++++++++++++ 4 files changed, 218 insertions(+) create mode 100644 .gitignore create mode 100644 schemas/flow-template.json create mode 100644 template-reference/flow_template.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 00000000..ad247459 --- /dev/null +++ b/.gitignore @@ -0,0 +1,3 @@ +.vscode/ +.claude/ +tmp/ \ No newline at end of file diff --git a/docs.json b/docs.json index a3b7ce49..0cb1e8f4 100644 --- a/docs.json +++ b/docs.json @@ -372,6 +372,18 @@ } ] }, + { + "item": "Templates", + "icon": "file-code", + "groups": [ + { + "group": "Flow Templates", + "pages": [ + "template-reference/flow_template" + ] + } + ] + }, { "item": "API Reference", "icon": "code", diff --git a/schemas/flow-template.json b/schemas/flow-template.json new file mode 100644 index 00000000..551a07be --- /dev/null +++ b/schemas/flow-template.json @@ -0,0 +1,97 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "https://kosli.mintlify.app/schemas/flow-template.json", + "title": "Kosli Flow Template", + "description": "Schema for Kosli flow template YAML files used with `kosli create flow --template-file`.", + "type": "object", + "required": ["version"], + "additionalProperties": false, + "properties": { + "version": { + "description": "The version of the specification schema.", + "type": "integer", + "enum": [1] + }, + "trail": { + "description": "The trail specification.", + "type": "object", + "additionalProperties": false, + "properties": { + "attestations": { + "description": "Attestations required at the trail level for it to be compliant.", + "type": "array", + "items": { + "$ref": "#/$defs/trailAttestation" + } + }, + "artifacts": { + "description": "Artifacts expected to be produced in the trail.", + "type": "array", + "items": { + "$ref": "#/$defs/artifact" + } + } + } + } + }, + "$defs": { + "trailAttestation": { + "type": "object", + "required": ["name", "type"], + "additionalProperties": false, + "properties": { + "name": { + "description": "A unique name for the attestation within this template.", + "type": "string" + }, + "type": { + "description": "The attestation type.", + "type": "string", + "enum": ["generic", "jira", "junit", "pull_request", "snyk", "sonar", "*"] + } + } + }, + "artifactAttestation": { + "type": "object", + "required": ["name", "type"], + "additionalProperties": false, + "properties": { + "name": { + "description": "A unique name for the attestation within this artifact.", + "type": "string" + }, + "type": { + "description": "The attestation type. Use `custom:` for custom attestation types.", + "oneOf": [ + { + "type": "string", + "enum": ["generic", "jira", "junit", "pull_request", "snyk", "sonar"] + }, + { + "type": "string", + "pattern": "^custom:.+" + } + ] + } + } + }, + "artifact": { + "type": "object", + "required": ["name"], + "additionalProperties": false, + "properties": { + "name": { + "description": "A reference name for the artifact (e.g. `frontend-app`, `backend`).", + "type": "string" + }, + "attestations": { + "description": "Attestations required for this artifact to be compliant.", + "type": "array", + "items": { + "$ref": "#/$defs/artifactAttestation" + } + } + } + } + } +} diff --git a/template-reference/flow_template.md b/template-reference/flow_template.md new file mode 100644 index 00000000..a6ec3aa2 --- /dev/null +++ b/template-reference/flow_template.md @@ -0,0 +1,106 @@ +--- +title: Flow Template +description: "Reference for the YAML template file used to define compliance controls for a Kosli flow." +--- + +A flow template defines what attestations are required for a trail and its artifacts to be compliant. You pass the template file when creating or updating a flow with [`kosli create flow --template-file`](/client_reference/kosli_create_flow). + +## Specification + + + The version of the specification schema. Currently only `1` is supported. + + + + The trail specification. Defines what must be attested at the trail level and what artifacts are expected. + + + + Attestations required at the trail level for it to be compliant. + + + + A unique name for the attestation within this template. + + + + The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, `*` (matches any type). + + + + + + Artifacts expected to be produced in the trail. Each artifact can have its own attestation requirements. + + + + A reference name for the artifact (e.g. `frontend-app`, `backend`). + + + + Attestations required for this artifact to be compliant. + + + + A unique name for the attestation within this artifact. + + + + The attestation type. One of: `generic`, `jira`, `junit`, `pull_request`, `snyk`, `sonar`, or `custom:` for [custom attestation types](/client_reference/kosli_create_attestation-type). + + + + + + + + +## Example + +Add the `$schema` comment to get editor validation and autocomplete: + +```yaml +# yaml-language-server: $schema=https://kosli.mintlify.app/schemas/flow-template.json +version: 1 +trail: + attestations: + - name: jira-ticket + type: jira + - name: risk-level-assessment + type: generic + artifacts: + - name: backend + attestations: + - name: unit-tests + type: junit + - name: security-scan + type: snyk + - name: frontend + attestations: + - name: manual-ui-test + type: generic + - name: coverage-metrics + type: custom:coverage-metrics +``` + +## Using the template + +Pass the template file when creating or updating a flow: + +```shell +kosli create flow my-flow --template-file ./flow-template.yml +``` + +Once the flow exists, start a trail with [`kosli begin trail`](/client_reference/kosli_begin_trail) and record attestations using the [`kosli attest`](/client_reference/kosli_attest_generic) commands. Kosli evaluates trail compliance against the template automatically. + + + Trail-level attestations apply to the entire trail. Artifact-level attestations apply to a specific artifact produced within the trail. + + +## Editor validation + +A [JSON Schema](https://kosli.mintlify.app/schemas/flow-template.json) is available for the flow template format. Add the following comment to the top of your template file to enable inline validation and autocomplete in VS Code (requires the [YAML extension](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)) and other schema-aware editors: + +```yaml +# yaml-language-server: $schema=https://kosli.mintlify.app/schemas/flow-template.json +``` From 089b1d7f97968d43db0778c92f1e3bef51b699b5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Dan=20Gr=C3=B8ndahl?= Date: Mon, 16 Mar 2026 15:17:00 +0100 Subject: [PATCH 2/2] fix: rename Templates nav item to Template Reference --- .gitignore | 2 +- docs.json | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/.gitignore b/.gitignore index ad247459..94b38948 100644 --- a/.gitignore +++ b/.gitignore @@ -1,3 +1,3 @@ .vscode/ .claude/ -tmp/ \ No newline at end of file +tmp/ diff --git a/docs.json b/docs.json index 0cb1e8f4..7cb9d4fa 100644 --- a/docs.json +++ b/docs.json @@ -373,11 +373,11 @@ ] }, { - "item": "Templates", + "item": "Template Reference", "icon": "file-code", "groups": [ { - "group": "Flow Templates", + "group": "Templates", "pages": [ "template-reference/flow_template" ]