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

> Learn how HVE Core uses JSON schema validation to enforce quality for AI artifacts, ensuring metadata contracts are met before publication or consumption.

- Repository: [Microsoft/hve-core](https://github.com/microsoft/hve-core)
- Tags: how-to-guide
- Published: 2026-03-09

---

**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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/docs-frontmatter.schema.json), while skill definitions map to [`skill-frontmatter.schema.json`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/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:

```powershell

# 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:

```powershell

# 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`](https://github.com/microsoft/hve-core/blob/main/scripts/linting/schemas/prompt-frontmatter.schema.json) and add:

```json
"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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/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`](https://github.com/microsoft/hve-core/blob/main/schema-mapping.json) file maps file glob patterns (e.g., `docs/**/*.md`) to specific schema files like [`skill-frontmatter.schema.json`](https://github.com/microsoft/hve-core/blob/main/skill-frontmatter.schema.json) or [`prompt-frontmatter.schema.json`](https://github.com/microsoft/hve-core/blob/main/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.