Summary

The frontmatter validation script applies the wrong schema to README.md files in subdirectories, causing false positive warnings.

Root Cause

The Get-SchemaForFile function in scripts/linting/Validate-MarkdownFrontmatter.ps1 has a pattern matching issue:

# Line 270-271: Root file pattern check
if ($rule.pattern -match '\|') {
    $patterns = $rule.pattern -split '\|'
    if ($fileName -in $patterns) {  # ← Matches README.md in ANY location

When a file is named README.md, it matches the root pattern README.md|CONTRIBUTING.md|... regardless of which directory it's in.

Impact

Files incorrectly validated with root-community-frontmatter.schema.json:

• docs/getting-started/README.md (should use docs-frontmatter.schema.json)
• docs/rpi/README.md (should use docs-frontmatter.schema.json)
• docs/contributing/README.md (should use docs-frontmatter.schema.json)
• .github/chatmodes/README.md (should use a github schema)
• .github/prompts/README.md (should use a github schema)
• .devcontainer/README.md (should use a devcontainer schema or base)

Current Warnings

WARNING: JSON Schema validation errors in docs/getting-started/README.md:
WARNING:   - Field 'ms.topic' must be one of: overview, concept, reference. Got: tutorial

The tutorial value IS valid in docs-frontmatter.schema.json, but the wrong schema is being applied.

Proposed Fix

Task 1: Fix pattern matching order in schema-mapping.json

Process more specific patterns before generic ones:

{
  "mappings": [
    { "pattern": ".github/**/*.md", "schema": "..." },
    { "pattern": "docs/**/*.md", "schema": "docs-frontmatter.schema.json" },
    { "pattern": ".devcontainer/**/*.md", "schema": "..." },
    { "pattern": "README.md|CONTRIBUTING.md|...", "scope": "root-only", "schema": "root-community-frontmatter.schema.json" }
  ]
}

Task 2: Update Get-SchemaForFile logic

• Check directory scope before matching filename patterns
• Process glob patterns (docs/**/*.md) before pipe-separated filename patterns
• Only apply root pattern to files actually in repo root

Task 3: Expand ms.topic enum values

Related

Discovered during PR #102