Dun & Bradstreet · API Governance Rules

Dun & Bradstreet API Rules

Spectral linting rules defining API design standards and conventions for Dun & Bradstreet.

Dun & Bradstreet API Rules is a Spectral governance ruleset published by Dun & Bradstreet on the APIs.io network, containing 8 lint rules.

The ruleset includes 3 error-severity rules, 4 warning-severity rules, and 1 info-severity rule.

Tagged areas include Business Data, Company Data, D-U-N-S Number, Credit, and Risk.

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

8 Rules error 3 warn 4 info 1
View Rules File View on GitHub

Rule Categories

dnb

Rules

warn
dnb-duns-field-name
Identifier for a business should use the field name `duns`.
$.components.schemas..properties
error
dnb-operation-id-camel-case
Direct+ operationIds are lowerCamelCase verbs.
$.paths.*[get,post,put,delete,patch]
warn
dnb-tags-title-case
Tags use Title Case.
$.tags[*].name
warn
dnb-summary-title-case
Operation summaries use Title Case.
$.paths.*[get,post,put,delete,patch].summary
error
dnb-bearer-auth-required
All non-token operations must require bearer auth.
$.paths[?(@property != "/v3/token")].*[get,post,put,delete,patch]
error
dnb-version-in-path
Direct+ paths must be prefixed with /v{n}/.
$.paths
warn
dnb-country-code-iso2
Country codes use ISO 3166-1 alpha-2 (countryISOAlpha2Code).
$..parameters[?(@.name == 'country' || @.name == 'countryCode')]
info
dnb-pagination-page-size
Paginated list endpoints expose pageNumber and pageSize.
$.paths[?(@property =~ /search/)].get.parameters[*].name

Spectral Ruleset

Raw ↑ 
extends: [[spectral:oas, all]]
documentationUrl: https://directplus.documentation.dnb.com/
rules:
  # D&B Direct+ uses lowerCamelCase for all JSON field names; D-U-N-S Number
  # is the singular identifier that should appear consistently as `duns`.
  dnb-duns-field-name:
    description: Identifier for a business should use the field name `duns`.
    message: 'Use `duns` (not `dunsNumber`, `duns_number`, or `DUNS`) as the identifier field.'
    severity: warn
    given: $.components.schemas..properties
    then:
      field: dunsNumber
      function: falsy
  dnb-operation-id-camel-case:
    description: Direct+ operationIds are lowerCamelCase verbs.
    message: '`operationId` must be lowerCamelCase.'
    severity: error
    given: $.paths.*[get,post,put,delete,patch]
    then:
      field: operationId
      function: pattern
      functionOptions:
        match: '^[a-z][a-zA-Z0-9]+$'
  dnb-tags-title-case:
    description: Tags use Title Case.
    message: 'Tag names should use Title Case (e.g. `Identity Resolution`).'
    severity: warn
    given: $.tags[*].name
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z][A-Za-z0-9]*( [A-Z][A-Za-z0-9-+]*)*$'
  dnb-summary-title-case:
    description: Operation summaries use Title Case.
    severity: warn
    given: $.paths.*[get,post,put,delete,patch].summary
    then:
      function: pattern
      functionOptions:
        match: '^[A-Z]'
  dnb-bearer-auth-required:
    description: All non-token operations must require bearer auth.
    severity: error
    given: $.paths[?(@property != "/v3/token")].*[get,post,put,delete,patch]
    then:
      field: security
      function: truthy
  dnb-version-in-path:
    description: Direct+ paths must be prefixed with /v{n}/.
    message: 'Paths must begin with /v1/, /v2/, or /v3/.'
    severity: error
    given: $.paths
    then:
      field: '@key'
      function: pattern
      functionOptions:
        match: '^/v[0-9]+/'
  dnb-country-code-iso2:
    description: Country codes use ISO 3166-1 alpha-2 (countryISOAlpha2Code).
    severity: warn
    given: $..parameters[?(@.name == 'country' || @.name == 'countryCode')]
    then:
      function: falsy
  dnb-pagination-page-size:
    description: Paginated list endpoints expose pageNumber and pageSize.
    severity: info
    given: $.paths[?(@property =~ /search/)].get.parameters[*].name
    then:
      function: enumeration
      functionOptions:
        values: [pageNumber, pageSize, searchTerm, countryISOAlpha2Code]