---
title: tld validate
description: Check workspace YAML, verify symbols against source, and catch
  diagrams that have fallen behind.
editUrl: true
head: []
template: doc
sidebar:
  hidden: false
  attrs: {}
pagefind: true
draft: false
---

`tld validate` is your quality gate. It checks the workspace structure, verifies that referenced symbols still exist in source, and flags diagrams whose metadata is older than the file's last Git commit.

```bash
tld validate
```

## What it catches

- **Missing elements**: a connector references an element that doesn't exist
- **Duplicate refs**: two elements with the same key
- **Invalid types**: an element kind that isn't recognized
- **Circular parent references**: a diagram that's its own ancestor
- **Broken view references**: connectors pointing to views that don't exist
- **Stale symbols**: an element points at a file or symbol that moved or disappeared
- **Outdated diagrams**: metadata is older than the source's latest commit

A clean workspace prints a summary:

```
✓ Workspace valid: 42 elements, 12 views, 35 connectors
```

## Strictness levels

The validation level controls how strict checks are. Set it globally or override per run:

```bash
tld validate --strictness 1   # Minimal
tld validate --strictness 2   # Standard (default)
tld validate --strictness 3   # Strict — checks labels, descriptions, naming
tld validate --strictness 3 --verbose
```

## Architectural warnings

After structural validation, `tld validate` runs the architectural linter and prints a summary grouped by rule code:

```
Architectural Warnings (Level 2: Standard)

CODE     RULE              VIOLATIONS
ARC001   Isolated Object   1
ARC002   High Density      1
```

Pass a rule code to see its full detail, including every violating element and how to fix it:

```bash
tld validate ARC001
```

Known codes: `ARC001`–`ARC007`, `ARC101`–`ARC103`, `ARC201`–`ARC203`. See [Linting Rules](/docs/tld/linting-rules) for what each one means.

## Outdated diagrams in CI

Outdated diagrams are warnings by default. In CI, make them fail the build:

```bash
tld validate --strict
```

`--strict` exits non-zero when any diagram is outdated, so stale architecture docs break the build instead of slipping through.

## Suppressing rules

Suppress specific rule codes in workspace config:

```yaml
# .tld/.tld.yaml
validation:
  exclude_rules: [ARC002]
```

## Flags

| Flag | Default | What it does |
|---|---|---|
| `--strictness` | config / 2 | Override validation level [1-3] |
| `-v, --verbose` | `false` | Show full architectural warning output |
| `--strict` | `false` | Exit non-zero when outdated diagrams are detected |