Bộ Hướng dẫn Triển khai Core FHIR cho Việt Nam - Draft for Community Review (v0.6.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

OperationOutcome & Registry quy tắc

OperationOutcome & Registry quy tắc kiểm tra hợp lệ — OperationOutcome & Validation Rule Registry

Quy ước cách máy chủ FHIR trả kết quả kiểm tra hợp lệ về cho hệ thống gửi (HIS/EMR/vendor), và registry mã quy tắc (rule code) để mọi lỗi liên thông có ngữ nghĩa thống nhất giữa các nhà cung cấp.

Trang này bổ trợ — không thay thế — Hướng dẫn kiểm tra hợp lệ. Phân vai:

• validation-guidance.html = các tầng & chi tiết từng quy tắc (FHIRPath invariant, server-side, business rule).
• trang này = quy ước phản hồi (OperationOutcome) + registry mã rule machine-readable để tham chiếu.

Mô hình hóa theo thông lệ nền tảng liên thông quốc gia (đối sánh "Daftar Response Validasi" + "Kamus Rule Number" của SATUSEHAT Indonesia), nhưng FHIR-native: registry là CodeSystem versionable thay vì bảng tính phân tán.

1. Vì sao cần registry mã rule

Khi triển khai đa-vendor, một lỗi như "thiếu serviceProvider" phải được mọi hệ thống hiểu giống nhau. VN Core gán cho mỗi quy tắc một mã rule ổn định (vd VN-RULE-ENC-001), kèm sẵn severity, tầng kiểm tra, căn cứ pháp lý và biểu thức. Vendor có thể:

• Tra cứu mã để biết chính xác lỗi gì và cách sửa.
• Tự kiểm thử (self-test) trước khi pilot.
• Đối chiếu phản hồi giữa các máy chủ khác nhau.

Registry là CodeSystem VNValidationRuleCS (http://fhir.hl7.org.vn/core/CodeSystem/vn-validation-rule-cs).

2. Quy ước OperationOutcome của VN Core

Mọi lỗi/cảnh báo kiểm tra hợp lệ trả về dưới dạng OperationOutcome, mỗi issue tuân thủ:

Nguyên tắc kiểm soát căn cứ (kế thừa từ validation-guidance): chỉ những rule có category = normative-data-standard, legal-business-rule hoặc profile-conformance mới được dùng làm lý do từ chối hồ sơ thật. Rule technical-quality-guardrail / source-exception chỉ ở mức warning/regression.

Ví dụ — lỗi đơn (Encounter thiếu serviceProvider)

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "required",
    "details": {
      "coding": [{
        "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-validation-rule-cs",
        "code": "VN-RULE-ENC-001"
      }],
      "text": "Encounter.serviceProvider là bắt buộc"
    },
    "expression": ["Encounter.serviceProvider"]
  }]
}

Ví dụ — phản hồi thành công

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "information",
    "code": "informational",
    "details": { "text": "Hồ sơ hợp lệ theo VN Core" }
  }]
}

3. Ngữ nghĩa transaction Bundle (atomic)

Khi nộp một lượt khám = một transaction Bundle (xem Playbook Nội trú), nếu bất kỳ resource nào sai thì toàn bộ Bundle bị từ chối (atomic) — máy chủ trả OperationOutcome với expression trỏ vào entry cụ thể:

{
  "resourceType": "OperationOutcome",
  "issue": [{
    "severity": "error",
    "code": "business-rule",
    "details": {
      "coding": [{
        "system": "http://fhir.hl7.org.vn/core/CodeSystem/vn-validation-rule-cs",
        "code": "VN-RULE-CLM-014"
      }],
      "text": "Số ngày giường phải khớp số ngày nằm viện"
    },
    "expression": ["Bundle.entry[11].resource.item.where(category.coding.code='2.2')"]
  }]
}

Mỗi entry của transaction Bundle phải có request.method + request.url (rule VN-RULE-BDL-001, FHIR bdl-3).

4. Registry quy tắc (seed) — VNValidationRuleCS

Bộ mã khởi tạo (tiếp tục mở rộng). Bản đầy đủ + property tại CodeSystem-vn-validation-rule-cs.

Quy ước đặt mã: VN-RULE-{DOMAIN}-{NNN} — DOMAIN: PAT (Patient), ADDR (Address), ENC (Encounter), CON (Condition), MED (Medication chain), CLM (Claim), BHYT (liên thông BHXH), BDL (Bundle), TERM (Terminology). Mã đã cấp không tái sử dụng kể cả khi rule bị bãi bỏ (đánh dấu deprecated).

5. Tự kiểm thử (self-test) cho vendor

Vendor NÊN chạy hết rule error ở category bắt buộc trước khi xin truy cập production.

Liên hệ với các trang khác

English Summary

This page defines how VN Core servers return validation results to client systems via OperationOutcome, and introduces a machine-readable validation rule registry (VNValidationRuleCS). Each rule has a stable code (e.g., VN-RULE-ENC-001) carrying severity, validation tier, evidence category, FHIRPath expression, linked invariant, and legal basis — referenced from OperationOutcome.issue.details.coding. This FHIR-native registry (inspired by SATUSEHAT's rule-number dictionary but versionable rather than spreadsheet-based) gives multi-vendor implementations a shared error vocabulary, including atomic transaction-Bundle rejection semantics. It complements the detailed three-tier validation guidance page and supports vendor self-testing before production access.