Did you know that an AI agent can call a tool with perfectly valid JSON and still do the wrong job? An API can change the meaning of a status, add a required field, rename an argument or alter the default behaviour of an operation. Tool-contract drift happens when the agent’s expectations no longer match the service it calls. A safe system tests the interface and its meaning before taking consequential actions, and verifies the actual result afterwards.
The practical method is to version the tool schema and behavioural contract, capture the exact request and response assumptions, check compatibility against real provider behaviour, refuse unsafe changes and reconcile external effects. This guide works through ninety-six fictional tool interactions, shows why ‘accepted’ cannot always mean ‘completed’, and transfers the method to a school worksheet publishing workflow. All examples and quantities are invented for learning rather than claims about eduKate’s actual operations or existing artificial superintelligence.
This specialist chapter connects the How Super Intelligence Works library with Workflow Migrations and Test Oracles. Those cover running workflows and general correctness. Here we concentrate on contracts between an agent and an external service: the names, types, defaults, meaning and side effects of each tool operation.
Choose a useful reading route
- Integrating a tool? Start with syntax versus semantics, defaults and provider versions.
- Managing live agents? Review authentication, accepted-versus-completed states and uncertain writes.
- Learning technology? Work through the ninety-six-call case and worksheet transfer exercise.
- Auditing reliability? Check consumer-driven contracts, hard release gates and final resource readback.
Contents
- 1. The interface boundary is a promise about behaviour
- 2. Schemas describe shape, not the whole truth
- 3. Field renames and defaults are common breaking changes
- 4. Status changes can silently change user outcomes
- 5. Units, time and format are part of the contract
- 6. Permissions are not granted by a valid schema
- 7. Version the contract and the consumer expectations
- 8. Consumer-driven contracts test what a client relies upon
- 9. Mock tests cannot certify the live provider
- 10. A fictional ninety-six-call contract laboratory
- 11. Use a table with different verification predicates
- 12. Detect drift before the release reaches users
- 13. Plan for provider outages and unrecognised responses
- 14. Transfer exercise: a changed worksheet publishing tool
- 15. Diagnose five tool-contract failures
- 16. A safe contract checklist for working teams
- Frequently asked questions
- Official standards and testing sources
- Further reading
1. The interface boundary is a promise about behaviour
A model may generate a tool call by choosing a name and supplying arguments that conform to a declared schema. That establishes only that the request fits the available description; it does not guarantee that the remote service still implements that description. A publishing tool, for example, might accept a status field while interpreting the value differently from the agent’s last known version. The prompt is not the source of truth for a live API.
Separate the contract into syntax, semantics, authority and effect. Syntax covers field names and value types. Semantics covers what each field and result actually means. Authority covers the user and service permissions needed for that specific target. Effect covers what the provider did and how completion can be observed. A robust tool gate needs all four, especially when the action would send information, modify records or publish content.
Think of a fictional lesson-note service. Version one uses `submit` to save a private draft. Version two also supports a `publish` mode with extra approval requirements. If the agent equates any successful submission with a public post, its response may be wrong without a single malformed argument. An API description needs explicit effects, not merely attractive operation names.
Document each consumer’s assumptions. A source-retrieval agent expects an answer containing an applicable document revision, while a downstream article writer expects to see complete source text. A change that remains valid for the retrieval service may be incompatible with the writer’s assumptions. Contract drift is relational: the provider and the consumer can each be functioning correctly under different versions yet fail together.
Return to contents or continue with Schemas describe shape, not the whole truth.
2. Schemas describe shape, not the whole truth
The OpenAPI Specification provides a machine-readable format for describing HTTP endpoints, parameters, request bodies, responses and related interface information. The official OpenAPI site has several version branches, and the service must declare the version it actually supports. A schema can help a test reject missing or badly typed fields, but it cannot by itself show that a saved file is publicly visible or that an institution’s current policy is accurately cited.
A JSON Schema rule might require a nonempty document ID and restrict a status to a defined enumeration. That is valuable. Yet an allowed status called `accepted` might mean only that work entered a queue. A model that immediately tells the user the job completed has crossed from structural validation into an unsupported semantic claim. The actual target state or a trustworthy provider completion receipt must settle the stronger assertion.
Be careful about apparently harmless schema relaxations. Making a previously required target field optional can introduce an implicit default. If the default points to the currently active project rather than the user’s intended resource, a valid request might update the wrong object. A contract reviewer should ask what happens when fields are omitted, not only whether all supplied fields have the right type.
OpenAPI’s official descriptions and Pact’s consumer contracts serve different roles. A declarative API description can enumerate an interface, while an executable consumer-driven contract tests interactions relied upon by particular consumers. Neither is an automatic business-permission grant. A developer still needs source-specific verification, tool authorization and negative tests for consequences outside the schema.
Return to contents or continue with Field renames and defaults are common breaking changes.
3. Field renames and defaults are common breaking changes
A tool formerly accepting `document_id` might introduce `resource_id` in a new release. If the old name is silently ignored and a default resource is chosen, the agent can produce a syntactically accepted request aimed at the wrong document. A strict validator can catch an unexpected or missing field before execution when configured appropriately. Silent acceptance of unknown fields may be useful for some evolvable APIs but dangerous for a consequential write.
Default values deserve explicit versioning. Suppose omission of `notify_subscribers` once meant false, but a later service starts applying true. The agent could publish a page and unexpectedly send emails even though it never requested distribution. The expected default should be part of the contract, verified against the actual service and overridden by an explicit safe setting when relevant. The model’s belief about the old default does not control the new implementation.
Case sensitivity and null values create further surprises. An empty string, absent key and explicit null may be distinct under a particular API. A value such as `0` may mean a legitimate quantity rather than a missing parameter. The agent should use typed arguments and the provider’s documented semantics rather than guessing from how natural language sounds. Edge cases should be included in contract tests before release.
Version transitions require accountability. The team introducing a new field should identify existing consumers, how they will behave and how the change is rolled out. A consumer should pin or discover the intended provider contract version and validate response states. Both sides must agree on the meaning of the operation before a real user is asked to rely on its result.
Return to contents or continue with Status changes can silently change user outcomes.
4. Status changes can silently change user outcomes
Consider a fictional storage API that returned `success` only after the file became visible. A new asynchronous version responds `accepted` when an update is queued. The same HTTP-level successful status no longer proves the same business condition. If an agent interprets a normal response code as completion, it can tell a teacher the corrected timetable is live when readers still see the earlier revision.
Define a state machine for every consequential operation. Drafted, queued, accepted, committed, independently verified, failed and unknown are examples of different meanings. Each transition needs an authoritative observation and an appropriate user-facing label. A final generated sentence should describe the state the application established, not the state the model wishes had happened.
Even a field named `completed` needs scope. The provider might have finished writing a temporary staging file while a separate publication job remains pending. A service-level completion receipt may not prove that all copies or downstream indexes have updated. Write a task-specific acceptance rule identifying the actual target resource and expected revision instead of reusing one generic success predicate everywhere.
When the tool returns a new enum value, do not assume it means the closest old label. An unknown status should be treated as an unrecognised contract or unresolved state, not silently mapped to success. The adapter may safely stop and ask the provider or accountable operator for clarification. Graceful degradation sometimes means preserving a private draft while the public write remains blocked.
Return to contents or continue with Units, time and format are part of the contract.
5. Units, time and format are part of the contract
An agent might submit a price in dollars while a new API expects minor currency units, or send a local date string where the provider expects an offset-aware timestamp. Both requests can carry valid numbers or strings and still represent the wrong operation. Unit conversion must be explicit and checked. For a fictional amount of 12.50 dollars, using 1250 cents is appropriate only where the contract truly expects cents.
Time semantics can also change. A scheduled school reminder might previously accept local Singapore time but later require an ISO timestamp with a timezone offset. A message at 09:00 cannot be interpreted correctly without knowing the intended location and effective date. A model should not infer those facts from the server’s current timezone and then claim the event was scheduled as the user requested.
Date-only values differ from instants. An admissions deadline stated as a calendar date is not necessarily equivalent to a timestamp ending at midnight UTC. The API contract should identify whether a field represents local date, instant, duration or a business-effective interval. A schema accepting `string` does not by itself capture the full meaning. Versioned examples and transfer tests can prevent subtle shifts.
Parse numerical responses with declared units. A returned latency value of 250 milliseconds is not 250 seconds, and a percentage expressed as 0.8 can mean eighty percent under one representation. The Numeric Integrity guide covers general calculations. Tool-contract checks add the responsibility to match the producer’s unit and meaning for each field.
Return to contents or continue with Permissions are not granted by a valid schema.
6. Permissions are not granted by a valid schema
An agent may possess a syntactically valid `delete_file` call but lack permission to delete that person’s document. The executing service must check current identity, resource ownership, consent and applicable policy before performing the change. A tool schema is a description of the callable shape, not a certificate that the user authorised every value. The model cannot manufacture authority by choosing a plausible argument.
Beware of permission changes when APIs evolve. A new endpoint might combine drafting and transmission while inheriting a broad service credential. The older client expected draft-only behaviour; the new API’s wider scope could expose a dangerous shortcut. Place object-level and action-level checks at the protected resource, and include negative tests that attempt unapproved sending or a wrong-recipient update.
Do not use a more powerful fallback credential when a token is rejected because of scope or expiry. That is not compatibility repair; it is a privilege escalation. A trustworthy adapter should return a bounded refusal and preserve safe work until a person grants the right permission. Availability pressure should not turn an API migration into a bypass of the user’s decision.
The Agent Identity chapter explains general delegation. The specialist task here is to attach the right permission check to each changed tool contract. A formerly harmless operation can become consequential after a provider update, and that change deserves an explicit release review.
Return to contents or continue with Version the contract and the consumer expectations.
7. Version the contract and the consumer expectations
Store a version bundle identifying tool name, declared schema, provider or SDK version, policy version, expected status transitions and relevant acceptance tests. A consumer may also need model prompt and tool adapter versions, because they determine which arguments it generates. A recorded operation should say which bundle it used, allowing a reviewer to reconstruct behaviour without guessing from today’s code.
Not every change requires a new major version. An additive optional response field might be compatible for consumers that ignore it. A changed default on a consequential operation can be breaking even if the schema still validates. Classify compatibility by observed consumer behaviour, not solely by whether the number in a version string increased.
Pinning a known-good provider release can reduce drift for long-running tasks when the platform supports it. Other integrations need compatibility adapters or safe migrations. New tasks may use the updated contract while paused old tasks continue under their original meaning. Do not assume a completed historical approval covers a new action created by a changed endpoint.
Create explicit cutoff boundaries. At time T, new workflows may be routed to contract v2 while existing workflows complete under v1 or undergo a tested state migration. If providers change without notice, the application may need runtime response validation and a safe hold on unknown states. A release plan is valuable only if it accounts for real in-flight work.
Return to contents or continue with Consumer-driven contracts test what a client relies upon.
8. Consumer-driven contracts test what a client relies upon
Pact’s documentation describes consumer-driven contract testing as executable examples of interactions between a consumer and provider. A consumer records the requests and expected responses it needs; provider verification checks those expectations against a running implementation under the chosen test conditions. This can detect a breaking change that schema-only inspection might miss for a specific client path.
A mock generated from a consumer’s contract allows local deterministic tests, but success against that mock is only one half of the story. The provider must verify that it actually satisfies the interactions. If the mocked provider always returns a conveniently completed status while the real system sometimes queues work, the contract itself may be incomplete. Test timeout and incomplete-result behaviours explicitly when they matter.
A contract broker can record which consumer and provider versions were verified. Pact’s documentation describes deployment checks using that version information. Such a check supports compatibility claims under the tested combinations; it does not establish that the agent’s school explanation is correct or that the user permitted a write. Keep provider compatibility and business authority as separate release gates.
A source of error is consumer over-specification. A client that expects fields in an irrelevant order may fail when the provider makes a harmless change, while a client that checks only HTTP 200 may miss a dangerous semantic shift. Describe the minimal meaningful interaction properties the consumer truly needs. The aim is compatibility with trustworthy behaviour, not compatibility with one accidental formatting detail.
Return to contents or continue with Mock tests cannot certify the live provider.
9. Mock tests cannot certify the live provider
An internal simulation might always return the expected JSON schema while the production service actually returns an asynchronous receipt or a different error family. Use provider verification and controlled integration checks against the specific deployed version. Where live testing could send real messages or change private records, provide an authorised isolated account or read-only route rather than experimenting on actual users.
Test failures as well as success. The service might reject an expired credential, return a rate-limit response or time out after accepting the write. The consumer needs distinct paths for safely retryable errors, permanent denials and unknown effects. One generic catch-all handler that reruns the whole agent can create duplicates or broaden permissions.
Use a protected fixture whose expected effect is known. A fake document with a stable ID can be updated within a sandbox, then fetched again to establish that the right fields changed and protected fields remained intact. For a public publishing system, independently read the saved draft or post rather than rely solely on the adapter’s acknowledgment. The actual resource state is a stronger oracle than the response message.
Tool credentials and environments must be fenced. A test flag in the prompt is not enough if an integration accidentally points to a production endpoint. Record the chosen base URL, service account, tenant and allowed operations through trusted configuration. An external contract test should not be allowed to send messages to real parents just because a model selected the Send operation.
Return to contents or continue with A fictional ninety-six-call contract laboratory.
10. A fictional ninety-six-call contract laboratory
Imagine the invented Maple Study Tools platform updates a document API while ninety-six agent calls are evaluated. Sixty calls remain fully compatible and reach independently verified intended states. Eighteen calls are correctly rejected because their old arguments no longer match the declared contract. Ten calls pass structural validation but produce a materially wrong interpretation of an accepted status or default. Eight have unresolved provider acknowledgements that require reconciliation.
The outcome categories sum to 60 + 18 + 10 + 8 = 96. Fully verified compatible calls make up 60 ÷ 96 = 62.5%. Correctly rejected incompatible requests are 18 ÷ 96 = 18.75%. Semantic-mismatch cases are 10 ÷ 96 ≈ 10.42%, and unresolved effects are 8 ÷ 96 ≈ 8.33%. The numbers are deliberately chosen examples, not observed commercial error rates or evidence that a particular model failed.
A dashboard reporting seventy-eight ‘successful calls’ by adding the sixty verified completions and eighteen correct refusals would obscure their different business meanings. A refusal can be the correct protective outcome without completing the user’s intended edit. Another dashboard might treat the eight unknown effects as failed operations and attempt them again, risking duplicated writes. Categories must preserve what was actually established.
The ten semantic-mismatch cases are the critical diagnostic group: their arguments can pass JSON validation yet still cause wrong user outcomes. Inspect whether the provider changed defaults, unit conventions or accepted-versus-completed semantics. A release gate can block the affected write capability until the provider and consumer agree on the actual contract and a fresh test shows the intended resource state.
Return to contents or continue with Use a table with different verification predicates.
11. Use a table with different verification predicates
A meaningful report lists compatible verified operations, rejected arguments, silent semantic mismatches and unresolved effects. For each category, attach the evidence needed to classify it. A compatible call requires the intended external result; a rejection requires a trustworthy validation or authorization decision; a semantic mismatch needs a reference comparison; and an unknown effect needs the original operation identity.
One logical user task may generate several calls. The ninety-six-call example deliberately reports provider-operation units. It cannot tell us what percentage of distinct users received good advice because a single user might have called the tool several times. If a manager wants task-level completion, join the operation ledger to stable parent-task IDs and evaluate the final accepted user outcome separately.
Count corrected results as revisions, not as erased failures. Suppose six of the ten semantic mismatches are fixed by a compatible adapter and independently verified. At the later snapshot, verified cases become sixty-six and unresolved semantic cases four, with the other categories unchanged. The total remains ninety-six. That improvement belongs to a tested adapter release, not to the fictional API having been safe all along.
A report should also distinguish the consequences of different mismatches. Changing a text label might be a low-impact defect; unexpectedly sending a public notification or editing a wrong account is not. Define hard gates for real-world effects and qualified source-sensitive claims before choosing a score. No average count of compatible harmless reads should offset a critical unauthorized write.
| Disposition | Calls | Share | Meaning |
|---|---|---|---|
| Verified compatible calls | 60 | 62.50% | Correct saved result |
| Correctly refused old requests | 18 | 18.75% | Unsafe or incompatible arguments blocked |
| Semantic contract mismatches | 10 | 10.42% | Unexpected default or state |
| Unresolved provider effects | 8 | 8.33% | Await original operation reconciliation |
| All fictional calls | 96 | 100% | Fixed operation denominator |
Return to contents or continue with Detect drift before the release reaches users.
12. Detect drift before the release reaches users
Include schema and contract diffs in the tool deployment pipeline. Check removed fields, newly required properties, enum changes, altered defaults, unit changes and authorization scope. A static diff is a starting point, because the same schema can conceal different business effects. Pair it with consumer-driven provider verification and targeted negative tests for consequential actions.
Use controlled canary traffic where appropriate. Route a small safe test population to the new provider version, measure actual tool responses and compare independently observed outcomes. Shadow mode may compute candidate actions without executing them. This is useful when a new version introduces a potentially different completion state; it does not require publishing a duplicate or sending an extra real message.
Maintain an immediate stop condition. A confirmed unauthorised action, a silent wrong-recipient default or a status mapping that claims completion without readback may justify blocking the affected capability. A routine optional field mismatch may permit a narrower fallback. The response should follow consequence and evidence rather than the number of green schema checks.
Rollback must respect already committed external effects. Returning to v1 code does not undo a message sent under v2. Track which tasks used which contract and reconcile the target state before resumption. The workflow-migration guide explains this broader problem; contract drift is one reason such careful cutovers are needed.
Return to contents or continue with Plan for provider outages and unrecognised responses.
13. Plan for provider outages and unrecognised responses
A provider may become temporarily unavailable during an upgrade. The agent should distinguish a retryable connection condition from an authorization denial or an unknown side effect. Retrying a harmless read with a bounded policy can be appropriate; blindly resending a consequential write is not when the first may have succeeded. Preserve the original operation ID for reconciliation.
If a service returns an enum value the consumer does not know, refuse to interpret it as final success. Store the raw trusted response safely, record the schema and adapter version and route the task to an updated parser or accountable reviewer. An unresolved status can be inconvenient, but it is more truthful than choosing whichever old status sounds closest.
Recover service without inventing permission. If the provider requires a new OAuth scope, the controller should not silently switch to a broad administrator token. The user or service owner needs to authorize the new operation under the actual access policy. A safe degraded mode may preserve a draft until appropriate authority and provider compatibility return.
Observable recovery needs more than a successful health check. Test a representative permitted operation end to end against the new contract and read back its actual saved result. A healthy HTTP endpoint might still apply the wrong default or write to the wrong namespace. The usefully verified outcome is the final gate.
Return to contents or continue with Transfer exercise: a changed worksheet publishing tool.
14. Transfer exercise: a changed worksheet publishing tool
Move the method to a fictional school worksheet publisher. Under v1, calling Save without a status argument creates a private draft. Under v2, a new default is Published unless the caller explicitly requests Draft. The agent’s old request remains structurally valid, but its effect is now materially different. What should the adapter do? It should pin the intended mode or explicitly set Draft and enforce the applicable approval before any public operation.
Suppose the teacher approves revision 4 for public release, but the model later changes one answer and produces revision 5. An API contract check may confirm that publish accepts the file, yet the earlier human approval does not automatically cover the changed content. The tool boundary must verify the actual approved revision as well as the request schema. A successful provider response cannot supply missing user authority.
Now introduce an Accepted state that means queued. The model tells the teacher the worksheet is public immediately. The correct oracle is a later fetch of the canonical post and expected revision. If the service timed out after acceptance, preserve Unknown and reconcile that same operation instead of creating a second post. The exercise shows semantic compatibility and operation recovery together.
Finally, calculate a small fictional report. Of forty submitted worksheet operations, twenty-eight complete as intended, six are correctly refused for invalid old arguments, four silently select an unsafe default and two have unknown outcomes. The categories sum to forty, with 28 ÷ 40 = 70% verified completion and 4 ÷ 40 = 10% semantic mismatch. Those are designed teaching values; the correct response is to repair the default and test the actual target, not to call ninety percent of requests safe because only four were visibly wrong.
Return to contents or continue with Diagnose five tool-contract failures.
15. Diagnose five tool-contract failures
Failure one: a renamed identifier field causes the tool to update a default resource. Repair strict input validation, explicit resource identity and version-aware adapters. Failure two: Accepted is misread as Completed. Repair a typed state model and independent readback. Failure three: a changed unit turns a normal number into a wrong amount or time. Repair the unit contract, conversion test and source timestamp representation.
Failure four: a fallback provider accepts the old schema but requires a wider permission scope. Repair through legitimate reauthorization and resource-level enforcement, not an administrator shortcut. Failure five: the mock tool always reports success while the live service may time out after a commit. Repair provider verification, fault-injection scenarios and stable operation reconciliation.
Test both permitted and prohibited paths. A draft-only request should never transmit or publish; a valid explicitly approved current version should complete once; an unknown result should remain unknown until checked. A structural schema validator is necessary for some of these tests, but its green result does not cover business meaning or actual external effects.
Keep a change record that describes what the provider changed, which consumer assumptions broke, the first affected task and what verification established the fix. The model can help draft a reader-friendly explanation, but the factual source is the versioned request, provider response and target state. That makes the incident actionable and avoids repeating the same error after the next upgrade.
Return to contents or continue with A safe contract checklist for working teams.
16. A safe contract checklist for working teams
Name the tool and owner, expected endpoint version, argument schema, field defaults, units, status meanings and forbidden effects. Bind source and resource identities to stable IDs rather than natural-language titles. Test malformed inputs and protected operations before allowing the model to call the tool. The smallest useful interface is often one that exposes fewer powerful operations under narrower scopes.
At deployment, verify consumer expectations against the actual provider version. For event-driven or asynchronous tools, include duplicate, delayed, reordered and unknown results. Protect the code and tests that enforce approval and target revision. A regression suite that only checks the shape of successful JSON replies does not cover the user outcomes the organisation needs.
After release, monitor unrecognised status values, schema-validation refusals, target readback mismatches and tasks held for safe reconciliation. Denied unsafe calls can be evidence that a control worked. A rise in refused calls after a provider change may signal incompatibility without implying the model became less intelligent. Report real task completion and correctness separately from tool-call count.
The transferable lesson is that a valid function call is a beginning, not a verified result. Students can practise by changing an invented tool’s default while leaving its syntax unchanged and observing which acceptance rule fails. Builders can connect the same method to contracts, human approval and live-state verification. More capable AI will still need precise interfaces with trustworthy meanings.
Return to contents.
21. Runtime contract discovery is not automatic permission
Some agent frameworks inspect a dynamic tool catalogue at runtime and present operation names, descriptions and argument schemas to a model. This can reduce hard-coded integration work, yet a newly discovered operation might be more powerful than the one a user authorised when the task began. A catalogue update can expose write or delete capabilities without any change to the model’s natural-language prompt. Tool admission must therefore be a trusted application decision, not automatic acceptance of whatever a remote manifest announces.
Treat the manifest as a description to validate, not as a root of authority. Confirm the provider identity, permitted operation list, expected contract version and any signature or transport assurances appropriate to the platform. Restrict the model to the functions needed for the current user task. If a new endpoint appears that publishes public content, require an explicit capability review before making it callable. A well-typed API cannot grant itself permission to send or delete.
Add a negative test: an agent has authorisation to draft a private worksheet, then the tool catalogue changes to include a publish action with a default public audience. The expected behaviour is to continue drafting under existing scope while holding public publication for a legitimate new grant and suitable versioned contract check. The visible interface may advertise the new function, but actual trusted permission must still govern execution.
Return to contents to revisit the interface checks.
22. Safe migration across old and new clients
One provider may need to support two generations of clients during a transition. An older agent might expect `success` to mean a completed file, while the new client correctly treats `accepted` as asynchronous. A safe compatibility adapter can translate explicitly documented states or pin versions under a supported migration plan. It must not invent a completed result from a pending receipt simply to preserve a green compatibility score.
Before retiring the older response shape, identify all active consumers and paused jobs. Run consumer-driven verification against the deployed provider versions, test unknown error responses and confirm that accepted external effects can be reconciled. A controlled dual run may compare hypothetical outputs without performing two real side effects. Keep the rollback plan tied to external state, because reverting code does not unsend a message already dispatched under the new API.
Use an acceptance checklist with separate rows for valid argument structure, correct default, authorisation, source version, execution semantics and final readback. A failed structural rule can prevent the request, while a failed semantic rule may require a provider repair or capability hold. The person should receive an honest status such as ‘draft saved, publication pending verification’ rather than a fabricated success. This same distinction lets a later auditor reconstruct why an apparently compatible tool was not released.
Return to contents to revisit the interface checks.
Frequently asked questions
Can a valid JSON tool call still be wrong?
Yes. It can use an obsolete default, wrong unit, changed status meaning or unauthorized target while satisfying structural syntax.
Does OpenAPI prove that an external operation completed?
No. OpenAPI describes interface contracts; an actual target result needs service-specific completion evidence.
What do consumer-driven contract tests check?
They test the interactions a particular consumer relies on against a provider implementation under defined conditions.
Should an unknown enum be mapped to success?
Not automatically. Unknown or newly added states need explicit interpretation, safe holding and appropriate verification.
Can provider compatibility create missing user permission?
No. Technical compatibility and current authority are independent requirements.
What is the safest response to an uncertain write after an upgrade?
Reconcile the original operation and target resource before deciding whether another attempt is needed.
Official standards and testing sources
Sources reviewed 24 October 2026. The Maple Study Tools example, 96 requests and every result are fictional. The published specifications and developer documentation support technical concepts but do not certify this invented system.
- OpenAPI Specification portal: Official interface-description versions and scope.
- OpenAPI 3.1.2: The published 2025 interface description and Schema Object framework.
- Pact — Consumer-Driven Contract Testing: Executable consumer-provider interactions and limits of schema-only checks.
- Pact FAQ: Provider verification and compatible deployment decisions.
- HTTP Semantics: HTTP success and representation semantics distinct from business completion.
- OWASP Authorization: Object and operation permission checks at real resource boundaries.
Further reading
Continue through Super Intelligence curriculum; How X Works hub; Workflow Migrations; Test Oracles; Change Control; Numeric Integrity; Gold Standard of Education. The client and provider must agree not only on payload shape but also on authority, side effects and independently checked completion.