Skip to content

Latest commit

 

History

History
121 lines (81 loc) · 3.7 KB

6.0.md

File metadata and controls

121 lines (81 loc) · 3.7 KB

Spectral v5 to v6 Migration Guide

General

  1. Spectral has become a monorepo and CLI <-> Core have been split into separate packages. If you intend to use a CLI version of Spectral make sure to install @stoplight/spectral-cli. Otherwise, go with @stoplight/spectral-core which is the JS API.
  2. No ruleset is loaded by default. If you don't supply a ruleset, Spectral refuses to lint the document. If you use CLI, make sure to have a valid ruleset in your project or use a --ruleset flag. JS API has a method called setRuleset which can be used to set the relevant ruleset.
  3. Spectral is stricter overall and certain soft errors that previously were marked as warnings have changed to errors.

Core

  1. run doesn't accept { documentUri }. Use Document and specify the source of the document there.

Workaround:

import { Document, Spectral } from "@stoplight/spectral-core";
import { Json as JsonParser } from "@stoplight/spectral-parsers";
import * as path from "@stoplight/path";

const s = new Spectral();

const doc = new Document(
  `{
  "street": null
}`,
  JsonParser,
  path.join(__dirname, "street-doc.json"),
);

await spectral.run(doc);
  1. Spectral constructor takes no proxyUri.
import { Document, Spectral } from "@stoplight/spectral-core";
import { Json as JsonParser } from "@stoplight/spectral-parsers";
import * as path from "@stoplight/path";

const s = new Spectral();

const doc = new Document(
  `{
  "street": null
}`,
  JsonParser,
  path.join(__dirname, "street-doc.json"),
);

await spectral.run(doc);

The workaround here can look as follows

import { Spectral } from "@stoplight/spectral-core";
import { createHttpAndFileResolver } from "@stoplight/spectral-ref-resolver";
import ProxyAgent from "proxy-agent";

const spectral = new Spectral({
  resolver: createHttpAndFileResolver({ agent: new ProxyAgent(process.env.PROXY) }),
});

Functions

  1. schema function uses Ajv v8 in favor of Ajv v6. It's preferred to provide JSON Schema Draft 7 schemas or newer, albeit older drafts are also supported via json-schema-migrate. oasVersion is no longer supported. Use the oasSchema function from the OAS ruleset if you want to supply an OAS Schema Object.
  2. schemaPath is no longer available. If you happened to use this function, you can write a custom function that implements the same functionality.

CLI

  1. deprecated --show-unmatched-globs flag has been removed. Alternative available: --fail-on-unmatched-globs
  2. --skip-rule has been removed. Use a custom ruleset instead - set the severity of a particular rule to "off".

Rulesets

OAS

Changed

  • oas2-valid-parameter-example & oas2-valid-definition-example & oas2-valid-response-schema-example into oas2-valid-schema-example.

Change: merge

  • oas2-valid-response-example -> oas2-valid-media-example

Change: rename

  • Merged oas3-valid-parameter-schema-example & oas3-valid-header-schema-example & oas3-valid-schema-example into oas3-valid-schema-example

Change: merge

  • Merged oas3-valid-oas-parameter-example & oas3-valid-oas-header-example & oas3-valid-oas-content-example oas3-valid-media-example

Change: merge

  • operation-2xx-response -> operation-success-response

Change: 3xx response is accepted as well.

  • oas3-unused-components-schema -> oas3-unused-component

Change: all reusable components are now validated.

Removed

  • operation-default-response

Workaround: Insert the following rule in your custom ruleset.

 "operation-default-response": {
  "description": "Operations must have a default response.",
  "recommended": false,
  "given": "$.paths.*.*.responses",
  "then": {
    "field": "default",
    "function": "truthy"
  }
},