Architect of the Capitol · API Governance Rules

Architect of the Capitol API Rules

Spectral linting rules defining API design standards and conventions for Architect of the Capitol.

13 Rules error 8 warn 5
View Rules File View on GitHub

Rule Categories

aoc

Rules

error
aoc-building-id-required
Building responses must include an id field
$.components.schemas.Building.properties
error
aoc-building-name-required
Building responses must include a name field
$.components.schemas.Building.properties
error
aoc-artwork-title-required
Artwork responses must include a title field
$.components.schemas.Artwork.properties
error
aoc-artwork-artist-required
Artwork responses must include an artist field
$.components.schemas.Artwork.properties
error
aoc-preservation-status-enum
Preservation project status must be a valid enum value
$.components.schemas.PreservationProject.properties.status
warn
aoc-list-responses-have-total
List responses must include a total count
$.components.schemas[*List].properties
warn
aoc-list-responses-have-limit
List responses must include a limit field
$.components.schemas[*List].properties
warn
aoc-operations-have-tags
All API operations must have tags
$.paths[*][get,post,put,patch,delete]
error
aoc-operations-have-summary
All API operations must have a summary
$.paths[*][get,post,put,patch,delete]
error
aoc-operations-have-operation-id
All API operations must have an operationId
$.paths[*][get,post,put,patch,delete]
warn
aoc-path-parameters-described
Path parameters must have descriptions
$.paths[*][*].parameters[?(@.in=='path')]
warn
aoc-info-contact-required
API info must include contact information
$.info
error
aoc-servers-defined
API must define at least one server
$

Spectral Ruleset

Raw ↑ 
rules:
  aoc-building-id-required:
    description: Building responses must include an id field
    message: Building object must have an id property
    severity: error
    given: "$.components.schemas.Building.properties"
    then:
      field: id
      function: truthy

  aoc-building-name-required:
    description: Building responses must include a name field
    message: Building object must have a name property
    severity: error
    given: "$.components.schemas.Building.properties"
    then:
      field: name
      function: truthy

  aoc-artwork-title-required:
    description: Artwork responses must include a title field
    message: Artwork object must have a title property
    severity: error
    given: "$.components.schemas.Artwork.properties"
    then:
      field: title
      function: truthy

  aoc-artwork-artist-required:
    description: Artwork responses must include an artist field
    message: Artwork object must have an artist property
    severity: error
    given: "$.components.schemas.Artwork.properties"
    then:
      field: artist
      function: truthy

  aoc-preservation-status-enum:
    description: Preservation project status must be a valid enum value
    message: PreservationProject status must be planned, active, or completed
    severity: error
    given: "$.components.schemas.PreservationProject.properties.status"
    then:
      field: enum
      function: truthy

  aoc-list-responses-have-total:
    description: List responses must include a total count
    message: List schema must include a total property
    severity: warn
    given: "$.components.schemas[*List].properties"
    then:
      field: total
      function: truthy

  aoc-list-responses-have-limit:
    description: List responses must include a limit field
    message: List schema must include a limit property
    severity: warn
    given: "$.components.schemas[*List].properties"
    then:
      field: limit
      function: truthy

  aoc-operations-have-tags:
    description: All API operations must have tags
    message: Operation must include at least one tag
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  aoc-operations-have-summary:
    description: All API operations must have a summary
    message: Operation must include a summary
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  aoc-operations-have-operation-id:
    description: All API operations must have an operationId
    message: Operation must include an operationId
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  aoc-path-parameters-described:
    description: Path parameters must have descriptions
    message: Path parameter should include a description
    severity: warn
    given: "$.paths[*][*].parameters[?(@.in=='path')]"
    then:
      field: description
      function: truthy

  aoc-info-contact-required:
    description: API info must include contact information
    message: Info object must have a contact field
    severity: warn
    given: "$.info"
    then:
      field: contact
      function: truthy

  aoc-servers-defined:
    description: API must define at least one server
    message: Servers array must be defined and non-empty
    severity: error
    given: "$"
    then:
      field: servers
      function: truthy