Restream API Rules

extends: spectral:oas
rules:
  restream-operation-id-required:
    description: All operations must have an operationId for SDK and documentation generation.
    message: "Operation must have an operationId"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  restream-operation-summary-required:
    description: All operations must have a summary for developer experience.
    message: "Operation must have a summary"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  restream-summary-title-case:
    description: Operation summaries must use Title Case per Restream API style.
    message: "Summary must use Title Case: '{{value}}'"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-z]*(\\s[A-Z][a-z]*)*$"

  restream-tags-required:
    description: All operations must be tagged for grouping in the developer portal.
    message: "Operation must have at least one tag"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  restream-oauth2-scopes-documented:
    description: OAuth2-secured operations must declare required scopes.
    message: "OAuth2-secured operation must declare scopes"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].security[*].OAuth2"
    then:
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  restream-response-200-required:
    description: All operations must define a 200/201 success response.
    message: "Operation must have a success response (200 or 201)"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          anyOf:
            - required: ["200"]
            - required: ["201"]

  restream-path-kebab-case:
    description: API paths must use kebab-case for multi-word segments.
    message: "Path segment must use kebab-case: '{{value}}'"
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}-]+((/[a-z0-9{}-]+)*)?)$"

  restream-v2-prefix:
    description: All paths must be prefixed with /v2 or use the OAuth token path.
    message: "Path must begin with /v2 or /oauth"
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^/(v2|oauth)/"