Spectral rules missing description

I’m noticing that some Spectral rules that were added recently are missing a ‘description’ field but instead have a ‘summary’ field.

Is this a bug or is this to be expected? An example rule would be the oas3 rule “valid-schema-example-in-content”:

    "valid-schema-example-in-content": {
      "summary": "Examples must be valid against their defined schema.",
      "message": "{{error}}",
      "severity": 0,
      "recommended": true,
      "type": "validation",
      "given": "$..content..[?(@property !== 'properties' && @.example && (@.type || @.format || @.$ref))]",
      "then": {
        "function": "schemaPath",
        "functionOptions": {
          "field": "example",
          "schemaPath": "$"

Hi @roy.jacobs, the description field was deprecated with Spectral v4. You can find more information on this here.

Hi Ross, the page you linked to doesn’t seem to say anything of the sort? It only says the summary property is gone.

In fact, all rules in Spectral 4.0.3 had a description field, it’s only in rules introduced somewhere between 4.0.3 and 4.2.0 that suddenly don’t contain a description anymore.

@rjacobs My mistake, you’re right. description is the correct field to use, and it looks like summary is silently ignored. I’ll open an issue with the team to have that corrected. Apologies for the confusion!

The rule definitions have now been updated to use description instead of summary. Thanks for the heads up!

1 Like