schema-required-properties-defined

Since 0.9.0 · In the rulesets: Recommended at warning, Strict at error, All at error

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.

The OpenAPI linter has a rule of the same name, schema-required-properties-defined, for OpenAPI 3.x documents.

Turn the rule off when required properties are intentionally left undescribed.

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

Turn it off or change its severity

In apigenie.yaml, off turns the rule off and warning or error sets its severity; a rule with options takes the severity and the options as a pair, [warning, options]. lint.swagger has the details.

commands:
  lint:
    swagger:
      rules:
        schema-required-properties-defined: off

Related rules

Further reading

Last updated on View as Markdown
Was this helpful?