### Install vacuum with go get

Source: https://quobix.com/vacuum/api/getting-started

Install the vacuum library for Go development.

```bash
go get github.com/daveshanley/vacuum
```

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

### Generate report from Kubernetes example spec

Source: https://quobix.com/vacuum/commands/html-report

Use the example Kubernetes spec from the vacuum source directory.

```bash
vacuum html-report model/test_files/k8s.yaml
```

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

### Example ruleset configuration for asyncApiMessageExamples

Source: https://quobix.com/vacuum/functions/asyncapi/asyncapimessageexamples

YAML configuration for a vacuum rule using the asyncApiMessageExamples function. No function options are required. Empty examples are reported on the example node.

```yaml
rules:
  example-asyncapimessageexamples:
    description: Validate message examples.
    severity: error
    formats: [asyncapi3]
    given: $
    then:
      function: asyncApiMessageExamples

```

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

### Generate report from Asana example spec

Source: https://quobix.com/vacuum/commands/html-report

Use the example Asana spec from the vacuum source directory.

```bash
vacuum html-report model/test_files/asana.yaml
```

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

### Install via curl

Source: https://quobix.com/vacuum/installing

Simple installation for CI/CD pipelines using a shell script.

```bash
curl -fsSL https://quobix.com/scripts/install_vacuum.sh | sh
```

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

### Install via yarn

Source: https://quobix.com/vacuum/installing

Installs vacuum globally via yarn.

```bash
yarn global add @quobix/vacuum
```

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

### OpenAPI 3.0 example with requestBody and response examples

Source: https://quobix.com/vacuum/rules/examples/oas3-missing-example

Shows a valid OpenAPI 3.0 path definition for a POST /burgers endpoint. It includes examples for the request body and response content, each with multiple named examples. This demonstrates how to satisfy the oas3-missing-example rule by providing examples for all media types.

```yaml
paths:
  /burgers:
    post:
      operationId: createBurger
      tags:
        - "Burgers"
      summary:  Create a new burger
      description: A new burger for our menu, yummy yum yum.
      requestBody:
        description: Give us the new burger!
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Burger'
            examples:
              pbjBurger:
                summary: A horrible, nutty, sticky mess.
                value:
                  name: Peanut And Jelly
                  numPatties: 3
              cakeBurger:
                summary: A sickly, sweet, atrocity
                value:
                  name: Chocolate Cake Burger
                  numPatties: 5
      responses:
        "200":
          description: A tasty burger for you to eat.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Burger'
              examples:
                quarterPounder:
                  summary: A yummy tasty two patty burger.
                  value:
                    name: Quarter Pounder with Cheese
                    numPatties: 1
                filetOFish:
                  summary: A Cripsy Fish Sammich filled with ocean goodness.
                  value:
                    name: Filet-O-Fish
                    numPatties: 1

```

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

### Good example: message example with payload

Source: https://quobix.com/vacuum/rules/examples/asyncapi-message-examples

Shows an AsyncAPI 3.1.0 message example that includes a payload, satisfying the rule.

```yaml
asyncapi: 3.1.0
components:
  messages:
    UserCreated:
      examples:
        - name: created-user
          payload:
            id: usr_123

```

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

### vacuum docs config file example

Source: https://quobix.com/vacuum/commands/docs

Example printing press config file for larger builds. CLI flags win over config file values.

```yaml
title: Internal API Catalog
description: API documentation for internal services.
output: ./api-docs
publish: true
metrics: true

scan:
  root: ./services
  include:
    - "**/*.yaml"
    - "**/*.json"
  ignoreRules:
    - "**/vendor/**"
    - "**/testdata/**"

build:
  mode: fast
  maxPools: 4
  workersPerPool: 2
```

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

### Generate report from Stripe example spec

Source: https://quobix.com/vacuum/commands/html-report

Use the example Stripe spec from the vacuum source directory.

```bash
vacuum html-report model/test_files/stripe.yaml
```

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

### Run Per-Node Mode Example

Source: https://quobix.com/vacuum/api/custom-javascript-functions

Command to run the per-node mode example using the Sentiment Analyzer API. Makes 29 API calls and takes ~3 seconds.

```bash
vacuum lint model/test_files/sad-spec.yaml \
  -r rulesets/examples/sentiment-check.yaml \
  -f plugin/sample/js

```

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

### Install via NPM

Source: https://quobix.com/vacuum/installing

Installs vacuum globally via npm.

```bash
npm install -g @quobix/vacuum
```

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

### Good example: direct schemas and valid multi-item combinator

Source: https://quobix.com/vacuum/rules/schemas/no-unnecessary-combinator

Shows the corrected schemas using direct references, types, and enums, plus a valid multi-item allOf example.

```yaml
components:
  schemas:
    User:
      $ref: "#/components/schemas/Person"  # Direct reference
    Product:
      type: string  # Direct type
    Status:
      enum: [active, inactive]  # Direct enum

    # Valid multi-item combinators
    Employee:
      allOf:
        - $ref: "#/components/schemas/Person"
        - type: object
          properties:
            employeeId:
              type: string

```

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

### Good example: with defaultContentType

Source: https://quobix.com/vacuum/rules/messages/asyncapi-content-type

This example adds defaultContentType: application/json at the document root, which satisfies the rule.

```yaml
asyncapi: 3.1.0
defaultContentType: application/json
components:
  messages:
    UserCreated:
      payload:
        type: object

```

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

### Another good example: string with format, pattern, and maxLength

Source: https://quobix.com/vacuum/rules/owasp/owasp-string-restricted

Another good example that uses format, pattern, and maxLength to restrict the string value.

```yaml
openapi: "3.1.0"
info:
  version: "1.0"
components:
  schemas:
    Foo:
      type: string
      format: hex
      pattern: ^[0-9a-fA-F]+$
      maxLength: 16

```

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

### Good example: compatible allOf schemas

Source: https://quobix.com/vacuum/rules/schemas/json-schema-composition-sanity

This example shows a valid `allOf` composition where both schemas are compatible, allowing an object with a `size` property. Use this as a reference for correct usage.

```json
{
  "allOf": [
    { "type": "object" },
    {
      "properties": {
        "size": {
          "type": "string"
        }
      }
    }
  ]
}
```

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

### Run Batch Mode Example

Source: https://quobix.com/vacuum/api/custom-javascript-functions

Command to run the batch mode example using the Sentiment Analyzer API. Makes 1 API call and takes ~100 milliseconds.

```bash
vacuum lint model/test_files/sad-spec.yaml \
  -r rulesets/examples/sentiment-check-batch.yaml \
  -f plugin/sample/js

```

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

### Good example: string with format email

Source: https://quobix.com/vacuum/rules/owasp/owasp-string-restricted

This example satisfies the rule by adding a format constraint (email) to the string schema.

```yaml
openapi: "3.1.0"
info:
  version: "1.0"
components:
  schemas:
    Foo:
      type: string
      format: email

```

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

### Set up the plugin directory and module

Source: https://quobix.com/vacuum/api/custom-functions

Commands to create a new directory for the plugin, initialize the Go module, and add vacuum as a dependency.

```bash
mkdir my-plugin && cd my-plugin
```

```bash
go mod init my-awesome-functions
```

```bash
go get github.com/daveshanley/vacuum
```

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

### Build sample plugin with go build -buildmode=plugin

Source: https://quobix.com/vacuum/api/custom-functions

Build the sample plugin with Go's plugin build mode, specifying the source files boot.go, check_single_path.go, and useless_func.go.

```bash
go build -buildmode=plugin boot.go check_single_path.go useless_func.go
```

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

### Good example: GET operation using query parameters

Source: https://quobix.com/vacuum/rules/operations/no-request-body

Shows a corrected GET operation that uses a query parameter instead of a requestBody.

```yaml
paths:
  /users/{id}:
    get:
      summary: Get user details
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: includeDetails  # ✅ Use query parameters instead
          in: query
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: User details
```

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

### Bad example: GET operation with requestBody

Source: https://quobix.com/vacuum/rules/operations/no-request-body

Shows a GET operation that incorrectly defines a requestBody. This violates the rule and may cause interoperability issues.

```yaml
paths:
  /users/{id}:
    get:
      summary: Get user details
      operationId: getUser
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:  # ❌ GET should not have a request body
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                includeDetails:
                  type: boolean
      responses:
        '200':
          description: User details
```

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

### Preview docs with --serve flag

Source: https://quobix.com/vacuum/api-docs

Use --serve to preview the published layout locally. Then open http://127.0.0.1:9090.

```bash
vacuum docs my-openapi-spec.yaml --serve --port 9090
```

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

### Bad example: missing security rule

Source: https://quobix.com/vacuum/rules/owasp/owasp-protection-global-unsafe

An OpenAPI document that violates the rule because the GET operation under /security-ko-get has no security rule, and the HEAD operation has an empty security array. This example is used to illustrate the violation.

```yaml
openapi: 3.0.1
info:
  version: 1.2.3
  title: securitySchemes
paths:
  /security-ko-get:
    get:
      responses: {}
    head:
      security: []
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

```

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

### Bad example: unprotected operations

Source: https://quobix.com/vacuum/rules/owasp/owasp-protection-global-safe

Shows an OpenAPI 3.0.1 spec where the GET and HEAD operations lack security definitions, violating the rule.

```yaml
openapi: 3.0.1
info:
  version: "1.2.3"
  title: "securitySchemes"
paths:
  /security-ko-get:
    get:
      responses: {}
    head:
      security: []
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic

```

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

### Clone vacuum repo and enter sample plugin directory

Source: https://quobix.com/vacuum/api/custom-functions

Clone the vacuum repo and change into the plugin/sample directory to access the example function plugin.

```bash
git clone https://github.com/daveshanley/vacuum.git && \
cd vacuum/plugin/sample
```

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

### Good example: operation with 4xx response

Source: https://quobix.com/vacuum/rules/operations/operation-4xx-response

Shows the same path but with 4xx responses added (429 for GET, 401 for POST) to satisfy the rule.

```yaml
"/burger":
  get:
    responses:
      "200":
        description: All the burgers please
      "429":
        description: We're super busy right now, please wait.  
  post:
    responses:
      "401":
        description: This API is protected, only authorized users.
      "200":
        description: Burger was created! well done    

```

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

### Build vacuum from source

Source: https://quobix.com/vacuum/installing

Builds the vacuum binary from source using Go.

```bash
go build vacuum.go
```

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

### Good example: With servers object

Source: https://quobix.com/vacuum/rules/servers/asyncapi-servers

Shows an AsyncAPI document with a root servers object containing a server definition, which passes the asyncapi-servers rule.

```yaml
asyncapi: 3.1.0
info:
  title: User events
  version: 1.0.0
servers:
  production:
    host: events.example.com
    protocol: mqtt
channels: {}

```

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

### Bad example: HTTP verbs in path segments

Source: https://quobix.com/vacuum/rules/operations/no-http-verbs-in-path

Shows a path with segments 'go/get/something' and 'post/new/thing' that include the verbs 'get' and 'post', which violate the rule.

```yaml
paths: 
  '/go/get/something':
    get:
      description: GET is a part of the path, which is bad
  '/post/new/thing':
    post:
      description: Do not include verbs in paths.

```

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

### Compile vacuum from source

Source: https://quobix.com/vacuum/api/custom-functions

Go back up into the vacuum directory and compile vacuum.

```bash
cd ../../ && go build vacuum.go
```

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

### Bad example: missing 500 response

Source: https://quobix.com/vacuum/rules/owasp/owasp-define-error-responses-500

Shows an OpenAPI 3.1.0 spec with a GET endpoint that only defines a 200 response, violating the rule. The 500 response is absent.

```yaml
openapi: 3.1.0
info:
  version: 1.0
paths:
  /no-error-response:
    get:
      responses:
        200:
          description: OK
          content:
            "application/problem+json": {}

```

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

### Good example: Server url with real domain

Source: https://quobix.com/vacuum/rules/information/oas3-host-not-example

Shows an OpenAPI 3.1 document with a Server url set to https://quibix.com/vacuum/api and a description, which passes the oas3-host-not-example rule.

```yaml
openapi: 3.1
servers:
 - url: "https://quibix.com/vacuum/api"
   description: "Central API endpoint for the vacuum endpoint"
  ...

```

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

### Good example: parameter with description

Source: https://quobix.com/vacuum/rules/descriptions/oas3-parameter-description

Shows the same parameter but with a description added, which satisfies the rule. The description is "Numeric ID of the chicken nugget that you want to get".

```yaml
paths:
  /chicken/nuggets/{nuggetId}:
    get:
      summary: "Get a chicken nugget by ID"
      parameters:
        - in: path
          name: nuggetId
          schema:
            type: integer
          required: true
          description: "Numeric ID of the chicken nugget that you want to get"
        ...

```

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

### Good example: OpenAPI spec with rate limit headers

Source: https://quobix.com/vacuum/rules/owasp/owasp-rate-limit

Shows an OpenAPI 3.1.0 specification for a GET operation that includes the X-RateLimit-Limit and X-RateLimit-Reset headers, satisfying the owasp-rate-limit rule.

```yaml
openapi: 3.1.0
info:
  version: 1.0
paths:
  /:
    get:
      responses:
        "201":
          description: ok
          headers:
            "X-RateLimit-Limit":
              schema:
                type: string
            "X-RateLimit-Reset":
              schema:
                type: string`

```

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

### Good example: info object with license

Source: https://quobix.com/vacuum/rules/information/info-license

Shows an info object with a license defined, which satisfies the info-license rule.

```yaml
info:
  title: Chicken Nuggets Inc. Developer API
  license:
    name: "MIT"
    url: https://opensource.org/licenses/MIT

```

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

### Good example: valid JSON Pointer target

Source: https://quobix.com/vacuum/rules/arazzo/arazzo-selector

Shows the corrected Arazzo workflow where the 'target' is '/name', a valid JSON Pointer that starts with '/'. This resolves the arazzo-selector violation.

```yaml
arazzo: 1.0.1
info:
  title: Read a pet
  version: '1.0'
  description: Retrieve a pet from the API.
  summary: Read a pet.
sourceDescriptions:
  - name: api
    url: api.yaml
    type: openapi
workflows:
  - workflowId: readPet
    description: Retrieve a pet.
    summary: Read a pet.
    steps:
      - stepId: read
        description: Call the read operation.
        operationId: $sourceDescriptions.api.read
        requestBody:
          contentType: application/json
          payload: {}
          replacements:
            - target: /name
              value: Fido

```

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

### Good example: channel server references root server

Source: https://quobix.com/vacuum/rules/channels/asyncapi-3-channel-servers

Shows a channel server reference pointing to `#/servers/production`, which is the correct way to reference a root-level server.

```yaml
asyncapi: 3.1.0
servers:
  production:
    host: events.example.com
    protocol: mqtt
channels:
  userEvents:
    address: users
    servers:
      - $ref: '#/servers/production'

```

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

### Bad example: OpenAPI spec missing rate limit headers

Source: https://quobix.com/vacuum/rules/owasp/owasp-rate-limit

Shows an OpenAPI 3.1.0 specification for a GET operation that does not include any rate limiting headers, violating the owasp-rate-limit rule.

```yaml
openapi: 3.1.0
info:
  version: 1.0
paths:
  /chicken/nuggets:
    get:
      description: get
      responses:
        "201":
          description: "ok"
          headers:
            "SomethingElse":
              schema:
                type: string

```

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

### Build API catalog from directory

Source: https://quobix.com/vacuum/api-docs

Pass a directory instead of a single file to build an entire API catalog. Scans for supported OpenAPI and AsyncAPI documents, groups specs by service and version, and renders a top-level portal plus full documentation.

```bash
vacuum docs ./services --output ./api-docs
```

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

### Good example: includes 429 response

Source: https://quobix.com/vacuum/rules/owasp/owasp-define-error-responses-429

Shows an OpenAPI 3.1.0 specification that defines a GET endpoint with a 429 response, satisfying the OWASP rule. Use this as a template for compliant specifications.

```yaml
openapi: "3.1.0"
info:
  version: "1.0"
paths:
  /:
    get:
      responses:
        429:
          description: ok
          content:
            "application/json":

```

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

### Bad example: operation without 4xx response

Source: https://quobix.com/vacuum/rules/operations/operation-4xx-response

Shows an OpenAPI path with GET and POST operations that only return 200 responses, violating the rule because no 4xx error code is defined.

```yaml
"/burger":
  get:
    responses:
      "200":
        description: All the burgers please
  post:
    responses:
      "200":
        description: Burger was created! well done    

```

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

### Good example: with contact

Source: https://quobix.com/vacuum/rules/information/asyncapi-info-contact

An AsyncAPI document that satisfies the asyncapi-info-contact rule by including a contact object with name, url, and email, along with a license.

```yaml
asyncapi: 3.1.0
info:
  title: User events
  version: 1.0.0
  description: Events emitted by the user lifecycle service.
  contact:
    name: API Platform
    url: https://example.com/support
    email: api@example.com
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT

```

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

### Good example: $ref in Operations

Source: https://quobix.com/vacuum/rules/operations/path-item-refs

Shows the recommended approach: use $ref pointers inside operations (post, get) rather than as Path Items, avoiding duplicate path definitions.

```yaml
paths:
  /pizza/{cake}/{icecream}:
    post:
      $ref: 'operations/pizza/cake/post.yaml'
  /pizza/{soda}/{candy}:
    get: 
      $ref: 'operations/pizza/soda/get.yaml'

```

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

### Good example: parameters with descriptions

Source: https://quobix.com/vacuum/rules/descriptions/oas2-parameter-description

Shows a parameter list where each parameter includes a meaningful description, satisfying the rule.

```yaml
paths:
  /chicken/nuggets/{nuggetId}:
    get:
      summary: "Gets a chicken nugget by ID."
      parameters:
        - in: path
          name: nuggetId
          description: "Chicken nuggetId is the kebab-case name of the product."
        - in: query
          name: addSauce
          description: "Set this to 'true' to add ketchup, leave blank otherwise."
        ...

```

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

### Bad example: missing 429 response

Source: https://quobix.com/vacuum/rules/owasp/owasp-define-error-responses-429

Shows an OpenAPI 3.1.0 specification that defines a GET endpoint with only a 200 response, omitting the required 429 error response. This violates the OWASP rule.

```yaml
openapi: "3.1.0"
info:
  version: "1.0"
paths:
  /:
    get:
      responses:
        200:
          description: ok
          content:
            "application/problem+json":

```

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

### Good example: step with description

Source: https://quobix.com/vacuum/rules/arazzo/arazzo-step-description

Shows a workflow step with a description explaining why the step is called. This satisfies the rule.

```yaml
workflows:
  - workflowId: readPet
    steps:
      - stepId: read
        description: Fetch the pet, we need its ID for the next step.
        operationId: $sourceDescriptions.api.read

```

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

### Bad example: invalid JSON Pointer target

Source: https://quobix.com/vacuum/rules/arazzo/arazzo-selector

Shows an Arazzo workflow where the 'target' in a request body replacement is 'name', which is not a valid JSON Pointer because it does not start with '/'. This triggers the arazzo-selector violation.

```yaml
arazzo: 1.0.1
info:
  title: Read a pet
  version: '1.0'
  description: Retrieve a pet from the API.
  summary: Read a pet.
sourceDescriptions:
  - name: api
    url: api.yaml
    type: openapi
workflows:
  - workflowId: readPet
    description: Retrieve a pet.
    summary: Read a pet.
    steps:
      - stepId: read
        description: Call the read operation.
        operationId: $sourceDescriptions.api.read
        requestBody:
          contentType: application/json
          payload: {}
          replacements:
            - target: name
              value: Fido

```

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

### Bad example: duplicate path definitions

Source: https://quobix.com/vacuum/rules/operations/duplicate-paths

Shows an OpenAPI 3.1.0 specification with duplicate '/users/{id}' path keys. The first definition with a GET operation will be lost during YAML parsing, leaving only the POST operation.

```yaml
openapi: 3.1.0
info:
  title: API with duplicate paths
  version: 1.0.0
paths:
  /users/{id}:
    get:
      summary: Get user by ID
      # This definition will be lost!
  /users/{id}:
    post:
      summary: Create user
      # Only this definition will be kept

```

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

### Bad example: step sends undeclared parameter petId

Source: https://quobix.com/vacuum/rules/arazzo/arazzo-parameter

This Arazzo workflow defines a step 'read' that sends a parameter 'petId' in path, but the target operation GET /pets does not declare it. This triggers the arazzo-parameter violation.

```yaml
arazzo: 1.0.1
info:
  title: Read a pet
  version: '1.0'
  description: Retrieve a pet from the API.
  summary: Read a pet.
sourceDescriptions:
  - name: api
    url: api.yaml
    type: openapi
workflows:
  - workflowId: readPet
    description: Retrieve a pet.
    summary: Read a pet.
    steps:
      - stepId: read
        description: Call the read operation.
        operationId: $sourceDescriptions.api.read
        parameters:
          - name: petId
            in: path
            value: 1

```

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

### Bad example: server host with example.com

Source: https://quobix.com/vacuum/rules/servers/asyncapi-3-server-not-example-com

Shows a server host that still uses the placeholder example.com, which triggers the asyncapi-3-server-not-example-com violation.

```yaml
asyncapi: 3.1.0
servers:
  production:
    host: example.com
    protocol: mqtt

```

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

### Good Response Example in OpenAPI 2.0

Source: https://quobix.com/vacuum/rules/examples/oas2-valid-schema-example

Shows a valid response example for a POST /pet operation in OpenAPI 2.0. The example includes a response with an 'application/json' example containing id, name, color, and type fields. This demonstrates how to add examples to responses, as OpenAPI 2.0 does not support request body examples.

```yaml
"/pet":
  post:
    produces:
    - application/json
    parameters:
    - in: body
      name: body
      description: Pet object that needs to be added to the store
      required: true
      schema:
        "$ref": "#/definitions/Pet"
    responses:
      '200':
        description: New pet was added
        examples:
          application/json:
            id: 12345
            name: My New Pet
            color: Brown
            type: Dog

```

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

### Good example: workflow with summary

Source: https://quobix.com/vacuum/rules/arazzo/arazzo-workflow-summary

Shows a workflow with a 'summary' field, which passes the rule. The summary is a short one-line description of the workflow.

```yaml
workflows:
  - workflowId: readPet
    summary: Read a pet.
    description: Retrieve a single pet so it can be shown to a customer.
    steps:
      - stepId: read
        operationId: $sourceDescriptions.api.read

```

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

### Configure ruleset and base path in vacuum.conf.yaml

Source: https://quobix.com/vacuum/configuring

Example configuration file that sets the ruleset and base path for vacuum.

```yaml
ruleset: "../rules/production-ruleset.yaml"
base: "../../specs"

```

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

### asyncApiMessageExamples

Source: https://quobix.com/vacuum/functions/asyncapi/asyncapimessageexamples

AsyncAPI-specific function that ensures message examples include payload or headers. It reports empty examples on the example node.

```APIDOC
## asyncApiMessageExamples

### Description
Ensures message examples include payload or headers. Empty examples are reported on the example node.

### Function Name
asyncApiMessageExamples

### Options
No function options are required.

### Result Behavior
Empty examples are reported on the example node.

### Example Ruleset Configuration
```yaml
rules:
  example-asyncapimessageexamples:
    description: Validate message examples.
    severity: error
    formats: [asyncapi3]
    given: $
    then:
      function: asyncApiMessageExamples
```

### Used By
- asyncapi-message-examples
```

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

### Good example: component with description

Source: https://quobix.com/vacuum/rules/descriptions/component-description

Shows a component schema with a description property, which passes the rule.

```yaml
components:
  schemas:
    ChickenNugget:
      type: object
      description: "This represents a chicken nugget, used for all kinds of nugget fun."
      properties:
        id:
          type: integer
        name:
          type: string

```

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

### Install via Homebrew cask

Source: https://quobix.com/vacuum/installing

Recommended for macOS. Installs the official signed vacuum release binary via the Homebrew cask. Note: `brew install vacuum` installs the Homebrew core formula, which is not the signed upstream release.

```bash
brew install --cask daveshanley/vacuum/vacuum
```

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

### Bad example: empty message example

Source: https://quobix.com/vacuum/rules/examples/asyncapi-message-examples

Shows an AsyncAPI 3.1.0 message example that defines neither payload nor headers, triggering the violation.

```yaml
asyncapi: 3.1.0
components:
  messages:
    UserCreated:
      examples:
        - name: empty-example

```

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

### vacuum docs common examples

Source: https://quobix.com/vacuum/commands/docs

Common examples of the vacuum docs command: local OpenAPI file, local AsyncAPI file, remote OpenAPI URL, output directory, custom ruleset, preview locally, build for static hosting, generate an API catalog, and use a docs config file.

```bash
vacuum docs ./openapi.yaml
```

```bash
vacuum docs ./events.asyncapi.yaml
```

```bash
vacuum docs https://example.com/openapi.yaml
```

```bash
vacuum docs ./openapi.yaml --output ./public/api-docs
```

```bash
vacuum docs ./openapi.yaml -r ./ruleset.yaml
```

```bash
vacuum docs ./openapi.yaml --serve --port 9090
```

```bash
vacuum docs ./openapi.yaml --publish --base-url https://docs.example.com/api
```

```bash
vacuum docs ./services --output ./api-docs
```

```bash
vacuum docs --docs-config ./printing-press.yaml
```

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

### Example ignore file with exact paths

Source: https://quobix.com/vacuum/ignoring

An example ignore file using exact result paths. Exact paths are checked first, so existing ignore files continue to work as-is.

```yaml
component-description:
  - $.paths['/burgers']
  - $.paths['/burgers/{burgerId}']
  - $.paths['/burgers/{burgerId}/dressings']
  - $.paths['/dressings/{dressingId}']
  - $.paths['/dressings']
paths-kebab-case:
  - $.paths['/burgers/notKebabCase/']
  - $.paths['/NotKebabCase/notKebabCase/']
```

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

### Strict mode error example and reported message

Source: https://quobix.com/vacuum/rules/examples/oas3-valid-schema-example

Schema and example that trigger a strict mode violation. The example includes an undeclared property 'extra', which vacuum reports when strictMode: true. Without strict mode, this example would pass because JSON Schema allows additional properties by default.

```yaml
components:
  schemas:
    Pet:
      type: object
      properties:
        name:
          type: string
      example:
        name: "Buddy"
        extra: "undeclared"  # This property is not in the schema!

```

```text
example contains undeclared property 'extra' at $.components.schemas['Pet'] (declared properties: [name])

```

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

### Chain multiple overlays with vacuum apply-overlay

Source: https://quobix.com/vacuum/commands/apply-overlay

Pipes three vacuum apply-overlay commands to apply overlays in sequence: base.yaml with servers.yaml, then security.yaml, then metadata.yaml, producing final.yaml. Each overlay builds on the previous result, enabling composable transformations.

```bash
vacuum apply-overlay base.yaml servers.yaml -o | \
vacuum apply-overlay -i security.yaml -o | \
vacuum apply-overlay -i metadata.yaml final.yaml
```

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

### Good example: with info.summary

Source: https://quobix.com/vacuum/rules/arazzo/arazzo-info-summary

Shows an Arazzo document with a summary added to the info object, resolving the violation.

```yaml
arazzo: 1.0.1
info:
  title: Read a pet
  version: '1.0'
  summary: Find and read pets.
  description: Workflows for finding and reading pets from the pet store API.

```

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

### Schema with invalid date-time example for formatAssertions

Source: https://quobix.com/vacuum/rules/examples/oas3-valid-schema-example

Example schema that triggers a violation when formatAssertions is enabled. The example value 'nullable datetime' is not a valid date-time, so vacuum reports it. The nullable: true property does not affect format validation.

```yaml
registration_date:
  type: string
  format: date-time
  example: nullable datetime
  nullable: true

```

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

### Good example: workflow with description

Source: https://quobix.com/vacuum/rules/arazzo/arazzo-workflow-description

Shows a workflow with a 'description' field that explains the workflow's purpose. This satisfies the rule.

```yaml
workflows:
  - workflowId: readPet
    description: Retrieve a single pet so it can be shown to a customer.
    steps:
      - stepId: read
        operationId: $sourceDescriptions.api.read

```

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

### Valid operation-success-response example

Source: https://quobix.com/vacuum/rules/operations/operation-success-response

A valid example showing an operation that returns a 2xx success response code.

```yaml
"/pet":
  post:
    responses:
      '200':
        description: New pet was added, great job.

```