If you haven't written a custom ruleset, never used a config and use Spectral via CLI only, it's very likely you are unaffected by any of the breaking changes we introduced, therefore you might upgrade your Spectral version right away. Our docs have been updated, so you can always refer to them, but to make the transition less painful, this migration guide covers the most notable changes.
Note, 3.0 version was a bit of a transition-version, without any significant changes, besides the config file we removed in 4.0. That said, the following migration is kind of 2.x/3.x to 4.x.
- summary property is gone
We introduced a more powerful message property. It not only lets you define a static message, but also lets you compose them.
If you want to have error from function printed, you can do so as follows
message: '{{error}}'Printing description is equally straighforward:
message: '{{description}}'If you want a property key to be printed instead...
message: '{{property}}'Bear in mind, property might be an empty string. You can also compose a fancier message if you'd like to.
message: 'Errored at {{property}}... Error message is: {{error}}'Let us know if there is any shorthand you'd like to see.
A real-world example of the migration can be found here stoplightio/spectral#367
- jsonpath is swapped with jsonpath-plus
There shouldn't be any significant differencies, but jsonpath-plus does come with its own syntax for special selectors. Please refer to their docs for the comprehensive list. https://github.com/s3u/JSONPath#features You can also take a look at changes we had to make internally https://github.com/stoplightio/spectral/pull/347/commits/c79691da636f76c5b0ab5c611779d6be16d32292
- Config is gone...
...here is no way to restore it. Since 4.0 on, you need to pass the flag manually via CLI. This change shouldn't hurt you much, as CLI support all flags config did, so no functionality will be missing.
- --max-results flag is removed
We don't provide a replacement either.
- Import paths have changed.
In 4.0 we significantly cahnged our release process, therefore, as a side affect, the project structure we submit to NPM is a bit different. You need to rewrite imports as follows,
const { oas3Functions, rules: oas3Rules } = require('@stoplight/spectral/rulesets/oas3');to
const { oas3Functions, rules: oas3Rules } = require('@stoplight/spectral/dist/rulesets/oas3');Note, the dist in between. This is the only difference. You'll need to apply the change to all other imports accordingly.
In future, we will simplify rulesets loading even further, so you won't need any of that.
More on that can be found here stoplightio/spectral#366
- json-ref-resolver has been updated
If you ever provided a custom resolver, you might need to bump json-ref-resolver package to reflect the potential changes in interfaces we introduced.
As always, suggest updating @stoplight/yaml and @stoplight/json if you happened to use them.