CNH · API Governance Rules

CNH API Rules

Spectral linting rules defining API design standards and conventions for CNH.

9 Rules error 4 warn 4 info 1
View Rules File View on GitHub

Rule Categories

cnh

Rules

error
cnh-info-contact
API contact information must be present.
$.info
error
cnh-server-https
All server URLs must use HTTPS.
$.servers[*].url
warn
cnh-server-host
Production server should target api.fieldops.cnh.com or api.cnh.com.
$.servers[*].url
error
cnh-oauth-security
An OAuth 2.0 security scheme must be defined.
$.components.securitySchemes[*]
error
cnh-operation-id
Every operation must declare a unique operationId.
$.paths[*][get,post,put,patch,delete]
warn
cnh-operation-tags
Operations must declare at least one tag.
$.paths[*][get,post,put,patch,delete]
warn
cnh-telemetry-date-range
Telemetry GET operations must accept startDate and endDate query parameters (one-day window recommended).
$.paths[?(@property && @property.indexOf('/telemetry') > -1 || @property.indexOf('/metrics') > -1)].get
info
cnh-iso15143-profile
Telemetry endpoints should expose a `profile` parameter restricted to CP or MH.
$.paths[?(@property && @property.indexOf('/telemetry') > -1)].get.parameters[?(@.name == 'profile')].schema
warn
cnh-error-401
Operations should declare 401 Unauthorized response.
$.paths[*][get,post,put,patch,delete].responses

Spectral Ruleset

Raw ↑ 
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"]