Spectral

https://github.com/stoplightio/spectral
Admin
Spectral is a generic linter for JSON/YAML documents, enabling the creation of custom rulesets and...
Tokens:62,172
Snippets:572
Trust Score:8.5
License:Apache-2.0
Update:4 weeks ago
Show doc for...
Tokens:
Raw
### asyncapi-payload-examples Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a payload with examples that are valid against the payload schema.

```yaml
payload:
  type: object
  properties:
    value:
      type: integer
  required:
    - value
  examples:
    - value: 13
    - value: 17
```

--------------------------------

### Install Spectral dependencies

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/4f-js-rulesets.md

Installs the Spectral functions and formats packages, which are used in the example to create common rules and target OpenAPI formats.

```bash
npm install --save @stoplight/spectral-functions
npm install --save @stoplight/spectral-formats
```

--------------------------------

### asyncapi-3-tag-description Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Example of tags with descriptions.

```yaml
info:
  tags:
    - name: "Aardvark"
      description: Funny-nosed pig-head raccoon.
    - name: "Badger"
      description: Angry short-legged omnivores.

```

--------------------------------

### Real example scenario

Source: https://github.com/stoplightio/spectral/blob/develop/test-harness/README.md

A complete example scenario showing the expected stdout output format. The {document} placeholder is replaced with the full file path.

```text
====test====
scenario-example
====document====
openapi: 3.0.2
servers:
  - url: "localhost"
info:
  title: "my api"
  description: "An example"
  contact:
    name: "Stoplight"
  version: "1.0"
paths:
  /todos:
    get:
      tags:
        - "example"
      description: "Example endpoint"
      operationId: getTodos
      responses:
        200:
          description: Get Todo Items
          content:
            'application/json':
              example: hello
====command====
{bin} lint {document}
====stdout====
OpenAPI 3.x detected

{document}
 2:6  warning  some-rule  This rule is complaining about something.

✖ 1 problems (1 error, 0 warning, 0 infos, 0 hints)
```

--------------------------------

### Install @stoplight/spectral-ref-resolver with npm or yarn

Source: https://github.com/stoplightio/spectral/blob/develop/packages/ref-resolver/README.md

Install the package using either npm or yarn. The commands are alternatives; choose one based on your package manager.

```bash
npm install --save @stoplight/spectral-ref-resolver

# OR

yarn add @stoplight/spectral-ref-resolver
```

--------------------------------

### Good example for oas2-valid-media-example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Good example for the oas2-valid-media-example rule: the example values match the schema types (id is integer, name and petType are strings).

```yaml
paths:
  '/pet/{petId}':
    get:
      ...
      responses:
        '200':
          description: Pet Found
          schema:
            $ref: '#/definitions/Pet'
          examples:
            Get Pet Bubbles:
              id: 123
              name: 'Bubbles'
              petType: 'dog'
```

--------------------------------

### Install Spectral standalone binary via shell script

Source: https://github.com/stoplightio/spectral/blob/develop/docs/getting-started/2-installation.md

Install the standalone Spectral binary for your operating system via a shell script. The binaries do not autoupdate, so run the command again to install new versions.

```bash
curl -L https://raw.github.com/stoplightio/spectral/master/scripts/install.sh | sh
```

--------------------------------

### Install Spectral Core with Yarn

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/3-javascript.md

Installs the @stoplight/spectral-core package globally using Yarn. Alternative to npm for Yarn users.

```bash
yarn global add @stoplight/spectral-core
```

--------------------------------

### asyncapi-payload-examples Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a payload with examples that are invalid: one has a wrong type and another misses a required property.

```yaml
payload:
  type: object
  properties:
    value:
      type: integer
  required:
    - value
  examples:
    - value: nope! # Wrong type
    - notGoodEither: 17 # Missing required property
```

--------------------------------

### asyncapi-tags: Example with path and tags

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows an example of an AsyncAPI path object with a tags array, as required by the asyncapi-tags rule. The rule is recommended and has a default severity of warn when enabled.

```yaml
/invoices/{id}/items:
  tags:
    - Invoice Items
```

--------------------------------

### Install Spectral Core with npm

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/3-javascript.md

Installs the @stoplight/spectral-core package globally using npm. Required before using the Spectral JS API.

```bash
npm install -g @stoplight/spectral-core
```

--------------------------------

### Install Spectral CLI with npm or Yarn

Source: https://github.com/stoplightio/spectral/blob/develop/docs/getting-started/2-installation.md

Install the Spectral CLI client globally using npm or Yarn. Choose the command that matches your package manager.

```bash
npm install -g @stoplight/spectral-cli
```

```bash
yarn global add @stoplight/spectral-cli
```

--------------------------------

### asyncapi-server-security: Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Valid server security configuration where the security scheme 'petstore_auth' is defined in components.securitySchemes.

```yaml
asyncapi: 2.0.0
servers:
  production:
    url: test.mosquitto.org
    security:
      - petstore_auth: []
components:
  securitySchemes:
    petstore_auth: ...
```

--------------------------------

### openapi-tags example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Example for the openapi-tags rule. Shows an operation with a tags array, demonstrating the required non-empty tags array.

```yaml
/invoices/{id}/items:
  get:
    tags:
      - Invoice Items
```

--------------------------------

### Bad example for oas2-valid-media-example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the oas2-valid-media-example rule: petType is an integer instead of a string, causing an error.

```yaml
paths:
  '/pet/{petId}':
    get:
      ...
      responses:
        '200':
          description: Pet Found
          schema:
            $ref: '#/definitions/Pet'
          examples:
            Get Pet Bubbles:
              id: 123
              name: 'Bubbles'
              petType: 123
```

--------------------------------

### asyncapi-3-tag-description Business Object Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Example of a tag with a long description for a business concept.

```yaml
info:
  tags:
    - name: Invoice Items
      description: |+
        Giant long explanation about what this business concept is, because other people _might_ not have a clue!

```

--------------------------------

### asyncapi-message-examples: Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Valid message example: the payload value 'foobar' matches the string schema, and the headers object contains a valid property.

```yaml
asyncapi: "2.0.0"
info:
  title: Good API
  version: "1.0.0"
components:
  messages:
    someMessage:
      payload:
        type: string
      headers:
        type: object
      examples:
        - payload: foobar
          headers:
            someHeader: someValue
```

--------------------------------

### xor function example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/functions.md

Example of the `xor` function requiring exactly one of `value` or `externalValue` to be defined on an example.

```yaml
components-examples-value-or-externalValue:
  description: Examples should have either a `value` or `externalValue` field, but not both.
  given: "$.components.examples.*"
  then:
    function: xor
    functionOptions:
      properties:
        - externalValue
        - value
```

--------------------------------

### oas3-valid-schema-example: Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Valid example for the oas3-valid-schema-example rule. The example values match their declared types: id is integer, name and petType are strings.

```yaml
schemas:
  Pet:
    title: Pet
    type: object
    properties:
      id:
        type: integer
        example: 123
      name:
        type: string
        example: Bubbles
      petType:
        type: string
        example: dog
    required:
      - id
      - name
      - petType
```

--------------------------------

### asyncapi-info-license Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid AsyncAPI document with a license object. The rule requires the info object to have a license key.

```yaml
asyncapi: "2.0.0"
info:
  license:
    name: MIT
```

--------------------------------

### pattern function rule examples (YAML)

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/functions.md

Two Spectral rules using the pattern function. The first, no-x-headers, rejects header names starting with 'X-' using notMatch: "/^x-/i". The second, path-no-trailing-slash, rejects paths ending with '/' using notMatch: "\/$".

```yaml
no-x-headers:
  message: "Header {{property}} should not start with `X-`."
  given: "$..parameters[?(@.in === 'header')].name"
  then:
    function: pattern
    functionOptions:
      notMatch: "/^x-/i"

path-no-trailing-slash:
  description: "Paths should not end with `/`."
  given: "$.paths[*]~"
  then:
    function: pattern
    functionOptions:
      notMatch: "\/$"
```

--------------------------------

### asyncapi-3-channel-servers Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Valid channel server reference that is defined in the servers object.

```yaml
asyncapi: "3.1.0"
info:
  title: Awesome API
  description: A very well-defined API
  version: "1.0"
servers:
  production:
    url: "stoplight.io"
    protocol: "https"
channels:
  hello:
    servers:
      - $ref: #/servers/production

```

--------------------------------

### asyncapi-channel-servers: Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Invalid channel server reference: the channel 'hello' references server 'development' which is not defined in the servers object.

```yaml
asyncapi: "2.0.0"
info:
  title: Awesome API
  description: A very well-defined API
  version: "1.0"
servers:
  production:
    url: "stoplight.io"
    protocol: "https"
channels:
  hello:
    servers:
      - development
```

--------------------------------

### Valid object example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/5-custom-functions.md

Example object that passes the custom function check because the message is "hello".

```yaml
greeting:
  message: hello
```

--------------------------------

### info-license Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Shows an OpenAPI document with a license object in the info section, satisfying the info-license rule.

```yaml
openapi: "3.0.2"
info:
  license:
    name: MIT

```

--------------------------------

### oas3-valid-schema-example: Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Invalid example for the oas3-valid-schema-example rule. The example value for petType is an integer (123) instead of a string, causing an error.

```yaml
schemas:
  Pet:
    title: Pet
    type: object
    properties:
      id:
        type: integer
        example: 123
      name:
        type: string
        example: Bubbles
      petType:
        type: string
        example: 123
    required:
      - name
      - petType
```

--------------------------------

### Install Spectral JavaScript API with npm or Yarn

Source: https://github.com/stoplightio/spectral/blob/develop/docs/getting-started/2-installation.md

Install the Spectral JavaScript API globally using npm or Yarn. Choose the command that matches your package manager.

```bash
npm install -g @stoplight/spectral-core
```

```bash
yarn global add @stoplight/spectral-core
```

--------------------------------

### asyncapi-info-license-url Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid AsyncAPI document with a license object that includes a url. The rule requires a license URL to be present.

```yaml
asyncapi: "2.0.0"
info:
  license:
    name: MIT
    url: https://www.tldrlegal.com/l/mit
```

--------------------------------

### asyncapi-channel-servers: Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Valid channel server reference: the channel 'hello' references server 'production' which is defined in the servers object.

```yaml
asyncapi: "2.0.0"
info:
  title: Awesome API
  description: A very well-defined API
  version: "1.0"
servers:
  production:
    url: "stoplight.io"
    protocol: "https"
channels:
  hello:
    servers:
      - production
```

--------------------------------

### or function example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/functions.md

Example of the `or` function requiring at least one of `title`, `summary`, or `description` to be defined on a schema.

```yaml
schemas-descriptive-text-exists:
  description: Defined schemas must have one or more of `title`, `summary` and/or `description` fields.
  given: "$.components.schemas.*"
  then:
    function: or
    functionOptions:
      properties:
        - title
        - summary
        - description
```

--------------------------------

### Example: Defining tags in AsyncAPI operations

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows an AsyncAPI document with a tags array in an operation, demonstrating how to define tags for an operation. This example is used to illustrate the asyncapi-3-tags rule, which requires a non-empty tags array.

```yaml
invoicedItems:
  address: /invoices/{id}/items
  tags:
    - Invoice Items
```

--------------------------------

### asyncapi-message-examples: Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Invalid message example: the payload value '2137' does not match the string schema, and the headers value is a string instead of an object.

```yaml
asyncapi: "2.0.0"
info:
  title: Bad API
  version: "1.0.0"
components:
  messages:
    someMessage:
      payload:
        type: string
      headers:
        type: object
      examples:
        - payload: 2137
          headers: someHeader
```

--------------------------------

### oas3_1-callbacks-in-webhook: Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the oas3_1-callbacks-in-webhook rule: callbacks are defined in a webhook, which is not allowed.

```yaml
webhooks:
  newPet:
    post:
      callbacks: ...
```

--------------------------------

### asyncapi-3-channel-servers Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Invalid channel server reference that is not defined in the servers object.

```yaml
asyncapi: "3.1.0"
info:
  title: Awesome API
  description: A very well-defined API
  version: "1.0"
servers:
  production:
    url: "stoplight.io"
    protocol: "https"
channels:
  hello:
    servers:
      - $ref: #/servers/development

```

--------------------------------

### asyncapi-server-security: Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Invalid server security configuration where the security scheme 'not_defined' is not defined in components.securitySchemes.

```yaml
asyncapi: 2.0.0
servers:
  production:
    url: test.mosquitto.org
    security:
      - not_defined: []
components:
  securitySchemes:
    petstore_auth: ...
```

--------------------------------

### asyncapi-info-description Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid AsyncAPI document with a non-empty description in the info object. The description can contain Markdown.

```yaml
asyncapi: "2.0.0"
info:
  version: "1.0.0"
  title: Descriptive API
  description: >+
    Some description about the general point of this API, and why it exists when another similar but different API also exists.
```

--------------------------------

### oas3-examples-value-or-externalValue: Bad example with both value and externalValue

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the `oas3-examples-value-or-externalValue` rule: an example object contains both `value` and `externalValue`, which is not allowed. The comment indicates that only one of them can be used.

```yaml
paths:
  /pet:
    put:
      operationId: "replace-pet"
      requestBody:
        content:
          "application/json":
            examples:
              foo:
                summary: A foo example
                value: { "foo": "bar" }
                externalValue: "http://example.org/foo.json"
                # marp! no, can only have one or the other
```

--------------------------------

### asyncapi-3-tags-alphabetical Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Tags in alphabetical order.

```yaml
info:
  tags:
    - name: "Aardvark"
    - name: "Badger"

```

--------------------------------

### license-url Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Shows an OpenAPI document with a license object that includes a url, satisfying the license-url rule.

```yaml
openapi: "3.0.2"
info:
  license:
    name: MIT
    url: https://www.tldrlegal.com/l/mit

```

--------------------------------

### operation-success-response bad example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the operation-success-response rule. Shows an operation with only a 418 response, which is not a success response.

```yaml
paths:
  /path:
    get:
      responses:
        418:
          description: teapot
```

--------------------------------

### oas3_callbacks_in_callbacks: Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the oas3_callbacks_in_callbacks rule: a callback is defined within another callback, which is not allowed.

```yaml
paths:
  /path:
    get:
      callbacks:
        onData:
          /data:
            post:
              callbacks: ...
```

--------------------------------

### oas3_1-servers-in-webhook: Bad Example at Path Item Object Level

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the oas3_1-servers-in-webhook rule at the path item object level: servers are defined in a webhook, which is not allowed.

```yaml
webhooks:
  servers:
    - url: https://example.com/
    - url: https://example.com/api/
```

--------------------------------

### oas3-server-variables: Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Good example for the oas3-server-variables rule: both {region} and {version} variables are properly defined and used in the server URL, and the default value for region is within the allowed values.

```yaml
servers:
  - url: "https://api.{region}.example.com/{version}"
    variables:
      region:
        default: "us-west"
        enum:
          - "us-west"
          - "us-east"
      version:
        default: "v1"
```

--------------------------------

### Example responses object with numeric and non-numeric keys

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/4a-rules.md

Example data showing a 'responses' object with keys '123' and '456avbas'. The pattern rule above would error on '456avbas'.

```yaml
responses:
  123:
    foo: bar
  456avbas:
    foo: bar
```

--------------------------------

### asyncapi-operation-security Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid security definition where the operation's security references a scheme defined in components.securitySchemes.

```yaml
channels:
  "user/signup":
    publish:
      security:
        - petstore_auth: []
components:
  securitySchemes:
    petstore_auth: ...
```

--------------------------------

### Lint a Document with Spectral JS (example-1.mjs)

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/3-javascript.md

Shows a complete script that creates a Spectral instance, sets a ruleset, and lints a YAML document. Requires @stoplight/spectral-parsers and @stoplight/spectral-functions to be installed.

```javascript
import spectralCore from "@stoplight/spectral-core";
const { Spectral, Document } = spectralCore;
import Parsers from "@stoplight/spectral-parsers"; // make sure to install the package if you intend to use default parsers!
import { truthy } from "@stoplight/spectral-functions"; // this has to be installed as well

// this will be our API specification document
const myDocument = new Document(
  `---
responses:
  '200':
    description: ''`,
  Parsers.Yaml,
  "/my-file",
);

const spectral = new Spectral();
spectral.setRuleset({
  // this will be our ruleset
  rules: {
    "no-empty-description": {
      given: "$..description",
      message: "Description must not be empty",
      then: {
        function: truthy,
      },
    },
  },
});

// we lint our document using the ruleset we passed to the Spectral object
spectral.run(myDocument).then(console.log);
```

--------------------------------

### oas3_1-servers-in-webhook: Bad Example at Operation Level

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the oas3_1-servers-in-webhook rule at the operation level: servers are defined in a webhook operation, which is not allowed.

```yaml
webhooks:
  newPet:
    post:
      servers:
        -url: https://example.com/
```

--------------------------------

### info-contact Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Shows an OpenAPI document with a contact object in the info section, satisfying the info-contact rule.

```yaml
openapi: "3.0.2"
info:
  title: Awesome API
  version: "1.0"
  contact:
    name: A-Team
    email: a-team@goarmy.com

```

--------------------------------

### asyncapi-tag-description: Example with tags and descriptions

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid tags list where each tag includes a name and a description, as required by the asyncapi-tag-description rule. The rule is not recommended by default and has a default severity of warn when enabled.

```yaml
tags:
  - name: "Aardvark"
    description: Funny-nosed pig-head raccoon.
  - name: "Badger"
    description: Angry short-legged omnivores.
```

--------------------------------

### info-description Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Shows an OpenAPI document with a non-empty info description, satisfying the info-description rule. The description can contain Markdown.

```yaml
openapi: 3.0.0
info:
  version: "1.0.0"
  title: Descriptive API
  description: >+
    Some description about the general point of this API, and why it exists when another similar but different API also exists.## AuthenticationThis API uses OAuth2 and tokens can be requested from [Dev Portal: Tokens](https://example.org/developers/tokens).

```

--------------------------------

### asyncapi-payload-default Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a payload with a default value that conforms to the payload schema.

```yaml
payload:
  type: object
  properties:
    value:
      type: integer
  required:
    - value
  default:
    value: 17
```

--------------------------------

### array-items: Good example with items field

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Good example for the array-items rule: array schema has a sibling items field. The rule is recommended and has a default severity of error.

```yaml
TheGoodModel:
  type: object
  properties:
    favoriteColorSets:
      type: array
      items:
        type: array
        items: {}

```

--------------------------------

### Mock HTTP and file system with serveAssets

Source: https://github.com/stoplightio/spectral/blob/develop/CONTRIBUTING.md

Example of using serveAssets to mock HTTP requests and file system reads in tests. Works in both Karma and Jest environments.

```ts
import { serveAssets } from '@stoplight/spectral-test-utils';
import * as path from '@stoplight/path';

const cwd = '/tmp/some-fake-path';

serveAssets({
  'https://library.com/defs.json': { // all requests for given resource will be mocked
    components: {
      schemas: {
        ExternalHttp: {
          type: 'number',
        },
      },
    },
  },
  [path.join(cwd, 'file.json')]: { // fs.read will return this
    openapi: '3.1.0',
    info: {
      title: 'Test file',
    },
    paths: {},
  },
})
```

--------------------------------

### asyncapi-3-tags-alphabetical Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Tags not in alphabetical order.

```yaml
info:
  tags:
    - name: "Badger"
    - name: "Aardvark"

```

--------------------------------

### asyncapi-3-server-no-trailing-slash Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Server host without a trailing slash.

```yaml
servers:
  - host: mqtt://example.com

```

--------------------------------

### asyncapi-info-contact Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid AsyncAPI document with a contact object. The rule requires the info object to contain a contact object.

```yaml
asyncapi: "2.0.0"
info:
  title: Awesome API
  version: "1.0"
  contact:
    name: A-Team
    email: a-team@goarmy.com
```

--------------------------------

### oas3-server-trailing-slash: Bad example with trailing slashes

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the `oas3-server-trailing-slash` rule: server URLs have trailing slashes, which can cause awkward URLs when combined with paths.

```yaml
servers:
  - url: https://example.com/
  - url: https://example.com/api/
```

--------------------------------

### asyncapi-server-no-trailing-slash Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows server URLs without trailing slashes, which is the recommended format.

```yaml
servers:
  - url: mqtt://example.com
  - url: mqtt://example.com/broker
```

--------------------------------

### Partial OpenAPI document example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/5-custom-functions.md

YAML snippet showing a partial OpenAPI document used to illustrate how 'input' is derived from the 'given' JSON Path.

```yaml
openapi: 3.0.0
info:
  title: foo
```

--------------------------------

### asyncapi-3-server-no-trailing-slash Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Server hosts with trailing slashes, which are invalid.

```yaml
servers:
  - host: mqtt://example.com/
  - host: mqtt://example.com/broker/

```

--------------------------------

### Bad Example for arazzo-step-success-criteria-validation

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/arazzo-rules.md

An invalid success criteria because the context 'hello' is not a valid runtime expression.

```yaml
- context: hello
  condition: "^200$"
  type: regex
```

--------------------------------

### Scenario with custom asset

Source: https://github.com/stoplightio/spectral/blob/develop/test-harness/README.md

Example scenario using a custom asset (ruleset) with the asset:<pattern> syntax. The asset is referenced in the command with {asset:ruleset} and the expected exit code is 1.

```text
====test====
assets real-life example
====document====
openapi: 3.0.0
info:
  version: 1.0.0
  title: Stoplight
paths: {}
====asset:ruleset====
extends: spectral:oas
rules:
  oas3-api-servers: error
====command====
{bin} lint {document} -r {asset:ruleset}
====status====
1
====stdout====
OpenAPI 3.x detected

{document}
 1:1    error  oas3-api-servers  OpenAPI `servers` must be present and non-empty array.
 1:1  warning  openapi-tags      OpenAPI object should have non-empty `tags` array.
 2:6  warning  info-contact      Info object should contain `contact` object.
 2:6  warning  info-description  OpenAPI object info `description` must be present and non-empty string.

✖ 4 problems (1 error, 3 warnings, 0 infos, 0 hints)
```

--------------------------------

### asyncapi-tags-alphabetical: Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid tags list where the tags are in alphabetical order by name, satisfying the asyncapi-tags-alphabetical rule. The rule is not recommended by default and has a default severity of warn when enabled.

```yaml
tags:
  - name: "Aardvark"
  - name: "Badger"
```

--------------------------------

### oas3-server-trailing-slash: Good example without trailing slashes

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Good example for the `oas3-server-trailing-slash` rule: server URLs do not have trailing slashes. This avoids awkward URLs like `https://example.com/api//pets` when joining with paths.

```yaml
servers:
  - url: https://example.com
  - url: https://example.com/api
```

--------------------------------

### Good Example: Unique tag names in AsyncAPI info.tags

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid AsyncAPI document where the info.tags array contains unique names, satisfying the asyncapi-3-tags-uniqueness rule.

```yaml
info:
  tags:
    - name: "Aardvark"
    - name: "Badger"
```

--------------------------------

### asyncapi-operation-security Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows an invalid security definition where the operation references a scheme not defined in components.securitySchemes.

```yaml
channels:
  "user/signup":
    publish:
      security:
        - not_defined: []
components:
  securitySchemes:
    petstore_auth: ...
```

--------------------------------

### contact-properties Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Shows a valid OpenAPI document with a complete contact object including name, email, and url. This satisfies the contact-properties rule.

```yaml
openapi: "3.0.2"
info:
  title: Awesome API
  description: A very well-defined API
  version: "1.0"
  contact:
    name: A-Team
    email: a-team@goarmy.com
    url: goarmy.com/apis/support

```

--------------------------------

### Mix and match ruleset sources in extends

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/7-sharing-rulesets.md

Shows how to combine local files, HTTP URLs, and npm packages in the `extends` array of a Spectral ruleset. The npm package must be installed in `node_modules` and have a valid `package.json`.

```yaml
extends:
  - ./config/spectral.json
  - https://example.org/api/style.yaml
  - some-npm-module # note that this would be treated as any other npm package, therefore it has to live under node_modules, and have a valid package.json.
```

--------------------------------

### Good Example for arazzo-info-description

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/arazzo-rules.md

An Arazzo document with a non-empty info description that includes Markdown.

```yaml
arazzo: 1.0.0
info:
  title: BNPL Workflow Description
  version: 1.0.0
  description: |
    ## Overview

    This workflow guides the process of applying for a loan at checkout using a "Buy Now, Pay Later" (BNPL) platform. It orchestrates a series of API interactions to ensure a seamless and efficient loan application process, integrating multiple services across different API providers.

    ### Key Features
    - **Multi-step Loan Application:** The workflow includes multiple steps to check product eligibility, retrieve terms and conditions, create customer profiles, initiate the loan, and finalize the payment plan.
    - **Dynamic Decision Making:** Based on the API responses, the workflow adapts the flow, for example, skipping customer creation if the customer is already registered or ending the workflow if no eligible products are found.
    - **User-Centric:** The workflow handles both existing and new customers, providing a flexible approach to customer onboarding and loan authorization.
```

--------------------------------

### Lint a file with the extended ruleset

Source: https://github.com/stoplightio/spectral/blob/develop/docs/getting-started/3-rulesets.md

Run the `spectral lint` command on a file to apply the ruleset. This example lints `myapifile.yaml`.

```bash
spectral lint myapifile.yaml
```

--------------------------------

### Create the ruleset folder

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/4f-js-rulesets.md

Creates a folder for the JavaScript ruleset and navigates into it.

```bash
mkdir style-guide
cd style-guide
```

--------------------------------

### JSON Formatter Output Schema and Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/2-cli.md

The JSON formatter outputs an array of objects, each with code, path, message, severity, range, and source properties. The schema defines the structure, and the example shows a sample output for a rule violation. Enable it with `-f json --quiet`.

```yaml
type: array
items:
  type: object
  properties:
    code:
      type: string
      description: A string that represents the rule code that has been violated or triggered in Spectral. This code is unique to each rule defined in Spectral.
    path:
      type: array
      description: An array of strings that indicate the location within the analyzed document where the rule was triggered. It shows the "path" in the document structure to the issue.
      items:
        type: string
    message:
      type: string
      description: A string that contains a human-readable message describing the issue found by Spectral. This message typically provides information on why the rule was triggered and how to fix the issue.
    severity:
      enum:
        - 0
        - 1
        - 2
        - 3
      description: An integer representing the severity level of the rule violation. The severity levels usually follow a specific scale defined by Spectral. 0 equals error, while 3 is hint.
    range:
      type: object
      description: An object that describes where in the file the issue was found. It contains two sub-properties, start and end, each of which is an object with line and character properties. line and character are integers that represent the line number and the character position within the line, respectively, where the issue starts or ends. All the values are zero indexed.
      properties:
        start:
          type: object
          properties:
            line:
              type: integer
              minimum: 0
            character:
              type: integer
              minimum: 0
          required:
            - line
            - character
        end:
          type: object
          properties:
            line:
              type: integer
              minimum: 0
            character:
              type: integer
              minimum: 0
          required:
            - line
            - character
    source:
      type: string
      description: A string that contains the file path of the document that was analyzed by Spectral. It points to the source of the issue.
  required:
    - code
    - path
    - message
    - severity
    - range
    - source
```

```json
[
  {
    "code": "invalid-response",
    "path": ["paths", "/users/{id}", "get", "responses", "200"],
    "message": "The '200' response should include a schema definition.",
    "severity": 2,
    "range": {
      "start": {
        "line": 32,
        "character": 12
      },
      "end": {
        "line": 35,
        "character": 14
      }
    },
    "source": "/Users/johndoe/projects/api-definition/openapi.yaml"
  }
]
```

--------------------------------

### asyncapi-info-contact-properties Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a valid AsyncAPI document with a contact object containing name, email, and url properties. This rule requires all three properties to be present.

```yaml
asyncapi: "2.0.0"
info:
  title: Awesome API
  description: A very well-defined API
  version: "1.0"
  contact:
    name: A-Team
    email: a-team@goarmy.com
    url: https://goarmy.com/apis/support
```

--------------------------------

### asyncapi-operation-operationId-uniqueness: Good Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Valid operationId usage: each operation has a unique operationId ('turnOn' and 'turnOff').

```yaml
channels:
  smartylighting.streetlights.1.0.action.{streetlightId}.turn.on:
    publish:
      operationId: turnOn
  smartylighting.streetlights.1.0.action.{streetlightId}.turn.off:
    publish:
      operationId: turnOff
```

--------------------------------

### oas3-api-servers: Valid servers array

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Example of a valid OpenAPI v3 `servers` array with production, staging, and development URLs. Required by the `oas3-api-servers` rule.

```yaml
servers:
  - url: https://example.com/api
    description: Production server
  - url: https://staging.example.com/api
    description: Staging server
  - url: http://localhost:3001
    description: Development server
```

--------------------------------

### Use pretty formatter in JavaScript

Source: https://github.com/stoplightio/spectral/blob/develop/packages/formatters/README.md

Import the pretty formatter from the package and use it to format the results of a Spectral validation run. The example shows creating a Spectral instance, running it on a document, and then formatting the result with pretty before logging it to stderr.

```ts
import { pretty } from "@stoplight/spectral-formatters";

const spectral = new Spectral();
// ...
const result = await spectral.run(document);

// You can also filter the results here.
const output = pretty(result);

console.error(output);
// ...
```

--------------------------------

### tag-description: Tags with descriptions

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Example of tags with descriptions, as recommended by the tag-description rule. The rule is not recommended by default and has a default severity of warn.

```yaml
tags:
  - name: "Aardvark"
    description: Funny-nosed pig-head raccoon.
  - name: "Badger"
    description: Angry short-legged omnivores.

```

--------------------------------

### asyncapi-server-no-trailing-slash Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows server URLs with trailing slashes, which can cause awkward URLs when joined with channels.

```yaml
servers:
  - url: mqtt://example.com/
  - url: mqtt://example.com/broker/
```

--------------------------------

### operation-operationId-valid-in-url bad example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the operation-operationId-valid-in-url rule. Shows an operationId with a space, which is not URL-safe.

```yaml
paths:
  /pets:
    get:
      operationId: get cats
```

--------------------------------

### asyncapi-payload-default Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows a payload with a default value that does not conform to the payload schema (string instead of integer).

```yaml
payload:
  type: object
  properties:
    value:
      type: integer
  required:
    - value
  default:
    value: nope!
```

--------------------------------

### operation-operationId-unique bad example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the operation-operationId-unique rule. Shows two operations with the same operationId.

```yaml
paths:
  /pet:
    patch:
      operationId: "update-pet"
      responses:
        200:
          description: ok
    put:
      operationId: "update-pet"
      responses:
        200:
          description: ok
```

--------------------------------

### operation-operationId-unique good example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Good example for the operation-operationId-unique rule. Shows two operations with unique operationIds.

```yaml
paths:
  /pet:
    patch:
      operationId: "update-pet"
      responses:
        200:
          description: ok
    put:
      operationId: "replace-pet"
      responses:
        200:
          description: ok
```

--------------------------------

### Create the ruleset file

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/4f-js-rulesets.md

Creates the JavaScript file that will hold the ruleset.

```bash
touch spectral.js
```

--------------------------------

### Example ruleset with a single rule

Source: https://github.com/stoplightio/spectral/blob/develop/docs/getting-started/3-rulesets.md

A YAML ruleset defining a rule `paths-kebab-case` that validates OpenAPI paths are kebab-case. It uses the `pattern` function with a regex to match allowed path segments.

```yaml
rules:
  paths-kebab-case:
    description: Paths should be kebab-case.
    message: "{{property}} should be kebab-case (lower-case and separated with hyphens)"
    severity: warn
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^(\/|[a-z0-9-.]+|{[a-zA-Z0-9_]+})+$"
```

--------------------------------

### Use a Proxy with Spectral (example-4.mjs)

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/3-javascript.md

Configure Spectral to route all remote asset requests (including $refs and rules) through an HTTP(S) proxy. The proxy URL is read from the PROXY environment variable. This example uses the createHttpAndFileResolver function with a ProxyAgent instance.

```javascript
import { Spectral } from "@stoplight/spectral-core";
import ProxyAgent from "proxy-agent";
import { createHttpAndFileResolver } from "@stoplight/spectral-ref-resolver";

// start Spectral using a proxy
const spectral = new Spectral({
  resolver: createHttpAndFileResolver({ agent: new ProxyAgent(process.env.PROXY) }),
});

// ... load document

// ... lint document - $refs and rules will be requested using the proxy
```

--------------------------------

### Use setRuleset to load a JSON ruleset

Source: https://github.com/stoplightio/spectral/blob/develop/docs/migration-guides/5.0.md

If your ruleset is stored in a plain JSON file, you can use 'setRuleset' to load it directly instead of 'loadRuleset'. The example shows how to require the ruleset and pass it to 'setRuleset' before running the document.

```javascript
const { Spectral } = require("@stoplight/spectral");
const ruleset = require("./my-ruleset.json");

const spectral = new Spectral();
spectral.setRuleset(ruleset);
spectral.run(myOpenApiDocument).then(results => {
  console.log("here are the results", results);
});
```

--------------------------------

### Legacy YAML ruleset (.spectral.yaml)

Source: https://github.com/stoplightio/spectral/blob/develop/packages/ruleset-migrator/README.md

Example of a legacy Spectral ruleset in YAML format, extending the OAS ruleset, specifying formats, and defining a custom rule with a pattern function.

```yaml
# .spectral.yaml
extends: spectral:oas
formats: [oas2, json-schema-loose]
rules:
  oas3-schema: warning
  valid-type:
    message: Type must be valid
    given: $..type
    then:
      function: pattern
      functionOptions:
        mustMatch: ^(string|number)$

```

--------------------------------

### no-$ref-siblings Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Shows a $ref with a sibling property (example), which is a violation of the no-$ref-siblings rule for OpenAPI versions before v3.1.

```yaml
TheBadModel:
  $ref: "#/components/TheBadModelProperties"
  # This property should be ignored
  example: May or may not show up

```

--------------------------------

### asyncapi-tags-alphabetical: Bad Example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/asyncapi-rules.md

Shows an invalid tags list where the tags are not in alphabetical order by name. This violates the asyncapi-tags-alphabetical rule. The rule is not recommended by default and has a default severity of warn when enabled.

```yaml
tags:
  - name: "Badger"
  - name: "Aardvark"
```

--------------------------------

### casing function example with type camel

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/functions.md

Example rule that enforces camelCase for the value at `$.name`. Uses the `casing` function with `functionOptions.type: camel`.

```yaml
camel-case-name:
  description: Name should be camelCased.
  given: "$.name"
  then:
    function: casing
    functionOptions:
      type: camel
```

--------------------------------

### enumeration function example with values option

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/functions.md

Configures a rule to restrict the 'tags' field to a specific set of values: 'users', 'articles', and 'categories'. The 'values' option is required and accepts an array of numbers or strings.

```yaml
whitelisted-tags:
  description: Pick from a very restrictive set of tags.
  given: "$.paths.*"
  then:
    field: tags
    function: enumeration
    functionOptions:
      values:
        - users
        - articles
        - categories
```

--------------------------------

### no-eval-in-markdown bad example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the no-eval-in-markdown rule. Shows an OpenAPI document with a title containing an eval() call, which could lead to XSS when rendered.

```yaml
openapi: "3.0.2"
info:
  title: 'some title with eval(',
```

--------------------------------

### Use Document source instead of documentUri

Source: https://github.com/stoplightio/spectral/blob/develop/docs/migration-guides/6.0.md

Workaround for the removed `{ documentUri }` option in `run`. Create a `Document` with the source path and pass it to `run`.

```typescript
import { Document, Spectral } from "@stoplight/spectral-core";
import { Json as JsonParser } from "@stoplight/spectral-parsers";
import * as path from "@stoplight/path";

const s = new Spectral();

const doc = new Document(
  `{
  "street": null
}`,
  JsonParser,
  path.join(__dirname, "street-doc.json"),
);

await spectral.run(doc);
```

--------------------------------

### no-script-tags-in-markdown bad example

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the no-script-tags-in-markdown rule. Shows an OpenAPI document with a title containing a <script> tag, which could execute arbitrary code when rendered as HTML.

```yaml
openapi: "3.0.2"
info:
  title: 'some title with <script>alert("You are Hacked");</script>',
```

--------------------------------

### array-items: Bad example missing items field

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the array-items rule: inner array schema lacks an items field. The rule is recommended and has a default severity of error.

```yaml
TheBadModel:
  type: object
  properties:
    favoriteColorSets:
      type: array
      items:
        type: array

```

--------------------------------

### Run a single test harness scenario

Source: https://github.com/stoplightio/spectral/blob/develop/test-harness/README.md

Run a single test scenario by passing a path relative to the ./tests directory. All scenarios are converted to .js files under ./tests.

```bash
yarn test.harness test-harness/tests/require-module
```

--------------------------------

### typed-enum: Bad example with string in integer enum

Source: https://github.com/stoplightio/spectral/blob/develop/docs/reference/openapi-rules.md

Bad example for the typed-enum rule: enum contains a string value while the type is integer. The rule is recommended and has a default severity of warn.

```yaml
TheBadModel:
  type: object
  properties:
    number_of_connectors:
      type: integer
      description: The number of extension points.
      enum:
        - 1
        - 2
        - "a string!"
        - 8

```

--------------------------------

### Lint files using glob syntax

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/2-cli.md

Use glob syntax to match multiple files at once.

```bash
spectral lint ./reference/**/*.oas*.{json,yml,yaml}
```

--------------------------------

### Lint with a remote ruleset via CLI

Source: https://github.com/stoplightio/spectral/blob/develop/docs/guides/7-sharing-rulesets.md

Shows how to pass a remote ruleset URL directly to the Spectral CLI using the `-r` flag.

```shell
spectral lint -r https://example.com/some-ruleset.yml
```
Tokens:
Raw