CNH API Rules

extends:
  - spectral:oas

# Spectral linting rules for CNH FieldOps API.
# Tuned to api.fieldops.cnh.com conventions: HTTPS-only, OAuth 2.0 with
# refresh/access tokens, ISO 15143-3 telemetry profiles (CP/MH), and
# tag-grouped resources for equipment, telemetry, operations,
# prescriptions, farm setup, and webhooks.
rules:
  cnh-info-contact:
    description: API contact information must be present.
    severity: error
    given: "$.info"
    then:
      field: contact
      function: truthy

  cnh-server-https:
    description: All server URLs must use HTTPS.
    severity: error
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "^https://"

  cnh-server-host:
    description: Production server should target api.fieldops.cnh.com or api.cnh.com.
    severity: warn
    given: "$.servers[*].url"
    then:
      function: pattern
      functionOptions:
        match: "(api\\.fieldops\\.cnh\\.com|api\\.cnh\\.com)"

  cnh-oauth-security:
    description: An OAuth 2.0 security scheme must be defined.
    severity: error
    given: "$.components.securitySchemes[*]"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          properties:
            type:
              enum: ["oauth2", "openIdConnect"]

  cnh-operation-id:
    description: Every operation must declare a unique operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  cnh-operation-tags:
    description: Operations 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

  cnh-telemetry-date-range:
    description: Telemetry GET operations must accept startDate and endDate query parameters (one-day window recommended).
    severity: warn
    given: "$.paths[?(@property && @property.indexOf('/telemetry') > -1 || @property.indexOf('/metrics') > -1)].get"
    then:
      field: parameters
      function: schema
      functionOptions:
        schema:
          type: array
          minItems: 1

  cnh-iso15143-profile:
    description: Telemetry endpoints should expose a `profile` parameter restricted to CP or MH.
    severity: info
    given: "$.paths[?(@property && @property.indexOf('/telemetry') > -1)].get.parameters[?(@.name == 'profile')].schema"
    then:
      field: enum
      function: truthy

  cnh-error-401:
    description: Operations should declare 401 Unauthorized response.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].responses"
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          required: ["401"]