extends: spectral:oas
rules:
  # MindSphere uses assetId and aspectName as primary identifiers in paths
  mindsphere-path-params-asset-aspect:
    description: Asset and aspect path parameters should use consistent naming
    message: "Path parameter should be named 'assetId' or 'aspectName' per MindSphere conventions"
    severity: warn
    given: "$.paths[*][*].parameters[?(@.in == 'path')]"
    then:
      field: name
      function: pattern
      functionOptions:
        match: "^(assetId|aspectName|typeId|entityId|tenantId|agentId|fileId|eventId)$"

  # MindSphere APIs use Bearer authentication consistently
  mindsphere-bearer-auth:
    description: MindSphere APIs must use Bearer token authentication
    message: Security scheme should use Bearer token (type: http, scheme: bearer)
    severity: error
    given: "$.components.securitySchemes[*]"
    then:
      field: scheme
      function: enumeration
      functionOptions:
        values:
          - bearer

  # All operations must have operationId
  mindsphere-operation-id-required:
    description: All operations must have an operationId
    message: Operation is missing an operationId
    severity: error
    given: "$.paths[*][get,post,put,delete,patch]"
    then:
      field: operationId
      function: truthy

  # Time series data must include _time field documentation
  mindsphere-timeseries-time-field:
    description: Time series schemas should document the _time field
    message: Timeseries data schema should include _time field for timestamp
    severity: warn
    given: "$.components.schemas[?(@.properties._time)]"
    then:
      field: properties._time
      function: truthy

  # Pagination parameters should use from/size pattern
  mindsphere-pagination-from-size:
    description: MindSphere uses from/size pagination parameters
    message: Pagination should use 'from' and 'size' query parameters
    severity: hint
    given: "$.paths[*].get.parameters[?(@.in == 'query')]"
    then:
      field: name
      function: pattern
      functionOptions:
        match: "^(from|size|page|limit|sort|filter|ifModifiedSince)$"

  # Error responses must be defined for 4xx status codes
  mindsphere-error-responses:
    description: Operations should define error response schemas
    message: Operation should define 400 and 401 error responses
    severity: warn
    given: "$.paths[*][get,post,put,delete,patch].responses"
    then:
      field: "401"
      function: truthy

  # All operations must have a summary
  mindsphere-operation-summary-required:
    description: All operations must have a summary
    message: Operation is missing a summary
    severity: error
    given: "$.paths[*][*]"
    then:
      field: summary
      function: truthy

  # MindSphere uses EU1/US1/JP1 regional base URLs
  mindsphere-regional-base-url:
    description: MindSphere API base URLs should use regional gateway pattern
    message: "Server URL should match MindSphere regional gateway pattern (gateway.{region}.mindsphere.io)"
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://gateway\\.(eu1|us1|jp1)\\.mindsphere\\.io"