Data contract là gì? Bản quy ước để hiểu đúng dữ liệu thị trường

Hai API có thể cùng nói về một mức giá, nhưng trả về hai con số khác nhau: 25.400 và 25.4.

Dữ liệu trên bảng giá hoặc luồng sổ lệnh thường biểu diễn giá theo đơn vị đồng, nên 25.400 có nghĩa là 25.400 đồng. Dữ liệu dùng để vẽ đồ thị kỹ thuật lại thường biểu diễn theo đơn vị nghìn đồng, nên cùng mức giá đó trở thành 25.4. Nếu chỉ nhìn tên trường và giá trị số mà không biết đơn vị, chương trình có thể hiểu hai mức giá chênh nhau một nghìn lần dù chúng thực chất là một.

Nếu chỉ nhìn tên cột và con số, người dùng rất dễ ghép hai bảng với nhau. Chương trình vẫn chạy, biểu đồ vẫn hiện, nhưng kết luận có thể đã lệch từ đầu.

Data contract giúp làm rõ những khác biệt như vậy. Có thể hiểu đơn giản, đây là bản quy ước chung để người tạo dữ liệu, người viết công cụ và người sử dụng dữ liệu hiểu cùng một ý.¹

Chữ contract ở đây nên được hiểu là những quy ước được viết rõ để các bên cùng làm theo, không phải một hợp đồng mua bán. Từ đây, bài viết sẽ gọi khái niệm này bằng tên gần gũi hơn là quy ước dữ liệu. Với một dự án cá nhân, quy ước dữ liệu chưa cần là tài liệu phức tạp: một bảng Excel hoặc một trang Markdown mô tả tên trường, ý nghĩa, đơn vị, mốc thời gian và cách xử lý dữ liệu thiếu đã là điểm khởi đầu hữu ích.

Tóm tắt trong một phút

• Data contract (quy ước dữ liệu) là bản mô tả thống nhất về cấu trúc, ý nghĩa, đơn vị, thời gian và cách xử lý ngoại lệ để người tạo dữ liệu, công cụ và người phân tích hiểu cùng một ý.
• Schema chỉ mô tả hình dạng kỹ thuật của bảng dữ liệu (tên cột, kiểu dữ liệu, trường bắt buộc) và là một phần bên trong data contract.
• Mapping dữ liệu là bước đối chiếu và chuyển đổi tên trường, đơn vị, định dạng từ từng API về quy ước chung.
• Metadata ngữ nghĩa là lớp chú giải đi kèm giúp con người, chương trình Python và trợ lý AI không suy diễn sai phạm vi của con số.
• Adapter (bộ chuyển đổi) là phần mã thực thi việc đưa dữ liệu đầu vào về đúng chuẩn đã quy ước trước khi tính toán.

Data contract (quy ước dữ liệu) giải quyết vấn đề gì?

Một Open API chứng khoán có thể chứa nhiều nhóm dữ liệu khác nhau, từ danh mục mã và giá lịch sử đến dữ liệu trong phiên. Tài liệu API thường mô tả địa chỉ kết nối, tham số và cấu trúc phản hồi. Tuy nhiên, biết cách lấy được một trường dữ liệu chưa đồng nghĩa đã hiểu đầy đủ cách dùng trường đó.

Người làm tài chính thường cần thêm những câu trả lời như:

• Giá đang tính bằng đồng hay nghìn đồng?
• Khối lượng là của một lần khớp, của cây nến hay lũy kế từ đầu phiên?
• Cây nến một phút được đánh dấu ở đầu phút hay cuối phút?
• Giá đóng cửa là giá gốc hay đã qua một bước điều chỉnh?
• Một phản hồi mô tả toàn bộ trạng thái thị trường tại thời điểm đó hay chỉ chứa phần vừa thay đổi?
• Thời điểm 09:30 thuộc múi giờ nào?
• Giá trị 0 nghĩa là thực sự bằng không hay chưa có dữ liệu?
• Khi nguồn thay đổi tên trường, phần phân tích nào sẽ bị ảnh hưởng?

Đây là phần thường chưa được mô tả đầy đủ tại giao điểm giữa tài liệu kỹ thuật và cách thị trường được biểu diễn thành dữ liệu. Lập trình viên có thể đọc đúng kiểu dữ liệu nhưng không biết khối lượng đang nói về phạm vi nào. Người làm tài chính hiểu bảng giá nhưng có thể không nhận ra null, 0 và trường không xuất hiện là ba trạng thái kỹ thuật khác nhau.

Quy ước dữ liệu đưa hai phía về cùng một cách hiểu trước khi dữ liệu được dùng để tính toán.

Từ bảng giá quen thuộc đến mapping các trường kỹ thuật trong API

Người mới làm quen với API thường đã biết cách đọc bảng giá hoặc một website phân tích. Trên giao diện, họ nhìn thấy những nhãn quen thuộc như “Mã CK”, “Giá khớp”, “KL”, “Dư mua” hay “Dư bán”. Thông tin được sắp xếp để con người quan sát nhanh và thường đã qua một lớp định dạng trước khi hiển thị.

API trình bày cùng thế giới đó theo cách phù hợp hơn với hệ thống. “Mã CK” có thể trở thành symbol hoặc ticker; “Giá khớp” có thể nằm trong một trường mang tên last_price; khối lượng có thể được tách thành khối lượng của lần khớp gần nhất, khối lượng tại một mức giá hoặc tổng khối lượng từ đầu phiên. Dư mua và dư bán có thể không còn là vài cột phẳng mà trở thành danh sách nhiều mức giá và khối lượng.

Vì vậy, mapping dữ liệu không chỉ là đổi một tên tiếng Anh sang tiếng Việt. Người dùng cần đối chiếu ba lớp:

1. Thứ nhìn thấy trên giao diện: nhãn, cách làm tròn và cách sắp xếp để con người dễ đọc.
2. Trường kỹ thuật trong API: tên trường, kiểu dữ liệu và vị trí của nó trong phản hồi.
3. Ý nghĩa thực tế: con số mô tả giá trị nào, tại thời điểm nào, theo đơn vị và phạm vi nào.

Nếu thiếu lớp thứ ba, một phép đổi tên như last_price thành gia_khop vẫn chưa đủ. Chương trình còn phải biết đó là giá của lần khớp gần nhất, giá đóng cửa của cây nến hay một giá trị đang được cập nhật trong phiên.

Khi tên trường chưa đủ: vai trò của metadata mô tả ngữ nghĩa

Tên trường trong API thường được viết bằng tiếng Anh để thuận tiện cho lập trình và tích hợp. Một số hệ thống dùng tên viết tắt hoặc tiếng Việt không dấu. Các cách đặt tên này đều có thể hoạt động tốt khi đã có tài liệu đi kèm, nhưng bản thân tên trường không phải lúc nào cũng tái hiện đầy đủ ý nghĩa ban đầu.

Ví dụ, một tên như khoiluong có thể được con người đoán là “khối lượng”, nhưng vẫn chưa cho biết đó là khối lượng của một lần khớp, một cây nến hay toàn phiên. Tên viết tắt còn có thể mang nhiều cách hiểu hơn nếu bị tách khỏi tài liệu của nguồn.

Điểm này càng đáng chú ý khi bên đọc API không chỉ là con người. Trợ lý AI và các công cụ tự động cũng đọc tài liệu, tên trường và mẫu phản hồi để viết mã. Một tên trường có vẻ quen với người đã dùng hệ thống lâu năm vẫn có thể bị AI suy diễn sai nếu thiếu ngữ cảnh.

Vì thế, bên cạnh tên trường cần có metadata mô tả ngữ nghĩa, chẳng hạn:

• tên hiển thị bằng ngôn ngữ gần với người dùng;
• định nghĩa ngắn gọn của trường;
• đơn vị và kiểu dữ liệu;
• phạm vi thời gian;
• giá trị mẫu;
• quan hệ với trường khác;
• quy ước khi dữ liệu bằng 0, để trống hoặc không xuất hiện.

Metadata không làm thay đổi dữ liệu gốc. Nó tạo thêm lớp chú giải để con người, chương trình và AI agent cùng có cơ sở diễn giải một trường theo cùng một cách.

Hãy hình dung quy ước dữ liệu như phiếu mô tả một con số

Khi nhận một bảng Excel, bạn thường muốn biết ai lập bảng, số liệu thuộc kỳ nào, đơn vị là gì và công thức ra sao. Quy ước dữ liệu làm việc tương tự, nhưng có cấu trúc rõ hơn để cả con người lẫn chương trình đều có thể kiểm tra.

Ví dụ, thay vì chỉ ghi:

một bản quy ước có thể mô tả:

Phần quan trọng nhất không nằm ở tên volume. Nó nằm ở những dòng giải thích phía sau. Nhờ đó, người đọc biết liệu có thể ghép con số này với một bảng khác hay không.

Bảy thành phần nên có trong một data contract

Không phải dự án cá nhân nào cũng cần một tiêu chuẩn phức tạp. Các tiêu chuẩn quốc tế có thể mô tả nhiều lớp như cấu trúc, chất lượng và quy tắc nghiệp vụ,² nhưng với dữ liệu phục vụ nghiên cứu thị trường, bạn có thể bắt đầu bằng bảy nhóm thông tin sau.

1. Cấu trúc bảng và các trường dữ liệu (Schema)

Phần này trả lời bảng có những cột nào, mỗi cột chứa chữ, số hay thời gian và trường nào bắt buộc.

Ví dụ, một bảng giá lịch sử có thể thống nhất các cột:

• time: thời điểm của kỳ dữ liệu;
• open, high, low, close: các mức giá;
• volume: khối lượng;
• symbol: mã định danh của tài sản.

Đây là phần gần nhất với khái niệm schema trong kỹ thuật. Người làm tài chính có thể hiểu nó đơn giản là “mẫu bảng chuẩn”.

2. Ý nghĩa của từng trường

Tên cột chỉ là nhãn. Ngữ nghĩa mới cho biết con số thực sự nói về điều gì.

Chẳng hạn, volume có thể chỉ:

• khối lượng của một giao dịch;
• tổng khối lượng trong một phút;
• khối lượng lũy kế trong phiên;
• khối lượng khớp lệnh, có hoặc không gồm phần thỏa thuận.

Nếu phần này không được nói rõ, đổi tên tất cả về volume chỉ làm cho dữ liệu trông giống nhau hơn, chứ chưa làm chúng tương đương.

3. Đơn vị và cách biểu diễn

Một con số giá 25.4 có thể là 25,4 nghìn đồng hoặc 25,4 đồng. Một con số thời gian có thể tính bằng giây hoặc mili giây. Khối lượng và giá trị cũng có thể được biểu diễn theo những đơn vị khác nhau.

Quy ước dữ liệu nên ghi rõ:

• đơn vị tiền tệ;
• giá trị gốc hay đã quy đổi;
• thời gian được lưu theo định dạng nào;
• quy tắc làm tròn;
• đơn vị của khối lượng và giá trị.

Đây là một trong những lỗi nguy hiểm nhất vì chương trình thường không báo lỗi khi hai số khác đơn vị được đặt cạnh nhau.

4. Mốc thời gian và khung dữ liệu

Với dữ liệu thị trường, cần biết thời điểm đánh dấu đầu kỳ hay cuối kỳ, múi giờ nào, phiên nào được tính và một cây nến đã hoàn tất hay vẫn đang được cập nhật.

Một thời điểm như 09:30:00 có thể là:

• thời điểm bắt đầu cây nến;
• thời điểm kết thúc cây nến;
• thời điểm bản tin được tạo tại nguồn;
• thời điểm chương trình của người dùng nhận được bản tin.

Nếu trộn các mốc này, việc so sánh theo thời gian rất dễ tạo ra sai lệch.

5. Quy ước cho dữ liệu thiếu và bất thường

Trong dữ liệu thị trường, 0 không giống “chưa có”. Một khoảng thời gian không phát sinh khớp lệnh khác với trường hợp chương trình chưa nhận được bản tin hoặc nguồn không trả trường đó.

Quy ước dữ liệu nên nói rõ:

• khi nào dùng null hoặc để trống;
• có được thay giá trị thiếu bằng 0 hay không;
• giá trị âm có hợp lệ không;
• bản ghi trùng được xử lý thế nào;
• điều kiện nào khiến một dòng bị xem là bất thường.

Quy ước này giúp tránh tình trạng làm sạch dữ liệu quá tay và vô tình thay đổi ý nghĩa kinh tế của con số.

6. Nguồn gốc và cách hình thành kết quả

Một cột có thể đến trực tiếp từ phản hồi của API, được đọc từ tệp trên máy hoặc được tính từ nhiều cột khác. Ba trường hợp này nên được phân biệt.

Với kết quả tự tính, nên lưu thêm:

• công thức;
• trường đầu vào;
• kỳ dữ liệu;
• quy tắc xử lý ngoại lệ;
• thời điểm chạy.

Khi đó, câu hỏi “con số này ở đâu ra?” có thể được trả lời bằng một đường đi cụ thể thay vì dựa vào trí nhớ.

7. Quy tắc khi dữ liệu thay đổi

API và tệp đầu vào có thể thay đổi theo thời gian. Một trường được đổi tên, một kiểu dữ liệu chuyển từ số sang chuỗi hoặc cấu trúc bản tin được bổ sung thêm lớp lồng nhau đều có thể ảnh hưởng đến chương trình phía sau.

Quy ước dữ liệu nên có số phiên bản và ghi lại những thay đổi quan trọng. Khi một thay đổi không còn tương thích, chương trình có thể dừng để người dùng kiểm tra thay vì tiếp tục tạo ra kết quả khó phát hiện là sai.

Quy ước dữ liệu không tự quyết định cách dùng dữ liệu

Một bản quy ước tốt không tự quyết định nên dùng giá gốc hay giá điều chỉnh, nên ghép các bản tin trong phiên ra sao hoặc khung thời gian nào phù hợp với câu hỏi nghiên cứu.

Nó chỉ làm cho lựa chọn đó trở nên rõ ràng.

Đây là khác biệt quan trọng. Quy ước dữ liệu không biến mọi nguồn thành giống nhau và cũng không khẳng định một cách diễn giải là đúng cho mọi mục đích. Nó giúp người dùng biết:

• hai bảng đang giống và khác nhau ở đâu;
• phép so sánh nào hợp lý;
• giả định nào đã được sử dụng;
• điều gì cần kiểm tra lại trước khi đưa vào phân tích.

Vì vậy, phần khó nhất của quy ước dữ liệu thường không phải viết tên cột. Phần khó là chuyển tài liệu kỹ thuật và kiến thức thị trường thành một cách diễn giải đủ rõ để người khác có thể dùng lại.

Vì sao có tài liệu API vẫn cần thêm lớp hỗ trợ?

Tài liệu API được viết trước hết để người tích hợp biết cách kết nối: xác thực ra sao, gửi tham số nào và phản hồi có cấu trúc gì. Mức độ giải thích nghiệp vụ, ví dụ sử dụng, thư viện hỗ trợ và kênh giải đáp có thể khác nhau giữa các bên.

Với người dùng phổ thông hoặc người nhờ AI viết code, khoảng cách thường xuất hiện ở ba bước:

1. Đọc được phản hồi: biết trường nào nằm ở đâu và chuyển thành bảng như thế nào.
2. Hiểu đúng phản hồi: biết trường đó mô tả trạng thái nào của thị trường, thuộc khung thời gian nào và dùng đơn vị nào.
3. Dùng được trong một quy trình: chuẩn hóa, kiểm tra, tính toán và lưu lại để lần sau có thể chạy lại.

AI hỗ trợ tốt bước viết mã, nhưng thường không thể tự suy ra chính xác một quy ước chưa được mô tả. Nếu chỉ đưa cho AI một mẫu JSON, nó có thể đổi tên cột rất nhanh nhưng vẫn hiểu sai khối lượng lũy kế, mốc thời gian hoặc đơn vị giá.

Vì thế, hỗ trợ kỹ thuật và nội dung giải thích ngữ nghĩa cần đi cùng nhau. Một đoạn code chạy được trả lời câu hỏi “làm thế nào”. Phần mô tả dữ liệu trả lời câu hỏi “con số này nghĩa là gì và nên dùng trong trường hợp nào”.

Vnstock hỗ trợ quá trình này như thế nào?

Vnstock được tổ chức như một bộ khung làm việc trên máy người dùng, nơi thư viện Python, hướng dẫn cho AI agent và tài liệu sử dụng phối hợp với nhau. Mục tiêu không chỉ là giúp một lệnh kết nối chạy được, mà còn đưa đúng hướng dẫn và ngữ cảnh tới người dùng hoặc agent ở thời điểm cần thiết.

Phần cốt lõi của trải nghiệm này nằm ở các công cụ chạy cục bộ. Bài viết và nội dung chia sẻ là lớp bổ sung, giúp giải thích ngữ nghĩa và cách sử dụng bằng ngôn ngữ gần với người làm tài chính.

Thư viện là lớp thực thi

Các thư viện giúp người dùng và AI agent làm việc với dữ liệu qua những hàm và cấu trúc quen thuộc trong Python. Thư viện kết nối đảm nhiệm việc truy xuất và chuẩn hóa đầu vào trên máy người dùng (điều kiện và phạm vi sử dụng dữ liệu đầu vào tuân theo quy định của từng nguồn), trong khi các công cụ tính toán và xử lý quy trình làm việc trực tiếp trên bảng dữ liệu bạn đưa vào. Khi một thao tác cần thêm bước xác thực, tài liệu hoặc quyền truy cập, thư viện cũng trả về chỉ dẫn phù hợp.

AGENTS.md và Agent Skills là lớp chỉ dẫn

Tệp AGENTS.md cung cấp hướng dẫn khởi đầu để agent nhận ra cách làm việc với Vnstock. Khi nhiệm vụ cụ thể hơn, Agent Skills bổ sung quy trình, cú pháp, giới hạn và cách kiểm tra cần thiết. Một số chỉ dẫn còn được kích hoạt từ chính quá trình sử dụng thư viện, giúp agent biết khi nào cần đăng nhập hoặc nạp thêm tài liệu và skill thay vì chờ người dùng tìm từng liên kết rồi đưa vào cuộc trò chuyện.

Blog và nội dung chia sẻ giúp người dùng hiểu vấn đề

Nhiều người trong cộng đồng tiếp cận lập trình theo kiểu vibe coding: mô tả điều mình muốn rồi nhờ AI viết phần lớn mã nguồn. Cách làm này giúp bắt đầu nhanh, nhưng người dùng dễ bế tắc khi gặp những khái niệm như schema, mapping, metadata, kiểu dữ liệu hay đơn vị đo. Mã có thể chạy mà kết quả vẫn sai, trong khi người dùng chưa có đủ nền tảng để biết nên kiểm tra ở đâu hoặc đặt lại câu hỏi thế nào.

Blog và các bài chia sẻ kiến thức của Vnstock nhằm thu hẹp khoảng trống đó. Nội dung không yêu cầu người đọc trở thành kỹ sư dữ liệu, mà giúp họ hiểu cốt lõi của vấn đề đủ để mô tả yêu cầu rõ hơn, kiểm tra kết quả do AI tạo ra và tiếp tục xử lý khi quy trình không chạy như mong đợi. Các chủ đề như Open API, dữ liệu thị trường, quy ước dữ liệu và chuẩn hóa vì thế không chỉ phục vụ việc viết code; chúng còn giúp cộng đồng xây dựng cách tư duy cần thiết để làm việc hiệu quả hơn với AI.

Khi các lớp này nối với nhau, agent có thể tự tìm đúng chỉ dẫn và thực hiện nhiều bước trong phạm vi được cho phép, thay vì người viết code phải nạp tài liệu bằng tay cho từng yêu cầu. Người dùng vẫn là người chọn nguồn, cấp quyền và kiểm tra kết quả; Vnstock không thay nguồn quyết định ý nghĩa hay chất lượng dữ liệu.

Bắt đầu bằng một quy ước dữ liệu nhỏ

Bạn không cần bắt đầu bằng một hệ thống phức tạp. Hãy chọn một bảng đang dùng thường xuyên và tạo một trang mô tả với bảy cột:

Sau đó, thử trả lời ba câu hỏi:

1. Một người khác đọc bảng này có hiểu giống bạn không?
2. AI có đủ thông tin để viết đoạn chuyển đổi mà không phải đoán không?
3. Nếu đổi nguồn đầu vào, bạn có xác định được phần nào cần ánh xạ lại không?

Nếu câu trả lời còn mơ hồ, quy ước dữ liệu vẫn chưa mô tả đủ ý nghĩa.

Từ bản quy ước dữ liệu tới bộ chuyển đổi (Adapter)

Quy ước dữ liệu nói rõ đầu ra mong muốn. Bộ chuyển đổi, hay adapter, thực hiện việc đưa dữ liệu từ từng nguồn về đầu ra đó.

Thứ tự hợp lý là:

1. Xác định câu hỏi phân tích.
2. Chọn dữ liệu cần dùng.
3. Viết quy ước dữ liệu.
4. Tạo bộ chuyển đổi cho từng nguồn.
5. Áp dụng các phép kiểm dữ liệu trước khi tính toán.
6. Lưu lại nguồn, phiên bản và thời điểm chạy.

Nếu viết adapter trước khi thống nhất ý nghĩa, chương trình có thể đổi tên cột rất đẹp nhưng vẫn ghép nhầm dữ liệu. Bạn có thể xem bước triển khai cụ thể trong bài Chuẩn hóa dữ liệu chứng khoán khi vibe coding để tránh lỗi.

Câu hỏi thường gặp

Data contract khác gì API schema?

API schema chủ yếu mô tả hình dạng kỹ thuật của dữ liệu như tên trường, kiểu dữ liệu (string, float, integer) và trường bắt buộc. Data contract bao gồm cả schema nhưng bổ sung thêm ngữ nghĩa nghiệp vụ, đơn vị tính, quy ước thời gian, cách xử lý dữ liệu thiếu và quy tắc quản lý khi cấu trúc thay đổi.

Dự án cá nhân bằng Python có cần viết data contract phức tạp không?

Không. Với nhu cầu nghiên cứu cá nhân, một bảng Markdown hoặc trang tính ghi rõ bảy cột (tên trường, ý nghĩa, kiểu dữ liệu, đơn vị, khung thời gian, quy ước giá trị thiếu và nguồn/công thức) đã đủ để kiểm soát chất lượng đầu vào và tái sử dụng lâu dài.

Làm sao để AI agent tuân thủ quy ước dữ liệu khi vibe coding?

Thay vì chỉ đưa mẫu JSON phản hồi cho AI, hãy đính kèm bảng quy ước dữ liệu vào tệp hướng dẫn của dự án (chẳng hạn AGENTS.md hoặc tài liệu tham chiếu trong thư mục làm việc) và yêu cầu AI viết bước kiểm tra đơn vị, múi giờ, giá trị thiếu trước khi thực hiện phép tính.

Điều cần nhớ

Quy ước dữ liệu không phải khái niệm chỉ dành cho kỹ sư dữ liệu. Với người làm tài chính, nó là bản mô tả giúp một con số giữ nguyên ý nghĩa khi đi từ API hoặc tệp dữ liệu sang Excel, Python, AI và báo cáo phân tích.

Một quy ước dữ liệu hữu ích cần làm rõ ít nhất: cấu trúc, ý nghĩa, đơn vị, thời gian, giá trị thiếu, nguồn gốc và cách quản lý thay đổi. Khi những điểm này được viết ra, người làm tài chính và người hỗ trợ kỹ thuật có thể trao đổi trên cùng một nền, còn AI có ít khoảng trống hơn để tự suy đoán.

Đó cũng là phần Vnstock muốn đóng góp bên cạnh công cụ: tài liệu kỹ thuật để chương trình chạy được, nội dung giải thích để người dùng hiểu dữ liệu, và các quy ước giúp cách làm có thể được kiểm tra rồi sử dụng lại.

---

Nội dung phục vụ học tập, nghiên cứu và tham khảo, không phải khuyến nghị đầu tư. Phạm vi và ý nghĩa trường dữ liệu có thể thay đổi theo nguồn; hãy đọc tài liệu hiện hành, tuân thủ điều kiện sử dụng và tự kiểm tra trước khi đưa dữ liệu vào phân tích.

Footnotes

1. IBM mô tả data contract là thỏa thuận xác định cấu trúc, ngữ nghĩa, chất lượng và khả năng sẵn có của dữ liệu: What Is a Data Contract? ↩

2. Bitol duy trì Open Data Contract Standard, một khung tham khảo gồm schema, chất lượng, quy tắc nghiệp vụ và các thông tin vận hành: Open Data Contract Standard ↩