eduevidence 6.0.0 → 6.3.0

package/schemas/applicability.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/37chengshan/eduevidence/schemas/applicability.schema.json",
+  "title": "ApplicabilityAssessment",
+  "description": "Stage-7 deliverable: who the evidence applies to, in which contexts, for which outcomes, and where it stops. Either an assessment or an explicit NOT_CAPTURED record is required - silence used to render as an empty report section with no gate failing.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "status"
+  ],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": [
+        "ASSESSED",
+        "NOT_CAPTURED"
+      ]
+    },
+    "reason": {
+      "type": "string"
+    },
+    "who": {
+      "type": "string"
+    },
+    "suitable_for": {
+      "type": "string"
+    },
+    "not_suitable_for": {
+      "type": "string"
+    },
+    "which_course": {
+      "type": "string"
+    },
+    "which_outcome": {
+      "type": "string"
+    },
+    "conditions": {
+      "type": [
+        "string",
+        "array"
+      ]
+    },
+    "target_population": {
+      "type": "string"
+    },
+    "target_context": {
+      "type": "string"
+    },
+    "boundary": {
+      "type": "string"
+    },
+    "notes": {
+      "type": "string"
+    },
+    "excluded_populations": {
+      "type": [
+        "string",
+        "array"
+      ]
+    },
+    "uncertainty": {
+      "type": [
+        "string",
+        "array"
+      ]
+    },
+    "extensions": {
+      "type": "object",
+      "additionalProperties": true
+    },
+    "required_conditions": {
+      "type": [
+        "string",
+        "array"
+      ],
+      "description": "Conditions that must hold for the evidence to apply."
+    },
+    "evidence_boundary": {
+      "type": "string"
+    },
+    "transfer_boundaries": {
+      "type": [
+        "string",
+        "array"
+      ]
+    },
+    "outcome_limits": {
+      "type": [
+        "string",
+        "array"
+      ]
+    }
+  }
+}

package/schemas/chart-spec.schema.json

@@ -2,14 +2,14 @@
   "$schema": "http://json-schema.org/draft-07/schema#",
   "$id": "https://github.com/37chengshan/eduevidence/schemas/chart-spec.schema.json",
   "title": "ChartSpec",
-  "description": "Chart spec produced by visualization build_charts.py. integrity is a per-check map with PASS/FAIL/NOT_CHECKED strings (P0-2 rewrite to match the real producer).",
+  "description": "One chart record inside a ReportSpec. Producer: visualization/eduevidence-report/scripts/build_report.py::build_report_spec. Kept in sync with the producer by scripts/check_protocol_alignment.py.",
   "type": "object",
   "additionalProperties": false,
   "required": [
     "chart_id",
     "purpose",
     "engine",
-    "chart_type"
+    "data_ref"
   ],
   "properties": {
     "chart_id": {
@@ -28,7 +28,7 @@
     },
     "chart_type": {
       "type": "string",
-      "minLength": 1
+      "description": "Optional chart family label. The Lieflat gallery carries its own type on result.visual_layout; this field is only used by callers that build chart specs by hand."
     },
     "semantic_basis": {
       "type": "string"
@@ -83,6 +83,13 @@
           ]
         }
       }
+    },
+    "data_ref": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Pointer to the data the chart reads, or null when the chart is rendered inline from result.json by the report builder."
     }
   }
 }

package/schemas/evidence.schema.json

@@ -5,77 +5,350 @@
   "description": "Claim-level evidence object. MANDATORY fields (schema v1.1): evidence_id, source_id, study_id, sample_id, claim_id, claim, outcome_type, relation_to_claim, effect_direction, source_location. Missing any mandatory field marks the object as UNSUPPORTED. 三种方向语义严格分开：relation_to_claim（支持/反驳某条 claim）、effect_direction（研究观察到的效应方向）、decision_relation（对最终教学决策的意义）。direction 为旧契约字段，仅向后兼容，已废弃（deprecated）。扩展字段一律放在 extensions 内。",
   "type": "object",
   "additionalProperties": false,
-  "required": ["evidence_id", "source_id", "study_id", "sample_id", "claim_id", "claim", "outcome_type", "relation_to_claim", "effect_direction", "source_location"],
+  "required": [
+    "evidence_id",
+    "source_id",
+    "study_id",
+    "sample_id",
+    "claim_id",
+    "claim",
+    "outcome_type",
+    "relation_to_claim",
+    "effect_direction",
+    "source_location"
+  ],
   "properties": {
-    "evidence_id": { "type": "string", "examples": ["E-001"] },
-    "source_id": { "type": "string", "examples": ["S-2023-kazemitabaar"] },
-    "study_id": { "type": "string", "description": "所属研究的稳定标识，用于独立研究计数（独立于 evidence_id，防止同一研究的多条 Evidence Object 重复放大信心）。" },
-    "sample_id": { "type": "string", "description": "所属样本的稳定标识，用于独立样本计数。无法区分样本时可显式使用 UNKNOWN-SAMPLE-<study_id>，但不能静默缺失。" },
-    "claim_id": { "type": "string", "description": "该证据所绑定 Claim 的稳定标识（Claim Registry 一等字段，Claim -> Evidence -> Source 不再依赖渲染阶段临时编号）。", "examples": ["C-003"] },
-    "title": { "type": "string" },
-    "year": { "type": ["integer", "null"] },
+    "evidence_id": {
+      "type": "string",
+      "examples": [
+        "E-001"
+      ]
+    },
+    "source_id": {
+      "type": "string",
+      "examples": [
+        "S-2023-kazemitabaar"
+      ]
+    },
+    "study_id": {
+      "type": "string",
+      "description": "所属研究的稳定标识，用于独立研究计数（独立于 evidence_id，防止同一研究的多条 Evidence Object 重复放大信心）。"
+    },
+    "sample_id": {
+      "type": "string",
+      "description": "所属样本的稳定标识，用于独立样本计数。无法区分样本时可显式使用 UNKNOWN-SAMPLE-<study_id>，但不能静默缺失。"
+    },
+    "claim_id": {
+      "type": "string",
+      "description": "该证据所绑定 Claim 的稳定标识（Claim Registry 一等字段，Claim -> Evidence -> Source 不再依赖渲染阶段临时编号）。",
+      "examples": [
+        "C-003"
+      ]
+    },
+    "title": {
+      "type": "string"
+    },
+    "year": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
     "study_type": {
       "type": "string",
-      "enum": ["rct", "quasi_experimental", "observational", "survey", "qualitative", "meta_analysis", "literature_review", "case_study", "mixed_methods"]
+      "enum": [
+        "rct",
+        "quasi_experimental",
+        "observational",
+        "survey",
+        "qualitative",
+        "meta_analysis",
+        "literature_review",
+        "case_study",
+        "mixed_methods"
+      ]
+    },
+    "education_level": {
+      "type": "string",
+      "examples": [
+        "undergraduate",
+        "k12",
+        "graduate"
+      ]
+    },
+    "subject": {
+      "type": "string",
+      "examples": [
+        "programming",
+        "mathematics",
+        "writing"
+      ]
+    },
+    "population": {
+      "type": "string",
+      "examples": [
+        "first_year_CS_students"
+      ]
+    },
+    "sample_size": {
+      "type": [
+        "integer",
+        "null"
+      ],
+      "minimum": 0
+    },
+    "intervention": {
+      "type": "string",
+      "examples": [
+        "copilot_allowed_in_lab"
+      ]
+    },
+    "comparison": {
+      "type": "string",
+      "examples": [
+        "no_ai_control_group"
+      ]
     },
-    "education_level": { "type": "string", "examples": ["undergraduate", "k12", "graduate"] },
-    "subject": { "type": "string", "examples": ["programming", "mathematics", "writing"] },
-    "population": { "type": "string", "examples": ["first_year_CS_students"] },
-    "sample_size": { "type": ["integer", "null"], "minimum": 0 },
-    "intervention": { "type": "string", "examples": ["copilot_allowed_in_lab"] },
-    "comparison": { "type": "string", "examples": ["no_ai_control_group"] },
     "outcome_type": {
       "type": "string",
       "enum": [
-        "knowledge_gain", "concept_understanding", "retention", "transfer",
-        "independent_problem_solving", "completion_time", "accuracy",
-        "code_quality", "assignment_score", "engagement", "motivation",
-        "cognitive_load", "help_seeking", "metacognition", "ai_dependency",
-        "over_reliance", "reduced_effort", "reduced_transfer",
-        "academic_integrity_risk", "false_confidence"
+        "knowledge_gain",
+        "concept_understanding",
+        "retention",
+        "transfer",
+        "independent_problem_solving",
+        "completion_time",
+        "accuracy",
+        "code_quality",
+        "assignment_score",
+        "engagement",
+        "motivation",
+        "cognitive_load",
+        "help_seeking",
+        "metacognition",
+        "ai_dependency",
+        "over_reliance",
+        "reduced_effort",
+        "reduced_transfer",
+        "academic_integrity_risk",
+        "false_confidence",
+        "policy_effectiveness",
+        "cost_effectiveness",
+        "equity",
+        "feasibility",
+        "implementation_risk"
+      ],
+      "description": "Outcome Taxonomy token, as registered in domains/<id>/outcome_taxonomy.json. Education registers the first 20 tokens (learning / task_performance / process / risk categories); policy registers the remaining 5 (effectiveness / cost / equity / feasibility / risk). The registry is the authority - scripts/check_protocol_alignment.py fails if this enum and the registry disagree."
+    },
+    "outcome_measure": {
+      "type": "string",
+      "examples": [
+        "final_exam_score",
+        "post_test_transfer_task"
+      ]
+    },
+    "claim": {
+      "type": "string",
+      "description": "The specific claim this evidence supports or contradicts."
+    },
+    "direction": {
+      "type": "string",
+      "enum": [
+        "support",
+        "contradict",
+        "neutral"
+      ],
+      "description": "DEPRECATED: legacy direction field, kept for backward compatibility only. Use relation_to_claim instead."
+    },
+    "relation_to_claim": {
+      "type": "string",
+      "enum": [
+        "support",
+        "contradict",
+        "neutral"
+      ],
+      "description": "该证据与 claim 的关系（支持/反驳/中性）。Claim Audit 只依据此字段判断支持/反驳，不得用 effect_direction 或 legacy direction 替代。"
+    },
+    "effect_direction": {
+      "type": "string",
+      "enum": [
+        "positive",
+        "negative",
+        "null"
+      ],
+      "description": "研究观察到的效应方向。Outcome 可视化 / 聚合只依据此字段。"
+    },
+    "decision_relation": {
+      "type": "string",
+      "enum": [
+        "support_adoption",
+        "oppose_adoption",
+        "conditional",
+        "neutral"
+      ],
+      "description": "该证据对最终教学决策的意义（支持采纳/反对采纳/有条件采纳/中性）。跨研究一致性（Consistency）与 Tribunal 依据此字段计算。"
+    },
+    "effect": {
+      "type": "string",
+      "examples": [
+        "positive_medium",
+        "null",
+        "negative_small"
+      ]
+    },
+    "duration": {
+      "type": "string",
+      "examples": [
+        "8_weeks"
       ]
     },
-    "outcome_measure": { "type": "string", "examples": ["final_exam_score", "post_test_transfer_task"] },
-    "claim": { "type": "string", "description": "The specific claim this evidence supports or contradicts." },
-    "direction": { "type": "string", "enum": ["support", "contradict", "neutral"], "description": "DEPRECATED: legacy direction field, kept for backward compatibility only. Use relation_to_claim instead." },
-    "relation_to_claim": { "type": "string", "enum": ["support", "contradict", "neutral"], "description": "该证据与 claim 的关系（支持/反驳/中性）。Claim Audit 只依据此字段判断支持/反驳，不得用 effect_direction 或 legacy direction 替代。" },
-    "effect_direction": { "type": "string", "enum": ["positive", "negative", "null"], "description": "研究观察到的效应方向。Outcome 可视化 / 聚合只依据此字段。" },
-    "decision_relation": { "type": "string", "enum": ["support_adoption", "oppose_adoption", "conditional", "neutral"], "description": "该证据对最终教学决策的意义（支持采纳/反对采纳/有条件采纳/中性）。跨研究一致性（Consistency）与 Tribunal 依据此字段计算。" },
-    "effect": { "type": "string", "examples": ["positive_medium", "null", "negative_small"] },
-    "duration": { "type": "string", "examples": ["8_weeks"] },
-    "method": { "type": "string", "examples": ["quasi_experimental_pre_post"] },
-    "strengths": { "type": "array", "items": { "type": "string" } },
-    "limitations": { "type": "array", "items": { "type": "string" } },
-    "confounders": { "type": "array", "items": { "type": "string" } },
-    "source_location": { "type": "string", "description": "Verifiable pointer to the source (DOI / URL / database identifier / page)." },
+    "method": {
+      "type": "string",
+      "examples": [
+        "quasi_experimental_pre_post"
+      ]
+    },
+    "strengths": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "limitations": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "confounders": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "source_location": {
+      "type": "string",
+      "description": "Verifiable pointer to the source (DOI / URL / database identifier / page)."
+    },
     "quality_dimensions": {
       "type": "object",
       "additionalProperties": true,
       "description": "D1 Study Design, D2 Sample Quality, D3 Measurement Validity, D4 Temporal Strength, D5 Directness. Each scored 0/1/2.",
       "properties": {
-        "D1_study_design": { "type": "integer", "minimum": 0, "maximum": 2 },
-        "D2_sample_quality": { "type": "integer", "minimum": 0, "maximum": 2 },
-        "D3_measurement_validity": { "type": "integer", "minimum": 0, "maximum": 2 },
-        "D4_temporal_strength": { "type": "integer", "minimum": 0, "maximum": 2 },
-        "D5_directness": { "type": "integer", "minimum": 0, "maximum": 2 }
+        "D1_study_design": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "D2_sample_quality": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "D3_measurement_validity": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "D4_temporal_strength": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        },
+        "D5_directness": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 2
+        }
       }
     },
-    "quality_score": { "type": ["number", "null"], "minimum": 0, "maximum": 10 },
+    "quality_score": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "minimum": 0,
+      "maximum": 10
+    },
     "evidence_level": {
       "type": "string",
-      "enum": ["strong", "moderate", "weak", "very_weak"]
+      "enum": [
+        "strong",
+        "moderate",
+        "weak",
+        "very_weak"
+      ]
     },
     "applicability": {
       "type": "object",
       "additionalProperties": true,
       "description": "Match against the target context: learner match, subject match, tool match, usage match, teacher support match."
     },
-    "confidence": { "type": ["number", "null"], "minimum": 0, "maximum": 1 },
-    "status": { "type": "string", "enum": ["SUPPORTED", "UNSUPPORTED", "DOWNGRADE_CONFIDENCE", "CONTRADICT"], "default": "SUPPORTED" },
+    "confidence": {
+      "type": [
+        "number",
+        "null"
+      ],
+      "minimum": 0,
+      "maximum": 1
+    },
+    "status": {
+      "type": "string",
+      "enum": [
+        "SUPPORTED",
+        "UNSUPPORTED",
+        "DOWNGRADE_CONFIDENCE",
+        "CONTRADICT"
+      ],
+      "default": "SUPPORTED"
+    },
     "extensions": {
       "type": "object",
       "description": "结构化扩展字段的统一容器（P1-01）。未列入本 schema 的字段必须放在这里，禁止在顶层新增属性。",
       "additionalProperties": true
+    },
+    "effect_size": {
+      "type": [
+        "number",
+        "object",
+        "null"
+      ],
+      "description": "Standardized effect size for this finding: a bare number for g, or an object such as {metric, value, ci_lower, ci_upper, p_value}. Read by the forest-plot and cascade extractors; rendering is suppressed when absent rather than approximated."
+    },
+    "effect_estimate": {
+      "type": [
+        "number",
+        "object",
+        "null"
+      ],
+      "description": "Raw effect estimate carried through V1 -> V2 migration so magnitudes survive the hop."
+    },
+    "wwc_rating": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "enum": [
+        "meets_without_reservations",
+        "meets_with_reservations",
+        "does_not_meet",
+        null
+      ],
+      "description": "WWC 5.0 study rating, when the auditor assigned one."
+    },
+    "outcome_dimension": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Coarse outcome dimension used for grouping (falls back to outcome_type)."
+    },
+    "study_label": {
+      "type": [
+        "string",
+        "null"
+      ],
+      "description": "Human-readable study label used on chart axes."
     }
   }
 }

package/schemas/fetch-result.schema.json

@@ -33,7 +33,8 @@
         "markdown_new",
         "defuddle",
         "raw_html",
-        "pdf_parser"
+        "pdf_parser",
+        "sciverse_content"
       ]
     },
     "fetch_status": {

package/schemas/report-result.schema.json

@@ -232,9 +232,9 @@
         "required": [
           "evidence_id",
           "source_id",
-          "outcome_type",
-          "direction"
-        ]
+          "outcome_type"
+        ],
+        "description": "Evidence row as embedded in a rendered result. `direction` is NOT required: it is deprecated in schemas/evidence.schema.json, and consumers must read relation_to_claim (claim support) and effect_direction (observed effect) instead."
       },
       "description": "Evidence rows (projection of evidence.schema.json; stage-level gate enforces the full contract)."
     },