Skip to content

Z611: FORBIDDEN_DOMAIN_REFERENCE

  • Severity: Error

    Penalty: 0.0 points | Category: general

  • Remediation & Opt-In

    Auto-Fixable: No | Opt-In: No

Description

A link in this document references an external domain that has been explicitly forbidden in [policies].forbidden_external_domains.

The Policy-as-Code Engine (v0.28.0) evaluates all link types in the document to prevent blind spots:

  • Native Markdown links: [text](https://forbidden.example.com/path)
  • Raw HTML links: <a href="https://forbidden.example.com/path">text</a>

Domain matching is case-insensitive and covers exact domain matches and all subdomains:

  • forbidden.example.com matches https://forbidden.example.com/page
  • forbidden.example.com also matches https://api.forbidden.example.com/v1

This rule is particularly useful for:

  • Preventing references to deprecated or obsolete external services.
  • Blocking competitor domain mentions from reaching published documentation.
  • Enforcing a corporate approved-domains policy.

How to Fix

Replace the link to the forbidden domain with an approved alternative, or remove the link entirely.

Before (non-compliant):

See the [legacy docs](https://legacy.corp/docs) for older configuration options.

After (compliant):

See the [current docs](https://docs.myproject.dev/configuration) for configuration options.

Configuration

Z611 is opt-in and inactive by default. It is only emitted when [policies].forbidden_external_domains is declared with a non-empty list in .zenzic.toml.

[policies]
# These domains must not appear in any link across the documentation.
forbidden_external_domains = [
    "legacy.corp",
    "competitor.example.com",
]

When the list is empty or the [policies] section is absent, no Z611 findings are emitted.

Suppression

If a specific link to a forbidden domain is intentional (e.g. a historical CHANGELOG entry or an ADR explaining why the domain was deprecated), suppress the finding inline:

<!-- zenzic:ignore:Z611 -->
See the [legacy system](https://legacy.corp/docs) for historical context.

Or use [governance].per_file_ignores in .zenzic.toml for structural suppressions:

[governance.per_file_ignores]
"changelogs/**" = ["Z611"]
"docs/developers/explanation/adr-vault/**" = ["Z611"]

Reference

See the Finding Codes Index for finding code details.