# Openapi Knowledge Patch > OpenAPI - Skill: `nevaberry/openapi-knowledge-patch` (Agent Skill, multi-file: 5 files) - Install (CLI): `npx skillmds@latest add nevaberry/openapi-knowledge-patch` - Raw SKILL.md: https://api.skillmd.com/api/skills/nevaberry/openapi-knowledge-patch/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: MIT - Author: nevaberry (https://skillmd.com/u/nevaberry) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/nevaberry/openapi-knowledge-patch --- # OpenAPI Knowledge Patch Load this skill when authoring, reviewing, validating, or generating from an OpenAPI document. Start with the behavior changes and deprecations below, then open the topic reference that matches the part of the document being changed. ## Reference index | Reference | Topics | | --- | --- | | [Document structure and operations](references/document-structure-and-operations.md) | Document identity, nested tags, QUERY and extension methods, responses, reusable media types | | [Payloads and serialization](references/payloads-and-serialization.md) | Sequential and multipart media, whole-query-string parameters, parameter and header serialization, XML, examples, discriminators | | [Security, servers, and validation](references/security-servers-and-validation.md) | OAuth device authorization, security-scheme metadata and references, named servers, template grammar, JSON Schema and HTTP references | ## Behavior changes and deprecations ### Prefer `xml.nodeType` Use `nodeType` to say how a schema maps to XML. The available values are `element`, `attribute`, `text`, `cdata`, and `none`. ```yaml type: string xml: nodeType: attribute ``` Do not introduce `attribute: true` or `wrapped: true`; both are deprecated. Arrays default to `nodeType: none` for compatibility. The `xml` keyword is valid on any Schema Object, namespace values may be IRIs, and a root XML schema should use its component name. ### Apply serialization rules by location and style `allowReserved` is valid on Header Objects and on parameters at any `in` location. It matters only when the chosen location and style would otherwise percent-encode a value. Header serialization itself does not use percent-encoding. Cookie parameters can select `style: cookie`. That style separates values with semicolons and leaves data values unencoded. ```yaml parameters: - name: preferences in: cookie style: cookie schema: type: object ``` ### Respect the tightened Server Object rules A Server Object may have `name`. Keep its `url` free of query and fragment components, and do not repeat a server variable in the URL. ```yaml servers: - name: production url: https://{region}.example.com variables: region: default: eu ``` Server substitution, path templating, and Link Object runtime expressions now have formal ABNF grammars. Follow those grammars when implementing a parser, validator, renderer, or generator. ### Update validators and HTTP handling Use `draft-bhutton-json-schema-01` for JSON Schema core, `draft-bhutton-json-schema-validation-01` for JSON Schema validation, and RFC 9110 for HTTP semantics. Do not validate these documents against older referenced drafts merely because an earlier toolchain did so. ## Document identity and navigation ### Set an explicit base URI with `$self` Top-level `$self` gives the document an identity and supplies the base URI for relative reference resolution. ```yaml openapi: 3.2.0 $self: https://api.example.com/openapi.yaml ``` Use this identity when resolving relative references rather than assuming the retrieval location is always the intended base. ### Build nested, purpose-specific tag structures Tag Objects accept `summary`, `parent`, and free-form `kind`. A `parent` value names the containing tag. `kind` lets tooling recognize a conventional purpose, such as `nav`, without restricting other values. ```yaml tags: - name: products summary: Products kind: nav - name: books parent: products kind: nav ``` ## Operations and responses ### Represent QUERY and extension methods correctly Use the lowercase `query` Path Item field for a QUERY operation. Put other extension HTTP methods in `additionalOperations`, keyed by their correctly capitalized method names. ```yaml paths: /items: query: operationId: queryItems additionalOperations: LINK: operationId: linkItems ``` First-class methods remain ordinary lowercase sibling fields. For example, use `head`, not a `HEAD` entry in `additionalOperations`. ### Use concise responses when appropriate A Response Object no longer requires `description`, and it can carry a short `summary`. ```yaml responses: "204": summary: Deleted ``` Keep a description when it adds useful detail; do not synthesize one solely to satisfy an outdated validator. ## Media types and parameters ### Describe sequential representations with `itemSchema` Media Type Objects use `itemSchema` for each repeated item in a sequential representation, including `text/event-stream`, `application/jsonl`, `application/json-seq`, and `multipart/mixed`. ```yaml content: text/event-stream: itemSchema: $ref: "#/components/schemas/Event" ``` For multipart media types, use `prefixEncoding` and `itemEncoding` in place of the older `encoding` field. ### Reuse complete Media Type Objects Define reusable Media Type Objects under `components.mediaTypes`, then reference them from content entries. ```yaml components: mediaTypes: event: itemSchema: $ref: "#/components/schemas/Event" ``` ### Model the whole query string as one value Use `in: querystring` when one Parameter Object represents the entire query string. Describe its representation with `content`, rather than splitting it into separate query parameters. ```yaml parameters: - name: filter in: querystring content: application/json: schema: type: object ``` ## Examples and schema selection ### Separate structured and wire examples Example Objects use `dataValue` for structured data and `serializedValue` for the wire representation. An existing `externalValue` also denotes a serialized value. ```yaml examples: structured: dataValue: id: 42 onTheWire: serializedValue: '{"id":42}' ``` Choose the field that matches whether consumers need data to process or bytes to send. ### Provide a discriminator fallback `Discriminator.propertyName` is optional. Use `defaultMapping` to select a schema when the property is missing or its value is unrecognized. ```yaml discriminator: defaultMapping: "#/components/schemas/Unknown" ``` ## Security quick reference OAuth 2.0 flows can use `deviceAuthorization` with `deviceAuthorizationUrl`, `tokenUrl`, and `scopes`. Security Scheme Objects also support `oauth2MetadataUrl` and `deprecated`. ```yaml type: oauth2 oauth2MetadataUrl: https://auth.example.com/.well-known/oauth-authorization-server flows: deviceAuthorization: deviceAuthorizationUrl: https://auth.example.com/device tokenUrl: https://auth.example.com/token scopes: {} ``` A security scheme may be referenced by URI instead of being declared under components. Preserve that form in resolvers and generators.