{
  "from_version": "0.1",
  "to_version": "0.2",
  "description": "Canonical mapping from PIF v0.1 to v0.2 document shape. Used by validators and downstream tools to translate v0.1 documents into v0.2 form (one-way, additive). v0.1 documents continue to validate against v0.1 schemas indefinitely (per the v0.1 stability commitment); this mapping is for producers who want to emit v0.2 going forward and for consumers who choose to canonicalise incoming documents to v0.2 internally.",

  "principles": [
    "Additive: every v0.1 field has a v0.2 equivalent (sometimes via rename + value translation); no v0.1 field is dropped without a replacement.",
    "Cumulative validation: v0.2 schemas accept v0.1 documents directly. The mapping below is the canonical translation; consumers MAY apply it on read or work with the v0.1 shape natively.",
    "Lossless on round-trip for translatable fields. Some v0.2 fields (e.g., conditional_applicability, pif_corpus_version) are new in v0.2 with no v0.1 equivalent and are documented as additive."
  ],

  "field_renames": {
    "WorkflowDescription": {
      "gxp_domains_self_declared": "regulatory_domains_self_declared"
    },
    "PreflightAssertion": {
      "gxp_domains_identified": "regulatory_domains_identified"
    }
  },

  "value_translations": {
    "WorkflowDescription.gxp_domains_self_declared -> regulatory_domains_self_declared": {
      "GMP": "gxp:GMP",
      "GDP": "gxp:GDP",
      "GCP": "gxp:GCP",
      "GLP": "gxp:GLP",
      "GVP": "gxp:GVP",
      "CSV": "gxp:CSV",
      "data_integrity": "gxp:data_integrity",
      "quality_systems": "gxp:quality_systems",
      "regulatory_affairs": "gxp:regulatory_affairs",
      "pharmacovigilance": "gxp:pharmacovigilance",
      "labeling": "gxp:labeling",
      "none_claimed": "none_claimed"
    },
    "PreflightAssertion.gxp_domains_identified -> regulatory_domains_identified": {
      "GMP": "gxp:GMP",
      "GDP": "gxp:GDP",
      "GCP": "gxp:GCP",
      "GLP": "gxp:GLP",
      "GVP": "gxp:GVP",
      "CSV": "gxp:CSV",
      "data_integrity": "gxp:data_integrity",
      "quality_systems": "gxp:quality_systems",
      "regulatory_affairs": "gxp:regulatory_affairs",
      "pharmacovigilance": "gxp:pharmacovigilance",
      "labeling": "gxp:labeling"
    },
    "PreflightAssertion.missing_controls[].control": {
      "note": "v0.1 free-text values (e.g., 'audit_trail', 'human_approval_gate') are accepted by v0.2 schemas under the cumulative ControlIdentifier pattern (DEPRECATED in v0.2, removed in v0.3). v0.2 producers SHOULD migrate to CURIE form. Recommended translations of common v0.1 control names below.",
      "audit_trail": "gxp:audit_trail",
      "human_approval_gate": "gxp:human_approval_gate",
      "validated_source_retrieval": "gxp:validated_source_retrieval",
      "documented_user_requirements_specification": "gxp:documented_user_requirements_specification",
      "risk_based_qualification_plan": "gxp:risk_based_qualification_plan",
      "ai_output_attribution_in_record": "gxp:ai_output_attribution_in_record",
      "audit_trail_of_ai_invocations": "gxp:audit_trail_of_ai_invocations",
      "change_control_for_model_updates": "gxp:change_control_for_model_updates",
      "periodic_performance_review": "gxp:periodic_performance_review"
    }
  },

  "additive_fields": {
    "PreflightAssertion": {
      "pif_corpus_version": {
        "type": "string",
        "required": "optional in v0.2; RECOMMENDED for producers emitting any token outside the v0.2.0 recommended-token list",
        "purpose": "Audit trail for which corpus snapshot the producer validated against. Lets consumers reproduce 'unrecognised token' advisories deterministically.",
        "v0.1_equivalent": null
      },
      "applicable_requirements[].conditional_applicability": {
        "type": "boolean",
        "required": "optional",
        "purpose": "When true, signals the requirement's applicability depends on an assumption in assumptions_made resolving in a specific direction. Decouples assumption-driven retrieval from precision torpedoing.",
        "v0.1_equivalent": null
      },
      "regulatory_domains_identified": {
        "type": "array of CURIEs",
        "required": "optional",
        "purpose": "Cross-industry generalisation of gxp_domains_identified. Same semantic role, broader vocabulary.",
        "v0.1_equivalent": "gxp_domains_identified (translated value-by-value via the table above)"
      }
    },
    "WorkflowDescription": {
      "regulatory_domains_self_declared": {
        "type": "array of CURIEs",
        "required": "optional",
        "purpose": "Cross-industry generalisation of gxp_domains_self_declared.",
        "v0.1_equivalent": "gxp_domains_self_declared (translated value-by-value via the table above)"
      }
    }
  },

  "tightened_required_array": {
    "PreflightAssertion": {
      "v0.1_required_set": [
        "pif_version",
        "assertion_id",
        "workflow_ref",
        "produced_by",
        "produced_at",
        "risk_classification",
        "applicable_requirements",
        "missing_controls",
        "assumptions_made",
        "verification_steps",
        "status"
      ],
      "v0.2_additionally_required": [
        "out_of_scope",
        "clarifying_questions"
      ],
      "rationale": "v0.1 spec.md prose stated 'Honesty by architecture. Required fields like assumptions_made, clarifying_questions, out_of_scope, and applicability_basis make uncertainty and limits structural' — but the v0.1 schema's required array did not include out_of_scope or clarifying_questions. The eval n=1 run passed conformance despite lacking out_of_scope because of this schema-vs-prose drift. v0.2 closes the drift. v0.1 documents that omit these fields continue to validate against v0.1 schemas indefinitely; v0.2 schemas enforce the additional required fields ONLY when pif_version is 0.2.",
      "applied_via": "JSON Schema if/then construct keyed on pif_version=0.2; v0.1 documents (pif_version=0.1) bypass the additional required check via cumulative validation."
    }
  },

  "deprecation_timeline": {
    "gxp_domains_self_declared (WorkflowDescription)": {
      "v0.2": "DEPRECATED. Retained in v0.2 schemas for cumulative validation; v0.2 producers MUST NOT emit; v0.2 consumers MUST accept and translate.",
      "v0.3": "Still accepted (six-month minimum migration window per Round 3 R3.17).",
      "v1.0": "Removed."
    },
    "gxp_domains_identified (PreflightAssertion)": {
      "v0.2": "DEPRECATED. Same handling as gxp_domains_self_declared.",
      "v0.3": "Still accepted.",
      "v1.0": "Removed."
    },
    "missing_controls[].control free-text shape": {
      "v0.2": "DEPRECATED. Accepted via cumulative ControlIdentifier pattern; v0.2 producers SHOULD emit CURIE form.",
      "v0.3": "Removed — only the CURIE shape will validate."
    }
  },

  "schema_url_change": {
    "v0.1_schemas": "https://pif-spec.github.io/pif/v0.1/<type>.schema.json",
    "v0.2_schemas": "https://pif-spec.github.io/pif/v0.2/<type>.schema.json",
    "rationale": "v0.1 schemas continue to be served at the v0.1 URLs per the stability commitment. v0.2 publishes under a neutral host (GitHub Pages on the pif-spec org) per Round 4 design lock — open standard, not commercial domain."
  }
}