ATTOM · API Governance Rules

ATTOM API Rules

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

10 Rules error 6 warn 3 info 1
View Rules File View on GitHub

Rule Categories

attom

Rules

error
attom-operation-id-pattern
ATTOM operationIds must be lowerCamelCase verb-resource ("getPropertyDetail", "searchPois").
$.paths.*[get,post,put,patch,delete].operationId
error
attom-operation-summary-title-case
Operation summaries must use Title Case ("Get Property Detail", not "Get property detail").
$.paths.*[get,post,put,patch,delete].summary
error
attom-operation-tag-required
Every operation must have at least one tag.
$.paths.*[get,post,put,patch,delete]
error
attom-path-no-trailing-slash
Paths must not end with a trailing slash (except the root).
$.paths
warn
attom-path-kebab-or-flat
ATTOM paths use flat-case or single-word segments (no camelCase except v4 endpoints).
$.paths
error
attom-security-apikey-header
ATTOM APIs MUST authenticate via the `apikey` header.
$.components.securitySchemes
error
attom-global-security-required
Specs must declare a top-level security requirement.
$
warn
attom-server-base-url
ATTOM servers should point at api.gateway.attomdata.com.
$.servers[*].url
info
attom-status-envelope
Every 200 response schema should reference a status block.
$.components.schemas
warn
attom-info-contact-email
info.contact.email should be set to [email protected].
$.info.contact

Spectral Ruleset

Raw ↑ 
extends: spectral:oas
rules:
  # Operation conventions
  attom-operation-id-pattern:
    description: ATTOM operationIds must be lowerCamelCase verb-resource ("getPropertyDetail", "searchPois").
    severity: error
    given: $.paths.*[get,post,put,patch,delete].operationId
    then:
      function: pattern
      functionOptions:
        match: "^[a-z][a-zA-Z0-9]+$"

  attom-operation-summary-title-case:
    description: Operation summaries must use Title Case ("Get Property Detail", not "Get property detail").
    severity: error
    given: $.paths.*[get,post,put,patch,delete].summary
    then:
      function: pattern
      functionOptions:
        match: "^([A-Z][a-zA-Z0-9'\\-]*\\s?)+$"

  attom-operation-tag-required:
    description: Every operation must have at least one tag.
    severity: error
    given: $.paths.*[get,post,put,patch,delete]
    then:
      field: tags
      function: truthy

  # Path conventions
  attom-path-no-trailing-slash:
    description: Paths must not end with a trailing slash (except the root).
    severity: error
    given: $.paths
    then:
      function: pattern
      functionOptions:
        match: "^(\\/|.*[^/])$"
      field: "@key"

  attom-path-kebab-or-flat:
    description: ATTOM paths use flat-case or single-word segments (no camelCase except v4 endpoints).
    severity: warn
    given: $.paths
    then:
      function: pattern
      functionOptions:
        match: "^/[a-zA-Z0-9{}\\-_./]*$"
      field: "@key"

  # Auth
  attom-security-apikey-header:
    description: ATTOM APIs MUST authenticate via the `apikey` header.
    severity: error
    given: $.components.securitySchemes
    then:
      function: schema
      functionOptions:
        schema:
          type: object
          patternProperties:
            ".*":
              type: object
              required: [type, in, name]
              properties:
                type:
                  const: apiKey
                in:
                  const: header
                name:
                  const: apikey

  attom-global-security-required:
    description: Specs must declare a top-level security requirement.
    severity: error
    given: $
    then:
      field: security
      function: truthy

  # Servers
  attom-server-base-url:
    description: ATTOM servers should point at api.gateway.attomdata.com.
    severity: warn
    given: $.servers[*].url
    then:
      function: pattern
      functionOptions:
        match: "^https://api\\.gateway\\.attomdata\\.com.*$"

  # Schemas
  attom-status-envelope:
    description: Every 200 response schema should reference a status block.
    severity: info
    given: $.components.schemas
    then:
      function: truthy
      field: Status

  # Info block
  attom-info-contact-email:
    description: info.contact.email should be set to [email protected].
    severity: warn
    given: $.info.contact
    then:
      field: email
      function: truthy