Status & governance
This page answers the question every evaluator asks before adopting a specification: what may still change, who decides, and what happens when it does.
Status of the specification
Section titled “Status of the specification”The specification is published and version 1 is stable. Quoting the spec’s own status section:
The reserved field set is stable in intent; individual field shapes MAY change in minor revisions dated after this document’s revision header. Breaking changes will spawn a separate “version 2” document; version 1 will remain readable indefinitely.
In practice:
- A v1 revision is additive. New reserved fields, new entries in an open vocabulary, new conformance vectors — nothing already published is withdrawn.
- A breaking change does not land in v1. It starts a separate “version 2” document, so /schema/v1.json and /spec/v1 stay addressable at the URLs they have today.
- v1 stays readable indefinitely. There is no sunset date for the document and no forced migration.
The handling rule (§3.7) is what makes the additive promise safe to rely on: a consumer built against an older revision MUST ignore reserved keys and extension namespaces it does not know and MUST preserve them on round-trip. A document written against a newer v1 revision is still readable by every tool that implemented an earlier one.
Revision history
Section titled “Revision history”Every published revision of the specification is a tag in the specification repository. This table is generated from those tags at build time.
| Revision | Published | Document |
|---|---|---|
v1.21.0 | 2026-11-08 | spec/v1.md at v1.21.0 |
v1.20.0 | 2026-11-06 | spec/v1.md at v1.20.0 |
v1.19.0 | 2026-11-03 | spec/v1.md at v1.19.0 |
v1.18.0 | 2026-10-30 | spec/v1.md at v1.18.0 |
v1.17.0 | 2026-10-21 | spec/v1.md at v1.17.0 |
v1.16.3 | 2026-10-19 | spec/v1.md at v1.16.3 |
v1.16.2 | 2026-10-18 | spec/v1.md at v1.16.2 |
v1.16.1 | 2026-10-18 | spec/v1.md at v1.16.1 |
v1.16.0 | 2026-10-18 | spec/v1.md at v1.16.0 |
v1.15.0 | 2026-10-17 | spec/v1.md at v1.15.0 |
v1.14.0 | 2026-10-16 | spec/v1.md at v1.14.0 |
v1.13.0 | 2026-10-13 | spec/v1.md at v1.13.0 |
v1.12.0 | 2026-10-11 | spec/v1.md at v1.12.0 |
v1.11.0 | 2026-10-11 | spec/v1.md at v1.11.0 |
v1.10.0 | 2026-10-09 | spec/v1.md at v1.10.0 |
v1.9.0 | 2026-09-30 | spec/v1.md at v1.9.0 |
v1.8.0 | 2026-09-29 | spec/v1.md at v1.8.0 |
v1.7.0 | 2026-09-26 | spec/v1.md at v1.7.0 |
v1.6.1 | 2026-09-17 | spec/v1.md at v1.6.1 |
v1.6.0 | 2026-09-16 | spec/v1.md at v1.6.0 |
v1.5.0 | 2026-09-06 | spec/v1.md at v1.5.0 |
v1.4.0 | 2026-09-06 | spec/v1.md at v1.4.0 |
v1.3.0 | 2026-08-28 | spec/v1.md at v1.3.0 |
v1.2.0 | 2026-08-28 | spec/v1.md at v1.2.0 |
v1.1.0 | 2026-08-27 | spec/v1.md at v1.1.0 |
v1.0.0 | 2026-08-25 | spec/v1.md at v1.0.0 |
Tool versioning
Section titled “Tool versioning”The three CLIs are versioned separately from the specification, so a document written against one v1 revision works with every tool release, and a tool release never requires a document change. The tools themselves follow Semantic Versioning; read each project’s release notes before upgrading:
| Tool | Repository |
|---|---|
pf-cli |
kiota.ch/projectfile/cli |
pf-bridge |
kiota.ch/projectfile/bridge |
pf-ci |
kiota.ch/projectfile/ci |
Who maintains it
Section titled “Who maintains it”The specification and its tooling are maintained by Damián Búho as a single-maintainer project. Decisions about what lands in a revision are made in the open, in the issue tracker and in pull requests, so the reasoning behind a change is part of the public record.
How to propose a change
Section titled “How to propose a change”Specification changes — new fields, clarifications, corrections, new conformance vectors — go through the specification repository:
- Open an issue describing the change, the current behaviour and the behaviour you expect instead.
- Open a pull request against
spec/v1.mdwith the edit. - Commits follow Conventional Commits; the version a revision implies follows SemVer.
Bug reports and enhancement suggestions are tracked in
Codeberg Issues, with
mirrors on kiota.ch and
GitHub. Security
reports go to damian.buho@proton.me rather than the public tracker.
Registering an extension namespace
Section titled “Registering an extension namespace”You do not need permission to use a namespace. Claim a reverse-DNS path you control, document it at a stable URL, and ship tooling against it; consumers MUST preserve what they do not understand (§3.7), so your namespace survives every round-trip.
Registering it in the non-normative registry is what makes it discoverable. It is advisory, with no gate-keeping:
Contributing an entry is a pull request with a one-line purpose; the registry exists for discoverability, not permission. — §6.5
An entry carries the namespace key, an owner, a stable docs URL, a
one-line summary, a status (proposed, draft, stable, deprecated),
and optionally a shape fragment under spec/shapes/{namespace}.yaml and a
links list naming the tools that consume, produce or reference the namespace.
Licensing of the record
Section titled “Licensing of the record”- Specification text (
spec/v1.md, this site’s prose): CC-BY-4.0. - JSON Schema, examples, site code: MIT.
Implementers MAY copy schema and example snippets without attribution.