# audience-defined

Source: https://apigenie.pl/docs/linter/openapi/rules/audience-defined

A rule of the OpenAPI linter, which reads OpenAPI 3.0, 3.1 and 3.2 documents. Since 0.0.1. In the rulesets: Strict at error, All at error.

This rule checks that `info` has an `x-audience` field, and that its value is one of
`internal-team`, `internal-company`, `partner` and `public`.

## Rule details

Who an API is for decides how much design review, documentation and lifecycle care it gets: an
API shared with partners or published to everyone is held to a higher standard than one used by
a single team. The audience has no place in the OpenAPI specification, so the rule looks for the
`x-audience` extension of the info object.

The rule reports `API audience (x-audience) is missing` when the field is absent, and
`API audience (x-audience) has invalid value (...)` when it is not one of the four values:

- `internal-team`: used by the team that owns it.
- `internal-company`: used across the company.
- `partner`: used by selected external clients.
- `public`: available to everyone.

## Examples

**Good**. The API says it is public.

```yaml
openapi: 3.0.3
info:
  title: Orders
  version: 1.2.3
  x-audience: public
paths: {}
```

**Bad**. The value is not one of the four.

```yaml
openapi: 3.0.3
info:
  title: Orders
  version: 1.2.3
  x-audience: external
paths: {}
```
