# version-annotations-valid

Source: https://api-genie.dev/docs/linter/openapi/rules/version-annotations-valid

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. 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**.

```yaml
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.

```yaml
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
```
