# Material Passport Schema: Core Fields in Academic Research Skills

> Discover the core fields of the Material Passport schema, including origin_skill, origin_mode, and verification_status. Essential metadata for academic research artifacts.

- Repository: [Edward Cheng-I Wu/academic-research-skills](https://github.com/Imbad0202/academic-research-skills)
- Tags: api-reference
- Published: 2026-05-13

---

**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`](https://github.com/Imbad0202/academic-research-skills/blob/main/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`](https://github.com/Imbad0202/academic-research-skills/blob/main/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:

```yaml

# 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:

```json
// 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:

```yaml
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`](https://github.com/Imbad0202/academic-research-skills/blob/main/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`](https://github.com/Imbad0202/academic-research-skills/blob/main/shared/contracts/passport/reset_ledger_entry.schema.json)**: Schema definition for the optional `reset_boundary` extension.
- **[`shared/contracts/passport/literature_corpus_entry.schema.json`](https://github.com/Imbad0202/academic-research-skills/blob/main/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`](https://github.com/Imbad0202/academic-research-skills/blob/main/shared/contracts/passport/audit_artifact_entry.schema.json)**: Schema for entries in the optional `audit_artifact` ledger.
- **[`scripts/check_audit_artifact_consistency.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_audit_artifact_consistency.py)**: Lint script that validates optional `audit_artifact` entries against the schema.
- **[`scripts/check_repro_lock.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/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`](https://github.com/Imbad0202/academic-research-skills/blob/main/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`](https://github.com/Imbad0202/academic-research-skills/blob/main/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`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_audit_artifact_consistency.py) and [`scripts/check_repro_lock.py`](https://github.com/Imbad0202/academic-research-skills/blob/main/scripts/check_repro_lock.py) ensure compliance with specific optional sub-schemas.