EXAMPLES/metadata-validation

Metadata Validation

Demonstrates enforcing metadata requirements using JSON Schema validation to ensure examples have required fields like category and difficulty.

meta-yml7 FILESvalidationjson-schemaquality

Metadata Validation Example

This example demonstrates enforcing metadata requirements using JSON Schema validation.

Usage

bash

1# Scan and display examples (will show validation errors)
2npx functional-examples scan
3
4# Output as JSON to see error details
5npx functional-examples scan -f json

Configuration Schema

The config's metadata field defines a JSON Schema that all examples must satisfy:

{
  "$schema": "./.functional-examples/schema.json",
  "scan": {
    "include": ["src/**/*"],
    "exclude": ["**/node_modules/**", "**/dist/**"]
  },
  "metadata": {
    "type": "object",
    "properties": {
      "category": {
        "type": "string",
        "description": "Category for organizing examples"
      },
      "difficulty": {
        "type": "string",
        "enum": ["beginner", "intermediate", "advanced"],
        "description": "Difficulty level"
      }
    },
    "required": ["category", "difficulty"]
  }
}

text

1## Valid Metadata
2
3A passing example includes all required fields — `category` and `difficulty`:
4
5```typescript
6// ---
7// id: valid-example
8// title: Valid Example
9// description: This example has all required metadata fields
10// category: tutorials
11// difficulty: beginner
12// ---

Missing Fields

An example missing required fields will produce validation errors:

typescript

1// ---
2// id: missing-fields
3// title: Missing Required Fields
4// description: This example is missing category and difficulty
5// ---

When scanned, you'll see errors like:

text

1Errors (1):
2  - example:missing-fields: [config.metadata] must have required property 'category'

Two Levels of Validation

Plugin validators — Each plugin can define its own validator (e.g., JavaScript plugin requires id and title)
Config schema validation — The metadata JSON Schema in your config file (validated with AJV)

Both run during scanning, and all errors are collected.

Use Cases

Documentation sites — Require category for navigation
Tutorial platforms — Require difficulty for filtering
API references — Require version for versioned docs
Course content — Require chapter, order for sequencing

All Example Files

FILE EXPLORER

README.md

1# Metadata Validation Example
2
3This example demonstrates enforcing metadata requirements using JSON Schema validation.
4
5## Usage
6
7```bash
8# Scan and display examples (will show validation errors)
9npx functional-examples scan
10
11# Output as JSON to see error details
12npx functional-examples scan -f json
13```
14
15## Configuration Schema
16
17The config's `metadata` field defines a JSON Schema that all examples must satisfy:
18
19<%= file('functional-examples.config.json') %>
20
21## Valid Metadata
22
23A passing example includes all required fields — `category` and `difficulty`:
24
25```typescript
26// ---
27// id: valid-example
28// title: Valid Example
29// description: This example has all required metadata fields
30// category: tutorials
31// difficulty: beginner
32// ---
33```
34
35## Missing Fields
36
37An example missing required fields will produce validation errors:
38
39```typescript
40// ---
41// id: missing-fields
42// title: Missing Required Fields
43// description: This example is missing category and difficulty
44// ---
45```
46
47When scanned, you'll see errors like:
48
49```
50Errors (1):
51  - example:missing-fields: [config.metadata] must have required property 'category'
52```
53
54## Two Levels of Validation
55
561. **Plugin validators** — Each plugin can define its own validator (e.g., JavaScript plugin requires `id` and `title`)
572. **Config schema validation** — The `metadata` JSON Schema in your config file (validated with AJV)
58
59Both run during scanning, and all errors are collected.
60
61## Use Cases
62
63- **Documentation sites** — Require `category` for navigation
64- **Tutorial platforms** — Require `difficulty` for filtering
65- **API references** — Require `version` for versioned docs
66- **Course content** — Require `chapter`, `order` for sequencing
67