extends: spectral:oas
rules:
  # FHIR API path conventions
  fhir-r4-path-prefix:
    description: All FHIR endpoints must use /fhir/r4/ path prefix.
    message: "FHIR endpoint '{{property}}' must start with /fhir/r4/."
    severity: error
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^/fhir/r4/"

  # FHIR resource naming
  fhir-resource-title-case:
    description: FHIR resource segments must use UpperCamelCase (e.g., Patient, ExplanationOfBenefit).
    message: "FHIR resource name in path '{{value}}' must use UpperCamelCase."
    severity: warn
    given: "$.paths[*]~"
    then:
      function: pattern
      functionOptions:
        match: "^/fhir/r4/[A-Z][A-Za-z]+"

  # SMART on FHIR scopes
  fhir-operation-security:
    description: All FHIR operations must define security scopes.
    message: "FHIR operation '{{path}}' must define security requirements."
    severity: error
    given: "$.paths[*][get,post,put,delete]"
    then:
      field: security
      function: defined

  # HL7 FHIR content type
  fhir-accept-header:
    description: FHIR responses should return application/fhir+json content type.
    message: "FHIR response should use 'application/fhir+json' content type."
    severity: warn
    given: "$.paths[*][get].responses[200].content"
    then:
      field: "application/fhir+json"
      function: defined

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

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

  # Tags required on operations
  operation-tags-required:
    description: All operations must have at least one tag.
    message: "Operation at '{{path}}' must have at least one tag."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: defined

  # FHIR search: patient parameter required
  fhir-search-patient-param:
    description: FHIR search operations on clinical resources must support the patient parameter.
    message: "FHIR search operation should support 'patient' query parameter."
    severity: hint
    given: "$.paths[/fhir/r4/Coverage,/fhir/r4/ExplanationOfBenefit,/fhir/r4/Condition,/fhir/r4/Observation,/fhir/r4/MedicationRequest,/fhir/r4/Immunization,/fhir/r4/Encounter].get.parameters[*]"
    then:
      field: name
      function: enumeration
      functionOptions:
        values: [patient, _count, _page, service-date, type, category, status, date]

  # 401 responses required on secured operations
  response-401-required:
    description: Secured operations must define a 401 response.
    message: "Secured operation '{{path}}' must define a 401 Unauthorized response."
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      field: "401"
      function: defined