# audience-defined

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

A rule of the Swagger 2.0 linter, which reads Swagger 2.0 documents; OpenAPI 3 documents go to the OpenAPI linter. Since 0.9.0. In the rulesets: Strict at error, All at error.

This rule checks whether the intended audience of an API is declared in the
`x-audience` extension of the info object of a Swagger 2.0 document.

## Rule details

Knowing who an API is built for helps to decide how strict its review should
be, how carefully breaking changes must be handled, and where the API can be
published. Swagger 2.0 does not provide a field for this information.

The `audience-defined` rule fills this gap. It requires the `x-audience`
extension to be present in the info object, and its value to be one of the
following strings:

- `internal-team` - the API is used only by the team that owns it,
- `internal-company` - the API is used by other teams in the same company,
- `partner` - the API is shared with selected partners,
- `public` - the API is publicly available.

The rule reports `API audience (x-audience) is missing` when the extension
is absent, and `API audience (x-audience) has invalid value (...)` when its
value is not one of the strings listed above. For values that are not strings
at all the parentheses are empty.

The OpenAPI and AsyncAPI linters have rules of the same name,
[audience-defined](/docs/linter/openapi/rules/audience-defined) and
[audience-defined](/docs/linter/asyncapi/rules/audience-defined).

Turn the rule off if your organization does not classify its APIs by their audience.

## Examples

**Good**. The audience of the API is clearly stated.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
  x-audience: internal-company
paths: {}
```

**Bad**. The audience is not declared.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
paths: {}
```

**Bad**. The audience has a value that is not recognized.

```yaml
swagger: '2.0'
info:
  title: Pet Store
  version: 1.0.0
  x-audience: everyone
paths: {}
```
