Skip to content

Configuration Formats

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:

  • Oversized inline arrays
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" > <span class="md-tag md-tag-icon md-tag--json">JSON</span> <span class="md-tag md-tag-icon md-tag--toml">TOML</span> <span class="md-tag md-tag-icon md-tag--xml">XML</span> <span class="md-tag md-tag-icon md-tag--yaml">YAML</span> </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.2.0 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="M173.9 397.4c0 2-2.3 3.6-5.2 3.6-3.3.3-5.6-1.3-5.6-3.6 0-2 2.3-3.6 5.2-3.6 3-.3 5.6 1.3 5.6 3.6m-31.1-4.5c-.7 2 1.3 4.3 4.3 4.9 2.6 1 5.6 0 6.2-2s-1.3-4.3-4.3-5.2c-2.6-.7-5.5.3-6.2 2.3m44.2-1.7c-2.9.7-4.9 2.6-4.6 4.9.3 2 2.9 3.3 5.9 2.6 2.9-.7 4.9-2.6 4.6-4.6-.3-1.9-3-3.2-5.9-2.9M252.8 8C114.1 8 8 113.3 8 252c0 110.9 69.8 205.8 169.5 239.2 12.8 2.3 17.3-5.6 17.3-12.1 0-6.2-.3-40.4-.3-61.4 0 0-70 15-84.7-29.8 0 0-11.4-29.1-27.8-36.6 0 0-22.9-15.7 1.6-15.4 0 0 24.9 2 38.6 25.8 21.9 38.6 58.6 27.5 72.9 20.9 2.3-16 8.8-27.1 16-33.7-55.9-6.2-112.3-14.3-112.3-110.5 0-27.5 7.6-41.3 23.6-58.9-2.6-6.5-11.1-33.3 2.6-67.9 20.9-6.5 69 27 69 27 20-5.6 41.5-8.5 62.8-8.5s42.8 2.9 62.8 8.5c0 0 48.1-33.6 69-27 13.7 34.7 5.2 61.4 2.6 67.9 16 17.7 25.8 31.5 25.8 58.9 0 96.5-58.9 104.2-114.8 110.5 9.2 7.9 17 22.9 17 46.4 0 33.7-.3 75.4-.3 83.6 0 6.5 4.6 14.4 17.3 12.1C436.2 457.8 504 362.9 504 252 504 113.3 391.5 8 252.8 8M105.2 352.9c-1.3 1-1 3.3.7 5.2 1.6 1.6 3.9 2.3 5.2 1 1.3-1 1-3.3-.7-5.2-1.6-1.6-3.9-2.3-5.2-1m-10.8-8.1c-.7 1.3.3 2.9 2.3 3.9 1.6 1 3.6.7 4.3-.7.7-1.3-.3-2.9-2.3-3.9-2-.6-3.6-.3-4.3.7m32.4 35.6c-1.6 1.3-1 4.3 1.3 6.2 2.3 2.3 5.2 2.6 6.5 1 1.3-1.3.7-4.3-1.3-6.2-2.2-2.3-5.2-2.6-6.5-1m-11.4-14.7c-1.6 1-1.6 3.6 0 5.9s4.3 3.3 5.6 2.3c1.6-1.3 1.6-3.9 0-6.2-1.4-2.3-4-3.3-5.6-2"/></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.2.0 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.e2d2d235.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.91a19a9e.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>