Extending rules using SPectral

Question

I am following Spectral's documentation and I am trying to add my custom rule as an extension to oas3 ruleset, it looks like rule from the documentation is completely ignored.

My OpenApi 3.0 spec file:

openapi: 3.0.2
info:
  title: Project info
  description: |
    Project description
  contact:
    name: Test Testable
    email: [email protected]
  version: 1.0.0
servers:
- url: http://localhost:8080
tags:
- name: test-tag
paths:
  /test:
    get:
      tags:
      - test-tag
      summary: Some summary
      operationId: operationId
      description: Operation description
      responses:
        200:
          description: OKK

My .spectral.yml file:

extends: spectral:oas3
rules:
  my-rule-name:
    description: Tags must have a description.
    given: $.tags[*]
    then:
      field: description
      function: truthy

My API spec contains tags but the tag which is there doesn't have any description so it should fail but it doesn't:

>spectral lint api.yml

OpenAPI 3.x detected
No errors or warnings found!

Even if I try to change to function: falsy which I expect it should fail in one of these 2 cases - still no warnings and no errors. It looks like this rule is just not applied at all.

Answer 1

I found it. There is a field recommended: true needed in rule definition. Documentation mentions it but somehow too briefly:

Updated .spectral.yml:

extends: spectral:oas3
rules:
  my-rule-name:
    description: Tags must have a description.
    given: $.tags[*]
    recommended: true
    then:
      field: description
      function: truthy

and output:

13:3  warning  my-rule-name  Tags must have a description.

✖ 1 problem (0 errors, 1 warning, 0 infos)