knowledge_item_schema.yaml — Dữ Liệu Kỹ Thuật

📁 Đường dẫn tệp gốc: ../knowledge-base/schemas/knowledge_item_schema.yaml
📥 Tải tệp gốc xuống

# Knowledge Item Schema v0.1

# Phiên bản: 0.1 DRAFT
# Mục đích: Định nghĩa schema cho các Knowledge Card trong CXK KB
# Validator: validate_schema.py

$schema: "https://json-schema.org/draft/2020-12/schema"
title: "CXK Knowledge Item"
description: "Schema cho mỗi mục kiến thức y khoa trong knowledge base CXK Tuổi Bạc"
version: "0.1"

type: object
required:
  - id
  - title_vi
  - taxonomy_id
  - review_status
  - sources
  - content

properties:
  # === IDENTIFICATION ===
  id:
    type: string
    pattern: "^KC-[A-Z]+-[0-9]{3}$"
    description: "Knowledge Card ID, e.g. KC-OA-001"

  title_vi:
    type: string
    minLength: 5
    maxLength: 200
    description: "Tiêu đề tiếng Việt"

  title_en:
    type: string
    description: "Tiêu đề tiếng Anh (optional)"

  # === CLASSIFICATION ===
  taxonomy_id:
    type: string
    description: "ID từ msk_taxonomy_v1.yaml, e.g. THK_GOI"

  condition:
    type: string
    enum: ["knee_oa", "hip_oa", "hand_oa", "low_back_pain", "osteoporosis", "falls", "rheumatoid_arthritis", "gout", "septic_arthritis", "osteomyelitis", "exercise", "nutrition", "sarcopenia", "general"]

  content_type:
    type: string
    enum: ["definition", "symptom", "diagnosis", "treatment", "self_management", "warning", "prevention", "faq_answer", "risk_factor", "medication_info", "red_flag"]

  body_region:
    type: string
    enum: ["knee", "hip", "hand", "lumbar_spine", "cervical_spine", "foot", "shoulder", "bone_general", "muscle", "multiple_joints", "single_joint", "general"]

  # === CONTENT ===
  content:
    type: object
    required:
      - text_vi
    properties:
      text_vi:
        type: string
        minLength: 20
        description: "Nội dung chính tiếng Việt"
      text_en:
        type: string
        description: "Nội dung tiếng Anh (optional)"
      patient_friendly:
        type: string
        description: "Phiên bản dễ hiểu cho bệnh nhân/NCT"
      key_points:
        type: array
        items:
          type: string
        description: "Các điểm chính dạng bullet"

  # === SAFETY ===
  safety:
    type: object
    properties:
      action_class:
        type: string
        enum: ["SAFE_SELF_CARE", "INFORM_ONLY", "SUGGEST_CLINIC", "URGENT", "EMERGENCY"]
        description: "Mức độ hành động AI nên khuyên"
      red_flags:
        type: array
        items:
          type: string
        description: "Dấu hiệu nguy hiểm cần khám ngay"
      contraindications:
        type: array
        items:
          type: string
        description: "Chống chỉ định"
      disclaimer:
        type: string
        default: "Thông tin này mang tính tham khảo, không thay thế tư vấn của bác sĩ."

  # === PROVENANCE ===
  sources:
    type: array
    minItems: 1
    items:
      type: object
      required:
        - source_id
      properties:
        source_id:
          type: string
          description: "ID từ source_registry.csv"
        locator:
          type: string
          description: "Line number, page, section reference"
        claim_id:
          type: string
          description: "ID từ ClinicalClaims CSV"

  # === REVIEW ===
  review_status:
    type: string
    enum: ["DRAFT", "AI_REVIEWED", "NCS_REVIEWED", "CLINICAL_REVIEW", "APPROVED", "PUBLISHED", "BLOCKED_CONFLICT", "DEPRECATED"]
    description: "Trạng thái duyệt. APPROVED cần BS ký"

  review_history:
    type: array
    items:
      type: object
      properties:
        date:
          type: string
          format: date
        reviewer:
          type: string
        action:
          type: string
        notes:
          type: string

  # === METADATA ===
  created_date:
    type: string
    format: date

  last_updated:
    type: string
    format: date

  tags:
    type: array
    items:
      type: string

  related_kc:
    type: array
    items:
      type: string
    description: "IDs of related Knowledge Cards"

  related_faq:
    type: array
    items:
      type: string
    description: "IDs of related FAQ items"

# === FAQ SCHEMA ===
---
title: "CXK FAQ Item"
description: "Schema cho câu hỏi thường gặp"
version: "0.1"

type: object
required:
  - id
  - question_vi
  - taxonomy_id
  - review_status
  - sources

properties:
  id:
    type: string
    pattern: "^FAQ-[A-Z]+-[0-9]{3}$"

  question_vi:
    type: string
    description: "Câu hỏi tiếng Việt (ngôn ngữ bệnh nhân)"

  question_variants:
    type: array
    items:
      type: string
    description: "Các cách hỏi khác nhau"

  answer_vi:
    type: string
    description: "Câu trả lời tiếng Việt dễ hiểu"

  taxonomy_id:
    type: string

  content_type:
    type: string
    enum: ["general", "symptom", "treatment", "self_care", "warning", "medication", "lifestyle", "when_to_see_doctor"]

  safety:
    type: object
    properties:
      action_class:
        type: string
        enum: ["SAFE_SELF_CARE", "INFORM_ONLY", "SUGGEST_CLINIC", "URGENT", "EMERGENCY"]

  sources:
    type: array
    minItems: 1

  review_status:
    type: string
    enum: ["DRAFT", "AI_REVIEWED", "NCS_REVIEWED", "CLINICAL_REVIEW", "APPROVED", "PUBLISHED"]

  related_kc:
    type: array
    items:
      type: string

# === CASE SCHEMA ===
---
title: "CXK Case Study"
description: "Schema cho case study/tình huống"
version: "0.1"

type: object
required:
  - id
  - scenario_vi
  - taxonomy_id
  - expected_action
  - sources

properties:
  id:
    type: string
    pattern: "^CASE-[A-Z]+-[0-9]{3}$"

  scenario_vi:
    type: string
    description: "Mô tả tình huống tiếng Việt"

  patient_profile:
    type: object
    properties:
      age_range:
        type: string
      gender:
        type: string
      conditions:
        type: array
        items:
          type: string

  taxonomy_id:
    type: string

  expected_action:
    type: string
    enum: ["SAFE_SELF_CARE", "INFORM_ONLY", "SUGGEST_CLINIC", "URGENT", "EMERGENCY"]

  expected_response_elements:
    type: array
    items:
      type: string
    description: "Các yếu tố phải có trong câu trả lời"

  must_not_include:
    type: array
    items:
      type: string
    description: "Nội dung AI KHÔNG ĐƯỢC nói"

  sources:
    type: array

  review_status:
    type: string
    enum: ["DRAFT", "APPROVED"]

  test_type:
    type: string
    enum: ["functional", "safety", "red_team", "edge_case"]