How JSON Schema Validation Enforces Quality for AI Artifacts in HVE Core

JSON schema validation in HVE Core acts as a declarative gatekeeper that guarantees every AI artifact meets a rigorously defined metadata contract before publication or consumption.

The microsoft/hve-core repository stores AI-related artifacts—skills, prompts, agents, and collections—as Markdown files with YAML frontmatter. By coupling JSON schema files with a PowerShell linting pipeline, the repository ensures that every artifact's metadata conforms to strict presence, type, and formatting requirements.

Why AI Artifacts Need Schema Validation

AI artifacts in HVE Core are consumed by runtime engines and developer tooling. Inconsistent metadata breaks discoverability, causes runtime failures, and complicates automated processing. JSON schema validation enforces structural contracts at build time, catching malformed frontmatter before it reaches production.

Without this layer, a missing description field or an invalid user-invocable boolean could propagate undetected, leading to silent failures in the execution engine.

How JSON Schema Validation Works in HVE Core

The validation pipeline orchestrates schema discovery, frontmatter parsing, and constraint checking through three coordinated stages.

Schema Discovery and Mapping

The Get-SchemaForFile function in scripts/linting/Validate-MarkdownFrontmatter.ps1 (lines 34-62) reads scripts/linting/schemas/schema-mapping.json to determine which JSON schema applies to a given file path. For example, files matching docs/**/*.md map to docs-frontmatter.schema.json, while skill definitions map to skill-frontmatter.schema.json.

Frontmatter Parsing and Validation

The Invoke-FrontmatterValidation function from scripts/linting/Modules/FrontmatterValidation.psm1 parses the YAML block of every Markdown file into a hashtable. It returns a ValidationSummary object containing the parsed frontmatter and any syntax errors.

JSON Schema Overlay Execution

When the -EnableSchemaValidation switch is present, the script calls Initialize-JsonSchemaValidation to confirm native JSON support, then iterates over each FileResult and invokes Test-JsonSchemaValidation (lines 89-122 in Validate-MarkdownFrontmatter.ps1).

This function implements a soft validator using PowerShell's ConvertFrom-Json. It walks the schema and records errors for:

• Missing required fields (e.g., name and description for skills)
• Type mismatches (e.g., user-invocable must be a boolean)
• Pattern violations (e.g., name must match ^[a-z][a-z0-9-]*$)
• Enum constraints (e.g., agent can only be ask, edit, agent, or a custom name)
• Array item validation (e.g., tools must be an array of strings)
• Composition logic (e.g., oneOf ensures exactly one sub-schema matches for complex prompt schemas)

Errors surface in CI annotations via Write-CIAnnotations and write to logs/frontmatter-validation-results.json. If validation fails, the step summary marks the build as failed when -WarningsAsErrors is enabled.

Quality Gates Enforced by JSON Schema

JSON schema validation in HVE Core enforces six critical quality dimensions:

Presence – Required fields must exist. The schema mandates fields like name and description for skills, ensuring runtime engines receive complete metadata.

Type Safety – Values must match declared types. Boolean fields like user-invocable reject string representations ("true" vs. $true), preventing type coercion bugs.

Formatting – String patterns and minimum lengths enforce naming conventions. The name field must match ^[a-z][a-z0-9-]*$, guaranteeing kebab-case consistency and valid file system paths.

Controlled Vocabulary – Enumerated values restrict fields to approved options. The agent field accepts only ask, edit, agent, or custom names, preventing invalid agent type strings.

Array Shape – Items must conform to sub-schemas. The tools array validates that every element is a string, ensuring the runtime receives properly typed tool lists.

Composition – oneOf constraints ensure exactly one sub-schema matches. This handles complex prompt schemas where different prompt types require mutually exclusive field sets.

Practical Examples

Validating a Single File

To validate a specific prompt file with schema enforcement and fail on warnings:

# Validate a prompt file and abort on any schema violations

$summary = .\scripts\linting\Validate-MarkdownFrontmatter.ps1 `
    -Files @('docs/prompts/example.prompt.md') `
    -EnableSchemaValidation `
    -WarningsAsErrors
if ($summary.GetExitCode($true) -ne 0) { exit 1 }

The -EnableSchemaValidation flag activates the JSON-Schema overlay, while -WarningsAsErrors ensures schema violations break the build.

Direct Schema Testing

For unit testing or CI scripts, invoke the validator directly against a hashtable:

# Load a schema (in-memory) and test a hashtable

$schema = Get-Content 'scripts/linting/schemas/prompt-frontmatter.schema.json' -Raw |
          ConvertFrom-Json
$frontmatter = @{
    description = 'Summarize a PR'
    name        = 'pr-summarize'
}
$result = Test-JsonSchemaValidation -Frontmatter $frontmatter -SchemaContent $schema

# Inspect results

if (-not $result.IsValid) {
    $result.Errors | ForEach-Object { Write-Error $_ }
}

This pattern allows testing frontmatter structures without writing to disk.

Extending Schema Rules

To require a new tags field (array of strings) for prompts:

1. Edit scripts/linting/schemas/prompt-frontmatter.schema.json and add:

"properties": {
  "tags": {
    "type": "array",
    "items": { "type": "string" },
    "minItems": 1,
    "description": "Keywords for searchability"
  },
  ...
},
"required": ["description", "tags"]

2. Run the validation script with -EnableSchemaValidation; any prompt missing tags will now emit an error.

Summary

• JSON schema validation in microsoft/hve-core enforces strict metadata contracts for AI artifacts stored as Markdown frontmatter.
• The Validate-MarkdownFrontmatter.ps1 script orchestrates validation, using Get-SchemaForFile for schema discovery and Test-JsonSchemaValidation for constraint checking.
• Validation covers presence, type safety, formatting, controlled vocabulary, array shape, and composition constraints.
• The -EnableSchemaValidation switch activates the JSON-Schema overlay, while -WarningsAsErrors ensures violations break CI builds.
• Schema files are located in scripts/linting/schemas/ and map to file paths via schema-mapping.json.

Frequently Asked Questions

What happens when JSON schema validation fails?

When validation fails, the Test-JsonSchemaValidation function records specific errors (missing fields, type mismatches, or pattern violations) in the validation summary. These errors surface as CI annotations via Write-CIAnnotations and write to logs/frontmatter-validation-results.json. If -WarningsAsErrors is enabled, the build step fails and blocks merge.

Can I add custom validation rules?

Yes. You can extend existing schemas by editing the JSON files in scripts/linting/schemas/. Add new properties to the "properties" object and include them in the "required" array to enforce presence. For complex logic (like conditional fields), use JSON Schema keywords such as oneOf or if-then-else. No PowerShell code changes are required for standard constraints.

Which AI artifact types support schema validation?

HVE Core supports schema validation for all Markdown-based AI artifacts, including skills, prompts, agents, and collections. The schema-mapping.json file maps file glob patterns (e.g., docs/**/*.md) to specific schema files like skill-frontmatter.schema.json or prompt-frontmatter.schema.json.

How does schema validation integrate with CI/CD?

The validation runs as a PowerShell step in CI pipelines using Validate-MarkdownFrontmatter.ps1. The script accepts -EnableSchemaValidation to activate JSON-Schema checks and -WarningsAsErrors to treat schema violations as fatal errors. Results export to JSON logs and GitHub-style annotations, allowing platforms like GitHub Actions to surface violations directly in pull request diffs.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}