Set the interface contract standard for the estate
Draft
Set the interface contract standard for the estate
Allocation
| L2-04 | |
|---|---|
| Decides | Head of Enterprise Architecture |
| Consulted | CTO, CISO and Data Steward |
| Executes | Engineering |
| Evidence | Published contract standard covering schema descriptions, examples, error conditions, authentication discovery and action surface classification |
In plain terms
Define what a complete interface specification contains, estate-wide. This is what makes the fitness declaration at L2-05 possible, because fitness is judged against a standard rather than against an individual’s opinion.
What is being judged
What “complete” means when the consumer cannot ask questions.
Five requirements carry the standard. Descriptions on every field, accurate rather than restated field names. Real examples, not placeholders, since placeholder data teaches a shape and hides a convention. Every reachable error documented with cause and remediation. Authentication discoverable from the specification. Relationships stated explicitly where operation order or conditional field meaning matters.
The sixth requirement is newer and easy to underweight. Action surface classification: whether an autonomous consumer reads through this interface or acts through it. An interface returning inventory levels and one moving money are different governance objects, and a standard that does not distinguish them leaves the distinction to whoever writes the integration.
What this decision does not cover
It does not declare any interface fit, which is L2-05 and L3-04. It does not approve an integration pattern, which is L2-01.
When it fires
On event. On adoption. When a fitness declaration fails for a reason the standard does not cover, which is the standard telling you it is incomplete. On a change in how autonomous systems consume the estate, such as first introduction of agents that act.
On cycle. With the architecture standards register.
What you need before deciding
How AI systems currently consume interfaces, including the ones consuming data directly and bypassing interfaces entirely. The fitness declarations that have been made and what stewards actually checked. Which interfaces are action-bearing.
How this goes wrong
A standard for humans: the requirements read as documentation quality guidance, so an interface passes while remaining unintelligible to a consumer without judgment. No action surface classification: every interface treated identically, so nothing distinguishes read from act and the v1.0 action surface work has nothing to build on. A standard nobody validates against: published, not enforced in the build pipeline, so conformance is a matter of individual diligence.
Related decisions
Downstream L2-05 and L3-04 fitness, L2-08 breaking change, the Layer 2 machine consumability metrics.
Upstream L4-POL-03 control catalog where interface controls are mandatory.
Instrument references
None. TOGAF predates the condition. ISO/IEC 27001 A.8.26 addresses whether an interface is secure, not whether it is intelligible. Crosswalk gap 2.
Correction
The maintainer answers corrections. There is no service level. Responses are best-effort and opportunistic within a reasonable time: a correction raised on a Monday is answered that week or sooner.