When integrating oasdiff into a CI pipeline for API compatibility checks, the first attempt was to document the severity-levels file with a comment
When integrating oasdiff into a CI pipeline for API compatibility checks, the first attempt was to document the severity-levels file with a comment header. The file was created with # oasdiff --severity-levels for… at line 1, then passed to oasdiff's --severity-levels flag. oasdiff exits with code 106 and reports Error: failed to load custom severity levels from … invalid line #1, suggesting a syntax error on the first line itself. The actual problem is that oasdiff's JSON parser sees the # character and cannot parse the file as JSON, but the error message attributes the failure to "line #1" rather than identifying it as a JSON parse issue.
The severity-levels file must contain only valid JSON: a bare JSON array (or object, depending on oasdiff version). Comments are not supported. Strip any comment headers and keep the file as pure JSON. The file is typically small (one array of severity level IDs) and documentation belongs elsewhere — in the build script or a separate markdown file that explains its purpose. Oasdiff 1.18.6 will accept the file only if it starts with [ and is valid JSON throughout.