swagger:additionalProperties

Usage

// swagger:additionalProperties ( true | false | <type> )

What it does

Sets a schema’s additionalProperties — the policy for keys beyond the named properties.

On a struct it complements the named properties; on a map type it overrides the element-derived value schema; on a type that resolved to a bare $ref it defines a clean object. See the Maps & free-form objects tutorial.

Where it goes

On a type declaration (alongside swagger:model). A field-level equivalent exists as the additionalProperties: keyword.

Grammar (EBNF)

AdditionalPropertiesAnnotation = ANN_ADDITIONAL_PROPERTIES , ( BOOL_VALUE | ValueType ) ;
ValueType                      = TYPE_REF | IDENT_NAME | "[]" , ValueType ;

The required token is one of:

• true — allow arbitrary extra keys (additionalProperties: true);
• false — forbid extra keys, closing the object (additionalProperties: false);
• a value type — a primitive / Go-builtin / []T, or a known type name (which resolves to a $ref, and is registered for discovery). This reuses the /codescan/maintainers/annotations/swagger-type/ value grammar, except a type name becomes a $ref rather than an inline expansion.

Supported keywords

None of its own. It composes with maxProperties / minProperties / patternProperties.

Example

// Settings is an open object: it keeps its named property and complements it
// with typed (integer) extra values — the swagger:additionalProperties marker
// sets the policy for keys beyond the named ones.
//
// swagger:model
// swagger:additionalProperties integer
type Settings struct {
	Name string `json:"name"`
}

{
  "description": "Settings is an open object: it keeps its named property and complements it\nwith typed (integer) extra values — the swagger:additionalProperties marker\nsets the policy for keys beyond the named ones.",
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "x-go-name": "Name"
    }
  },
  "additionalProperties": {
    "type": "integer"
  },
  "x-go-package": "github.com/go-openapi/codescan/docs/examples/concepts/maps"
}

Precedence — lowest priority. additionalProperties only rides on an object. If a prior rule fixed a non-object type (a swagger:type scalar, swagger:strfmt, a special type), the marker is dropped with a CodeShapeMismatch diagnostic. It has no OAS-2 SimpleSchema form, so it never applies on a non-body parameter or response header.

Full example. fixtures/enhancements/additional-properties/api.go.