audience-defined

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.

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

Bad. The value is not one of the four.

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

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:
      audience-defined: off
Was this helpful?