How AI-DLC Validates Mermaid Diagrams: Content Validation Rules Explained

AI-DLC enforces mandatory syntax validation for all Mermaid diagrams through rules defined in common/content-validation.md, automatically falling back to plain-text alternatives when checks fail to prevent broken visualizations in downstream tooling.

The awslabs/aidlc-workflows repository implements a strict content-validation framework that ensures every Mermaid diagram generated by AI-DLC meets rigorous syntax standards before persisting to the repository. This validation process prevents malformed diagram blocks from breaking Markdown renderers and documentation generators while guaranteeing accessible text alternatives for every visual artifact.

Mandatory Validation Rules in the Core Workflow

In aidlc-rules/aws-aidlc-rules/core-workflow.md, the workflow explicitly lists "Validate Mermaid diagram syntax" under the MANDATORY: Content Validation section [1†L52-L55]. This rule triggers before any file containing a diagram is written to the repository, ensuring AI models cannot bypass syntax checks during file generation.

The Validation Checklist

According to aidlc-rules/aws-aidlc-rule-details/common/content-validation.md [2†L21-L27], AI-DLC applies a three-point validation checklist:

• Syntax verification – The Mermaid source must pass structural and grammatical validation checks.
• Character escaping – Special characters in node IDs and labels require proper escaping (e.g., " → \", ' → \').
• Fallback preparation – If syntax checks fail, the system generates a plain-text representation instead of the diagram [2†L28-L38].

Implementation Pattern for Validated Diagrams

When generating documentation, AI-DLC follows the conditional block pattern defined in common/content-validation.md [2†L40-L48]:

## Workflow Visualization

### Mermaid Diagram (if syntax valid)

```mermaid
[validated diagram content]

Text Alternative (always include)

Phase 1: INCEPTION
- Stage 1: Workspace Detection (COMPLETED)
…

The Mermaid block only renders after successful validation. Otherwise, only the **Text Alternative** section appears in the final output.

### Validation Logic Implementation

The underlying validation logic follows this pseudo-code pattern used by the AI agent:

```python
def validate_mermaid(diagram: str) -> bool:
    # 1. Ensure only alphanumeric/underscore in node IDs

    if re.search(r'[^\w\s\-]', diagram):
        return False
    # 2. Escape quotes in labels

    diagram = diagram.replace('"', r'\"').replace("'", r"\'")
    # 3. Run a lightweight Mermaid parser (e.g., mermaid-cli --validate)

    return run_mermaid_validator(diagram)

If validate_mermaid returns False, the agent emits only the Text Alternative section.

Error Handling and Fallback Strategy

When validation detects syntax errors, AI-DLC logs the failure, switches to the fallback text version, and continues the workflow without blocking the user [2†L72-L78]. This non-blocking approach ensures workflow continuity while maintaining documentation integrity.

The framework maintains consistency with ASCII diagram validation approaches documented in ascii-diagram-standards.md, illustrating a unified validation philosophy across all visual artifacts in the repository.

Why Content Validation Matters

By performing validation up-front, AI-DLC prevents malformed Mermaid blocks from breaking downstream tooling such as static site generators and IDE preview panels. The strict enforcement guarantees that every visual artifact has a reliable textual counterpart for accessibility and version control diffing.

Summary

• Mandatory validation is triggered from core-workflow.md before any diagram file creation [1†L52-L55].
• Three-point checklist covers syntax, character escaping, and fallback generation [2†L21-L27].
• Conditional rendering ensures only validated Mermaid blocks appear in output; otherwise text alternatives are emitted.
• Non-blocking error handling logs failures and substitutes text alternatives automatically without stopping the workflow [2†L72-L78].
• Repository integrity is protected by preventing malformed diagrams from entering the codebase and breaking downstream tools.

Frequently Asked Questions

What happens if a Mermaid diagram fails validation in AI-DLC?

If validation fails, AI-DLC logs the error and emits only the Text Alternative section containing a plain-text description of the workflow. The process continues without blocking, ensuring the documentation remains functional even when diagrams are malformed [2†L72-L78].

Where are the content validation rules defined for Mermaid diagrams?

The detailed validation checklist resides in aidlc-rules/aws-aidlc-rule-details/common/content-validation.md [2†L21-L27], while the mandatory trigger appears in aidlc-rules/aws-aidlc-rules/core-workflow.md under the MANDATORY: Content Validation section [1†L52-L55].

Does AI-DLC block the workflow when Mermaid validation fails?

No. AI-DLC implements non-blocking error handling that logs validation failures, substitutes a text alternative, and allows the workflow to continue. This design prevents syntax errors from halting development while maintaining documentation standards [2†L72-L78].

What character escaping is required for Mermaid diagrams in AI-DLC?

AI-DLC requires escaping double quotes (" → \") and single quotes (' → \') within node IDs and labels to prevent parsing errors in the Mermaid renderer [2†L21-L27].

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}