tomevault-io FAF Validate - Format Compliance Verification
Purpose
Verify that project.faf files comply with the IANA-registered application/vnd.faf+yaml specification. Catches syntax errors, missing required fields, and format violations before they cause issues.
The Goal: 100% format compliance. Zero errors. Championship-grade validation.
When to Use
This skill activates automatically when the user:
- Says "Validate my project.faf"
- Says "Check my FAF format"
- Says "Is my project.faf correct?"
- Before publishing or sharing project.faf
- After manual edits to project.faf
- When scoring fails unexpectedly
- When sync produces errors
- Asks "Does this follow the spec?"
Trigger Words: validate, check, verify, correct, compliant, spec, format, errors
How It Works
Step 1: Check File Exists
ls -la project.faf
If missing, suggest running faf init (use faf-init skill).
Step 2: Execute Validation
Run the existing validation command:
faf validate
This command (from faf-cli v5.0.6):
- Parses YAML syntax
- Checks required fields
- Verifies format version
- Validates IANA media type
- Checks field types and values
- Reports all errors and warnings
Step 3: Parse Results
Validation output includes:
✅ Success:
✓ Valid YAML syntax
✓ Format version 3.0.0
✓ IANA media type: application/vnd.faf+yaml
✓ All required fields present
✓ No errors
project.faf is valid!
❌ Errors:
✗ YAML syntax error: line 15, unexpected character
✗ Missing required field: name
✗ Invalid format_version: 2.5.0 (expected 3.0.0+)
✗ Missing IANA media type in metadata
project.faf has 4 errors
Step 4: Report to User
If valid:
- Congratulate user
- Show compliance status
- Suggest next steps (score, enhance, sync)
If errors:
- List all errors clearly
- Explain each error
- Provide fix guidance
- Offer to help correct
Step 5: Fix Errors (If Needed)
Guide user through fixing each error:
- YAML syntax: Show correct syntax
- Missing fields: Provide templates
- Invalid values: Explain valid options
- Format version: Update metadata
Validation Rules
Required Fields
Critical (must exist):
name: project-name # Required: string
purpose: What this project does # Required: string
version: 1.0.0 # Required: semver
metadata:
format_version: 3.0.0 # Required: 3.0.0+
iana_media_type: application/vnd.faf+yaml # Required: exact string
architecture:
type: web-app # Required: valid type
language: TypeScript # Required: string
Important (recommended):
stack:
runtime: Node.js 18+ # Recommended
framework: Next.js 14 # Recommended
testing:
framework: Jest # Recommended
Valid Architecture Types
Allowed values for architecture.type:
web-applibraryapiclimobile-appdesktop-appserviceframeworktoolextension
Format Version Requirements
Current: 3.0.0 (as of faf-cli v5.0.6)
History:
- v1.x: Original format (deprecated)
- v2.x: Added metadata section (deprecated)
- v3.x: IANA registration, full specification (current)
Migration: If project.faf uses old version:
# Auto-upgrade
faf migrate
# Or manually update:
metadata:
format_version: 3.0.0 # Changed from 2.x
iana_media_type: application/vnd.faf+yaml # Added
IANA Media Type
Required exact string:
metadata:
iana_media_type: application/vnd.faf+yaml
Why it matters:
- Official Internet standard (registered Oct 31, 2025)
- Same recognition as PDF, JSON, XML
- Browsers/email clients recognize .faf files
- Universal format authority
Common mistakes:
- ❌
iana_media_type: faf - ❌
iana_media_type: application/faf - ❌
media_type: application/vnd.faf+yaml - ✅
iana_media_type: application/vnd.faf+yaml
YAML Syntax Rules
Valid YAML:
name: my-project
purpose: AI-powered code analysis
stack:
runtime: Node.js 18+
framework: Next.js 14
dependencies:
- react: "^18.2.0"
- typescript: "^5.3.3"
Common errors:
# ❌ Tabs (YAML requires spaces)
name: my-project
# ❌ Missing colon
name my-project
# ❌ Incorrect indentation
stack:
runtime: Node.js
# ❌ Missing quotes on special chars
purpose: Here's my project # apostrophe breaks parsing
# ✅ Correct
purpose: "Here's my project"
Examples
Example 1: Successful Validation
User: "Validate my project.faf"
Skill Activates:
faf validate
# Output:
✓ Valid YAML syntax
✓ Format version 3.0.0
✓ IANA media type: application/vnd.faf+yaml
✓ All required fields present
✓ Architecture type valid: web-app
✓ No warnings
project.faf is valid!
AI-readiness: 72% (Gold tier)
Report: "Excellent! Your project.faf is fully compliant with the IANA-registered specification (application/vnd.faf+yaml). No errors found. You're ready to share, sync, or publish this file."
Example 2: YAML Syntax Error
User: "Check my FAF format"
Skill Activates:
faf validate
# Output:
✗ YAML syntax error on line 23:
Unexpected character ':'
21 | testing:
22 | framework: Jest
23 | coverage:: 78%
^----------- Extra colon here
project.faf has 1 error
Fix guidance: "YAML syntax error found on line 23. You have an extra colon after 'coverage'.
Incorrect:
coverage:: 78%
Correct:
coverage: 78%
Remove one colon and re-validate."
Example 3: Missing Required Fields
User: "Is my project.faf correct?"
Skill Activates:
faf validate
# Output:
✗ Missing required field: metadata.format_version
✗ Missing required field: metadata.iana_media_type
✗ Missing required field: architecture.type
project.faf has 3 errors
Fix guidance: "Your project.faf is missing 3 required fields. Add this metadata section:
metadata:
format_version: 3.0.0
iana_media_type: application/vnd.faf+yaml
created: 2025-11-02
architecture:
type: web-app # Or: library, api, cli, etc.
language: [your language]
framework: [your framework]
After adding these fields, run faf validate again."
Example 4: Format Version Mismatch
User: "Validate my FAF"
Skill Activates:
faf validate
# Output:
⚠ Warning: Old format version detected
Current: 2.1.0
Latest: 3.0.0
Run `faf migrate` to upgrade to latest format.
✗ Missing IANA media type (required in v3.0.0+)
project.faf has 1 error, 1 warning
Fix guidance: "Your project.faf uses format version 2.1.0 (old). The current version is 3.0.0 which includes IANA registration.
Option 1: Auto-migrate (recommended)
faf migrate
This will automatically upgrade your format to 3.0.0.
Option 2: Manual upgrade Update metadata section:
metadata:
format_version: 3.0.0 # Changed from 2.1.0
iana_media_type: application/vnd.faf+yaml # Added (required in 3.0.0+)
After migrating, run faf validate to confirm."
Validation Workflow
Before Sharing/Publishing
# 1. Validate format
faf validate
# 2. Check AI-readiness score
faf score
# 3. Sync to CLAUDE.md
faf bi-sync
# 4. Final validation
faf validate
# 5. Ready to share!
After Manual Edits
# Every time you manually edit project.faf:
faf validate
# If errors found:
# - Fix errors
# - Re-validate
# - Repeat until clean
Before Git Commit
# Pre-commit hook (optional):
#!/bin/bash
if [ -f project.faf ]; then
faf validate || exit 1
fi
This prevents committing invalid project.faf files.
Verification & Troubleshooting
Success Indicators
✅ Zero errors reported ✅ Zero warnings (or only minor warnings) ✅ Format version 3.0.0+ ✅ IANA media type present ✅ All required fields exist ✅ Valid YAML syntax
Common Issues
Issue: "YAML syntax error" but file looks correct
# Solution: Check for hidden characters
cat -A project.faf | head -30
# Look for:
# - Tabs (^I) instead of spaces
# - Unusual line endings
# - Non-ASCII characters
# Fix with proper editor (VS Code, Sublime, etc.)
Issue: Validation says field required but it exists
# Solution: Check indentation
# YAML is whitespace-sensitive
# ❌ Incorrect (2 spaces instead of 4)
metadata:
format_version: 3.0.0
# ✅ Correct (consistent indentation)
metadata:
format_version: 3.0.0
Issue: "Invalid architecture type"
# Solution: Use allowed type
# Valid: web-app, library, api, cli, mobile-app, desktop-app, service
architecture:
type: web-app # Not "website" or "webapp"
Issue: Validation passes but score is low
# Solution: Validation ≠ Quality
# Validation checks format compliance
# Scoring checks content completeness
# Format valid but sparse:
name: my-project
purpose: A project
architecture:
type: web-app
language: JavaScript
# This validates ✓ but scores low (maybe 25%)
# Use `faf enhance` to improve content
Supporting Files
This skill works with:
- faf-cli (v5.0.6+) - Validation engine
- project.faf - File being validated
- IANA specification - application/vnd.faf+yaml
Related Skills
Validation integrates with:
- faf-init - Creates valid project.faf from start
- faf-migrate - Upgrades old formats to current
- faf-score - Measures content quality (validation checks format)
- faf-enhance - Improves content (validation ensures correctness)
Key Principles
Format Compliance:
- IANA-registered specification
- Strict YAML syntax
- Required fields enforced
- Version compatibility checked
Clear Error Messages:
- Line numbers shown
- Examples provided
- Fix guidance included
- Actionable feedback
Prevention Over Correction:
- Validate early, validate often
- Pre-commit hooks recommended
- Catch errors before they propagate
- Championship-grade quality gates
NO BS ZONE:
- Errors are real (not warnings disguised as errors)
- Validation is strict (not lenient)
- Compliance is measurable (not subjective)
- Standards are enforced (not suggested)
Success Metrics
When this skill succeeds, users should:
- Know if their project.faf is valid
- Understand any errors found
- Know how to fix each error
- Trust the validation process
- Feel confident sharing their file
- Maintain format compliance going forward
Quick Reference
Validate:
faf validate
Common fixes:
# YAML syntax error → Fix indentation/colons
# Missing field → Add required section
# Old format → faf migrate
# Invalid type → Use allowed architecture type
Required minimum:
name: project-name
purpose: What it does
version: 1.0.0
metadata:
format_version: 3.0.0
iana_media_type: application/vnd.faf+yaml
architecture:
type: web-app | library | api | cli
language: Your language
Generated by FAF Skill: faf-validate v1.0.0 IANA Compliance Edition "100% format compliance. Zero errors. Championship standards."
Converted and distributed by TomeVault — claim your Tome and manage your conversions.