spec.yaml

extends: spectral:oas

rules:
  info-contact: off
  operation-operationId: off

  api-root:
    description: API SHOULD have a root path defined (`/`)
    recommended: true
    severity: warn
    given: $.paths
    then:
      field: /
      function: truthy
 
  api-root-get:
    description: Root path MUST have a GET defined, otherwise people won't know how to get it
    recommended: true
    severity: error
    given: $.paths[/]
    then:
      field: get
      function: truthy

  paths-kebab-case:
    description: Paths MUST be kebab-case
    recommended: true
    message: '{{property}} should be kebab-case'
    severity: error
    given: $.paths[*]~
    then:
      function: pattern
      functionOptions:
        match: "^\/([a-z0-9]+(-[a-z0-9]+)*)?(\/[a-z0-9]+(-[a-z0-9]+)*|\/{.+})*$"

  path-parameters-camelCase:
    description: Path parameters MUST be camelCase
    recommended: true
    severity: error
    message: "{{property}} path parameter is not camelCase: {{error}}"
    given: $..parameters[?(@.in == 'path')].name
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  operation-summary: 
    description: Operation summary MUST exist
    recommended: true
    severity: error
    given: $.paths.*[*]
    then:
      - field: summary
        function: truthy

  operation-short-summary: 
    description: Operation summary SHOULD be short and sweet, no full stops, less than 30 characters
    recommended: true
    severity: warn
    given: $.paths.*[*]
    then:
      - field: summary
        function: pattern
        functionOptions:
          notMatch: '\\.'
      - field: summary
        function: length
        functionOptions:
          max: 30

  schema-names-pascal-case:
    description: Schema names MUST be written in PascalCase
    recommended: true
    message: '{{property}} is not PascalCase: {{error}}'
    given: '$.components.schemas.*~'
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][a-zA-Z0-9]*$'

  semver:
    description: API version MUST follow semantic versioning
    recommended: true
    severity: error
    message: 'Please follow semantic versioning. {{value}} is not a valid version.'
    given: $.info.version
    then:
      function: pattern
      functionOptions:
        match: '^([0-9]+.[0-9]+.[0-9]+)$'

  no-x-headers:
    description: Header MUST not be prefixed wit X- (https://tools.ietf.org/html/rfc6648)
    recommended: true
    severity: warn
    message: "Headers MUST not be prefixed with X-. Please find a new name for {{property}}"
    given: $..parameters.[?(@.in === 'header')].name
    then:
      function: pattern
      functionOptions:
        notMatch: '^(x|X)-'

  headers-hyphenated-pascal-case:
    description: All HTTP headers MUST use Hyphenated-Pascal-Case notation
    recommended: true
    severity: error
    message: "'HTTP' headers MUST follow 'Hyphenated-Pascal-Case' notation"
    given: $..parameters[?(@.in == 'header')].name
    then: 
      function: pattern
      functionOptions:
        match: '/^([A-Z][a-z0-9]-)*([A-Z][a-z0-9])+/'

  request-get-no-body:
    description: A GET request MUST NOT accept a body parameter
    recommended: true
    severity: error
    given: $.paths..get.parameters..in
    then:
      function: pattern
      functionOptions:
        notMatch: '/^body$/'

  request-support-json:
    description: Every request MUST support `application/json` media type
    recommended: true
    severity: error
    message: "{{description}}: {{error}}"
    given: $.paths.[*].requestBody.content[?(@property.indexOf('json') === -1)]^
    then:
      function: falsy
  
  response-success-media-type:
    description: All success responses MUST be of media type `application/hal+json` or `application/json`
    recommended: true
    severity: error
    message: "Response documents MUST be of application/hal+json or application/json media types: {{error}}"
    given: $.paths..responses[?( @property == 200 )].content[*]~
    then:
      function: enumeration
      functionOptions:
        values:
          - application/json
          - application/hal+json