Skip to content

fix(linting): Schema mapping incorrectly applies root schema to nested README.md files #103

@WilliamBerryiii

Description

@WilliamBerryiii

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

Schema Add Values
root-community-frontmatter.schema.json guide, hub-page
docs-frontmatter.schema.json architecture, research
base-frontmatter.schema.json guide, hub-page, architecture

Related

Discovered during PR #102

Metadata

Metadata

Assignees

No one assigned

    Labels

    bugSomething isn't workinglinting

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions