# Ghi chú nhanh về 2 file JSON của cụm ingest-knowledge

Tài liệu này giải thích ngắn gọn vai trò của 2 file JSON đang đi cùng cụm `ingest-knowledge`, để đội dự án biết khi nào dùng file nào và cách chúng nối với taxonomy/manifest.

## 1. Hai file này dùng để làm gì

| File | Vai trò chính | Khi dùng |
| --- | --- | --- |
| `docs/kenh-xay-gold-reference-metadata-schema.json` | schema chuẩn cho metadata của tài liệu tham chiếu/gold reference | dùng khi muốn kiểm tra cấu trúc metadata chuẩn trước khi ingest hoặc review contract metadata |
| `docs/duong-ong-nam-hung-khanh-metadata-schema-example.json` | ví dụ metadata đã điền cho hồ sơ mẫu Nam Hưng Khánh | dùng khi cần hình dung một bộ metadata thực tế cho dự án pilot |

## 2. Cách hiểu mối quan hệ giữa 2 file

- `metadata-schema.json` trả lời câu hỏi: "metadata **nên có cấu trúc gì**"
- `metadata-schema-example.json` trả lời câu hỏi: "metadata **được điền thực tế ra sao**"

Nói ngắn gọn:

- schema = khung chuẩn
- example = mẫu tham chiếu

## 3. Liên hệ với taxonomy và manifest

### Với `docs/knowledge-taxonomy.md`
- taxonomy định nghĩa nhóm tài liệu, loại hồ sơ, giai đoạn, cách phân loại
- schema metadata nên bám cùng cách gọi trong taxonomy
- example metadata nên dùng giá trị phù hợp với taxonomy đã chốt

### Với `docs/project-dossier-manifest-template.md`
- manifest là danh mục hồ sơ cần theo dõi ở cấp công trình
- metadata là lớp mô tả chi tiết cho từng tài liệu hoặc chunk ingest
- khi map manifest sang ingest, cần giữ nhất quán:
  - `project_code`
  - `document_type`
  - `doc_family`
  - `doc_stage`
  - trạng thái nguồn/tài liệu liên quan

## 4. Cách dùng thực tế trong DSCons

Nên dùng theo thứ tự:

1. đọc `docs/knowledge-taxonomy.md`
2. đọc `docs/kenh-xay-gold-reference-metadata-contract.md`
3. đối chiếu `docs/kenh-xay-gold-reference-metadata-schema.json`
4. xem `docs/duong-ong-nam-hung-khanh-metadata-schema-example.json`
5. map lại với `docs/project-dossier-manifest-template.md` hoặc manifest công trình thực tế

## 5. Lưu ý vận hành

- không coi file example là chuẩn duy nhất cho mọi công trình
- không đổi tên trường metadata nếu chưa cập nhật contract/taxonomy liên quan
- nếu bổ sung field mới, nên cập nhật theo thứ tự:
  1. contract markdown
  2. schema JSON
  3. example JSON nếu cần
  4. manifest/tài liệu hướng dẫn liên quan
- ưu tiên giữ metadata ngắn gọn, truy vết được nguồn và hỗ trợ ingest rerunnable