Schema Validation

The Scoutica Protocol provides JSON Schema definitions for every card file. Validate cards before processing them to catch malformed data early.

Validating with Python

import json, jsonschema

# Load schema
with open('protocol/platform/01_schemas/candidate_profile.schema.json') as f:
    schema = json.load(f)

# Validate
with open('profile.json') as f:
    profile = json.load(f)

jsonschema.validate(profile, schema)  # Raises ValidationError if invalid

Install the dependency with:

python3 -m pip install 'jsonschema[format]' PyYAML

Available schemas

The schemas live in protocol/platform/01_schemas/ in the repository:

Schema file	Validates
`candidate_profile.schema.json`	`profile.json` — skills, seniority, primary domains, experience
`roe.schema.json`	`rules.yaml` — engagement types, compensation floors, remote policy, filters, privacy zones
`evidence.schema.json`	`evidence.json` — evidence items, URLs, skills demonstrated
`scoutica_discovery.schema.json`	`scoutica.json` — discovery metadata (in `schemas/` at repo root)

CLI validation

The Scoutica CLI validates an entire card directory in one command:

scoutica validate ./my-card/

This checks all card files against their schemas and reports any validation errors:

🔍 Validating Scoutica Card: /path/to/my-card

✅ SKILL.md: Valid (frontmatter present)
✅ Candidate Profile: Valid
✅ Evidence Registry: Valid
✅ Rules of Engagement: Valid
✅ rules/: All 4 rule files present

Results: 5 passed, 0 failed, 0 warnings
🎉 Card is valid!

Integration patterns

Pattern 2: ATS integration

An applicant tracking system can use the protocol to auto-populate candidate records and pre-flag offer mismatches before a recruiter even opens the profile.

sequenceDiagram
    participant ATS as ATS System
    participant GH as GitHub

    ATS->>GH: GET profile.json
    GH-->>ATS: {skills, primary_domains, seniority}
    ATS->>ATS: Auto-populate candidate record
    ATS->>GH: GET rules.yaml
    GH-->>ATS: {engagement.allowed_types, remote.policy, filters.blocked_industries}
    ATS->>ATS: Flag: "Would our offer be auto-rejected?"
    ATS->>GH: GET evidence.json
    GH-->>ATS: [{items with skills_demonstrated}]
    ATS->>ATS: Attach evidence links to candidate review

Embed a Scoutica Protocol badge on any personal website. The widget reads the card at runtime and renders a live profile summary.

{/* Scoutica Protocol badge for personal websites */}
<div id="scoutica-badge"
     data-url="https://github.com/user/my-card"
     data-theme="dark">
</div>
<script src="https://cdn.scoutica.dev/widget.js"></script>