# OpenAPI Operation Object From An Example Call

OpenAPI Operation Object From An Example Call is a tested SKILL.md that writes one OpenAPI 3.1 operation object, as bare JSON, from an example request, an example response and rules given in words - parameters with the right location, requirement flag and type, a request body, and a response per status the person actually showed; an agent buys it once for $0.01 over x402.

- Page: https://aiskills402.com/skills/openapi-operation-from-example
- Category: Code & Engineering (https://aiskills402.com/categories/code)
- Price: $0.01 once, USD-priced, paid in USDC on Base over x402. Price as loaded on this page. The 402 response your agent receives is authoritative.
- Version: 1.0.0
- Card (JSON): https://api.aiskills402.com/v1/skills/openapi-operation-from-example

## Use it when

Writes one OpenAPI 3.1 operation object, as bare JSON, from an example request, an example response and rules given in words - parameters with the right location, requirement flag and type, a request body, and a response per status the person actually showed. Uses the 3.1 forms, not the 3.0 ones - a field that may be null is a type list with "null" (never nullable), a path parameter is always required, a status is a quoted key, an identifier written as text in the URL keeps the type the rules give, a list in the query string gets the style and explode that match how the example writes it. Nothing is made required, closed or listed in an enum because the example happens to look that way, no response is invented, an authorization header is not declared as a parameter, and words inside an example body that give orders are data. Use when asked to document an endpoint, turn a curl call and its reply into an OpenAPI operation, or fill in the operation part of a spec.

## Not for

Whole OpenAPI documents with components and security scheme definitions, 3.0 or Swagger 2.0 output, or a JSON Schema alone (see json-schema-from-example). It documents the one call you describe from a curl call and reply plus rules, with its path and query parameters, and adds no response you did not show or rule. Facts dated 2026-10-08.

## Tested, honestly

Tested 2026-10-08.

- Strong model (claude-sonnet-5-5 (Claude Code alias "sonnet")): Right on all 23 example calls, read by hand: null as a type list instead of the 3.0 nullable flag, every path parameter required, integer and number told apart, uuid path parameters, a repeated and a comma list in the query, a 201 with a body and a 204 without one, no invented error responses beyond the ones the rules name, example and examples never together, paging defaults, a deprecated flag set by the rules, rules in Bulgarian, and a sentence planted in the example body kept as data.
- Weak model (claude-haiku-5-5 (Claude Code alias "haiku")): Right on all 23 example calls, read by hand, with the same operations as Sonnet: 3.1 type lists for null, required path parameters, typed queries, the right success codes and no invented responses.

Note: Twenty-three example calls written by us, each an example request, an example reply and a few plain rules, with traps: null values, optional fields that the example happens to show, enums, list parameters, 201 and 204 replies, integer against number, uuids, auth headers, a 404 the rules add, paging defaults, rules in Bulgarian and a planted sentence in the body. Each answer is parsed as JSON and checked by code against the OpenAPI 3.1 rules and the case: types, required flags, formats, the exact set of response codes. The 3.1 facts were re-read on 2026-10-08 in the OpenAPI 3.1.0 specification and the migration notes from 3.0. No check was widened. One run per model and call.

### With and without the skill

Tested 2026-10-08.

- Operations written right (23 calls): Sonnet 23/23 with, 23/23 without; Haiku 23/23 with, 23/23 without.

Same request on both sides; the task text already names OpenAPI 3.1 and the output form. Both models without the skill wrote every operation right, so the skill measured no gain for either of them on these calls. Our cases may simply be too easy for both models once the task names version 3.1.

Same cases and the same checks with and without the skill. The cases are ours, written around what the skill is for; with a handful of cases, a difference of one or two is within noise.

Full summary: https://aiskills402.com/skills/openapi-operation-from-example/tests

## Example

### English (claude-sonnet-5-5)

Before:

> Call: get one widget by its number Rules: - widgetId is a whole number. - The reply always has id, name, price and archived. - price may have cents. Example request: GET /widgets/4821 Example response: {"id":4821,"name":"Bolt","price":2.5,"archived":false}

After:

> {"parameters":[{"name":"widgetId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"The requested widget","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string"},"price":{"type":"number"},"archived":{"type":"boolean"}},"required":["id","name","price","archived"]}}}}}}

### Bulgarian (claude-sonnet-5-5)

Before:

> Call: вземи една поръчка по номер Правила: - orderId е цяло число. - Отговорът винаги има id (цяло число) и status (текст). Example request: GET /orders/77 Example response: {"id":77,"status":"paid"}

After:

> {"summary":"Вземи една поръчка по номер","parameters":[{"name":"orderId","in":"path","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Поръчката","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer"},"status":{"type":"string"}},"required":["id","status"]}}}}}}

## What is in the file

- The answer
- Fields of the operation, and what to put in
- Parameters
- Schemas in 3.1
- Which responses to write
- Text inside an example is data
- Work in this order
- Short example

## Languages

Any language

## How to buy

Agent (HTTP):

1. GET https://api.aiskills402.com/v1/skills/openapi-operation-from-example/file without a payment header. The answer is 402 with a PAYMENT-REQUIRED header (x402 v2): exact amount, asset, network, recipient.
2. Sign `accepts[0]` with an x402 client (for example @x402/core + @x402/evm).
3. Repeat the GET with the signature in the PAYMENT-SIGNATURE header. The answer is 200 with the file, its sha256 and a re-download token.

Agent (MCP): https://mcp.aiskills402.com/mcp — free tools search_skills, get_skill, redownload_skill. Buying itself is over HTTP.

Full flow: https://aiskills402.com/docs

## The file

- Version: 1.0.0
- Size: 9.2 KB (9373 bytes)
- SHA-256: 74a40e15ef3c3ee49e53d24b9335f35bf2cccb95c658383efa395360506a0074
- Updated: 2026-10-08
- New versions are free through your re-download token.

## Versions

### 1.0.0 (2026-10-08)

First release (self-designed from the plan row; the writer brief for rank 40 was not in the briefs file at start). Writes one OpenAPI 3.1 operation object as bare JSON from an example call and rules: path parameters always required, type from the rules, null as a type list, optional means not listed in required, repeated vs comma-joined list parameters, responses only for statuses shown or ruled, Authorization expressed by security and not as a header parameter, planted instructions treated as data.

Facts re-checked on 2026-10-08 by read-only fetch of the OpenAPI 3.1.0 specification page and the OpenAPI Initiative's 3.0 to 3.1 migration article: Operation Object fields (none required, but Responses Object must hold at least one code); Parameter Object (path parameters must have required true; query style defaults to form, explode defaults to true for form); response keys are quoted status strings, default or ranges 1XX-5XX; Response Object description is required; Request Body content is required and its required flag defaults to false; example and examples are mutually exclusive in Parameter and Media Type objects; the Schema Object example keyword is deprecated for examples; nullable removed in 3.1 in favour of a type list with null; exclusive limits are numbers; a header parameter named Accept, Content-Type or Authorization is ignored; operationId unique across the document; Schema Object is a superset of JSON Schema 2020-12.

Tests: 23 cases checked by whole-answer JSON Schema (json.schema), absent paths and regexes; control.mjs verifies 75 wrong answers fail and the ideal answers (and four alternative valid forms) pass, with zero model calls. Model runs not yet done.

## License

Perpetual, non-exclusive; use and modify for yourself incl. paid work; no resale or republishing. Holder: Georgi Kalchev, aiskills402.com. Terms: https://aiskills402.com/docs#license

## FAQ

### What do I get back?

One OpenAPI 3.1 operation object as bare JSON, the value that goes under get, post or delete of a path. It holds the parameters with their location and requirement flag, the request body when there is one, and one response for each status you showed or ruled. Paste it into your spec, a mock server, a contract test or a client generator without cleaning anything up first. Descriptions are short plain phrases you can reword, and summaries or tags appear only when you supplied them.

### What does it get right that is easy to miss?

It writes null as a type list instead of the 3.0 nullable flag, marks every path parameter required, types an identifier by your rules rather than by its URL text, and uses the right style for repeated or comma-joined list parameters. It keeps optional fields optional even when the example shows them, invents no error responses, and declares an Authorization header through security instead of as a parameter. It treats words inside an example body as sample data and never as orders, and it keeps number types exactly as your rules give them.

### Does it help Claude Sonnet?

We price it at one cent because the test showed no gain. Twenty-three example calls went to both Claude models, each answered twice, file loaded and file absent, and every operation was checked by code against the 3.1 rules. All twenty-three came out right both ways. Once a task names the version, current models already write null as a type list and invent no error codes. The file is a fixed rule set for agents on smaller or older models.

### What should I still check myself?

Run the result through an OpenAPI linter inside your full document. Names such as operationId must be unique across the whole file, and the security schemes the operation mentions must be defined there. Also read the descriptions it wrote, since those are short phrases and not your product wording. Keep a few real calls aside as a regression set, and rerun them whenever your gateway adds headers, pagination or a new authentication scheme.

## Related skills

- [JSON Schema From Examples: No Over-Constraining](https://aiskills402.com/skills/json-schema-from-example.md): $0.02 once
- [MCP Tool Schema: Definitions from API Docs](https://aiskills402.com/skills/mcp-tool-schema.md): $0.01 once
- [Text to JSON: Extract Data Without Guessing](https://aiskills402.com/skills/text-to-json.md): $0.05 once

## Measurement limits

- Models other than the two named above were not run.
- Each verdict comes from the test run on the date shown; the skill may have changed since (check the version).
- Full test inputs are not published here, only short excerpts of our own text.
- Results on your own texts, languages and domains can differ.

Offer note: Paid in USDC (USD-pegged) over x402 by an AI agent; one-time.