OpenAPI Specification Linting Service

Overview

The Specification Linting Service (SpecLintService) is an automated quality analysis tool that assesses OpenAPI v3 specifications. It identifies and reports on stylistic and quality issues that, while not violations of the OpenAPI Specification (OAS) 3.0 standard, can degrade the quality and usability of the published API contract for consumers.

This service acts as a secondary quality gate. It runs after the primary structural conformance check, which already enforces strict OAS 3.0 compliance and fails builds for definitive violations like broken references or duplicate operationIds. The linting service targets more subtle issues such as missing descriptions, untyped schema properties, and deviations from naming conventions.

The service is invoked during the specification generation and activation process. It takes an OpenAPI artifact as input, performs the linting analysis, calculates a quality score, and persists the results. It is designed to be "fail-soft," meaning any failure during the linting or persistence process is logged and does not block the overall spec generation or activation workflow.

How it works

The core logic resides in the lintAndStore method, which orchestrates the analysis and persistence of linting results for a given OpenAPI artifact.

flowchart TD
    subgraph Spec Generation/Activation Process
        A[OpenAPI Artifact Generated] --> B{Call SpecLintService.lintAndStore};
    end

    subgraph SpecLintService
        B --> C{Parse OpenAPI JSON};
        C -- Fails --> D[Create 'unparseable-document' finding];
        C -- Succeeds --> E{Traverse spec};
        E --> F[Apply linting rules];
        F --> G[Generate list of findings];
        G --> H{Calculate score};
        H --> I[Construct SpecLintResult];
        I --> J{Persist result via upsert};
    end

    subgraph Handling
        J -- Success --> K[Return SpecLintResult];
        J -- Fails --> L[Log warning, return null];
        D --> H;
    end

    A --> M((Database));
    K --> M;

The process follows these steps:

1. Invocation: The lintAndStore method is called with an OpenApiArtifactRecord, which contains the OpenAPI specification as a JSON string.
2. Parsing: The service first attempts to parse the JSON string. If the document is not well-formed JSON, it generates a single unparseable-document finding and proceeds to scoring.
3. Traversal and Analysis: If parsing succeeds, the service traverses the entire OpenAPI document structure, including paths, operations, parameters, and component schemas. During traversal, it applies a defined set of linting rules.
4. Finding Generation: For each rule violation, a SpecLintFinding object is created. This object captures the rule ID, severity, a JSON Path-like location of the issue in the document, and a descriptive message.
5. Scoring: After all findings are collected, a quality score is calculated. The score starts at 100, and points are subtracted for each finding based on its severity. The final score is floored at 0.
6. Persistence: A SpecLintResult object is created, containing the final score, counts of findings by severity, and the complete list of individual findings. This result is then persisted to the database via an upsert operation.
7. Fail-Soft Operation: The entire process within lintAndStore is wrapped in an exception handler. If any RuntimeException occurs during linting or persistence, the error is logged, and the method returns null. This ensures that a linting failure never blocks the parent spec generation or activation process.

Scoring Mechanism

The quality score provides a quantitative measure of the specification's adherence to quality standards.

• Base Score: 100
• Penalties:
  • error: -10 points per finding
  • warning: -3 points per finding
  • info: -1 point per finding
• Final Score: The total penalty is subtracted from the base score. The minimum possible score is 0.

Linting Rules

The service applies the following rules during analysis. Each finding includes a stable ruleId for programmatic use.

Data Models

The service produces and persists data according to the following models.

SpecLintResult

This object represents the complete result of a linting operation for a single artifact.

SpecLintFinding

This object represents a single quality issue found in the specification.

Troubleshooting

Fail-Soft Behavior

The SpecLintService is explicitly designed to never block specification generation or activation. If an unexpected error occurs during its execution, the lintAndStore method will:

1. Log a warning with details about the failure.
2. Return null to its caller.

The calling process will continue, meaning the specification will still be generated and activated, but no linting result will be persisted for that version.

Common Findings

• unparseable-document: This error finding indicates that the input to the linter was not valid JSON. This is a fundamental issue that prevents any further analysis.
• example-violates-schema: This error finding is critical. It means an example in the specification is invalid according to the schema it is supposed to illustrate. API consumers who copy and use this example in their requests will likely receive validation errors from the API gateway, leading to a poor developer experience.

See Also

• The linting service complements the primary conformance validation performed by OpenApiService.enforceConformantOas30, which handles strict OAS 3.0 compliance.
• The linting rules are registered and defined in more detail in internal design documentation (docs/lld/naming-and-standards.md).

All SOAP-to-REST docs