Provenance is the chain of custody for API knowledge — the history and origin story behind every artifact, rule, and decision — and it’s one of the quietly essential foundations of trustworthy governance. To trust an API definition, you need to know where it came from, who produced it, how it was generated, and how it has changed over time. To follow a governance rule willingly, you need to know why it exists, who decided it, and what reasoning produced it. Provenance is the answer to all those “where did this come from” questions, and the answers turn out to matter enormously. An artifact or a rule without provenance is an orphan you have no basis to trust; an artifact or a rule with clear provenance can be evaluated, trusted, and acted on with confidence. I’ve come to see provenance as a governance fundamental, because so much of governance depends on being able to trace things back to their origins.
I started thinking about provenance concretely in the context of OpenAPI, and the technical instinct was clear early. I wrote in 2017 about thinking about OpenAPI provenance — proposing extensions to capture where an API definition came from, how it was generated, and how it evolved. The instinct was that an OpenAPI definition shouldn’t be a context-free file you find lying around; it should carry its own provenance, documenting its source and its history so that anyone using it knows whether to trust it. A definition generated automatically from source code by the owning team has different provenance — and different trustworthiness — than a definition someone hand-wrote and abandoned. Capturing that provenance, making the origin and history of the definition part of the artifact itself, was an early expression of an instinct that would deepen over the years: that knowing where things come from is essential to being able to trust and govern them.
The data and dependency dimension of provenance is where it connects to real operational risk, and I pushed on it deliberately. I wrote in 2018 about making sure my API dependencies include data provenance — because when your API depends on data from other sources, knowing the provenance of that data (where it came from, how reliable it is, what its lineage is) is essential to understanding and governing your own API’s behavior. Including API dependencies within your API definition, which I wrote about in 2017, is partly a provenance discipline: documenting what your API depends on so the chain of dependencies is traceable. My concerns as a public data steward, which I wrote about in 2017, centered substantially on provenance — tracking the sources and origins of public data as it flows through systems, because data without provenance can’t be trusted or properly governed. Provenance, in the data context, is what lets you reason about the reliability and lineage of the information your APIs move.
The role of provenance in dealing with change is where it becomes genuinely central to governance, and I articulated it most fully in 2024. I wrote about the role of provenance in dealing with API change — because managing change responsibly requires knowing the history. When an API changes, you need to know what it was before, who changed it, when, and why; without that provenance, change becomes chaos, and you lose the ability to understand how the API got to where it is. Provenance is the historical record that makes change manageable, that lets you trace an API’s evolution, understand the reasoning behind past decisions, and govern future changes with knowledge of what came before. Knowing where each version of your OpenAPIs is, which I wrote about in 2022, is a provenance discipline at the operational level — maintaining the traceable history of your API artifacts across environments and versions.
GitOps is the practical mechanism that delivers provenance, and it’s why I’ve championed it so consistently. I wrote in 2024 about GitOps-driven API source of truth, and the connection to provenance is direct: when your API artifacts live in Git, you get provenance for free. Every change is a commit — attributed to a person, timestamped, with a message explaining why, linked to a review. The Git history is a complete provenance record, a chain of custody for every API artifact that lets you trace exactly how it got to its current state and who is responsible for each change. This is the deepest practical reason I advocate for putting API truth in Git: it makes provenance automatic and complete. The digital API supply chain, which I wrote about in 2024, extends this thinking — treating the flow of API artifacts through the organization as a supply chain whose provenance must be tracked, the way physical supply chains track the origin and custody of goods.
The governance-rule dimension of provenance is where it connects to the human side, and it’s the meaning the stub’s subtitle points at most directly. Just as artifacts need provenance, governance rules need provenance — the history and origin story behind why a rule exists. I’ve written that rule awareness amongst teams matters, and part of that awareness is access to rule provenance: teams need to know not just what a rule requires but where it came from, who decided it, and what reasoning produced it. A rule with clear provenance — a documented origin, a stated rationale, a decision history — is a rule teams can understand, evaluate, and follow willingly. A rule with no provenance, that just appears in the linter with no explanation of where it came from or why, is a rule teams resent and route around. Adding exceptions to governance rules, which I wrote about in 2025, is itself a provenance discipline — documenting not just that an exception exists but why, so the reasoning is traceable. The deepest point about provenance is that it’s what makes both artifacts and rules trustworthy and governable, because trust requires knowing origins. An API definition you can trace to its source, a rule you can trace to its reasoning, a change you can trace to its author and rationale — these are the things governance can actually work with. Provenance is the connective history that ties every artifact and every rule back to where it came from, and that history is what transforms a collection of context-free files and unexplained rules into a governable, trustworthy system whose every element can be understood in light of its origin. Without provenance, governance is acting on things it can’t trace and can’t trust; with it, governance has the historical foundation it needs to reason, decide, and act with confidence.
References
- Thinking About OpenAPI Provenance
- My Concerns As A Public Data Steward
- Including API Dependencies Within Your API Definition
- Making Sure My API Dependencies Include Data Provenance
- Providing Source Metadata As Part Of The APIs.json Index For Data APIs
- Knowing Where Each Version Of Our OpenAPIs Are
- The Digital API Supply Chain
- The Role Of Provenance In Dealing With API Change
- GitOps-Driven API Source Of Truth
- Adding Exceptions To API Governance Rules
