How to validate a profile

This guide shows how to check that a profile directory conforms to the format. There are two levels of validation, and they have different requirements.

Level 1: Schema validation (core)

Schema validation answers “is this a well-formed profile?” — do the files parse, and do they satisfy the Pydantic models? This is available in a core install and happens automatically when you load a profile.

Load the profile and force every file to be read by passing eager=True:

from researcher_profiles import ResearcherProfile, ProfileLoadError

try:
    p = ResearcherProfile.from_files("path/to/jane-doe", eager=True)
    print(f"OK: {p.name}, {len(p.papers)} papers")
except ProfileLoadError as e:
    print(f"invalid: {e}")
    print("offending file:", e.path)

ProfileLoadError is raised when a file is unreadable, is not valid YAML/JSON, or fails its schema. The exception carries the offending file path and, where available, the original underlying exception.

Without eager=True, files are read lazily on first access, so a malformed papers.yaml would not surface until you touch p.papers. Use eager=True when you want validation up front.

Validate individual files against JSON Schema

To validate a profile without installing this package — for example from another language or in CI — use the JSON Schema files in schemas/ with any JSON Schema validator. In Python, with the third-party jsonschema package:

import json, yaml, jsonschema

schema = json.load(open("schemas/profile_metadata.schema.json"))
data = yaml.safe_load(open("path/to/jane-doe/profile.yaml"))
jsonschema.validate(data, schema)  # raises ValidationError on mismatch

See Export JSON Schemas for how the schema files are generated and the schema reference for which file validates which artifact.

Level 2: Quality audit (requires the build package)

The audit CLI subcommand and the ResearcherProfile.validate() method run a richer set of build-time quality contracts — for example, minimum expertise length, field-coverage thresholds on papers.yaml, and summary completeness. These checks depend on an external build package (agentpipe) that is not part of the core install. On a core-only install they raise ImportError.

When the build package is available:

researcher-profiles audit path/to/jane-doe

p = ResearcherProfile.from_files("path/to/jane-doe")
report = p.validate()            # AuditReport
print(report.summary["n_errors"], report.summary["n_warnings"])

The audit command exits non-zero when the report contains errors. Add --json for machine-readable output or --quiet to suppress OK lines. See the CLI reference.