Metadata phải trả lời được NFT này đại diện cho điều gì, ai phát hành và bằng chứng nằm ở đâu. Metadata must explain what the NFT represents, who issued it, and where the proof lives.

1. Trường dữ liệu ở cấp collection 1. Collection-level fields

• slug là định danh máy ổn định cho route, worker và contract mapping.slug is the stable machine identifier for routes, workers, and contract mappings.
• category phân loại collection thành identity, certificate, reputation, creator hoặc treasury.category classifies a collection as identity, certificate, reputation, creator, or treasury.
• issuanceMode mô tả điều kiện thực tế để worker được phép tạo payload mint.issuanceMode describes the practical conditions that allow the worker to produce a mint payload.
• proofModel nói rõ loại bằng chứng nào phải xuất hiện trong metadata.proofModel defines which proof model must appear in metadata.
• publicReady cho biết collection đã đủ chuẩn để được hiển thị như production hay chưa.publicReady indicates whether the collection is ready to be shown as production-grade.

2. Trường dữ liệu ở cấp token 2. Token-level fields

• tokenId là định danh được worker sinh ra từ collection, subject và bằng chứng.tokenId is generated by the worker from the collection, subject, and proof inputs.
• recipientName và walletAddress mô tả chủ thể nhận NFT.recipientName and walletAddress identify the NFT recipient.
• contentHash là điểm neo chống chỉnh sửa âm thầm cho nội dung hoặc hồ sơ xác minh.contentHash is the anti-tampering anchor for the content or verification record.
• proofUrl trỏ đến tài liệu hoặc bundle bằng chứng để bên ngoài có thể kiểm tra.proofUrl points to the document or proof bundle used for external verification.
• externalUrl mở landing page hoặc trang context cho người dùng cuối.externalUrl opens the landing page or context surface for end users.

3. Ví dụ metadata JSON 3. Sample metadata JSON

{
  "name": "IAI Genesis Pass • Nguyễn Văn A",
  "description": "Metadata xác minh vai trò và provenance cho hệ sinh thái IAI.",
  "external_url": "https://nft.iai.one/?collection=iai-genesis-pass&token=DEMO-0001",
  "attributes": [
    { "trait_type": "Bộ sưu tập", "value": "IAI Genesis Pass" },
    { "trait_type": "Mạng", "value": "Base / EVM" },
    { "trait_type": "Hash nội dung", "value": "sha256:demo-proof" },
    { "trait_type": "Ví nhận", "value": "0x1234...abcd" }
  ],
  "properties": {
    "collection_slug": "iai-genesis-pass",
    "token_id": "DEMO-0001",
    "proof": {
      "content_hash": "sha256:demo-proof",
      "proof_url": "https://nft.iai.one/docs/verification/"
    }
  }
}

4. Issuance payload tối thiểu 4. Minimum issuance payload

{
  "collection": "iai-knowledge-certificates",
  "recipientName": "Nguyễn Văn A",
  "walletAddress": "0x1234...abcd",
  "contentHash": "sha256:lesson-proof",
  "proofUrl": "https://docs.iai.one/lessons/truth-and-provenance",
  "externalId": "IAI-LSN-2026-0042",
  "title": "Truth and Provenance Completion"
}

Payload này có thể gửi trực tiếp tới /api/issuance-preview để lấy metadata thật, checklist và mức độ sẵn sàng mint. This payload can be sent directly to /api/issuance-preview to obtain real metadata, the issuance checklist, and mint readiness.

5. Endpoint production 5. Production endpoints

• GET /api/health kiểm tra worker và version đang chạy.checks the live worker and version.
• GET /api/collections?lang=vi trả về collection đã dịch đúng ngôn ngữ.returns collections localized to the selected language.
• GET /api/metadata?collection=iai-genesis-pass&token=DEMO-0001&lang=vi sinh metadata trực tiếp từ query.generates metadata directly from query parameters.
• POST /api/issuance-preview trả về preview, checklist và URL metadata.returns a preview, checklist, and metadata URL.
• POST /api/issue là entrypoint cho live mint khi signer và contract đã được cấu hình.is the live-mint entrypoint once the signer and contract are configured.

6. Quy tắc versioning và UX 6. Versioning and UX rules

• Mỗi thay đổi schema phải tăng version để tránh làm vỡ indexer và contract writer.Every schema change must bump the version to avoid breaking indexers and contract writers.
• Ngôn ngữ hiển thị phải đồng bộ từ query lang, dropdown và metadata locale.Display language must stay synchronized across the lang query, the dropdown, and the metadata locale.
• Không được ghi đè proof cũ mà không tạo hash mới hoặc changelog tương ứng.Existing proof must never be overwritten without a new hash or a matching changelog.
• Người dùng cuối phải nhìn thấy title, subject, proof URL và trạng thái rõ ràng trước khi mint.End users must see the title, subject, proof URL, and clear status before minting.