Synopsys · API Governance Rules

Synopsys API Rules

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

12 Rules error 3 warn 7 info 2

View Rules File View on GitHub

Rule Categories

async issue operation paths polaris report scan

Rules

error

operation-operationId

All operations must have an operationId.

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

error

operation-summary

All operations must have a summary.

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

warn

operation-summary-title-case

Operation summaries must use Title Case.

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

warn

operation-tags

All operations must be tagged.

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

warn

operation-description

All operations should have a description.

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

info

scan-response-issue-count

Scan completion responses should include issue count information.

$.components.schemas.Scan.properties

error

issue-severity-required

Issue schema must include a severity field.

$.components.schemas.Issue.properties

warn

issue-cwe-field

Issue schema should include a CWE reference field.

$.components.schemas.Issue.properties

info

polaris-content-type

Polaris API responses may use versioned vendor content types.

$.paths[*][*].responses[*].content

warn

async-operation-202

Operations that may be asynchronous must include a 202 response.

$.paths[*].post.responses

warn

paths-kebab-case

Path segments must use kebab-case.

$.paths

warn

report-format-required

Report request schema must include a format field.

$.components.schemas.ReportRequest.properties

Spectral Ruleset

extends: spectral:oas
rules:
  # Require operationId
  operation-operationId:
    description: All operations must have an operationId.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: operationId
      function: truthy

  # Require summary
  operation-summary:
    description: All operations must have a summary.
    severity: error
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: summary
      function: truthy

  # Enforce Title Case on summaries
  operation-summary-title-case:
    description: Operation summaries must use Title Case.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete].summary"
    then:
      function: pattern
      functionOptions:
        match: "^[A-Z][a-zA-Z0-9 ()/-]*$"

  # Require tags
  operation-tags:
    description: All operations must be tagged.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: tags
      function: truthy

  # Require description
  operation-description:
    description: All operations should have a description.
    severity: warn
    given: "$.paths[*][get,post,put,patch,delete]"
    then:
      field: description
      function: truthy

  # Security scan responses should include issue counts
  scan-response-issue-count:
    description: Scan completion responses should include issue count information.
    severity: info
    given: "$.components.schemas.Scan.properties"
    then:
      field: issueCount
      function: truthy

  # Issues must have severity field
  issue-severity-required:
    description: Issue schema must include a severity field.
    severity: error
    given: "$.components.schemas.Issue.properties"
    then:
      field: severity
      function: truthy

  # Issues must have CWE field
  issue-cwe-field:
    description: Issue schema should include a CWE reference field.
    severity: warn
    given: "$.components.schemas.Issue.properties"
    then:
      field: cwe
      function: truthy

  # Polaris content-type pattern
  polaris-content-type:
    description: Polaris API responses may use versioned vendor content types.
    severity: info
    given: "$.paths[*][*].responses[*].content"
    then:
      function: truthy

  # Require 202 for async operations
  async-operation-202:
    description: Operations that may be asynchronous must include a 202 response.
    severity: warn
    given: "$.paths[*].post.responses"
    then:
      function: truthy

  # Paths must use kebab-case
  paths-kebab-case:
    description: Path segments must use kebab-case.
    severity: warn
    given: "$.paths"
    then:
      function: pattern
      functionOptions:
        match: "^(/[a-z0-9{}-]+)+$"

  # Report requests must specify format
  report-format-required:
    description: Report request schema must include a format field.
    severity: warn
    given: "$.components.schemas.ReportRequest.properties"
    then:
      field: format
      function: truthy