Configuration files are code too — they're read by humans, versioned in git, and debugged at 2am during outages. MCP Zen of Languages analyzes four data formats with dedicated detectors for each.
JSON — 9 Principles, 9 Detectors Rule ID Principle Category Severity Dogma json-001 Choose strictness intentionally Correctness 7 ZEN-EXPLICIT-INTENT json-002 Keep object depth understandable Structure 6 ZEN-RETURN-EARLY json-003 Keys must be unique Correctness 8 ZEN-EXPLICIT-INTENT json-004 Avoid magic string repetition Clarity 5 ZEN-EXPLICIT-INTENT json-005 Keys are case-sensitive identifiers Naming 5 ZEN-UNAMBIGUOUS-NAME json-006 Keep inline arrays bounded Structure 4 ZEN-RETURN-EARLY json-007 Prefer omission over null sprawl Correctness 5 ZEN-EXPLICIT-INTENT json-008 Dates must follow ISO 8601 Correctness 6 ZEN-EXPLICIT-INTENT json-009 Prefer key omission over explicit null Clarity 5 ZEN-EXPLICIT-INTENT
json-001 — Choose strictness intentionally Trailing commas should be rejected for JSON unless JSON5 is explicitly targeted.
Universal Dogmas: ZEN-EXPLICIT-INTENT
Common Violations:
Trailing commas in strict JSON mode Detectable Patterns:
json-002 — Keep object depth understandable Deeply nested objects/arrays are hard to reason about and validate.
Universal Dogmas: ZEN-RETURN-EARLY
Common Violations:
Nesting depth exceeds configured threshold json-003 — Keys must be unique Duplicate object keys silently override values in many parsers.
Universal Dogmas: ZEN-EXPLICIT-INTENT
Common Violations:
Duplicate keys in an object json-004 — Avoid magic string repetition Repeated string literals should be extracted or referenced consistently.
Universal Dogmas: ZEN-EXPLICIT-INTENT
Common Violations:
Repeated magic string values json-005 — Keys are case-sensitive identifiers Avoid mixing camelCase, snake_case, and PascalCase at the same object level.
Universal Dogmas: ZEN-UNAMBIGUOUS-NAME
Common Violations:
Mixed key casing at same object level json-006 — Keep inline arrays bounded Very large inline arrays are hard to review and often belong in separate data files.
Universal Dogmas: ZEN-RETURN-EARLY
Common Violations:
json-007 — Prefer omission over null sprawl Excessive null usage usually indicates optional keys that can be omitted.
Universal Dogmas: ZEN-EXPLICIT-INTENT
Common Violations:
Excessive null values across the document json-008 — Dates must follow ISO 8601 Date strings should use ISO 8601 format (YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ) for unambiguous, sortable representation. Locale-dependent formats such as MM/DD/YYYY create parsing ambiguity.
Universal Dogmas: ZEN-EXPLICIT-INTENT
Common Violations:
Non-ISO 8601 date string detected Detectable Patterns:
\d{1,2}/\d{1,2}/\d{2,4} \d{1,2}\.\d{1,2}\.\d{4} json-009 — Prefer key omission over explicit null Top-level object keys whose value is explicitly null should be omitted entirely. Explicit null at the top level signals optional absence, which is better expressed by omitting the key.
Universal Dogmas: ZEN-EXPLICIT-INTENT
Common Violations:
Top-level key set to explicit null Detector What It Catches JsonStrictnessDetector Flag trailing commas when strict JSON output is expected JsonSchemaConsistencyDetector Detect excessive JSON nesting depth JsonDuplicateKeyDetector Detect duplicate keys in JSON objects JsonMagicStringDetector Detect repeated magic-string values JsonKeyCasingDetector Detect mixed key casing at the same object level JsonArrayOrderDetector Detect oversized inline arrays JsonNullSprawlDetector Detect excessive null values across JSON objects/arrays JsonDateFormatDetector Identify date strings that deviate from ISO 8601 formatting JsonNullHandlingDetector Report top-level object keys whose values are explicitly null
SVG — 15 Principles, 15 Detectors Rule ID Principle Category Severity Dogma svg-001 Include a root title element for accessibility Usability 8 ZEN-UNAMBIGUOUS-NAME svg-002 Use role=img with aria-labelledby for inline SVG Usability 8 ZEN-UNAMBIGUOUS-NAME svg-003 Give image nodes alternative text Usability 7 ZEN-UNAMBIGUOUS-NAME svg-004 Provide a long description for complex graphics Documentation 6 ZEN-UNAMBIGUOUS-NAME svg-005 Prefer presentation attributes over inline styles Consistency 5 ZEN-EXPLICIT-INTENT svg-006 Use viewBox with fixed dimensions Structure 6 ZEN-RETURN-EARLY svg-007 Remove unused defs entries Organization 5 ZEN-STRICT-FENCES, ZEN-PROPORTIONATE-COMPLEXITY, ZEN-RUTHLESS-DELETION svg-008 Avoid excessive nested group depth Complexity 5 ZEN-PROPORTIONATE-COMPLEXITY, ZEN-RETURN-EARLY svg-009 Keep id attributes unique Correctness 8 ZEN-EXPLICIT-INTENT svg-010 Prefer relative path commands when practical Idioms 4 ZEN-RIGHT-ABSTRACTION svg-011 Avoid embedded base64 raster payloads Performance 7 ZEN-PROPORTIONATE-COMPLEXITY svg-012 Declare the SVG XML namespace Correctness 7 ZEN-EXPLICIT-INTENT, ZEN-UNAMBIGUOUS-NAME, ZEN-STRICT-FENCES svg-013 Use href instead of deprecated xlink:href Idioms 4 ZEN-RIGHT-ABSTRACTION svg-014 Keep node count within maintainable limits Performance 6 ZEN-PROPORTIONATE-COMPLEXITY svg-015 Remove production-bloat metadata and comments Performance 4 ZEN-PROPORTIONATE-COMPLEXITY, ZEN-UNAMBIGUOUS-NAME, ZEN-STRICT-FENCES
svg-001 — Include a root title element for accessibility SVGs without a child on the root are not announced well by screen readers.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Missing <title> child on root <svg></li> </ul> </details> <details class="info"> <summary><code>svg-002</code> — Use role=img with aria-labelledby for inline SVG</summary> <p><strong>Inline SVGs should be exposed as images and linked to accessible labels.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Missing role="img" and/or aria-labelledby on root <svg></li> </ul> </details> <details class="info"> <summary><code>svg-003</code> — Give image nodes alternative text</summary> <p><strong>Embedded raster images should carry alternative text for assistive technologies.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li><image> element missing alt/title/aria-label text</li> </ul> </details> <details class="info"> <summary><code>svg-004</code> — Provide a long description for complex graphics</summary> <p><strong>Charts or diagrams should provide a <desc> element to explain non-trivial content.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Complex SVG missing <desc> element</li> </ul> </details> <details class="info"> <summary><code>svg-005</code> — Prefer presentation attributes over inline styles</summary> <p><strong>Inline style attributes reduce maintainability and hinder targeted optimization.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Inline style attribute found in SVG element</li> </ul> </details> <details class="info"> <summary><code>svg-006</code> — Use viewBox with fixed dimensions</summary> <p><strong>Hardcoded width/height without viewBox reduces responsive scalability.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-RETURN-EARLY</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Root SVG has width/height but no viewBox</li> </ul> </details> <details class="info"> <summary><code>svg-007</code> — Remove unused defs entries</summary> <p><strong>Unused gradients, symbols, or patterns in <defs> increase file complexity.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-STRICT-FENCES</code>, <code>ZEN-PROPORTIONATE-COMPLEXITY</code>, <code>ZEN-RUTHLESS-DELETION</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Unused ID defined under <defs></li> </ul> </details> <details class="info"> <summary><code>svg-008</code> — Avoid excessive nested group depth</summary> <p><strong>Deeply nested <g> structures increase DOM complexity without semantic gain.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-PROPORTIONATE-COMPLEXITY</code>, <code>ZEN-RETURN-EARLY</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Nested <g> depth exceeds recommended threshold</li> </ul> </details> <details class="info"> <summary><code>svg-009</code> — Keep id attributes unique</summary> <p><strong>Duplicate IDs break references like <use>, url(#id), and ARIA links.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Duplicate id attribute value in SVG</li> </ul> </details> <details class="info"> <summary><code>svg-010</code> — Prefer relative path commands when practical</summary> <p><strong>Paths composed only of absolute commands are often larger and less portable.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-RIGHT-ABSTRACTION</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Path uses only absolute commands</li> </ul> </details> <details class="info"> <summary><code>svg-011</code> — Avoid embedded base64 raster payloads</summary> <p><strong>Base64 raster data inflates file size and should usually be externalized.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-PROPORTIONATE-COMPLEXITY</code></p> <p><strong>Common Violations:</strong></p> <ul> <li><image> uses data:image/*;base64 payload</li> </ul> </details> <details class="info"> <summary><code>svg-012</code> — Declare the SVG <abbr title="eXtensible Markup Language">XML</abbr> namespace</summary> <p><strong>Missing xmlns="<a href="http://www.w3.org/2000/svg">http://www.w3.org/2000/svg</a>" breaks parsing in non-browser contexts.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code>, <code>ZEN-UNAMBIGUOUS-NAME</code>, <code>ZEN-STRICT-FENCES</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Missing SVG namespace declaration</li> </ul> </details> <details class="info"> <summary><code>svg-013</code> — Use href instead of deprecated xlink:href</summary> <p><strong>xlink:href is deprecated in SVG 2 and should be replaced with href.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-RIGHT-ABSTRACTION</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Deprecated xlink:href attribute detected</li> </ul> </details> <details class="info"> <summary><code>svg-014</code> — Keep node count within maintainable limits</summary> <p><strong>Very large SVG DOM trees should be simplified or delivered as sprites.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-PROPORTIONATE-COMPLEXITY</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>SVG element count exceeds configured threshold</li> </ul> <p><strong>Thresholds:</strong></p> <table> <thead> <tr> <th>Parameter</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>max_node_count</code></td> <td><code>500</code></td> </tr> </tbody> </table> </details> <details class="info"> <summary><code>svg-015</code> — Remove production-bloat metadata and comments</summary> <p><strong>Editor metadata, vendor namespaces, and <abbr title="eXtensible Markup Language">XML</abbr> comments add unnecessary payload.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-PROPORTIONATE-COMPLEXITY</code>, <code>ZEN-UNAMBIGUOUS-NAME</code>, <code>ZEN-STRICT-FENCES</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Metadata/comments/editor namespaces found in production SVG</li> </ul> </details> <table> <thead> <tr> <th>Detector</th> <th>What It Catches</th> </tr> </thead> <tbody> <tr> <td><strong>SvgMissingTitleDetector</strong></td> <td>Detects root SVG elements that omit an accessible title child</td> </tr> <tr> <td><strong>SvgAriaRoleDetector</strong></td> <td>Detects root SVG elements missing image role and labeling attributes</td> </tr> <tr> <td><strong>SvgImageAltDetector</strong></td> <td>Detects embedded image elements lacking alternative text metadata</td> </tr> <tr> <td><strong>SvgDescForComplexGraphicsDetector</strong></td> <td>Detects complex SVG documents that lack a descriptive <desc> element</td> </tr> <tr> <td><strong>SvgInlineStyleDetector</strong></td> <td>Detects inline style usage inside SVG markup</td> </tr> <tr> <td><strong>SvgViewBoxDetector</strong></td> <td>Detects fixed dimensions used without a responsive viewBox</td> </tr> <tr> <td><strong>SvgUnusedDefsDetector</strong></td> <td>Detects IDs declared under defs that are never referenced</td> </tr> <tr> <td><strong>SvgNestedGroupsDetector</strong></td> <td>Detects excessive nesting depth of SVG group elements</td> </tr> <tr> <td><strong>SvgDuplicateIdDetector</strong></td> <td>Detects duplicate ID values across SVG elements</td> </tr> <tr> <td><strong>SvgAbsolutePathOnlyDetector</strong></td> <td>Detects paths composed only of absolute command letters</td> </tr> <tr> <td><strong>SvgBase64ImageDetector</strong></td> <td>Detects base64-embedded raster images in SVG content</td> </tr> <tr> <td><strong>SvgXmlnsDetector</strong></td> <td>Detects missing core SVG <abbr title="eXtensible Markup Language">XML</abbr> namespace declarations</td> </tr> <tr> <td><strong>SvgDeprecatedXlinkHrefDetector</strong></td> <td>Detects deprecated xlink:href attributes in SVG markup</td> </tr> <tr> <td><strong>SvgNodeCountDetector</strong></td> <td>Detects SVG documents exceeding a configurable node-count threshold</td> </tr> <tr> <td><strong>SvgProductionBloatDetector</strong></td> <td>Detects metadata/comments and editor namespace bloat in production SVG</td> </tr> </tbody> </table> <hr /> <h2 id="toml-8-principles-8-detectors"><abbr title="Tom's Obvious, Minimal Language">TOML</abbr> — 8 Principles, 8 Detectors<a class="headerlink" href="#toml-8-principles-8-detectors" title="Permanent link">¶</a></h2> <table> <thead> <tr> <th>Rule ID</th> <th>Principle</th> <th>Category</th> <th style="text-align: center;">Severity</th> <th>Dogma</th> </tr> </thead> <tbody> <tr> <td><code>toml-001</code></td> <td>Avoid inline tables</td> <td>Readability</td> <td style="text-align: center;">6</td> <td><code>ZEN-UNAMBIGUOUS-NAME</code></td> </tr> <tr> <td><code>toml-002</code></td> <td>Avoid duplicate keys</td> <td>Correctness</td> <td style="text-align: center;">8</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>toml-003</code></td> <td>Use lowercase keys</td> <td>Consistency</td> <td style="text-align: center;">5</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>toml-004</code></td> <td>Avoid trailing commas</td> <td>Readability</td> <td style="text-align: center;">5</td> <td><code>ZEN-UNAMBIGUOUS-NAME</code></td> </tr> <tr> <td><code>toml-005</code></td> <td>Clarity is paramount</td> <td>Clarity</td> <td style="text-align: center;">5</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>toml-006</code></td> <td>Order implies importance</td> <td>Organization</td> <td style="text-align: center;">4</td> <td><code>ZEN-STRICT-FENCES</code></td> </tr> <tr> <td><code>toml-007</code></td> <td>Time is specific</td> <td>Correctness</td> <td style="text-align: center;">6</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>toml-008</code></td> <td>Floats are not integers</td> <td>Correctness</td> <td style="text-align: center;">6</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> </tbody> </table> <details class="info"> <summary><code>toml-001</code> — Avoid inline tables</summary> <p><strong>Inline tables are harder to read; use full tables instead.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Inline table definitions in assignments</li> </ul> </details> <details class="info"> <summary><code>toml-002</code> — Avoid duplicate keys</summary> <p><strong>Duplicate keys can overwrite previous values.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Duplicate key definitions</li> </ul> </details> <details class="info"> <summary><code>toml-003</code> — Use lowercase keys</summary> <p><strong>Lowercase keys improve consistency across configurations.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Uppercase characters in keys</li> </ul> </details> <details class="info"> <summary><code>toml-004</code> — Avoid trailing commas</summary> <p><strong>Trailing commas reduce readability in <abbr title="Tom's Obvious, Minimal Language">TOML</abbr> arrays/tables.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Trailing commas before closing brackets</li> </ul> </details> <details class="info"> <summary><code>toml-005</code> — Clarity is paramount</summary> <p><strong>Explain magic values with comments.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Magic values without comments</li> </ul> <p><strong>Thresholds:</strong></p> <table> <thead> <tr> <th>Parameter</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>min_comment_lines</code></td> <td><code>1</code></td> </tr> </tbody> </table> </details> <details class="info"> <summary><code>toml-006</code> — Order implies importance</summary> <p><strong>Group related keys together before arrays or tables.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-STRICT-FENCES</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Repeated table headers spread apart</li> </ul> </details> <details class="info"> <summary><code>toml-007</code> — Time is specific</summary> <p><strong>Use <abbr title="International Organization for Standardization">ISO</abbr> 8601 timestamps for dates.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Non-<abbr title="International Organization for Standardization">ISO</abbr> date strings</li> </ul> </details> <details class="info"> <summary><code>toml-008</code> — Floats are not integers</summary> <p><strong>Use integer types where appropriate, avoid decimal .0 values.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Floats that represent integers</li> </ul> </details> <table> <thead> <tr> <th>Detector</th> <th>What It Catches</th> </tr> </thead> <tbody> <tr> <td><strong>TomlNoInlineTablesDetector</strong></td> <td>Flags inline table syntax (<code>key = { ... }</code>) that should use full table sections</td> </tr> <tr> <td><strong>TomlDuplicateKeysDetector</strong></td> <td>Catches repeated bare keys within the same scope of a <abbr title="Tom's Obvious, Minimal Language">TOML</abbr> file</td> </tr> <tr> <td><strong>TomlLowercaseKeysDetector</strong></td> <td>Enforces lowercase key names throughout the <abbr title="Tom's Obvious, Minimal Language">TOML</abbr> document</td> </tr> <tr> <td><strong>TomlTrailingCommasDetector</strong></td> <td>Detects trailing commas inside <abbr title="Tom's Obvious, Minimal Language">TOML</abbr> arrays and inline tables</td> </tr> <tr> <td><strong>TomlCommentClarityDetector</strong></td> <td>Ensures <abbr title="Tom's Obvious, Minimal Language">TOML</abbr> files with non-trivial configuration include explanatory comments</td> </tr> <tr> <td><strong>TomlOrderDetector</strong></td> <td>Detects poorly grouped table sections that are separated by excessive whitespace</td> </tr> <tr> <td><strong>TomlIsoDatetimeDetector</strong></td> <td>Enforces <abbr title="International Organization for Standardization">ISO</abbr> 8601 datetime formatting in quoted <abbr title="Tom's Obvious, Minimal Language">TOML</abbr> string values</td> </tr> <tr> <td><strong>TomlFloatIntegerDetector</strong></td> <td>Flags float literals ending in <code>.0</code> that should be plain integers</td> </tr> </tbody> </table> <hr /> <h2 id="xml-6-principles-6-detectors"><abbr title="eXtensible Markup Language">XML</abbr> — 6 Principles, 6 Detectors<a class="headerlink" href="#xml-6-principles-6-detectors" title="Permanent link">¶</a></h2> <table> <thead> <tr> <th>Rule ID</th> <th>Principle</th> <th>Category</th> <th style="text-align: center;">Severity</th> <th>Dogma</th> </tr> </thead> <tbody> <tr> <td><code>xml-001</code></td> <td>Mark up meaning, not presentation</td> <td>Clarity</td> <td style="text-align: center;">5</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>xml-002</code></td> <td>Attributes for metadata, Elements for data</td> <td>Structure</td> <td style="text-align: center;">5</td> <td><code>ZEN-RETURN-EARLY</code></td> </tr> <tr> <td><code>xml-003</code></td> <td>Namespaces prevent local collisions</td> <td>Correctness</td> <td style="text-align: center;">6</td> <td><code>ZEN-EXPLICIT-INTENT</code>, <code>ZEN-UNAMBIGUOUS-NAME</code>, <code>ZEN-STRICT-FENCES</code></td> </tr> <tr> <td><code>xml-004</code></td> <td>Validity supersedes well-formedness</td> <td>Correctness</td> <td style="text-align: center;">6</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>xml-005</code></td> <td>Hierarchy represents ownership</td> <td>Structure</td> <td style="text-align: center;">4</td> <td><code>ZEN-RETURN-EARLY</code></td> </tr> <tr> <td><code>xml-006</code></td> <td>Closing tags complete the thought</td> <td>Correctness</td> <td style="text-align: center;">5</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> </tbody> </table> <details class="info"> <summary><code>xml-001</code> — Mark up meaning, not presentation</summary> <p><strong>Prefer semantic tags over presentational markup.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Deprecated presentational tags or style attributes</li> </ul> </details> <details class="info"> <summary><code>xml-002</code> — Attributes for metadata, Elements for data</summary> <p><strong>Use attributes for metadata and elements for structured data.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-RETURN-EARLY</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Large text content stored in attributes</li> </ul> </details> <details class="info"> <summary><code>xml-003</code> — Namespaces prevent local collisions</summary> <p><strong>Declare namespaces when using prefixed elements.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code>, <code>ZEN-UNAMBIGUOUS-NAME</code>, <code>ZEN-STRICT-FENCES</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Prefixed elements without xmlns declarations</li> </ul> </details> <details class="info"> <summary><code>xml-004</code> — Validity supersedes well-formedness</summary> <p><strong>Provide schema references for validation.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Missing schema declaration</li> </ul> </details> <details class="info"> <summary><code>xml-005</code> — Hierarchy represents ownership</summary> <p><strong>Use nested structures to represent ownership.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-RETURN-EARLY</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Flat repeated elements without grouping</li> </ul> </details> <details class="info"> <summary><code>xml-006</code> — Closing tags complete the thought</summary> <p><strong>Avoid self-closing tags when content is expected.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Self-closing tags for non-empty elements</li> </ul> </details> <table> <thead> <tr> <th>Detector</th> <th>What It Catches</th> </tr> </thead> <tbody> <tr> <td><strong>XmlSemanticMarkupDetector</strong></td> <td>Flags presentational <abbr title="HyperText Markup Language">HTML</abbr>-era tags and inline style attributes in <abbr title="eXtensible Markup Language">XML</abbr></td> </tr> <tr> <td><strong>XmlAttributeUsageDetector</strong></td> <td>Identifies oversized attribute values that belong in child elements instead</td> </tr> <tr> <td><strong>XmlNamespaceDetector</strong></td> <td>Detects prefixed element names that lack a corresponding <code>xmlns</code> declaration</td> </tr> <tr> <td><strong>XmlValidityDetector</strong></td> <td>Checks for schema or <abbr title="Document Type Definition">DTD</abbr> references that enable structural validation</td> </tr> <tr> <td><strong>XmlHierarchyDetector</strong></td> <td>Flags repeated sibling elements that lack a grouping parent container</td> </tr> <tr> <td><strong>XmlClosingTagsDetector</strong></td> <td>Identifies self-closing tags (<code><tag /></code>) where explicit closing tags are preferred</td> </tr> </tbody> </table> <hr /> <h2 id="yaml-8-principles-8-detectors"><abbr title="YAML Ain't Markup Language">YAML</abbr> — 8 Principles, 8 Detectors<a class="headerlink" href="#yaml-8-principles-8-detectors" title="Permanent link">¶</a></h2> <table> <thead> <tr> <th>Rule ID</th> <th>Principle</th> <th>Category</th> <th style="text-align: center;">Severity</th> <th>Dogma</th> </tr> </thead> <tbody> <tr> <td><code>yaml-001</code></td> <td>Use consistent indentation</td> <td>Readability</td> <td style="text-align: center;">6</td> <td><code>ZEN-UNAMBIGUOUS-NAME</code></td> </tr> <tr> <td><code>yaml-002</code></td> <td>Avoid tabs in indentation</td> <td>Readability</td> <td style="text-align: center;">7</td> <td><code>ZEN-UNAMBIGUOUS-NAME</code></td> </tr> <tr> <td><code>yaml-003</code></td> <td>Avoid duplicate keys</td> <td>Correctness</td> <td style="text-align: center;">8</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>yaml-004</code></td> <td>Use lowercase keys</td> <td>Consistency</td> <td style="text-align: center;">5</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>yaml-005</code></td> <td>Keys should be self-explanatory</td> <td>Naming</td> <td style="text-align: center;">5</td> <td><code>ZEN-UNAMBIGUOUS-NAME</code></td> </tr> <tr> <td><code>yaml-006</code></td> <td>Consistency provides comfort</td> <td>Consistency</td> <td style="text-align: center;">5</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> <tr> <td><code>yaml-007</code></td> <td>Comments explain intent</td> <td>Documentation</td> <td style="text-align: center;">4</td> <td><code>ZEN-UNAMBIGUOUS-NAME</code></td> </tr> <tr> <td><code>yaml-008</code></td> <td>Strings should look like strings</td> <td>Clarity</td> <td style="text-align: center;">6</td> <td><code>ZEN-EXPLICIT-INTENT</code></td> </tr> </tbody> </table> <details class="info"> <summary><code>yaml-001</code> — Use consistent indentation</summary> <p><strong>Indentation should be consistent to avoid structural mistakes.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Mixed indentation widths</li> <li>Indentation not aligned to expected spaces</li> </ul> <p><strong>Thresholds:</strong></p> <table> <thead> <tr> <th>Parameter</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>indent_size</code></td> <td><code>2</code></td> </tr> </tbody> </table> </details> <details class="info"> <summary><code>yaml-002</code> — Avoid tabs in indentation</summary> <p><strong><abbr title="YAML Ain't Markup Language">YAML</abbr> indentation should use spaces, not tabs.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Tab characters in indentation</li> </ul> <p><strong>Detectable Patterns:</strong></p> <ul> <li><code></code></li> </ul> </details> <details class="info"> <summary><code>yaml-003</code> — Avoid duplicate keys</summary> <p><strong>Duplicate keys can cause data loss when parsing.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Duplicate mapping keys</li> </ul> </details> <details class="info"> <summary><code>yaml-004</code> — Use lowercase keys</summary> <p><strong>Lowercase keys improve consistency across configurations.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Uppercase characters in keys</li> </ul> </details> <details class="info"> <summary><code>yaml-005</code> — Keys should be self-explanatory</summary> <p><strong>Prefer descriptive keys over terse abbreviations.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Single-letter or cryptic keys</li> </ul> <p><strong>Thresholds:</strong></p> <table> <thead> <tr> <th>Parameter</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>min_key_length</code></td> <td><code>3</code></td> </tr> </tbody> </table> </details> <details class="info"> <summary><code>yaml-006</code> — Consistency provides comfort</summary> <p><strong>Use a consistent list style throughout the file.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Mixed list markers (- and *)</li> </ul> <p><strong>Thresholds:</strong></p> <table> <thead> <tr> <th>Parameter</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>allowed_list_markers</code></td> <td><code>['-']</code></td> </tr> </tbody> </table> </details> <details class="info"> <summary><code>yaml-007</code> — Comments explain intent</summary> <p><strong>Document complex sections with comments.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-UNAMBIGUOUS-NAME</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>No comments in a complex configuration</li> </ul> <p><strong>Thresholds:</strong></p> <table> <thead> <tr> <th>Parameter</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>min_comment_lines</code></td> <td><code>1</code></td> </tr> <tr> <td><code>min_nonempty_lines</code></td> <td><code>5</code></td> </tr> </tbody> </table> </details> <details class="info"> <summary><code>yaml-008</code> — Strings should look like strings</summary> <p><strong>Quote strings with spaces or special characters.</strong></p> <p><strong>Universal Dogmas:</strong> <code>ZEN-EXPLICIT-INTENT</code></p> <p><strong>Common Violations:</strong></p> <ul> <li>Unquoted strings with special characters</li> </ul> <p><strong>Thresholds:</strong></p> <table> <thead> <tr> <th>Parameter</th> <th>Default</th> </tr> </thead> <tbody> <tr> <td><code>require_quotes_for_specials</code></td> <td><code>True</code></td> </tr> </tbody> </table> </details> <table> <thead> <tr> <th>Detector</th> <th>What It Catches</th> </tr> </thead> <tbody> <tr> <td><strong>YamlIndentationDetector</strong></td> <td>Enforces uniform indentation width across all non-blank, non-comment lines</td> </tr> <tr> <td><strong>YamlNoTabsDetector</strong></td> <td>Detects tab characters anywhere in <abbr title="YAML Ain't Markup Language">YAML</abbr> content</td> </tr> <tr> <td><strong>YamlDuplicateKeysDetector</strong></td> <td>Catches repeated top-level mapping keys that cause silent data loss</td> </tr> <tr> <td><strong>YamlLowercaseKeysDetector</strong></td> <td>Enforces lowercase mapping keys throughout the <abbr title="YAML Ain't Markup Language">YAML</abbr> document</td> </tr> <tr> <td><strong>YamlKeyClarityDetector</strong></td> <td>Flags overly short mapping keys that sacrifice readability for brevity</td> </tr> <tr> <td><strong>YamlConsistencyDetector</strong></td> <td>Ensures a single, consistent list-marker style is used throughout the document</td> </tr> <tr> <td><strong>YamlCommentIntentDetector</strong></td> <td>Ensures complex <abbr title="YAML Ain't Markup Language">YAML</abbr> files include explanatory comments</td> </tr> <tr> <td><strong>YamlStringStyleDetector</strong></td> <td>Flags unquoted string values that contain spaces or special <abbr title="YAML Ain't Markup Language">YAML</abbr> characters</td> </tr> </tbody> </table> <hr /> <h2 id="see-also">See Also<a class="headerlink" href="#see-also" title="Permanent link">¶</a></h2> <ul> <li><a href="../../configuration/">Configuration</a> — Per-language pipeline overrides</li> <li><a href="../../understanding-violations/">Understanding Violations</a> — Severity scale reference</li> </ul> <nav class="md-tags" > <a href="../../../tags/#tag:cli" class="md-tag md-tag-icon md-tag--cli">CLI</a> <a href="../../../tags/#tag:configuration" class="md-tag md-tag-icon md-tag--config">Configuration</a> <a href="../../../tags/#tag:json" class="md-tag md-tag-icon md-tag--json">JSON</a> <a href="../../../tags/#tag:toml" class="md-tag md-tag-icon md-tag--toml">TOML</a> <a href="../../../tags/#tag:xml" class="md-tag md-tag-icon md-tag--xml">XML</a> <a href="../../../tags/#tag:yaml" class="md-tag md-tag-icon md-tag--yaml">YAML</a> </nav> </article> </div> <script>var tabs=__md_get("__tabs");if(Array.isArray(tabs))e:for(var set of document.querySelectorAll(".tabbed-set")){var labels=set.querySelector(".tabbed-labels");for(var tab of tabs)for(var label of labels.getElementsByTagName("label"))if(label.innerText.trim()===tab){var input=document.getElementById(label.htmlFor);input.checked=!0;continue e}}</script> <script>var target=document.getElementById(location.hash.slice(1));target&&target.name&&(target.checked=target.name.startsWith("__tabbed_"))</script> </div> <button type="button" class="md-top md-icon" data-md-component="top" hidden> <svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-circle-arrow-up" viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/><path d="m16 12-4-4-4 4M12 16V8"/></svg> Back to top </button> </main> <footer class="md-footer"> <nav class="md-footer__inner md-grid" aria-label="Footer" > <a href="../markdown/" class="md-footer__link md-footer__link--prev" aria-label="Previous: Markdown / MDX"> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-arrow-left" viewBox="0 0 24 24"><path d="m12 19-7-7 7-7M19 12H5"/></svg> </div> <div class="md-footer__title"> <span class="md-footer__direction"> Previous </span> <div class="md-ellipsis"> Markdown / MDX </div> </div> </a> <a href="../../understanding-violations/" class="md-footer__link md-footer__link--next" aria-label="Next: Understanding Violations"> <div class="md-footer__title"> <span class="md-footer__direction"> Next </span> <div class="md-ellipsis"> Understanding Violations </div> </div> <div class="md-footer__button md-icon"> <svg xmlns="http://www.w3.org/2000/svg" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" class="lucide lucide-arrow-right" viewBox="0 0 24 24"><path d="M5 12h14M12 5l7 7-7 7"/></svg> </div> </a> </nav> <div class="md-footer-meta md-typeset"> <div class="md-footer-meta__inner md-grid"> <div class="md-copyright"> <div class="md-copyright__highlight"> © 2026 MCP Zen of Languages contributors </div> </div> <div class="md-social"> <a href="https://github.com/Anselmoo/mcp-zen-of-languages" target="_blank" rel="noopener" title="github.com" class="md-social__link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512"><!--! Font Awesome Free 7.3.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2026 Fonticons, Inc.--><path fill="currentColor" d="M216.5 362.5c-66-8-112.5-55.5-112.5-117 0-25 9-52 24-70-6.5-16.5-5.5-51.5 2-66 20-2.5 47 8 63 22.5 19-6 39-9 63.5-9s44.5 3 62.5 8.5c15.5-14 43-24.5 63-22 7 13.5 8 48.5 1.5 65.5 16 19 24.5 44.5 24.5 70.5 0 61.5-46.5 108-113.5 116.5 17 11 28.5 35 28.5 62.5v52c0 15 12.5 23.5 27.5 17.5C441 459.5 512 369 512 257 512 115.5 397 0 255.5 0S0 115.5 0 257c0 111 70.5 203 165.5 237.5 13.5 5 26.5-4 26.5-17.5v-40c-7 3-16 5-24 5-33 0-52.5-18-66.5-51.5-5.5-13.5-11.5-21.5-23-23-6-.5-8-3-8-6 0-6 10-10.5 20-10.5 14.5 0 27 9 40 27.5 10 14.5 20.5 21 33 21s20.5-4.5 32-16c8.5-8.5 15-16 21-21"/></svg> </a> <a href="https://pypi.org/project/mcp-zen-of-languages/" target="_blank" rel="noopener" title="pypi.org" class="md-social__link"> <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 448 512"><!--! Font Awesome Free 7.3.1 by @fontawesome - https://fontawesome.com License - https://fontawesome.com/license/free (Icons: CC BY 4.0, Fonts: SIL OFL 1.1, Code: MIT License) Copyright 2026 Fonticons, Inc.--><path fill="currentColor" d="M439.8 200.5c-7.7-30.9-22.3-54.2-53.4-54.2h-40.1v47.4c0 36.8-31.2 67.8-66.8 67.8H172.7c-29.2 0-53.4 25-53.4 54.3v101.8c0 29 25.2 46 53.4 54.3 33.8 9.9 66.3 11.7 106.8 0 26.9-7.8 53.4-23.5 53.4-54.3v-40.7H226.2v-13.6h160.2c31.1 0 42.6-21.7 53.4-54.2 11.2-33.5 10.7-65.7 0-108.6M286.2 444.7a20.4 20.4 0 1 1 0-40.7 20.4 20.4 0 1 1 0 40.7M167.8 248.1h106.8c29.7 0 53.4-24.5 53.4-54.3V91.9c0-29-24.4-50.7-53.4-55.6-35.8-5.9-74.7-5.6-106.8.1-45.2 8-53.4 24.7-53.4 55.6v40.7h106.9v13.6h-147c-31.1 0-58.3 18.7-66.8 54.2-9.8 40.7-10.2 66.1 0 108.6 7.6 31.6 25.7 54.2 56.8 54.2H101v-48.8c0-35.3 30.5-66.4 66.8-66.4m-6.6-183.4a20.4 20.4 0 1 1 0 40.8 20.4 20.4 0 1 1 0-40.8"/></svg> </a> </div> </div> </div> </footer> </div> <div class="md-dialog" data-md-component="dialog"> <div class="md-dialog__inner md-typeset"></div> </div> <script id="__config" type="application/json">{"annotate":null,"base":"../../..","features":["navigation.instant","navigation.instant.prefetch","navigation.tracking","navigation.tabs","navigation.tabs.sticky","navigation.sections","navigation.indexes","navigation.expand","navigation.top","navigation.footer","navigation.path","toc.follow","content.code.copy","content.code.annotate","content.code.select","content.tabs.link","content.action.edit","content.action.view","content.tooltips","search.suggest","search.highlight","search.share","header.autohide","announce.dismiss"],"search":"../../../assets/javascripts/workers/search.7d14d953.min.js","tags":{"API":"api","Bash":"bash","C#":"csharp","C++":"cpp","CLI":"cli","CSS":"css","Configuration":"config","Docker Compose":"docker_compose","Dockerfile":"dockerfile","Go":"go","JSON":"json","JavaScript":"javascript","LaTeX":"latex","MCP":"mcp","Markdown":"markdown","PowerShell":"powershell","Python":"python","Ruby":"ruby","Rust":"rust","TOML":"toml","Terraform":"terraform","TypeScript":"typescript","XML":"xml","YAML":"yaml"},"translations":{"clipboard.copied":"Copied to clipboard","clipboard.copy":"Copy to clipboard","search.result.more.one":"1 more on this page","search.result.more.other":"# more on this page","search.result.none":"No matching documents","search.result.one":"1 matching document","search.result.other":"# matching documents","search.result.placeholder":"Type to start searching","search.result.term.missing":"Missing","select.version":"Select version"},"version":null}</script> <script src="../../../assets/javascripts/bundle.6970bfe9.min.js"></script> <script src="../../../javascripts/mathjax.js"></script> <script src="../../../javascripts/extra.js"></script> <script src="https://unpkg.com/mathjax@3/es5/tex-mml-chtml.js"></script> </body> </html>