version-annotations-valid

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

This rule checks the version annotations that let a client built from the newest document talk to servers of older versions: info.x-apigenie-versions and the x-apigenie- annotations on operations, parameters, properties and schemas.

Rule details

The annotations are experimental, outside the 1.0 compatibility promise. apigenie window writes them from the history of the document, and a client generator that understands them leaves out of a request what the server’s version doesn’t know. A value it can’t read, or a version it can’t place, makes the client guess, so the rule reports:

  • a malformed value: a version that isn’t a string (quote 1.0 in YAML), an x-apigenie-renamed-from without name, an x-apigenie-type-changed-from without schema, an x-apigenie-enum-added that doesn’t map enum values to versions;
  • an info.x-apigenie-versions that isn’t a list of distinct version strings, oldest first, that doesn’t list info.version, or that lists versions after it;
  • a version the generators can’t place: with info.x-apigenie-versions, one it doesn’t list; without it, one that isn’t a semantic version;
  • a version newer than info.version, except in x-apigenie-removed, which can announce a removal with a version the list doesn’t have yet;
  • an x-apigenie-removed at or before info.version on an element the document still has;
  • an annotation on an element it doesn’t apply to, for example x-apigenie-made-optional on an operation or x-apigenie-enum-added on a schema without enum.

Two listed versions are ordered by their position in info.x-apigenie-versions, two semantic versions by SemVer precedence (a v prefix and build metadata don’t count), and a version that isn’t listed is newer than a listed one: the order of apigenie window and of the generated clients. The rule reports nothing in a document that uses none of the annotations.

Examples

Good.

openapi: 3.1.0
info:
  title: Shipments
  version: 1.3.0
  x-apigenie-versions: [1.1.0, 1.2.0, 1.3.0]
paths:
  /shipments/{id}/hold:
    post:
      x-apigenie-added: 1.2.0
      responses:
        "204":
          description: Held
components:
  schemas:
    ServiceLevel:
      type: string
      enum: [standard, express, same_day]
      x-apigenie-enum-added:
        same_day: 1.3.0

Bad. A version the list doesn’t have, a version that isn’t one at all, and a rename without the old name.

openapi: 3.1.0
info:
  title: Shipments
  version: 1.3.0
  x-apigenie-versions: [1.1.0, 1.2.0, 1.3.0]
paths:
  /shipments/{id}/hold:
    post:
      x-apigenie-added: 1.4.0
      responses:
        "204":
          description: Held
components:
  schemas:
    Shipment:
      type: object
      properties:
        carrierRef:
          type: string
          x-apigenie-added: next
        status:
          type: string
          x-apigenie-renamed-from:
            version: 1.2.0

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.rules has the details.

commands:
  lint:
    rules:
      version-annotations-valid: off
Last updated on View as Markdown
Was this helpful?