OpenAPI 3.1: HTTP Contract as Source

_Locale: en-US · Lesson: DAT-013 · Public order: 70_

Outcome and working artifact

This lesson produces a OpenAPI HTTP Contract Review Record v1: a decision artifact that separates observations, assumptions, limits, and required evidence. The goal is a transferable model, not memorized tool names.

می‌تواند «OpenAPI 3.1: HTTP Contract as Source» را برای یک domain محدود مدل کند و constraint، compatibility یا recovery evidence لازم را مشخص کند.

Boundary model

OpenAPI can be the inspectable source for an HTTP contract, but a rendered documentation page is not runtime conformity evidence. A review must connect method and path, parameters, media types, request and response schemas, status outcomes, examples, and observed server behavior. It must also keep the OpenAPI document version separate from the product API version.

Keep three labels throughout the work: observed, bounded inference, and needs verification. When evidence is unavailable, record unknown. A product name or a passing happy path is not a substitute for evidence.

1. Version fields answer different questions

The top-level openapi value selects the specification version used by the document. info.version identifies the described API release under the team's versioning policy.

2. An operation is more than a path

Method, path template, path/query/header parameters, request body, media types, responses, and security declarations together define the bounded interface.

3. Schema Objects need a declared boundary

OpenAPI 3.1 aligns its Schema Object model with JSON Schema vocabularies, but tool support and dialect behavior still need to be pinned and tested.

4. Examples are evidence fixtures, not decoration

A request example should validate against the request schema and a response example should match its status code, media type, and schema. Negative fixtures reveal undocumented behavior.

5. Runtime drift needs a separate probe

A syntactically valid document can disagree with the deployed handler. Contract tests compare actual requests and responses to the source without claiming every implementation path was explored.

Five-step method

1. Pin the OAS version and state the independent API versioning rule.
2. Select one operation and enumerate its complete HTTP surface.
3. Validate request and response examples against the correct media type and Schema Object.
4. Probe a missing required parameter, wrong media type, undocumented status, and schema-invalid response.
5. Record document result, runtime observation, tool limitation, and compatibility decision separately.

Worked case

POST /orders accepts JSON with customerId and at least one item. The contract documents 201, 400, and 409 outcomes. A baseline example validates and the synthetic handler returns a 201 body matching its schema. Negative probes omit customerId, send text/plain, return an undocumented 500 shape, and add a future optional Idempotency-Key header. The record distinguishes a document defect from a handler drift and classifies the optional header separately from the new 409 response.

Decision and evidence matrix

Failure probes and repair

• OpenAPI documentation proves the server implementation conforms at runtime.
• The openapi field is the API product version or the same thing as info.version.
• OpenAPI 3.1 is the latest overall OAS feature set as of 2026-09-02.
• A valid Schema Object guarantees every code generator or validator behaves identically.

For each statement, narrow the claim, create a counterexample, and name the observation that could confirm or reject it.

Transfer challenge

Change the scenario so that one assumption in the worked case no longer holds. Rebuild the OpenAPI HTTP Contract Review Record v1 without copying the earlier decision, then explain what changed in the input and what stayed stable in the decision rule.

What this does not prove

This lesson does not claim certification, production guarantees, or coverage of every implementation. Its conclusion is valid only within the scenario boundary, dated sources, and recorded observations.

Self-check

• [ ] Did I separate responsibilities from framework or tool names?
• [ ] Did I state at least one failure probe and its predicted observable?
• [ ] Are fact, inference, and design choice visibly separated?
• [ ] Did I record non-claims and missing evidence?
• [ ] Did I complete transfer in a changed context without a prepared answer?

Sources and freshness boundary

Sources were reviewed for the frozen Bible as of 2026-09-19. A review_due date triggers a versioned requalification; it does not authorize silent in-place edits.

• OAS-3.1.2 — Normative OpenAPI 3.1 family semantics used by the locked lesson scope. (https://spec.openapis.org/oas/v3.1.2.html; review: 2026-10-17)
• OAS-LATEST — Current latest published OpenAPI Specification context; not used to rewrite the locked 3.1 lesson scope. (https://spec.openapis.org/oas/latest.html; review: 2026-10-17)