Material Passport Schema: Core Fields in Academic Research Skills

The Material Passport schema defines five required fields—origin_skill, origin_mode, origin_date, verification_status, and version_label—that form the mandatory metadata backbone for every artifact in the Academic Research Skills pipeline.

The Material Passport serves as the cross-stage metadata record that travels with every artifact produced by the Imbad0202/academic-research-skills repository. Defined in shared/handoff_schemas.md, this schema ensures that all generated artifacts carry essential provenance information required for integrity verification and downstream processing. Understanding these core required fields is essential for developers integrating with the pipeline or extending the passport with custom metadata extensions.

Understanding the Material Passport Schema

The Material Passport (Schema 9) is designed to maintain a consistent metadata contract across all stages of the research pipeline. While the schema supports numerous optional extensions for rich provenance tracking, the core fields represent the minimal valid set that must be present for any passport to be accepted by downstream agents.

The Five Required Core Fields

According to the handoff-schema definition in shared/handoff_schemas.md (lines 85-94), every valid Material Passport must include exactly these five fields:

• origin_skill (string): The skill that created the artifact (e.g., deep-research, academic-paper).
• origin_mode (string): The mode used when the artifact was generated (e.g., full, socratic, pre-review).
• origin_date (string ISO-8601): Timestamp indicating when the artifact was produced.
• verification_status (enum): Result of the most recent integrity-verification stage. Valid values are "VERIFIED", "UNVERIFIED", or "STALE".
• version_label (string): A human-readable version identifier (e.g., v1.0, paper_draft_v2).

These five fields constitute the immutable backbone of the Material Passport schema. All other entries are optional extensions that provide richer provenance data but are not required for validation.

Material Passport Code Examples

Minimal Valid Passport (YAML)

The following example demonstrates the smallest possible valid Material Passport containing only the required fields:

# Minimal Material Passport (YAML)

origin_skill: academic-paper
origin_mode: full
origin_date: 2026-03-08T14:30:00Z
verification_status: VERIFIED
version_label: paper_draft_v2

Minimal Valid Passport (JSON)

The same required fields expressed in JSON format:

// Minimal Material Passport (JSON)
{
  "origin_skill": "academic-paper",
  "origin_mode": "full",
  "origin_date": "2026-03-08T14:30:00Z",
  "verification_status": "VERIFIED",
  "version_label": "paper_draft_v2"
}

Extended Passport with Optional Fields

A complete passport often includes optional fields for enhanced traceability:

origin_skill: academic-paper
origin_mode: full
origin_date: 2026-03-08T14:30:00Z
verification_status: VERIFIED
version_label: paper_draft_v2
integrity_pass_date: 2026-03-08T15:45:00Z
content_hash: a3f2b7c9...
repro_lock:
  lockfile: scripts/adapters/folder_scan.py
  version: 1.0
literature_corpus:
  - citation_key: smith2021
    authors: [{family: "Smith", given: "J"}]
    year: 2021
    title: "A survey of AI‑assisted assessment"
    source_pointer: "zotero://item/12345"

Optional fields such as integrity_pass_date, content_hash, repro_lock, compliance_history, literature_corpus, and audit_artifact extend the passport's utility but are not mandatory for acceptance by downstream agents.

Schema Definition and Implementation Files

The Material Passport schema is distributed across the following key files in the repository:

• shared/handoff_schemas.md: Defines the core required fields and handoff contracts for the Material Passport schema.
• shared/contracts/passport/reset_ledger_entry.schema.json: Schema definition for the optional reset_boundary extension.
• shared/contracts/passport/literature_corpus_entry.schema.json: Schema for entries in the optional literature_corpus field.
• shared/contracts/passport/audit_artifact_entry.schema.json: Schema for entries in the optional audit_artifact ledger.
• scripts/check_audit_artifact_consistency.py: Lint script that validates optional audit_artifact entries against the schema.
• scripts/check_repro_lock.py: Validator for the optional repro_lock sub-block.

Summary

• The Material Passport schema requires exactly five core fields: origin_skill, origin_mode, origin_date, verification_status, and version_label.
• These fields are formally defined in shared/handoff_schemas.md and enforce minimum metadata requirements for all pipeline artifacts.
• Optional extensions like content_hash, repro_lock, and literature_corpus provide additional provenance data but are not required for passport validation.
• Both YAML and JSON formats are supported for passport serialization.
• Downstream agents automatically reject any passport missing one or more of the five required core fields.

Frequently Asked Questions

What happens if a Material Passport is missing one of the core fields?

Downstream agents in the Academic Research Skills pipeline will reject any passport that lacks one of the five required fields defined in the Material Passport schema. These core fields form the immutable backbone necessary for integrity verification and artifact tracking across pipeline stages.

Can I add custom fields to the Material Passport schema?

Yes, custom fields can be added as extensions provided they do not conflict with the core required fields. The schema explicitly supports optional extensions such as integrity_pass_date, content_hash, and literature_corpus, with detailed schemas for these extensions located under shared/contracts/passport/.

What are the valid values for the verification_status field?

The verification_status field accepts exactly three enum values: "VERIFIED", "UNVERIFIED", or "STALE". These values represent the artifact's current integrity state following the most recent verification stage in the Academic Research Skills pipeline.

Where is the Material Passport schema formally defined?

The canonical definition of the core fields resides in shared/handoff_schemas.md (lines 85-94), with supplementary JSON Schema definitions for optional extensions located in shared/contracts/passport/. Validation scripts in scripts/check_audit_artifact_consistency.py and scripts/check_repro_lock.py ensure compliance with specific optional sub-schemas.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}