CDK Global · API Governance Rules

CDK Global API Rules

Spectral linting rules defining API design standards and conventions for CDK Global.

CDK Global API Rules is a Spectral governance ruleset published by CDK Global on the APIs.io network, containing 10 lint rules.

The ruleset includes 2 error-severity rules, 5 warning-severity rules, and 3 hint-severity rules.

Tagged areas include Automotive, Dealer Management, DMS, Auto Retail, and F&I.

Rulesets can be applied to your own OpenAPI specs via Spectral to enforce the same governance standards.

10 Rules error 2 warn 5

View Rules File View on GitHub

Rule Categories

fortellis

Rules

warn

fortellis-host-required

Fortellis APIs declare api.fortellis.io as host (or fortellis.io for legacy specs).

$.host

error

fortellis-basepath-versioned

Fortellis basePath must include a /v{N} version segment (e.g., /service/sessions/v4/).

$.basePath

warn

fortellis-operation-id-camel-case

Fortellis operationIds use camelCase (e.g., queryAppointments, getProductInfo).

$.paths[*][get,post,put,patch,delete].operationId

error

fortellis-operation-id-required

All Fortellis operations must declare an operationId.

$.paths[*][get,post,put,patch,delete]

warn

fortellis-oauth-required

Fortellis APIs must define an OAuth2 securityDefinition pointing at identity.fortellis.io.

$.securityDefinitions[?(@.type=='oauth2')].authorizationUrl

hint

fortellis-event-channel-path

Event Relay webhook endpoints must follow /event/{channel} path pattern.

$.paths[?(@property.startsWith('/event'))]~

warn

fortellis-required-event-headers

Event-receiving operations must accept Fortellis-Event-Id, X-Request-Id, Data-Owner-Id headers.

$.paths[?(@property.startsWith('/event'))][post]

hint

fortellis-tags-titlecase

Tags should use Title Case for marketplace and docs consistency.

$.tags[*].name

hint

fortellis-contact-fortellis-email

Specifications should list a Fortellis-domain support contact email.

$.info.contact.email

warn

fortellis-description-required

Every operation must have a description (for marketplace listings + AI consumption).

$.paths[*][get,post,put,patch,delete]

Spectral Ruleset

extends: spectral:oas
rules:

  fortellis-host-required:
    description: Fortellis APIs declare api.fortellis.io as host (or fortellis.io for legacy specs).
    message: "host '{{value}}' should be api.fortellis.io"
    given: "$.host"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^(api\\.)?fortellis\\.io$"

  fortellis-basepath-versioned:
    description: Fortellis basePath must include a /v{N} version segment (e.g., /service/sessions/v4/).
    message: "basePath '{{value}}' must include a /v{N} segment"
    given: "$.basePath"
    severity: error
    then:
      function: pattern
      functionOptions:
        match: "/v[0-9]+"

  fortellis-operation-id-camel-case:
    description: Fortellis operationIds use camelCase (e.g., queryAppointments, getProductInfo).
    message: "operationId '{{value}}' should use camelCase"
    given: "$.paths[*][get,post,put,patch,delete].operationId"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  fortellis-operation-id-required:
    description: All Fortellis operations must declare an operationId.
    message: "Operation at {{path}} is missing operationId"
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: error
    then:
      field: operationId
      function: truthy

  fortellis-oauth-required:
    description: Fortellis APIs must define an OAuth2 securityDefinition pointing at identity.fortellis.io.
    message: "securityDefinition missing or not pointing at identity.fortellis.io"
    given: "$.securityDefinitions[?(@.type=='oauth2')].authorizationUrl"
    severity: warn
    then:
      function: pattern
      functionOptions:
        match: "identity\\.fortellis\\.io"

  fortellis-event-channel-path:
    description: Event Relay webhook endpoints must follow /event/{channel} path pattern.
    message: "Webhook path '{{property}}' should be /event/{channel}"
    given: "$.paths[?(@property.startsWith('/event'))]~"
    severity: hint
    then:
      function: pattern
      functionOptions:
        match: "^/event/\\{channel\\}$"

  fortellis-required-event-headers:
    description: Event-receiving operations must accept Fortellis-Event-Id, X-Request-Id, Data-Owner-Id headers.
    message: "Event endpoint at {{path}} is missing one of the standard Fortellis event headers"
    given: "$.paths[?(@property.startsWith('/event'))][post]"
    severity: warn
    then:
      field: parameters
      function: truthy

  fortellis-tags-titlecase:
    description: Tags should use Title Case for marketplace and docs consistency.
    message: "tag '{{value}}' should be Title Case"
    given: "$.tags[*].name"
    severity: hint
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][A-Za-z0-9 ]+$"

  fortellis-contact-fortellis-email:
    description: Specifications should list a Fortellis-domain support contact email.
    message: "contact.email '{{value}}' should be a fortellis.io address"
    given: "$.info.contact.email"
    severity: hint
    then:
      function: pattern
      functionOptions:
        match: "@fortellis\\.io$"

  fortellis-description-required:
    description: Every operation must have a description (for marketplace listings + AI consumption).
    message: "Operation at {{path}} is missing a description"
    given: "$.paths[*][get,post,put,patch,delete]"
    severity: warn
    then:
      field: description
      function: truthy