datamodel-code-generator: trình sinh mô hình dữ liệu Python
datamodel-code-generator là một công cụ dòng lệnh kiêm thư viện, chuyển OpenAPI, JSON Schema, GraphQL, Avro, Protobuf và dữ liệu JSON/YAML/CSV thô thành code Pydantic v2, dataclass, TypedDict hoặc msgspec.Struct. Nên dùng khi model của bạn xuất phát từ một schema mà bạn không muốn viết tay hai lần, nhất là khi cần chạy trong pipeline CI. Nên bỏ qua nếu tập schema của bạn nhỏ đến mức viết tay vài class Pydantic còn nhanh hơn học hệ thống preset và flag.
Sinh Mô Hình Python Từ Schema
datamodel-code-generator là một trình sinh code Python, đọc file schema rồi viết ra các class model Python tương ứng. Công cụ này nhận đầu vào là OpenAPI 3, AsyncAPI, JSON Schema, XML Schema, Protocol Buffers, Apache Avro, GraphQL, schema công cụ MCP, và dữ liệu JSON/YAML/CSV thô, rồi xuất ra code Pydantic v2 BaseModel, Pydantic v2 dataclass, dataclass chuẩn, TypedDict hoặc msgspec.Struct. Nó là CLI `datamodel-codegen` và cũng là một thư viện có thể import trực tiếp.
Định Dạng Đầu Vào Và Đầu Ra Được Hỗ Trợ
- ✓Đọc được OpenAPI 3, AsyncAPI, JSON Schema, XML Schema (XSD), Protocol Buffers/gRPC, Apache Avro, GraphQL, schema công cụ MCP, và dữ liệu JSON/YAML/CSV/dict Python thô làm đầu vào.
- ✓Xuất ra Pydantic v2 BaseModel, Pydantic v2 dataclass, dataclass chuẩn, TypedDict hoặc msgspec.Struct — bạn chọn kiểu đích bằng `--output-model-type`.
- ✓`--input-model path/to/file.py:ClassName` chuyển một class Pydantic, dataclass hoặc TypedDict có sẵn trong file khác sang kiểu output khác, nên bạn không bị khóa cứng vào kiểu model đã sinh lần đầu.
- ✓Xử lý được các cấu trúc schema phức tạp — `$ref`, `allOf`, `oneOf`, `anyOf`, enum và kiểu lồng nhau — thành type hint Python hoạt động đúng.
- ✓Có sẵn các preset đặt tên, như `standard-py312-20260619` và `practical-py312-20260619`, ghim sẵn một bộ giá trị mặc định được duy trì cho từng phiên bản Python đích, thay vì bắt bạn tự ghép hàng chục flag.
- ✓Mặc định định dạng code sinh ra bằng `black` và `isort`, dùng `--formatters builtin` để sinh nhanh hơn mà không cần các dependency đó, hoặc dùng Ruff qua `--formatters ruff-check ruff-format`.
Các Cách Cài Đặt
Theo README, cách cài được khuyến nghị cho việc dùng CLI độc lập là `uv tool install datamodel-code-generator`. Người dùng Conda có thể chạy `conda install -c conda-forge datamodel-code-generator`, còn dự án muốn ghim phiên bản trình sinh làm dev dependency nên dùng `uv add --dev datamodel-code-generator` thay vì cài toàn cục. Lệnh `pip install datamodel-code-generator` thông thường vẫn chạy được, hoặc bạn chạy thẳng không cần thêm vào dự án bằng `uv run --with datamodel-code-generator datamodel-codegen --help`. Có thêm các extra tùy chọn: `datamodel-code-generator[http]` để phân giải `$ref` từ xa, `[graphql]` cho đầu vào GraphQL, và `[protobuf]` cho đầu vào Protocol Buffers. Image Docker được publish dưới tên `koxudaxi/datamodel-code-generator` và chạy bằng tài khoản `appuser` không phải root, nên thư mục output gắn qua bind-mount cần được cấp quyền ghi cho tài khoản đó, hoặc bạn thêm `--user "$(id -u):$(id -g)"` vào lệnh docker run. Ngoài ra còn có gói cộng đồng cho Debian, Ubuntu, nixpkgs và openSUSE Tumbleweed, dù README lưu ý mức độ sẵn có và phiên bản khác nhau tùy bản phân phối.
Bắt Đầu Nhanh Với CLI
Lệnh quick-start trong README là: ```bash datamodel-codegen \ --input schema.json \ --input-file-type jsonschema \ --output-model-type pydantic_v2.BaseModel \ --preset standard-py312-20260619 \ --output model.py ``` Tên preset đó đã mã hóa sẵn phiên bản Python đích — `py312` nghĩa là Python 3.12 — và cho bạn một bộ flag mặc định được duy trì sẵn thay vì phải tự ghép. Trỏ `--input` vào bất kỳ file schema nào được hỗ trợ, đặt `--input-file-type` cho khớp, rồi chọn đích bằng `--output-model-type` (`pydantic_v2.BaseModel`, `dataclass`, `typeddict`, hoặc `msgspec.Struct`, cùng vài lựa chọn khác). Nếu muốn cấu hình lặp lại được, các tùy chọn tương tự có thể đặt trong bảng `[tool.datamodel-codegen]` của `pyproject.toml`, sau đó chỉ cần chạy `datamodel-codegen` trơn là nó tự đọc. Code sinh ra mặc định được định dạng bằng `black` và `isort`; thêm `--formatters builtin` để bỏ qua các dependency đó và sinh nhanh hơn, hoặc `--formatters ruff-check ruff-format` nếu bạn muốn dùng Ruff.
datamodel-code-generator Được Dùng Ở Đâu
- •Theo danh sách dependents trong README, openai/codex dùng datamodel-code-generator để sinh type cho public Python SDK từ protocol schema của mình.
- •modelcontextprotocol/python-sdk sinh các model protocol MCP từ JSON Schema được vendor sẵn bằng công cụ này, cũng theo danh sách đó.
- •apache/airflow chạy bước sinh datamodel từ OpenAPI cho airflow-ctl và task-sdk thông qua cấu hình codegen đặt trong pyproject, theo README.
- •PostHog/posthog chuyển JSON Schema thành model Pydantic bằng công cụ này, còn DataDog/integrations-core dùng nó để dựng các config model cho integration của mình.
- •Các bộ test và evaluation cũng dùng đến nó — README liệt kê nó là test dependency cho test MiniCPM3 của vllm-project/vllm, và là evaluation dependency của browser-use/browser-use.
Điểm Mạnh
- ✓Một công cụ bao phủ số lượng định dạng đầu vào khá rộng — OpenAPI, AsyncAPI, JSON Schema, XML Schema, Protocol Buffers, Avro, GraphQL, schema công cụ MCP, và JSON/YAML/CSV thô — thay vì phải dùng một trình sinh riêng cho từng định dạng.
- ✓`--input-model path/to/file.py:ClassName` chuyển một class Pydantic, dataclass hoặc TypedDict có sẵn sang kiểu output khác mà không cần viết tay lại.
- ✓Các preset có tên như `standard-py312-20260619` và `practical-py312-20260619` đóng gói sẵn giá trị mặc định hợp lý cho từng phiên bản Python đích, nên không phải mày mò hàng chục flag trước lần chạy đầu tiên.
- ✓Danh sách dependents trong README cho thấy công cụ này chạy trong codebase production thật — openai/codex, apache/airflow, PostHog/posthog — chứ không chỉ ví dụ minh họa.
- ✓Giấy phép MIT, nên không có điều khoản copyleft nào cần cân nhắc khi đưa trình sinh này vào build thương mại.
Lưu Ý Và Hành Vi Cần Biết
- △Code sinh ra hiện mặc định được định dạng bằng `black` và `isort`, nhưng README nói bản phát hành tương lai sẽ chuyển hai dependency này thành tùy chọn và đổi formatter mặc định sang `builtin` — nên ghim rõ formatter bạn muốn dùng để tránh pipeline bị thay đổi bất ngờ.
- △Phân giải `$ref` từ xa không có sẵn trong bản cài mặc định; phải cài thêm extra `[http]`, còn backend `httpx2` thử nghiệm cần cài riêng và không nằm trong `[all]`.
- △Đầu vào GraphQL và Protocol Buffers mỗi loại cần một extra riêng (`[graphql]`, `[protobuf]`) — không thể trỏ thẳng vào file `.proto` ngay khi cài mặc định.
- △Template output tùy chỉnh không được validator của `--formatters builtin` kiểm tra đầy đủ, nên output từ template lạ có thể cần báo lỗi thủ công thay vì tự động hoạt động đúng.
- △Ví dụ CI/CD trong README để phiên bản GitHub Action ở dạng placeholder (`@vX.Y.Z`) — bạn phải tự tìm và ghim một tag đã release thật.
Các Dự Án Liên Quan Trong Hệ Sinh Thái
Câu Hỏi Thường Gặp
datamodel-code-generator đọc được OpenAPI 3, AsyncAPI, JSON Schema, XML Schema, Protocol Buffers, Apache Avro, GraphQL, schema công cụ MCP, và dữ liệu JSON, YAML hoặc CSV thô, cùng các class Pydantic, dataclass hoặc TypedDict có sẵn qua `--input-model`.
datamodel-code-generator có thể xuất ra Pydantic v2 BaseModel, Pydantic v2 dataclass, dataclass chuẩn, TypedDict hoặc msgspec.Struct, chọn bằng flag `--output-model-type`.
README khuyến nghị chạy `uv tool install datamodel-code-generator` để dùng CLI độc lập, `conda install -c conda-forge datamodel-code-generator` cho Conda, hoặc `pip install datamodel-code-generator` thông thường; ngoài ra còn có image Docker được publish sẵn.
datamodel-code-generator được thiết kế có tính đến CI/CD: README có hẳn hướng dẫn CI/CD Integration cho GitHub Actions và pre-commit hook, cùng một GitHub Action tham chiếu dạng `koxudaxi/[email protected]` để sinh lại và kiểm tra model ngay trong pipeline.
README nói rằng playground chạy sinh code ngay trong trình duyệt của bạn qua Pyodide, nên schema và tùy chọn không được gửi lên backend; URL chia sẻ để tái hiện lỗi mã hóa trạng thái trong phần fragment của URL mà trình duyệt không gửi lên server — dù vậy URL đầy đủ vẫn có thể lưu lại trong lịch sử trình duyệt hoặc bất cứ đâu bạn dán nó.
datamodel-code-generator phát hành theo giấy phép MIT, theo file LICENSE được README dẫn tới.
Vấn Đề datamodel-code-generator Giải Quyết
Các team tiêu thụ hoặc phát hành spec JSON Schema, OpenAPI hay GraphQL vẫn thường phải tự viết tay code Pydantic hay dataclass tương ứng, và bản viết tay đó lệch khỏi schema ngay khi một trong hai bên thay đổi. datamodel-code-generator thu hẹp khoảng cách đó bằng cách sinh lại phần Python trực tiếp từ file schema, để việc cập nhật schema và cập nhật model chỉ còn cách nhau đúng một lệnh, thay vì hai lần sửa tay có thể lệch nhau.
Nên Dùng Cho Ai — Và Ai Nên Bỏ Qua
Nên dùng datamodel-code-generator nếu bạn đã có (hoặc đang tiêu thụ) một định nghĩa OpenAPI, JSON Schema, GraphQL, Avro hay Protobuf và muốn code Pydantic v2, dataclass, TypedDict hoặc msgspec.Struct tương ứng luôn được đồng bộ tự động — nhất là khi việc đồng bộ đó cần chạy trong CI. Nên bỏ qua nếu bạn không có schema chính thức nào để sinh từ đó, hoặc tập model của bạn nhỏ đến mức viết tay năm class Pydantic thực sự ít công hơn việc học hệ thống preset và flag trước.