Keyword reference

Keywords are the keyword: value lines that decorate an annotation block. They come in two flavours: inline (one line, keyword: value, the value classified by a value shape) and body (a header line plus indented continuation lines — a flat token list, a YAML map, or a per-line sub-language). Three things matter about any keyword: the class it belongs to, the annotation contexts that accept it, and its value shape.

This section groups the surface by class — pick the page that matches what you’re decorating. For the formal productions see grammar.md; for the value-shape and context-token reference tables see the Appendix.

Keyword classes

• Parameters & responses

  Keywords that decorate swagger:parameters fields and swagger:response headers — the reduced OAS 2.0 SimpleSchema surface, plus the parameter location and response-level examples.
• Schema validations & decorators

  Keywords that constrain and decorate a model schema or struct field — bounds, lengths, patterns, enums, defaults, and structural markers.
• Routes & operations

  Keywords carried in a swagger:route or swagger:operation block — the operation’s transport metadata and its parameter and response bodies.
• Security

  Keywords that wire authentication — the requirements that gate a spec, route, or operation, and the scheme catalogue declared once in meta.
• Spec metadata

  Top-of-document keywords authored under swagger:meta — version, host, base path, license, contact, terms of service — plus the cross-cutting vendor-extension and external-docs keywords.
• Appendix: shapes & contexts

  Reference tables — the value shapes the lexer classifies, and the meaning of each annotation-context token.

Context matrix

Which annotation family accepts a given keyword — the transpose of the annotation × keyword matrix. A ✅ means the keyword is legal on that annotation (on the annotation’s own block or on one of its fields); a blank means it is rejected there with a CodeContextInvalid diagnostic. The detailed entry for each keyword lives on its class page (linked above).

The parameters / response columns also cover the items sub-context (array elements): the array-element validations ride there too. model covers swagger:allOf member fields. See the Appendix for the precise meaning of each context token (param, header, schema, items, …).