OpenReason Protocol Specification

orp_version: "0.3"     # was "0.2"
profile: ORP-Policy    # recommended: keeps the L2 + L3 requirement explicit

ORP Document
├── Header (Required metadata; v0.3 adds `profile`)
├── attestation          (v0.3, optional — cryptographic signature; see Data Products)
├── L1: Data Provenance  (Required; v0.3 adds legal / access / freshness / reach fields)
├── L2: Consequence Simulation (required in ORP-Policy)
├── L3: Empathy Mapping        (required in ORP-Policy)
├── L4: Accountability Ledger  (v0.3 adds signed usage_records)
├── L5: Lineage          (fork registry + v0.3 derivation graph)
└── L6: usage_policy     (v0.3, optional — enforceable usage terms)

orp_version: "0.2"
document_id: "unique-identifier-001"
title: "Human-Readable Policy Title"
domain: "policy"  # or: ai-training, governance, research, other
authors:
  - name: "Author Name"
    role: "author"  # or: contributor, reviewer, analyst, reconstructor
    affiliation: "Organization Name"  # optional
created: "2026-01-01"
last_modified: "2026-01-01"
status: "draft"  # or: open-for-comment, ratified, superseded
compliance_level: "ORP-Full"  # or: ORP-Standard, ORP-Basic, ORP-PostHoc
summary: |
  Plain language description of what this document proposes,
  in 3-5 sentences. Written for a general audience.

post_hoc: true  # v0.2: Flags retrospective reconstruction
profile: ORP-Policy  # v0.3: ORP-Core | ORP-Policy | ORP-Ads | ORP-AI (default ORP-Core)
extensions:  # v0.2: Domain-specific extensions
  - "orp-ai-training-v1"
  - "orp-safety-v1"
forked_from: "parent-document-id"  # If this is a fork
license: "CC-BY-4.0"  # Licensing terms
contact: "[email protected]"  # Contact information

l1_data_provenance:
  - dataset_id: "enrollment-2024"
    name: "School Enrollment Data 2024"
    description: "What this dataset contains and why it was used"
    source: "government | academic | commercial | synthetic"
    collection_method: "How data was gathered"
    date_range: "2024-01-01 to 2024-12-31"
    geographic_scope: "Countries, regions, municipalities"
    
    inclusion_criteria:
      description: "What was included and why"
      
    exclusion_criteria:
      - "What was excluded and explicit justification"
      
    cleaning_decisions:
      - "What was done, why, and what alternatives were considered"
      
    synthetic_elements:
      present: false
      # If true: what was synthesized, how, and with what assumptions
      
    known_limitations:
      - "Explicit statement of what this dataset does not capture well"
      
    access:
      public: true
      url: "https://data.gov/dataset-id"  # if public
      
    attested_by:
      - name: "Data Steward Name"
        role: "data_manager"
        date: "2026-01-15"
        statement: "I attest this description is accurate"

l2_consequence_simulation:
  affected_population:
    description: "Who is affected by this proposal"
    size_estimate: "Approximate number"
  
  variables:
    independent:
      - variable: "funding_increase_percent"
        description: "What this variable represents"
        range: "0% to 30%"
        default_value: "15%"
    
    dependent:
      - variable: "class_size"
        description: "What we're measuring"
        unit: "students per classroom"
  
  model:
    type: "Linear regression | Agent-based | System dynamics"
    assumptions:
      - assumption: "Teacher hiring follows funding linearly"
        basis: "Historical data 2010-2024"
        sensitivity: "High - main driver of outcomes"
  
  scenarios:
    - scenario_id: "baseline"
      name: "Current Funding"
      description: "No change from 2024 levels"
      variable_values:
        funding_increase_percent: "0%"
      outcomes:
        class_size: "24.5"
    
    - scenario_id: "moderate"
      name: "15% Increase"
      description: "Proposed funding increase"
      variable_values:
        funding_increase_percent: "15%"
      outcomes:
        class_size: "21.2"
  
  primary_scenario: "moderate"

l3_empathy_mapping:
  stakeholder_map:
    - stakeholder: "Students"
      description: "How they're affected"
      estimated_population: "5.2 million"
      relationship_to_proposal: "Primary beneficiaries"
      impacts_by_scenario:
        - scenario_id: "moderate"
          direction: "positive | negative | mixed | neutral"
          magnitude: "Description of impact"
  
  minority_stress_test:
    description: "Testing impacts on underrepresented groups"
    groups_tested:
      - group: "Rural school districts"
        scenario_tested: "Moderate increase with uniform distribution"
        outcome: "Receives proportionally less benefit"
        mitigation: "Consider rural weighting factor"
  
  unresolved_impacts:
    - "Long-term effects we haven't modeled"
    - "Second-order consequences we're uncertain about"
  
  net_welfare_assessment:
    methodology: "How we assessed overall welfare"
    conclusion: "Net positive across all scenarios"
    confidence: "medium | high | low"
    confidence_basis: "Why we have this confidence level"

l4_accountability_ledger:
  entries:
    - timestamp: "2026-02-15T10:30:00Z"
      decision: "Switched from linear to log model for income effects"
      decision_maker: "Lead Analyst Name"
      role: "senior_analyst"
      basis: "Log model better fits historical data (R² = 0.89 vs 0.72)"
      affected_sections: ["l2_consequence_simulation"]
      
    - timestamp: "2026-02-20T14:00:00Z"
      decision: "Excluded private schools from dataset"
      decision_maker: "Data Manager Name"
      role: "data_steward"
      basis: "Data not available from private institutions"
      affected_sections: ["l1_data_provenance"]

l5_fork_registry:
  this_document:
    allows_forking: true
    license: "CC-BY-4.0"
    fork_invitation: "We encourage forking to test alternative assumptions"
  
  known_forks:
    - fork_id: "alt-funding-model-001"
      title: "Alternative Funding Model (Progressive)"
      authors: ["Contributor Name"]
      created: "2026-03-01"
      key_differences:
        - "Uses progressive rather than flat funding increase"
        - "Models teacher retention effects"
      url: "https://example.org/fork-001.yaml"
  
  responses_to_forks:
    - fork_id: "alt-funding-model-001"
      response_type: "acknowledged | adopted | rejected"
      reasoning: "Interesting approach but requires data we don't have"
      date: "2026-03-05"

orp validate your-document.yaml
orp validate segment.yaml --profile ORP-Ads   # v0.3: pick a profile; reports tier
orp conform                                    # v0.3: run the conformance suite

curl -X POST https://api.publicreasonproject.org/api/v1/validate \
  -H "Content-Type: application/json" \
  -d '{"document": "orp_version: 0.2\n..."}'