CodeSystem
Nguồn định nghĩa mã: code, display, designation, thuộc tính và trạng thái active/inactive.
VN Core Deep Dive
Terminology trong VN Core: đọc mã trước khi đọc payload
Trong FHIR, sai mã có thể nguy hiểm hơn sai cấu trúc JSON. VN Core v0.6.0 xuất bản 139 CodeSystems, 144 ValueSets và 6 ConceptMaps để đảm bảo mỗi mã có nguồn, ngữ cảnh và ý nghĩa rõ ràng.
Tóm tắt nhanh
- Không validate bằng
display. Nghĩa máy đọc nằm ởsystem + code + version; display chỉ để hiển thị và có thể thay đổi theo ngôn ngữ. - CodeSystem là nguồn mã, ValueSet là tập dùng trong ngữ cảnh. Một CodeSystem có thể sinh nhiều ValueSet khác nhau cho nhiều profile.
- Binding strength quyết định mức ràng buộc.
requiredlà bắt buộc thuộc ValueSet;extensiblecho phép ngoài tập khi có lý do hợp lệ. - Version và hiệu lực phải được quản trị. Danh mục y tế Việt Nam thay đổi theo văn bản pháp luật, nên cần tránh hard-code mã không có nguồn.
1. Vì sao terminology là lớp an toàn dữ liệu
Profile giúp payload có hình dạng đúng, nhưng terminology mới giúp payload có nghĩa đúng. Một Condition.code có thể hợp lệ về cấu trúc nhưng sai về hệ mã; một mã 01 có thể là dân tộc Kinh, nhóm chi phí, loại giấy tờ hoặc trạng thái khác tùy system. Vì vậy VN Core không cho phép diễn giải mã tách rời khỏi canonical URL của CodeSystem.
Khi triển khai, lớp terminology nên được xem là hợp đồng dữ liệu ngang hàng với profile. Bộ chuyển đổi HIS/EMR cần map mã nội bộ sang CodeSystem chuẩn; server cần lưu cả system, code, version khi có; UI có thể hiển thị display hoặc text, nhưng không được dùng chúng làm khóa.
2. Sáu khái niệm cần phân biệt
ValueSet
Tập mã được phép dùng trong một ngữ cảnh cụ thể; profile bind element coded vào ValueSet.
ConceptMap
Ánh xạ giữa các hệ mã, ví dụ ICD-10 VN với SNOMED CT hoặc danh mục legacy với FHIR-native.
NamingSystem
Đăng ký URI cho hệ thống định danh như CCCD, BHYT, BHXH, MRN; không phải bộ mã lâm sàng.
Coding.display
Nhãn hiển thị cho con người. Không dùng display làm khóa nghiệp vụ hoặc tiêu chí validation.
Version
Phiên bản bộ mã/danh mục. Bắt buộc quản trị khi văn bản pháp lý hoặc danh mục chuyên ngành thay đổi.
3. Các domain terminology trong VN Core
| Domain | Ví dụ bộ mã | Artifact liên quan |
|---|---|---|
| Hành chính và nhân khẩu học | Tỉnh/xã, dân tộc, quốc tịch, nghề nghiệp, tôn giáo. | Địa chỉ, Patient, Organization |
| BHYT và dữ liệu đầu ra KCB | Mã đối tượng, lý do vào viện, kết quả điều trị, tình trạng ra viện, nhóm chi phí. | Coverage, Claim, EOB, Invoice |
| Lâm sàng | ICD-10 VN, chỉ số cận lâm sàng, dị ứng, phát hiện lâm sàng, SNOMED CT VN. | Condition, Observation, AllergyIntolerance |
| Khám sức khỏe | Bộ câu trả lời KSK, phân loại sức khỏe, loại biểu mẫu, chỉ số KSK. | Questionnaire, QuestionnaireResponse, Observation |
| Y học cổ truyền | Thể lâm sàng, chẩn đoán, huyệt, kỹ thuật, dược liệu, bài thuốc. | Condition, Procedure, Medication |
| Pháp lý và governance | Mã tham chiếu văn bản pháp luật và domain tác động. | Citation, Provenance, pagecontent, traceability |
4. Best practice cho Coding.display
Coding.display hữu ích cho giao diện, log và trao đổi dữ liệu với con người, nhưng không phải thành phần định danh. Cùng một system + code có thể có display tiếng Việt, tiếng Anh hoặc display được cập nhật khi văn bản thay đổi cách gọi. Ngược lại, cùng một display có thể tồn tại ở nhiều CodeSystem khác nhau.
Với VN Core, nguyên tắc vận hành là: gửi display khi có nguồn đáng tin cậy, nhưng hệ thống nhận không được reject payload chỉ vì display khác chính tả hoặc thiếu dấu nếu system + code hợp lệ. Trường hợp cần giữ nguyên lời bác sĩ hoặc tên dịch vụ tại thời điểm ghi nhận, dùng CodeableConcept.text hoặc narrative riêng thay vì biến display thành nguồn sự thật.
Quy tắc review production: nếu một mapping rule so sánh display để quyết định nghiệp vụ, rule đó cần sửa. So sánh bằng system + code, còn display chỉ dùng để render.
5. Checklist triển khai terminology
Mỗi mã trong payload có `system`; không truyền code trần như `01`, `DN`, `I10`.
Khi bộ mã có version, lưu/trao đổi `Coding.version` để tái hiện quyết định tại thời điểm ghi nhận.
Không dùng `Coding.display` để validate, join dữ liệu hoặc quyết định thanh toán.
Map mã nội bộ sang CodeSystem chuẩn tại boundary, không để mã nội bộ lọt vào payload VN Core nếu không có NamingSystem/CodeSystem rõ.
Kiểm tra binding strength của từng element trước khi quyết định có được dùng mã ngoài ValueSet hay không.
Dùng ConceptMap có review lâm sàng/pháp lý cho mapping nhiều-nghĩa, không coi mọi mapping là tương đương tuyệt đối.
Chuỗi đọc VN Core Deep Dive
Đi từ overview sang IG theo đúng thứ tự.
Bốn bài này là lớp định hướng trước khi mở IG normative: nắm bản đồ artifact, đọc Profile, kiểm soát terminology, rồi validate Bundle/workflow.
Bản đồ artifact
Profile, terminology, capability, operation, example và package boundary.
Cách đọc Profile
Differential, snapshot, Must Support, slicing, binding và extension.
Terminology
Đang đọcCodeSystem, ValueSet, ConceptMap, NamingSystem và Coding.display.
Bundle và Validation
Bundle, example, CapabilityStatement, OperationDefinition và go-live checks.