SpecDoc

Governance Rules

Governance rules let you encode your API design standards as code. They run automatically in CI/CD and prevent inconsistencies from reaching production.

Built-in policies

SpecLayer ships three ready-made policy bundles. Select one in your pipeline configuration:

off

Governance disabled. Specs are published without any checks.

standard

Checks naming conventions, required descriptions on public operations, and basic security headers. Recommended for most teams.

strict

Everything in standard plus: 100% description coverage, response schema completeness, and security requirement on every operation.

Custom rule files

Create a .speclayer/governance.yaml file in your repository root to define custom rules alongside the built-in policy:

.speclayer/governance.yaml

extends: standard   # built-in base policy

rules:
  # Enforce kebab-case path segments
  naming.path-kebab-case:
    severity: error

  # Require x-internal tag on internal-only operations
  meta.internal-tag:
    severity: warning

  # All 4xx responses must have an 'error' property in the schema
  schema.error-envelope:
    severity: error
    options:
      required_property: error

  # Paths must start with the API version prefix
  naming.path-version-prefix:
    severity: error
    options:
      pattern: '^/v[0-9]+'

  # Require at least one 2xx example per operation
  docs.response-example:
    severity: warning

  # Disallow 'any' / free-form schema on request bodies
  schema.no-free-form:
    severity: error

Rule severity levels

error

Pipeline fails. Spec is not published until the issue is resolved.

warning

Logged and reported but pipeline continues. Portal is still published.

info

Informational only. Useful for tracking coverage metrics over time.

Available built-in rules

Rule	Category	Description
naming.path-kebab-case	Naming	All path segments must use kebab-case
naming.operation-id	Naming	Every operation must have an operationId
naming.path-version-prefix	Naming	Paths must start with a version prefix
docs.operation-description	Documentation	All public operations need a description
docs.parameter-description	Documentation	All parameters need descriptions
docs.response-example	Documentation	Success responses need at least one example
security.requires-auth	Security	Every operation must reference a security scheme
security.no-basic-auth	Security	Basic Auth schemes are disallowed
schema.no-free-form	Schema	Free-form additionalProperties disallowed on bodies
schema.error-envelope	Schema	4xx responses must have an error property
breaking.no-removal	Breaking	Operations and fields cannot be removed
breaking.no-type-change	Breaking	Property types cannot change

Report-only mode

To collect governance results without failing the pipeline, set all rules to warning severity or use report-only mode in the pipeline task:

azure-pipelines.yml

- task: speclayer-publish@1
  inputs:
    specFile: 'openapi/api.yaml'
    projectSlug: 'payments-api'
    governancePolicy: 'strict'
    governanceMode: 'report-only'   # Never fails the pipeline

Report-only mode is useful during initial adoption, but be careful — it removes the enforcement guarantee. Set a deadline to switch off report-only once the team has fixed existing violations.

Governance rule results are stored with each spec version in the Registry. You can track your quality score over time from the project dashboard.

Spec Registry

Developer Portals