DOCSEARCHbyAlgolia
Submit Docs

IBM OpenAPI Validator

repository·main·Indexed 20 days ago

https://github.com/ibm/openapi-validator

A tool for validating OpenAPI 3.0.x and 3.1.x documents against official specifications and IBM-defined best practices. It supports Spectral rulesets, provides a CLI via the lint-openapi command, and includes the @ibm-cloud/openapi-ruleset for IBM Cloud API design requirements. The validator can be installed via NPM, as a platform-specific binary, or run as a Docker container.

Tokens
48K
Snippets
136
Records
183
Agent score
69%

What's inside ibm-openapi-validator

  1. What is the OpenAPI Ruleset?

    main
    The @ibm-cloud/openapi-ruleset package provides a custom Spectral ruleset designed for validating OpenAPI documents. It extends the standard spectral:oas ruleset by introducing custom severity levels and additional rules based on IBM Cloud API design requirements and guidance. This ruleset serves as the default validation logic used in the ibm-openapi-validator package.

  2. Enable the ibm-property-consistent-name-and-type rule

    main

    The ibm-property-consistent-name-and-type rule ensures that like-named schema properties (across different schemas) use the same data type to maintain consistency.

    Note: This rule is disabled by default (severity: off). You must explicitly enable it in your Spectral configuration file to use it.

  3. Understand the IBM Cloud Validation Ruleset composition

    main

    The IBM Cloud Validation Ruleset, provided via the @ibm-cloud/openapi-ruleset package, is composed of two main parts:

    1. IBM Cloud validation rules: A custom collection of rules designed to implement and enforce best practices defined in the IBM Cloud API Handbook.
    2. Spectral's spectral:oas ruleset: The IBM Cloud ruleset extends the standard Spectral OpenAPI ruleset. This means all rules from spectral:oas are available when using the @ibm-cloud/openapi-ruleset package.

  4. Understand v1.x Validator Output changes

    main

    The validator output has been updated in v1.x:

    Text Output

    Text output is largely similar to v0.x, but the summary section is now always included by default. To output only the summary and suppress individual validation messages, use the -s or --summary-only flag.

    JSON Output

    The JSON structure has changed. The new schema is defined in packages/validator/src/schemas/results-object.yaml.

    Unlike v0.x, the v1.x validator now honors the following flags when producing JSON output:

    • --errors-only
    • --summary-only

    Important: When using --json mode, you must only provide a single file argument to ensure the output is a single, valid JSON object.

  5. How the ruleset selection works

    main

    The validator uses Spectral rulesets. By default, it looks for standard Spectral ruleset files (.spectral.yaml, .spectral.yml, .spectral.json, or .spectral.js) in the current working directory and its parents.

    If no Spectral files are found, it defaults to the IBM Cloud Validation Ruleset. To force the use of the IBM Cloud Validation Ruleset even if Spectral files are present, set ruleset to "default" in your configuration or use the -r default CLI flag.

  6. Security considerations for using the OpenAPI Validator

    main

    The OpenAPI Validator is designed as a local CLI utility for trusted API definitions. It is not intended to be deployed as a service that validates untrusted external input due to the following risks:

    • Parser attack surface: Maliciously crafted YAML/JSON or $ref structures can exploit parser vulnerabilities, cause DoS via circular references, or attempt path traversal.
    • Resource exhaustion: Large or pathological documents can consume excessive CPU and memory.
    • Untrusted ruleset execution: Custom rulesets are JavaScript modules; if an attacker can influence the ruleset path, they can achieve arbitrary code execution.

    If you must validate untrusted documents in a service, you must:

    1. Run the validator in an isolated sandbox (e.g., a container with no network access and strict resource limits).
    2. Validate and limit the size and structure of inputs before passing them to the validator.
    3. Ensure untrusted input cannot influence ruleset or configuration paths.

  7. How rulesets work in the OpenAPI Validator

    main

    The validator uses rulesets to determine what to check in your OpenAPI documents. It supports OpenAPI 3.0.x and 3.1.x and can use standard Spectral rulesets.

    Ruleset Selection Logic:

    1. Automatic Detection: If the validator detects a standard Spectral ruleset file (.spectral.yaml, .spectral.yml, .spectral.json, or .spectral.js) in the current directory or any parent directory, it will use that file.
    2. Default Ruleset: By default, the validator uses the IBM Cloud Validation Ruleset (provided via the @ibm-cloud/openapi-ruleset npm package).
    3. Explicit Specification: You can force the use of a specific ruleset using the -r/--ruleset option or the ruleset configuration property.

    Common Scenarios:

    • Use a custom file: Specify the path to your ruleset using --ruleset <path>.
    • Force IBM Cloud Ruleset: If a Spectral file is present but you want to ignore it and use the IBM defaults, use --ruleset default.

  8. Generate API impact scores and Markdown reports

    main

    The validator can compute API impact scores based on usability, security, robustness, and cost of evolution using the --impact-score (-q) flag.

    Additionally, you can use --markdown-report (-m) to generate a Markdown file containing all results, including individual violations, impact scores, and the data used for calculations. The filename is derived from the API definition file name and will overwrite existing files by default.

  9. Use the new v1.x unified configuration file

    main

    In v1.x, the separate .thresholdrc and .validaterc files are replaced by a single, consistent configuration file.

    Key features:

    • Format Support: Supports JSON, YAML, and JavaScript formats.
    • Unified Interface: Every command-line option is also available as a field within the configuration file.
    • Precedence: Options specified on the command line take precedence over options defined in the configuration file.

    To specify a custom configuration file name, use the -c or --config flag.

  10. Migrate from v0.x to v1.x

    main

    When migrating from the v0.x pre-release to the v1.x official release of the IBM OpenAPI Validator, note the following breaking changes:

    • Node.js Requirement: The minimum supported version is now Node.js 16.x (upgraded from 14.x).
    • OpenAPI Support: The v1.x validator supports only OpenAPI 3.0.x documents. Support for Swagger 2.x has been removed.
    • Configuration Files: The .thresholdrc and .validaterc files are no longer supported. Use the new unified configuration file format (JSON, YAML, or JavaScript).
    • Programmatic API: The direct v0.x JavaScript API is no longer supported. To invoke the validator programmatically, use the Spectral programmatic API.
    • CLI Delimiters: Multi-word options now use dashes (-) instead of underscores (_). For example, --errors_only must be changed to --errors-only.

  11. Extend the ruleset in a YAML or JSON Spectral config file

    main

    To use the IBM OpenAPI ruleset in a standard .spectral.yaml or .spectral.json file, use the extends keyword. No manual installation of the package is required for this method.

    # .spectral.yaml
extends: '@ibm-cloud/openapi-ruleset'
rules:
  content-entry-provided: off

  12. Build platform-specific binaries from source

    main

    You can generate platform-specific binaries (lint-openapi-macos, lint-openapi-linux, and lint-openapi-windows.exe) by running the pkg script in the project root. The resulting binaries will be located in packages/validator/bin.

    npm run pkg