target API Rules

rules:
  target-operation-ids-camel-case:
    description: Operation IDs must use camelCase
    message: "operationId '{{value}}' must use camelCase"
    severity: warn
    given: "$.paths[*][*].operationId"
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]*$"

  target-tags-title-case:
    description: Tags must use Title Case
    message: "Tag '{{value}}' must use Title Case"
    severity: warn
    given: "$.tags[*].name"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ]*$"

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

  target-paths-versioned:
    description: All paths must include a version prefix (e.g., /v1/, /v3/)
    message: "Path '{{value}}' must include a version prefix like /v1/ or /v3/"
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^/[a-z]+/v[0-9]+"

  target-operation-summary-exists:
    description: All operations must have a summary
    message: "Operation at '{{path}}' is missing a summary"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  target-operation-description-exists:
    description: All operations must have a description
    message: "Operation at '{{path}}' is missing a description"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  target-responses-200-exists:
    description: All operations must have a 200 response
    message: "Operation at '{{path}}' must define a 200 response"
    severity: error
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: "200"
      function: truthy

  target-responses-401-exists:
    description: Secured operations must document 401 response
    message: "Operation at '{{path}}' should define a 401 response"
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: "401"
      function: truthy

  target-parameters-description:
    description: All parameters must have descriptions
    message: "Parameter '{{value}}' is missing a description"
    severity: warn
    given: "$.paths[*][*].parameters[*]"
    then:
      field: description
      function: truthy

  target-bearer-auth-defined:
    description: bearerAuth security scheme must be defined
    message: "bearerAuth security scheme must be defined in components.securitySchemes"
    severity: error
    given: "$.components.securitySchemes"
    then:
      field: bearerAuth
      function: truthy

  target-info-contact:
    description: API must include contact information
    message: "API info must include contact details"
    severity: warn
    given: "$.info"
    then:
      field: contact
      function: truthy

  target-schema-properties-described:
    description: Schema properties should have descriptions
    message: "Schema property at '{{path}}' should have a description"
    severity: info
    given: "$.components.schemas[*].properties[*]"
    then:
      field: description
      function: truthy