Đặc tả Kỹ thuật5 Schemas • v1.x

Lược đồ Cấu trúc Dữ liệu (Schemas)

Đặc tả định dạng trường, ràng buộc kiểu dữ liệu và ý nghĩa ngữ nghĩa của các lược đồ chuẩn hoá trong mạng BOP Data. Đảm bảo các hệ thống máy đọc, crawler và AI agent có thể trích xuất dữ liệu một cách an toàn và nhất quán.

Trường (Field)	Kiểu dữ liệu (Type)	Bắt buộc	Mô tả & Quy cách
`canonicalId`	string	Có	Mã định danh bất biến của tập dữ liệu (dạng chấm chuẩn hóa). Không thay đổi khi URL hoặc phân loại đổi. Ví dụ:`vn.tax.vat.rates`
`title`	LocalizedText	Có	Tiêu đề bản ghi dữ liệu công dân (bản ngữ Việt Nam và tiếng Anh). Ví dụ:`{ "vi": "Biểu thuế GTGT...", "en": "VAT rates..." }`
`schemaId`	string	Có	Mã định danh lược đồ cấu trúc áp dụng cho bản ghi dữ liệu này. Ví dụ:`vn.tax.vat.rates`
`schemaVersion`	string	Có	Phiên bản của lược đồ cấu trúc đang áp dụng (Semantic Versioning). Ví dụ:`1.0.0`
`currentVersion`	string	Có	Mã phiên bản chu kỳ dữ liệu đang có hiệu lực thi hành. Ví dụ:`2026.01`
`sources`	Source[]	Có	Mảng các căn cứ pháp lý, cơ quan ban hành, số văn bản và đường dẫn đối chiếu gốc.
`body`	DataBody	Có	Đối tượng thân dữ liệu chuyên biệt tuân thủ cấu trúc của từng schemaId.

Trường (Field)	Kiểu dữ liệu (Type)	Bắt buộc	Mô tả & Quy cách
`body.renderer`	'table' \| 'rate-table'	Có	Chỉ dẫn thành phần hiển thị giao diện câu trả lời ngữ nghĩa (Answer Zone). Ví dụ:`'rate-table'`
`body.table.columns`	TableColumn[]	Có	Mảng định nghĩa các cột hiển thị: khóa (key), nhãn song ngữ (label), kiểu (type: text\|percent) và căn lề (align).
`body.records`	RateRecord[]	Có	Mảng các dòng biểu thuế: nhóm hàng hoá dịch vụ (group: string), thuế suất (rate: number %) và ghi chú căn cứ (note?: string). Ví dụ:`[{ "group": "Hàng hoá thông thường", "rate": 10 }]`
`body.highlights`	HighlightItem[]	Không	Các giá trị tiêu biểu trích xuất nhanh hiển thị trong Value Primitive tại Answer Zone. Ví dụ:`[{ "label": { "vi": "Mức chuẩn" }, "value": "10%" }]`

Xem mẫu cấu trúc JSON thực tế (Payload Example)

{
  "renderer": "rate-table",
  "table": {
    "columns": [
      { "key": "group", "label": { "vi": "Nhóm hàng hoá", "en": "Group" }, "type": "text" },
      { "key": "rate", "label": { "vi": "Thuế suất", "en": "Rate" }, "type": "percent" }
    ]
  },
  "records": [
    { "group": "Hàng hoá, dịch vụ thông thường", "rate": 10 },
    { "group": "Một số hàng hoá, dịch vụ ưu đãi", "rate": 8 },
    { "group": "Xuất khẩu hàng hoá, dịch vụ", "rate": 0 }
  ]
}

Trường (Field)	Kiểu dữ liệu (Type)	Bắt buộc	Mô tả & Quy cách
`body.renderer`	'rate-table'	Có	Chỉ định renderer bảng mức phí đa kỳ hạn (1 tháng, 6 tháng, 12 tháng, 24 tháng). Ví dụ:`'rate-table'`
`body.records`	FeeRecord[]	Có	Mảng các loại phương tiện (vehicleType: string) kèm đơn giá phí đường bộ theo chu kỳ (VND). Ví dụ:`[{ "vehicleType": "Ô tô chở người dưới 10 chỗ", "fee1m": 130000, "fee12m": 1560000 }]`

Trường (Field)	Kiểu dữ liệu (Type)	Bắt buộc	Mô tả & Quy cách
`body.renderer`	'tiered-price'	Có	Chỉ định renderer bậc thang lũy tiến dành cho giá năng lượng tiêu thụ. Ví dụ:`'tiered-price'`
`body.tiers`	ElectricityTier[]	Có	Mảng các bậc tính tiền điện: số bậc (tier: 1..6), khoảng điện năng (range: kWh), đơn giá (price: đ/kWh). Ví dụ:`[{ "tier": 1, "range": "0 - 50 kWh", "price": 1893, "unit": "đ/kWh" }]`

Trường (Field)	Kiểu dữ liệu (Type)	Bắt buộc	Mô tả & Quy cách
`body.renderer`	'score-scale'	Có	Chỉ định renderer dải điểm năng lực chuẩn quốc tế (0.0 - 9.0 với bước nhảy 0.5). Ví dụ:`'score-scale'`
`body.scale`	ScoreScaleConfig	Có	Cấu hình phạm vi dải điểm: min (0), max (9.0), step (0.5).
`body.bands`	IeltsBand[]	Có	Mảng diễn giải năng lực cho từng thang điểm: band (number), trình độ (skill: string), mô tả chi tiết (description).

Trường (Field)	Kiểu dữ liệu (Type)	Bắt buộc	Mô tả & Quy cách
`body.renderer`	'highlight'	Có	Chỉ định renderer thông số tức thời (Mua vào / Bán ra) kèm đơn vị lượng vàng. Ví dụ:`'highlight'`
`body.highlights`	HighlightItem[]	Có	Hai thông số cốt lõi: Giá mua (Buy) và Giá bán (Sell) tính theo VNĐ/lượng.

Lược đồ Cấu trúc Dữ liệu (Schemas)

0. Khung Siêu dữ liệu Gốc (Universal Data Page Contract)

Biểu thuế Giá trị Gia tăng (VAT Rates)

Biểu phí Duy trì Đường bộ Ô tô (Road Maintenance Fee)

Biểu giá Bán lẻ Điện Sinh hoạt (Residential Electricity Tariff)

Thang điểm Năng lực IELTS (IELTS Band Score Scale)

Bảng giá Vàng SJC (SJC Gold Price)