{"row":{"id":"ADR-082","title":"Workflow envelope: single version marker `nika: v1` (supersedes K8s apiVersion form)","file":"adr-082-envelope-nika-v1-single-version-marker.md","status":"accepted","date":"2026-05-25","cites":7,"supersedes":["ADR-021"],"superseded_by":[],"layers":["L0","L0.5"],"tags":["schema","yaml","envelope","version-marker"],"room":true},"pin":{"release_tag":"v0.107.0","commit":"5d61b7e13f1f6a10c17414f61146648f76bcf2bd"}}

[{"k":"h","depth":1,"text":"ADR-082: Workflow envelope — single version marker `nika: v1`","id":"adr-082-workflow-envelope--single-version-marker-nika-v1"},{"k":"h","depth":2,"text":"Context","id":"context"},{"k":"p","inline":[{"k":"text","text":"The public "},{"k":"strong","text":"`nika-spec`"},{"k":"text","text":" (Apache-2.0 · created 2026-05-22 · 5 pillars\nlocked D-2026-05-22-N1..N8) defines the canonical workflow envelope as a\n"},{"k":"strong","text":"single version marker"},{"k":"text","text":":"}]},{"k":"code","lang":"yaml","text":"nika: v1                 # required · language name (key) + contract version (value)\nworkflow: my-workflow-id # required · kebab-case · unique within file\ntasks:\n  <task-id>: ..."},{"k":"p","inline":[{"k":"text","text":"This "},{"k":"strong","text":"supersedes"},{"k":"text","text":" the Kubernetes-style envelope adopted in "},{"k":"strong","text":"ADR-021"},{"k":"text","text":"\n("},{"k":"code","text":"apiVersion: nika.sh/v1"},{"k":"text","text":" + "},{"k":"code","text":"kind"},{"k":"text","text":" + "},{"k":"code","text":"metadata"},{"k":"text","text":" + "},{"k":"code","text":"spec"},{"k":"text","text":"). The spec\nexplicitly rejects the two-field "},{"k":"code","text":"apiVersion:"},{"k":"text","text":"/"},{"k":"code","text":"schema:"},{"k":"text","text":" ceremony\n(cf "},{"k":"code","text":"nika-spec spec/01-envelope.md"},{"k":"text","text":" · \"Why one field, not apiVersion +\nschema\") on the grounds that modern specs converge on a single version\nmarker — OpenAPI writes "},{"k":"code","text":"openapi: 3.1.0"},{"k":"text","text":", Docker Compose dropped its\n"},{"k":"code","text":"version:"},{"k":"text","text":" field entirely."}]},{"k":"p","inline":[{"k":"text","text":"Two contradictory legacy forms were also still scattered across engine\ndocs and surfaced by a verification swarm 2026-05-25:"}]},{"k":"list","ordered":false,"items":[[{"k":"code","text":"apiVersion: nika.sh/v1"},{"k":"text","text":" (the ADR-021 K8s form)"}],[{"k":"code","text":"schema: \"nika/workflow@0.12\""},{"k":"text","text":" (the pre-Diamond brouillon form)"}]]},{"k":"p","inline":[{"k":"text","text":"A phantom citation "},{"k":"code","text":"ADR-044"},{"k":"text","text":" (\"adr-044-schema-envelope.md\") was referenced\nin several docs but the file never existed."}]},{"k":"h","depth":2,"text":"Decision","id":"decision"},{"k":"p","inline":[{"k":"strong","text":"Adopt `nika: v1` as the single canonical envelope version marker for\nevery Nika user-facing workflow YAML."},{"k":"text","text":" The contract version is "},{"k":"code","text":"v1"},{"k":"text","text":",\nlocked forever — a "},{"k":"code","text":"v2"},{"k":"text","text":" would require a breaking LANGUAGE contract change\n· effectively never. This LANGUAGE-envelope axis is "},{"k":"strong","text":"orthogonal to the\nengine version"},{"k":"text","text":": the engine ships real semver toward a 1.0 launch (ADR-002\n· amended D-2026-06-20-N1), but "},{"k":"code","text":"nika: v1"},{"k":"text","text":" stays frozen across every engine\nmajor (it is the real \"v1\" signal adopters always saw)."}]},{"k":"list","ordered":false,"items":[[{"k":"text","text":"The "},{"k":"strong","text":"`kind` discriminator"},{"k":"text","text":" + multi-document rationale from ADR-021\n"},{"k":"strong","text":"survives"},{"k":"text","text":" (9 doc kinds: Workflow · Skill · Agent · Provider · Mcp ·\nEval · Recipe · Shield · Lints). Only the "},{"k":"strong","text":"version-field shape"},{"k":"text","text":"\nchanged: "},{"k":"code","text":"apiVersion: nika.sh/v1"},{"k":"text","text":" → "},{"k":"code","text":"nika: v1"},{"k":"text","text":"."}],[{"k":"text","text":"The engine's internal canonical URI stays "},{"k":"code","text":"https://nika.sh/spec/v1"},{"k":"text","text":" for\nRDF / conformance tooling — but the "},{"k":"strong","text":"author never types a URL"},{"k":"text","text":"."}],[{"k":"text","text":"The serde discriminator becomes "},{"k":"code","text":"#[serde(tag = \"nika\")]"},{"k":"text","text":" with variant\n"},{"k":"code","text":"#[serde(rename = \"v1\")]"},{"k":"text","text":" (was "},{"k":"code","text":"tag = \"schema\""},{"k":"text","text":" / "},{"k":"code","text":"nika/workflow@0.12"},{"k":"text","text":")."}]]},{"k":"h","depth":2,"text":"Consequences","id":"consequences"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"nika-schema"},{"k":"text","text":" parser rewrite (Phase D) targets "},{"k":"code","text":"nika: v1"},{"k":"text","text":", not the\n"},{"k":"code","text":"apiVersion:"},{"k":"text","text":"/"},{"k":"code","text":"schema:"},{"k":"text","text":" forms."}],[{"k":"text","text":"ADR-021 marked "},{"k":"code","text":"superseded"},{"k":"text","text":"; its "},{"k":"code","text":"kind"},{"k":"text","text":"/multi-doc analysis stays valid\nreference material."}],[{"k":"text","text":"The phantom "},{"k":"code","text":"ADR-044"},{"k":"text","text":" references are removed; this ADR is the canonical\nengine-side anchor for the envelope decision (mirrors the public spec)."}],[{"k":"text","text":"Public canon source of truth: "},{"k":"code","text":"nika-spec spec/01-envelope.md"},{"k":"text","text":"."}]]},{"k":"h","depth":2,"text":"Related","id":"related"},{"k":"list","ordered":false,"items":[[{"k":"code","text":"docs/adr/adr-021-yaml-envelope-convention.md"},{"k":"text","text":" (superseded · K8s form)"}],[{"k":"code","text":"nika-spec"},{"k":"text","text":" spec/01-envelope.md — the public "},{"k":"code","text":"nika: v1"},{"k":"text","text":" contract"}],[{"k":"code","text":"docs/architecture/forward-compat-invariants.md"},{"k":"text","text":" — FCI-009 envelope versioning"}]]}]

ADR-082

Workflow envelope: single version marker `nika: v1` (supersedes K8s apiVersion form)

accepted · 2026-05-25 · L0 L0.5 · cites 7

Supersedes ADR-021.

ADR-082: Workflow envelope — single version marker `nika: v1` #

Context #

The public `nika-spec` (Apache-2.0 · created 2026-05-22 · 5 pillars locked D-2026-05-22-N1..N8) defines the canonical workflow envelope as a single version marker:

yaml

1nika: v1                 # required · language name (key) + contract version (value)2workflow: my-workflow-id # required · kebab-case · unique within file3tasks:4  <task-id>: ...

This supersedes the Kubernetes-style envelope adopted in ADR-021 (apiVersion: nika.sh/v1 + kind + metadata + spec). The spec explicitly rejects the two-field apiVersion:/schema: ceremony (cf nika-spec spec/01-envelope.md · "Why one field, not apiVersion + schema") on the grounds that modern specs converge on a single version marker — OpenAPI writes openapi: 3.1.0, Docker Compose dropped its version: field entirely.

Two contradictory legacy forms were also still scattered across engine docs and surfaced by a verification swarm 2026-05-25:

apiVersion: nika.sh/v1 (the ADR-021 K8s form)
schema: "nika/[email protected]" (the pre-Diamond brouillon form)

A phantom citation ADR-044 ("adr-044-schema-envelope.md") was referenced in several docs but the file never existed.

Decision #

Adopt `nika: v1` as the single canonical envelope version marker for every Nika user-facing workflow YAML. The contract version is v1, locked forever — a v2 would require a breaking LANGUAGE contract change · effectively never. This LANGUAGE-envelope axis is orthogonal to the engine version: the engine ships real semver toward a 1.0 launch (ADR-002 · amended D-2026-06-20-N1), but nika: v1 stays frozen across every engine major (it is the real "v1" signal adopters always saw).

The `kind` discriminator + multi-document rationale from ADR-021 survives (9 doc kinds: Workflow · Skill · Agent · Provider · Mcp · Eval · Recipe · Shield · Lints). Only the version-field shape changed: apiVersion: nika.sh/v1 → nika: v1.
The engine's internal canonical URI stays https://nika.sh/spec/v1 for RDF / conformance tooling — but the author never types a URL.
The serde discriminator becomes #[serde(tag = "nika")] with variant #[serde(rename = "v1")] (was tag = "schema" / nika/[email protected]).

Consequences #

nika-schema parser rewrite (Phase D) targets nika: v1, not the apiVersion:/schema: forms.
ADR-021 marked superseded; its kind/multi-doc analysis stays valid reference material.
The phantom ADR-044 references are removed; this ADR is the canonical engine-side anchor for the envelope decision (mirrors the public spec).
Public canon source of truth: nika-spec spec/01-envelope.md.

docs/adr/adr-021-yaml-envelope-convention.md (superseded · K8s form)
nika-spec spec/01-envelope.md — the public nika: v1 contract
docs/architecture/forward-compat-invariants.md — FCI-009 envelope versioning

read at v0.107.0 · the decision record ships with the engine

Every decision, with its status This one in the repo

Workflow envelope: single version marker `nika: v1` (supersedes K8s apiVersion form)

ADR-082: Workflow envelope — single version marker `nika: v1` #

Context #

Decision #

Consequences #

Related #