Linter rulesSwagger 2.0schema-required-properties-defined

schema-required-properties-defined

Since 0.9.0

This rule checks that every name listed in required is declared in properties.

Rule Details

A required property which is not declared is usually a typo (required: [nmae]) or a property removed from properties but not from required. Its value is not described, and generated code often cannot represent it.

The schema-required-properties-defined rule checks every schema of a Swagger 2.0 document that has a required list. It looks for the declaration of each name wherever the value of the schema is also described:

  • in the properties of the schema itself,
  • in its allOf members, following references,
  • in the schemas it is an allOf member of, and in their other members.

For every name that is not declared, it reports Required property '<name>' is not defined in 'properties'.

Schemas which may allow undeclared properties on purpose are skipped: when a schema of the group has a schema in additionalProperties (a map) or additionalProperties: true. Schemas whose group contains a reference that cannot be resolved are skipped too.

required in a schema that declares types (itself or through its allOf members) none of which is object, for example beside items in an array schema instead of inside it, has no effect. The rule reports it with 'required' has no effect because the schema does not allow objects.

Configuration

None.

Examples

Good. name is declared by the allOf member Named.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Named:
    type: object
    properties:
      name:
        type: string
  Pet:
    allOf:
      - $ref: '#/definitions/Named'
      - type: object
        required: [name, age]
        properties:
          age:
            type: integer

Bad. nmae is not declared.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Pet:
    type: object
    required: [nmae]
    properties:
      name:
        type: string

Bad. required applies to the array, not to its items.

swagger: '2.0'
info:
  title: Pets
  version: 1.0.0
paths: {}
definitions:
  Pets:
    type: array
    required: [name]
    items:
      type: object
      properties:
        name:
          type: string

When Not to Use It

Disable this rule when required properties are intentionally left undescribed.

Compatibility

This rule is compatible with Swagger 2.0 documents. OpenAPI 3.x documents are linted by the OpenAPI linter, which has a rule of the same name.

Related rules

Further reading