Keyword reference

This document catalogs the keyword: value forms recognised inside annotation blocks. The keywords come in two flavours:

• Inline keywords — one line, keyword: value shape, with the value classified by a value shape (number, integer, boolean, string, …).
• Body keywords — a header line followed by indented continuation lines. The body’s interpretation depends on the keyword (a flat token list for Consumes:, a YAML map for SecurityDefinitions:, a per-line sub-language for Parameters: / Responses: on swagger:route).

The reader-friendly orientation is in annotations.md (which annotation accepts which keywords, with examples); this file is the per-keyword reference card. Implementers wanting the formal productions should read grammar.md.

Table of contents

• Reading the tables
• Value shapes
• Annotation contexts
• Summary table
• Numeric validations — maximum, minimum, multipleOf
• Length / array validations — maxLength, minLength, maxItems, minItems
• Format validations — pattern, unique, collectionFormat
• Schema decorators — default, example, enum, required, readOnly, discriminator, deprecated
• Parameter location — in
• Meta single-line keywords — schemes, version, host, basePath, license, contact
• Body keywords — consumes, produces, security, securityDefinitions, responses, parameters, extensions, infoExtensions, tos, externalDocs

Reading the tables

Each keyword entry carries:

• Name — canonical spelling. This is what Property.Keyword.Name compares equal to. Comparisons are case-insensitive on the canonical spelling and on every alias.
• Aliases — alternate spellings the lexer accepts. They map to the canonical name at lex time; consumers never see alias values.
• Value shape — the lexical category of the value. See value shapes for what each one means and how it surfaces to consumers.
• Contexts — the family-level scopes where the keyword is legal. Using a keyword outside its legal contexts emits a CodeContextInvalid diagnostic and the keyword is dropped from the affected block.

Value shapes

The grammar’s lexer classifies every value into one of these shapes. The shape determines which Walker callback fires for the property and which field of Property.Typed carries the parsed value.

When typing fails (e.g. maximum: notanumber) the lexer emits a CodeInvalidNumber / CodeInvalidInteger / CodeInvalidBoolean diagnostic and the property reaches the Walker with a zero-value payload. Consumers gate on Property.IsTyped() to skip malformed-typed values; the corresponding builder field stays unwritten.

Annotation contexts

The closed set of contexts a keyword can legally appear in. A keyword table entry’s Contexts field combines these:

Summary table

The full keyword surface, in the order the keyword table declares them. Detailed entries follow this table.

Numeric validations

Apply to numeric schema types (integer, number). On a typed schema with a non-numeric type, these keywords emit CodeShapeMismatch and drop. On a typeless schema (no type: declared upstream), they apply best-effort.

maximum

Upper bound on a numeric value. Alias: max.

The value may carry a leading comparison operator that becomes the exclusive/inclusive bound:

• maximum: 10 — inclusive (≤ 10).
• maximum: <10 — exclusive (< 10).
• maximum: <=10 — inclusive (same as no prefix).
• maximum: =10 — inclusive.

Maps to schema.maximum and schema.exclusiveMaximum.

// Limit is the cap on items per page.
//
// maximum: 100
// minimum: 1
type Limit int

— from fixtures/enhancements/... (any numeric-validation fixture).

minimum

Lower bound on a numeric value. Alias: min. Same operator-prefix shape as maximum. Maps to schema.minimum and schema.exclusiveMinimum.

multipleOf

Divisibility constraint. The value must be a positive number. Aliases: multiple of, multiple-of. Maps to schema.multipleOf.

// AllowedStep enforces increments of 5.
//
// multipleOf: 5
type AllowedStep int

Length / array validations

maxLength / minLength apply only to string-typed schemas; maxItems / minItems apply only to array-typed schemas. Using the wrong pairing emits CodeShapeMismatch and drops the keyword.

maxLength

Maximum string length. Many aliases for ergonomic spelling: max length, max-length, maxLen, max len, max-len, maximum length, maximum-length, maximumLength, maximum len, maximum-len. Maps to schema.maxLength.

minLength

Minimum string length. Same alias set as maxLength with min in place of max. Maps to schema.minLength.

maxItems

Maximum array length. Aliases: max items, max-items, max.items, maximum items, maximum-items, maximumItems. Maps to schema.maxItems.

minItems

Minimum array length. Same alias shape as maxItems with min in place of max. Maps to schema.minItems.

// Tags is a non-empty, bounded list.
//
// minItems: 1
// maxItems: 20
// unique: true
type Tags []string

Format validations

pattern

A regex constraint on a string value. The pattern is preserved verbatim on schema.pattern. The grammar runs a best-effort RE2 compile (Go’s regex engine) on the value; if it fails, a CodeInvalidAnnotation diagnostic surfaces with the compile error. The value still lands on the schema — downstream tools may use JSON Schema’s wider regex dialect.

// Slug is a URL-friendly identifier.
//
// pattern: ^[a-z0-9-]+$
type Slug string

unique

Marks an array-typed schema as set-valued (no duplicates). Boolean. Maps to schema.uniqueItems.

collectionFormat

How an array value is serialised on the wire. Closed-vocab:

• csv — comma-separated (default).
• ssv — space-separated.
• tsv — tab-separated.
• pipes — pipe-separated.
• multi — repeated ?key=val&key=val2 (query params only).

Aliases: collection format, collection-format. Maps to parameter.collectionFormat / items.collectionFormat. Schema-level contexts ignore this keyword (it’s a SimpleSchema concept; schemas serialise via application/json).

When the source value doesn’t match the closed vocab, the raw value is preserved verbatim on the parameter (matches the original behaviour where pipe as a typo for pipes round-trips).

// Tags is the form-data array of label tokens.
//
// in: query
// type: array
// collectionFormat: csv
// items.type: string
type TagsParam []string

Schema decorators

default

Default value for a schema or simple-schema field. Raw-value shape — the post-colon text is captured verbatim and coerced against the resolved schema type at write time (ParseDefault / CoerceValue).

Multi-line bodies are accepted for complex literals:

// Limits is the throughput envelope.
//
// default:
//   {
//     "rps": 100,
//     "burst": 200
//   }
type Limits struct { ... }

Single-line form for primitives:

// Page is the page number.
//
// in: query
// type: integer
// default: 1
type PageParam int

example

An example value for the schema, surfaced in tooling. Same raw-value shape as default. Maps to schema.example (or parameter.example for SimpleSchema parameters).

enum

A closed set of allowed values. Three accepted surface forms:

• Comma list: enum: red, green, blue — split on , and trimmed.
• JSON array: enum: ["red", "green", "blue"] — parsed via YAML/JSON.
• Multi-line list with - markers:

  enum:
    - red
    - green
    - blue

Each element is coerced against the resolved schema type. Maps to schema.enum.

For string-typed enums driven by Go const declarations the swagger:enum annotation is the more idiomatic surface — it picks up the constant names AND their godoc descriptions and produces an x-go-enum-desc extension alongside the enum values. The enum: keyword is the manual override.

required

Marks a field as required. Boolean.

• On a swagger:model struct field: adds the field’s name to the enclosing schema’s required array.
• On a swagger:parameters struct field: sets parameter.required.
• On a swagger:response header: not applicable; the keyword is silently dropped (response headers don’t carry required).

readOnly

Marks a schema property as read-only. Aliases: read only, read-only. Maps to schema.readOnly.

Schema-only — emitting readOnly: inside a SimpleSchema context (non-body parameter, response header) emits CodeUnsupportedInSimpleSchema and drops the keyword.

discriminator

Marks the property as the discriminator for an allOf polymorphic schema. Boolean. Writes the property’s name onto the enclosing schema’s discriminator field. Schema-only.

deprecated

Marks the carrying entity as deprecated. Boolean. Legal on operations (operation.deprecated), routes (operation.deprecated on the synthesised op), and schemas (some downstream tools render this).

Parameter location

in

Where the parameter value comes from. Closed-vocab:

• query — query string parameter.
• path — path-parameter substitution.
• header — request header.
• body — request body (JSON, etc.).
• formData — form-data body field (note: form accepted as an alias inside swagger:route Parameters: chunks; the lexer normalises to formData at the canonical surface).

A non-matching value emits a context-invalid diagnostic; the parameter loses its in and may end up incorrectly classified downstream.

// PageParams declares pagination query parameters.
//
// swagger:parameters listItems
type PageParams struct {
	// in: query
	// minimum: 0
	Offset int `json:"offset"`

	// in: query
	// minimum: 1
	// maximum: 100
	// default: 20
	Limit int `json:"limit"`
}

Meta single-line keywords

Single-line keywords under swagger:meta. Values are taken as-is from the post-colon string.

schemes

Accepted URL schemes. Flexible list — all forms below produce the same ["http", "https"] output:

Schemes: http, https
Schemes:
  - http
  - https
Schemes: http
  - https

Maps to spec.schemes. See sub-languages.md §flex-lists for the unified rule.

version

API version string. Maps to info.version.

host

Default host. Defaults to localhost when empty. Maps to spec.host.

basePath

URL base path. Maps to spec.basePath. Aliases: base path, base-path.

license

License declaration. Two forms accepted:

License: Apache 2.0 http://www.apache.org/licenses/LICENSE-2.0.html

…where the trailing token starting with a URL scheme becomes license.url and the prefix becomes license.name. A bare name with no URL is accepted too.

contact

Contact declaration. Author writes a Name <email> URL triple, in any order. The grammar recognises:

• Name <email@example.com> — Go’s net/mail.ParseAddress form.
• Name <email@example.com> http://example.com — same + trailing URL.
• Just a URL, no name.

Aliases: contact info, contact-info. Maps to info.contact.

Body keywords

Body keywords have a header line ending in : and indented continuation lines. The body’s structure depends on the keyword. See sub-languages.md for the full sub-language specifications; this section covers the keyword shape.

consumes / produces

Media-type lists. Same flex-list rule as schemes: — comma inline, multi-line bare, YAML - markers, or any combination. Maps to consumes / produces on the surrounding scope (spec, operation).

Consumes:
  - application/json
  - application/xml

Produces: application/json

security

Security-requirements list. Each line is one requirement of shape schemeName: scope1, scope2. An empty scope list (schemeName:) means “no scopes required, but the scheme must be active.”

Security:
  api_key:
  oauth2: read, write

Maps to security (array of single-key maps).

securityDefinitions

YAML map declaring security schemes. The body is parsed as YAML directly into the spec.securityDefinitions shape — see OAS v2 §5.2.16.

SecurityDefinitions:
  api_key:
    type: apiKey
    in: header
    name: X-API-Key
  oauth2:
    type: oauth2
    flow: implicit
    authorizationUrl: https://example.com/auth
    scopes:
      read: read access
      write: write access

Aliases: security definitions, security-definitions. Meta-only.

responses

Per-route / per-operation response declarations. Each line is one response in the form <code>: <tokens>. See sub-languages.md §responses for the full per-line grammar.

Responses:
  200: body:User the requested user
  404: description: not found
  default: response:genericError

parameters

Per-route / per-operation parameter declarations. Body is a sequence of + name: chunks (the + is the chunk-start sigil; - is accepted as an alias). See sub-languages.md §parameters for the full per-chunk grammar.

Parameters:
  + name: id
    in: path
    type: integer
    required: true
  + name: limit
    in: query
    type: integer
    default: 20
    minimum: 1
    maximum: 100

extensions / infoExtensions

Vendor extension declarations as a YAML map. Keys must start with x- or X-; non-x-* keys emit CodeInvalidAnnotation and drop.

• extensions: lands the entries on the surrounding scope (spec.extensions, operation.extensions, schema.extensions, …).
• infoExtensions: is meta-only; entries land on info.extensions.

Extensions:
  x-internal-id: 42
  x-feature-flags:
    - alpha
    - beta
  x-nested:
    enabled: true
    rate: 0.5

Aliases: info extensions, info-extensions (for infoExtensions).

tos

Terms-of-service prose paragraph. Multi-line body is joined with \n after dropping whitespace-only lines. Aliases: terms of service, terms-of-service, termsOfService. Maps to info.termsOfService. Meta-only.

externalDocs

External documentation pointer as a YAML map with description and url keys. Aliases: external docs, external-docs. Multi-context (meta, route, operation, schema).

ExternalDocs:
  description: Reference documentation
  url: https://example.com/docs

Cross-keyword interactions

A handful of keyword interactions are worth flagging:

• default + example + enum on the same field: all three may co-occur. The values are coerced against the resolved schema type independently. If enum is declared and default is not a member of it, no diagnostic fires today — downstream JSON Schema validation catches it.
• type + numeric validations + format on a body parameter: the schema dispatcher’s checkShape gates numeric / length validations against the resolved type. format is type-blind (any format string lands).
• required on a $ref'd field: writes to the enclosing schema’s required array (the standard JSON-Schema-draft-4 shape). If the field has sibling overrides, the $ref rewrites into an allOf compound — see grammar.md §refoverride.