Confluent Schema Registry API Rules

extends:
  - spectral:oas

# Spectral linting rules tuned for Confluent Schema Registry.
# Validates that the OpenAPI spec follows Schema Registry conventions:
# resource paths under /subjects, /schemas, /config, /mode, /compatibility,
# JSON content types, and consistent use of the Subjects/Schemas/Config tags.
rules:
  schema-registry-info-contact:
    description: API contact information must be present.
    severity: error
    given: "$.info"
    then:
      field: contact
      function: truthy

  schema-registry-info-license:
    description: API license must be declared.
    severity: error
    given: "$.info"
    then:
      field: license
      function: truthy

  schema-registry-server-defined:
    description: At least one server URL must be defined.
    severity: error
    given: "$.servers"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  schema-registry-paths-prefix:
    description: All paths must live under /subjects, /schemas, /config, /mode, /compatibility, /contexts, or /exporters.
    severity: warn
    given: "$.paths"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^/(subjects|schemas|config|mode|compatibility|contexts|exporters)(/.*)?$"

  schema-registry-operation-id:
    description: Every operation must define an operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  schema-registry-operation-tags:
    description: Every operation must declare at least one tag.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  schema-registry-tag-vocabulary:
    description: Tags must come from the Schema Registry vocabulary (Subjects, Schemas, Config, Mode, Compatibility, Contexts, Exporters).
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].tags[*]"
    then:
      function: enumeration
      functionOptions:
        values:
          - Subjects
          - Schemas
          - Config
          - Mode
          - Compatibility
          - Contexts
          - Exporters

  schema-registry-error-shape:
    description: Non-2xx responses should reference the ErrorMessage schema.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses[?(@property.match(/^[45][0-9][0-9]$/))].content.application/json.schema"
    then:
      field: $ref
      function: pattern
      functionOptions:
        match: "ErrorMessage"

  schema-registry-content-type:
    description: 2xx responses should serve application/json (or application/vnd.schemaregistry.v1+json).
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses[?(@property == '200' || @property == '201')].content"
    then:
      field: "@key"
      function: pattern
      functionOptions:
        match: "^application/(vnd\\.schemaregistry\\.v1\\+json|json)$"

  schema-registry-compatibility-enum:
    description: Compatibility levels should use canonical values.
    severity: warn
    given: "$.components.schemas.Config.properties.compatibility"
    then:
      field: enum
      function: schema
      functionOptions:
        schema:
          type: array
          contains:
            enum:
              - NONE
              - BACKWARD
              - BACKWARD_TRANSITIVE
              - FORWARD
              - FORWARD_TRANSITIVE
              - FULL
              - FULL_TRANSITIVE