Diagnostics

Every build analyzes your OpenAPI document and your SDK configuration together, before a single file is generated, and reports everything the generator had to skip, guess, or degrade. Each finding is graded, and you decide which grades fail the build.

A successful build tells you the SDK compiled. It does not tell you the SDK is complete. Generation is forgiving by design: an operation no resource places is simply absent, a schema with no properties lowers to an untyped value, a pagination scheme nothing references is dead configuration. Each of those produces a perfectly valid SDK that is quietly missing something you meant to ship, and diagnostics are how you find out.

How it works

Diagnostics run as part of every build, after the document and configuration are loaded and compiled, and before any target is emitted.

The full report is part of the build output, whether the build passed the gate or failed it, so it is there in the build logs to read either way.

Two properties are worth knowing about, because they decide how much a finding can be trusted:

• Most findings are facts, not guesses. The loader, the configuration coercion, and the compiler report what they actually did. A Config/StaleEndpoint finding is not a second opinion about your configuration — it is the compiler saying that it skipped the method.
• Rules and generation share one implementation. Where a rule has to work something out for itself — the name a model would be generated under, whether a response media type can be decoded, which resource a schema belongs to — it calls the same helpers generation calls. A finding cannot drift away from what the generator actually does, because there is only one answer for both of them to read.

A rule that crashes never takes your build down with it. The engine isolates each rule, skips the one that failed, and records it as Internal/RuleCrash.

Anatomy of a finding

Every finding carries the same fields, whichever rule produced it:

Rendered, one finding reads like this:

[WARN] Config/StaleEndpoint  Config:63  Configured endpoint "get /v1/cards/{card_token}" has no matching operation in the document; the method is skipped.

Severity and the build gate

There are three severities, and the defaults follow a single rule: only conditions that stop generation outright are graded error. Everything else — every condition that used to pass silently — starts at warn or info, so the analysis never turns a healthy build red on its own. Exactly three rules default to error: Config/ParseError, Document/ReferenceError, and Pagination/UnknownScheme.

The gate itself lives in the diagnostics block of your SDK configuration:

{
  "diagnostics": {
    "failOn": "error",
    "maxWarnings": 20,
    "rules": {
      "Endpoint/NotConfigured": "warn",
      "Schema/EnumHasOneMember": "off"
    }
  }
}

• failOn is the lowest severity that fails the build, and defaults to error. Set it to warn to hold the build to a stricter standard, or to off to report without ever failing.
• maxWarnings and maxErrors are checked independently of failOn, so you can let warnings through while capping how many of them accumulate. Exceeding either one fails the build.
• rules re-grades a rule by code. off disables it entirely, so it neither reports nor counts toward the gate.

Overrides and suppressions are applied before the gate is evaluated, so a rule you graded down or a finding you suppressed cannot fail a build.

Provenance: whose file holds the fix

Each rule declares which document a finding is a critique of, which is what separates "fix your API description" from "fix your configuration":

The configuration Scalar generates for you is meant to report no config findings on its first build: the configuration generator applies the same rules the analyzer checks. Findings with document provenance legitimately survive a first build, because no configuration can invent what the description does not say.

Suppressing a finding

Sometimes a finding is correct and the situation is still intentional — an endpoint that is deliberately not in the SDK, an example that shows a failing request on purpose. Use diagnostics.ignored to record that intent, keyed by rule code:

{
  "diagnostics": {
    "ignored": {
      "Schema/EnumHasOneMember": true,
      "Endpoint/NotConfigured": "get /internal/*",
      "Model/Recommended": [
        { "location": "ApiError", "reason": "expanded inline on purpose" },
        { "target": "go", "reason": "not shipped for Go yet" }
      ]
    }
  }
}

• true suppresses the rule everywhere. Prefer a narrower form when you can, so a new occurrence still gets reported.
• A string matches the finding's suppression key, exactly or with * as a wildcard.
• An entry list mixes location matches (the same key grammar) with target matches, and each entry can carry a reason that stays with the suppression.

Suppressing is not the same as disabling. A suppressed finding is still produced and still recorded — it just does not count toward the gate — whereas "rules": { "...": "off" } stops the rule from running at all.

Every rule's suppression key is listed alongside it below.

What we check

Configuration and endpoints

Document and references

Schemas and models

Responses, pagination, and security

README examples

The generated README is code that has to compile, so its configured examples are checked against the methods actually generated.

Runtime support and generator health

AsyncAPI

An AsyncAPI build reports its own rule families — unsupported protocols and schema formats, unconfigured channels, and specification features that are read but not yet generated for. The rules that only fire on an AsyncAPI document are listed on the AsyncAPI page, and they are graded and suppressed exactly like the rules above.

Rules that read an OpenAPI shape do not run on an AsyncAPI document, so an AsyncAPI build is quieter than an OpenAPI one about the same underlying problem.

Next steps

• Configuration — the diagnostics block reference
• Managing your SDK — where build output and logs live
• AsyncAPI — the AsyncAPI rule family