Input Schema

Input Schema là gì?

Input Schema là định nghĩa cấu trúc dữ liệu đầu vào cho workflow hoặc node trong hệ thống automation. Nó xác định kiểu dữ liệu, trường bắt buộc, giá trị mặc định và quy tắc validation để đảm bảo dữ liệu đầu vào hợp lệ trước khi xử lý. Trong các nền tảng như n8n, New Relic hay SonataFlow, Input Schema giúp tránh lỗi runtime bằng cách kiểm tra dữ liệu ngay từ đầu.

Input Schema thường được viết dưới dạng JSON Schema hoặc YAML, với các thuộc tính như type, defaultValue. Ví dụ trong New Relic:

“ workflowInputs: myInput1: type: String myInput2: type: Number defaultValue: 42 “

Vai trò của Input Schema trong luồng dữ liệu

Input Schema đóng vai trò kiểm soát chất lượng dữ liệu đầu vào, ngăn chặn lỗi lan truyền trong workflow. Nó xác thực dữ liệu từ Trigger, Webhook hoặc API call trước khi truyền đến các node tiếp theo. Nhờ đó, workflow chạy ổn định hơn, giảm thời gian debug và tăng độ tin cậy hệ thống.

Trong automation, Input Schema giúp:

• Xác định Input Schema cho từng bước (steps), đảm bảo inputs khớp với action function.
• Validate toàn bộ dữ liệu workflow qua dataInputSchema trong Serverless Workflow.
• Hỗ trợ expressions như ${{ .workflowInputs.count }} để tham chiếu an toàn.

Input Schema được dùng như thế nào trong thực tế?

Input Schema được khai báo trong định nghĩa workflow, thường dưới dạng YAML hoặc JSON. Hệ thống tự động validate dữ liệu đầu vào dựa trên schema trước khi thực thi. Ví dụ, trong SonataFlow, bạn chỉ định URI đến JSON Schema:

“ "dataInputSchema": { "schema": "URL_to_json_schema", "failOnValidationErrors": false } “

Các bước sử dụng phổ biến bao gồm:

• Khai báo kiểu dữ liệu: type: String, Int, Boolean, List, Map để khớp với payload thực tế.
• Đặt giá trị mặc định: defaultValue tránh lỗi khi input thiếu.
• Validation động: Kiểm tra trước loop, switch hoặc action, như ${{ .steps.loopStep.loop.element }} chỉ hợp lệ trong scope.
• Tích hợp với tools: Truyền args an toàn qua call: tool: ProcessDataTool args: { userId: ${ args.userId } }.

Trong n8n hoặc tương tự, Input Schema xuất hiện ở node settings, giúp map dữ liệu từ JSON payload sang fields.

Những lỗi hoặc hiểu sai phổ biến về Input Schema

Lỗi phổ biến nhất là bỏ qua validation, dẫn đến workflow crash khi dữ liệu không khớp type. Ví dụ, truyền string vào field type: Number gây lỗi parse. Một hiểu sai khác là nghĩ schema chỉ static; thực tế nó hỗ trợ expressions và dynamic validation tùy hệ thống.

Các lỗi thường gặp:

• Thiếu defaultValue: Workflow fail nếu input tùy chọn không được cung cấp.
• Schema URI sai: Trong SonataFlow, classpath hoặc HTTP URL không tồn tại gây validation bỏ qua.
• Scope expressions sai: ${{ .steps.loopStep.loop.index }} chỉ dùng trong loop, lỗi nếu trích xuất ngoài.
• failOnValidationErrors = true: Workflow dừng ngay nếu dữ liệu sai, thay vì fallback.

Để tránh, luôn test schema với sample data trước deploy.

Các thuật ngữ liên quan đến Input Schema

Một số thuật ngữ thường liên kết trực tiếp với Input Schema trong automation:

• JSON Schema: Tiêu chuẩn định nghĩa cấu trúc dữ liệu, thường dùng cho dataInputSchema validation.
• Data Mapping: Quá trình ánh xạ fields từ input theo schema sang output hoặc node tiếp theo.
• Payload: Dữ liệu thực tế được validate bởi Input Schema, thường ở format JSON hoặc YAML.
• Validation: Quá trình kiểm tra dữ liệu khớp schema, có thể fail workflow nếu lỗi.

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

Input Schema khác gì với Output Schema?

Input Schema định nghĩa cấu trúc dữ liệu vào workflow hoặc node, còn Output Schema mô tả dữ liệu ra. Input tập trung validate đầu vào, Output đảm bảo định dạng kết quả nhất quán cho node sau.

Khi nào nên dùng defaultValue trong Input Schema?

Dùng defaultValue cho trường tùy chọn để tránh lỗi khi input thiếu. Nó phải khớp type, giúp workflow chạy mượt mà hơn mà không cần kiểm tra thủ công.

Làm sao nếu validation Input Schema fail?

Tùy hệ thống, set failOnValidationErrors: false để tiếp tục với dữ liệu mặc định hoặc fallback. Kiểm tra logs để debug schema hoặc input data.

Input Schema có hỗ trợ complex types như nested objects không?

Có, hỗ trợ Map, List cho cấu trúc lồng nhau. Ví dụ type: Map cho object con, nhưng phải định nghĩa chi tiết để validate đúng.