@rhoas/spectral-ruleset

RHOAS Spectral Ruleset

A custom ruleset for Spectral following the RHOAS API Guidelines.

Using

npm is required to use Spectral.

To use this Spectral ruleset add the following to your .spectral.yaml:

extends: '@rhoas/spectral-ruleset'

Alternatively you need to create new ruleset

echo 'extends: @rhoas/spectral-ruleset' > .spectral.yaml

Run the Spectral CLI with yarn:

yarn add @rhoas/spectral-ruleset
yarn spectral lint ./path/to/openapi.yaml

or npm:

npm i -g @rhoas/spectral-ruleset
spectral lint ./path/to/openapi.yaml

Rules

The RHOAS ruleset extends the Spectral built-in "oas" ruleset (except operation-tags, openapi-tags). You can see the full list of rules from that ruleset here

rhoas-oas3minimum

OpenAPI schemas should be a minimum of v3.

openapi: 3.0

Recommended: Yes

Severity: warning

rhoas-servers-config

The servers OpenAPI object must be defined and must specify at minimum the following URLs:

servers:
- url: https://api.openshift.com
- url: https://api.stage.openshift.com
- url: http://localhost:8000
- url: /

Recommended: Yes

Severity: warning

rhoas-info-license-apache2.0

The info.license.name field must be "Apache 2.0".

info:
  license:
    name: 'Apache 2.0'

Recommended: Yes Severity: warning

rhoas-info-license-apache2.0-url

The info.license.url field must have the correct link for Apache 2.0.

info:
  license:
    url: 'https://www.apache.org/licenses/LICENSE-2.0'

Recommended: Yes

Severity: warning

rhoas-path-regexp

All paths must match the specified regular expression: \/api\/([a-z_]*){1,}(\/v[0-9]*(alpha|beta)?)(\/{?[a-z_]*}?){0,}$.

• The first segment must be /api
• The second segement denotes the service name (e.g. /api/kafkas_mgmt) and may only be snake_case.
• The third segment must specify the API version. This can be a major version such as v1 or a channel-version such as v1beta, v1alpha.
• All following segments must follow snake_case and can only contain alphabetical characters along and underscores but can be repeated (e.g. /api/kafkas_mgmt/v1/kafkas/{id}/useful_metrics)

Recommended: Yes Severity: warning

rhoas-response-media-type

The content type for all responses must be application/json.

Recommended: Yes

Severity: warning

rhoas-error-response

All error response bodies must reference #/components/Schemas/Error

Recommended: Yes

Severity: error

rhoas-object-resource-schema

All API response bodies must be an object with three required properties:

type: object
required: [id, kind, href]
properties:
  id:
    type: string
  kind:
    type: string
  href:
    type: string

Recommended: Yes

Severity: error

rhoas-schema-name-pascal-case

All JSON schema objects defined in components.schemas must follow PascalCase.

Recommended: Yes

Severity: warning

rhoas-schema-properties-snake-case

All JSON schema properties defined must follow snake_case.

Recommended: Yes

Severity: error

rhoas-error-schema

components.schema MUST have a valid Error object.

Error:
  type: object
  required: [id, kind, href, code, reason]
  properties:
    id:
      type: string
    kind:
      type: string
    href:
      type: string
    code:
      type: string
    reason:
      type: string

Recommended: Yes

Severity: warning

rhoas-object-schema

components.schema MUST have a valid ObjectReference object.

ObjectReference:
  type: object
  required: [id, kind, href]
  properties:
    id:
      type: string
    kind:
      type: string
    href:
      type: string

Recommended: Yes

Severity: warning

rhoas-list-schema

components.schema MUST have a valid List object.

List:
  required:
    - kind
    - page
    - size
    - total
    - items
  type: object
  properties:
    items:
      type: array
    kind:
      type: string
    page:
      type: integer
    size:
      type: integer
    total:
      type: integer

Recommended: Yes

Severity: warning

rhoas-external-$ref

$ref values cannot be a relative path to an external file. Please use the absolute URL or convert it to an internal $ref.

Recommended: Yes

Severity: error

Development

NOTE: This project uses Yarn workspaces for easier development.

Install dependencies:

yarn install

Build:

yarn build

Running examples

Validate OpenAPI files using the uncompiled ruleset:

yarn build
yarn spectral-lint ./examples/openapi-valid.yaml