Response Model Reference

Overview

Zigmund provides response model features that control how route responses are shaped, validated, and documented in the OpenAPI specification.

ResponseModelAlias

Maps response model field paths to alternative names in the JSON output.

pub const ResponseModelAlias = struct {
    path: []const u8,
    alias: []const u8,
};

Usage in Response Models

Define aliases on your struct using the zigmund_response_aliases declaration:

const UserResponse = struct {
    first_name: []const u8,
    last_name: []const u8,
    email_address: []const u8,

    pub const zigmund_response_aliases: []const zigmund.ResponseModelAlias = &.{
        .{ .path = "first_name", .alias = "firstName" },
        .{ .path = "last_name", .alias = "lastName" },
        .{ .path = "email_address", .alias = "email" },
    };
};

ComputedFieldFn

A function that computes a field value from the existing response object.

pub const ComputedFieldFn = *const fn (std.json.ObjectMap, std.mem.Allocator) anyerror!std.json.Value

ComputedFieldEntry

Associates a computed field name with its computation function.

pub const ComputedFieldEntry = struct {
    name: []const u8,
    compute: ComputedFieldFn,
};

Usage in Response Models

Define computed fields using the zigmund_computed_fields declaration:

const OrderResponse = struct {
    subtotal: f64,
    tax: f64,

    pub const zigmund_computed_fields: []const zigmund.ComputedFieldEntry = &.{
        .{
            .name = "total",
            .compute = computeTotal,
        },
    };

    fn computeTotal(obj: std.json.ObjectMap, allocator: std.mem.Allocator) !std.json.Value {
        _ = allocator;
        const subtotal = obj.get("subtotal").?.float;
        const tax = obj.get("tax").?.float;
        return .{ .float = subtotal + tax };
    }
};

Response Transform and Validate

Transform

Define a zigmund_response_transform declaration on your response model struct to modify the JSON value before it is sent:

pub fn zigmund_response_transform(value: *std.json.Value, allocator: std.mem.Allocator) !void {
    // Modify the JSON value tree
}

Validate

Define a zigmund_response_validate declaration to validate the JSON value before sending:

pub fn zigmund_response_validate(value: *const std.json.Value, allocator: std.mem.Allocator) !void {
    // Return an error to reject the response
}

RouteOptions Response Model Fields

Example

try app.get("/orders/{id}", getOrder, .{
    .response_model = OrderResponse,
    .response_model_exclude = &.{"internal_notes"},
    .response_model_exclude_none = true,
});