Schema Validation
mcp.zig provides utilities for working with JSON Schema, commonly used for tool input validation.
Overview
JSON Schema defines the structure of tool arguments, ensuring valid inputs.
Basic Schemas
Creating a Schema
var builder = mcp.schema.SchemaBuilder.init();
const schema = builder
.string_()
.description("A user's name")
.build();Schema Types
| Type | Method | Description |
|---|---|---|
| Object | .object_() | JSON object |
| Array | .array_() | JSON array |
| String | .string_() | Text value |
| Number | .number_() | Floating point |
| Integer | .integer_() | Whole number |
| Boolean | .boolean_() | true/false |
InputSchemaBuilder
Build complete input schemas for tools:
var schema = mcp.schema.InputSchemaBuilder.init(allocator);
defer schema.deinit(allocator);
// Add string property (required)
_ = try schema.addString(allocator, "name", "User's name", true);
// Add number property (optional)
_ = try schema.addNumber(allocator, "age", "User's age", false);
// Add boolean property
_ = try schema.addBoolean(allocator, "active", "Is user active", false);
// Add enum property
_ = try schema.addEnum(
allocator,
"role",
"User's role",
&.{ "admin", "user", "guest" },
true,
);
// Build the schema
const inputSchema = try schema.toInputSchema(allocator);Using with Tools
try server.addTool(.{
.name = "create_user",
.description = "Create a new user",
.handler = createUserHandler,
.inputSchema = try schema.toInputSchema(allocator),
});Schema Properties
String Constraints
builder
.string_()
.pattern("^[a-zA-Z]+$")
.format("email")Number Constraints
builder
.number_()
.minimum(0)
.maximum(100)InputSchemaBuilder Constraints
// For string length constraints on tool arguments:
_ = schema.setPropertyLength("name", 1, 100);
// For numeric ranges on tool arguments:
_ = schema.setPropertyRange("age", 18, 120);Common Formats
| Format | Description |
|---|---|
email | Email address |
uri | URI/URL |
date-time | ISO 8601 datetime |
uuid | UUID string |
Full JSON Schema 2020-12 documents
Tool.inputSchema and Tool.outputSchema are complete JSON Schema 2020-12 documents, not just a property bag. The typed struct covers the common cases, but keywords it cannot express ($ref, $defs, allOf/anyOf/oneOf, additionalProperties, patternProperties, bounds, ...) would otherwise be silently dropped. Pass the raw document instead:
var b = try std.json.parseFromSlice(std.json.Value, allocator,
\\{
\\ "$schema": "https://json-schema.org/draft/2020-12/schema",
\\ "type": "object",
\\ "additionalProperties": false,
\\ "$defs": { "Name": { "type": "string" } },
\\ "properties": { "name": { "$ref": "#/$defs/Name" } },
\\ "required": ["name"]
\\}
, .{});
defer b.deinit();
const input = mcp.types.InputSchema.fromJson(b.value);
var builder = mcp.tools.ToolBuilder.init("greet");
const tool = builder
.description("Greets somebody")
.inputSchemaFromRaw(b.value)
.handler(handler)
.build();The server emits raw verbatim and then overlays any typed fields that are also set, so nothing is lost either way. OutputSchema.fromJson and outputSchemaFromRaw work the same way.
Common Schemas
Pre-defined schemas for common types:
// String schema
const str = try mcp.schema.CommonSchemas.string_schema(allocator);
// Number schema
const num = try mcp.schema.CommonSchemas.number_schema(allocator);
// URI schema
const uri = try mcp.schema.CommonSchemas.uri_schema(allocator);
// DateTime schema
const dt = try mcp.schema.CommonSchemas.datetime_schema(allocator);Converting to JSON
Schemas can be converted to JSON for the protocol:
const json_value = try schema.toJson(allocator);Complete Example
const std = @import("std");
const mcp = @import("mcp");
pub fn setupServer(allocator: std.mem.Allocator) !mcp.Server {
var server: mcp.Server = .init(allocator, .{
.name = "validated-server",
.version = "1.0.0",
});
// Build input schema
var schema = mcp.schema.InputSchemaBuilder.init(allocator);
defer schema.deinit(allocator);
_ = try schema.addString(allocator, "username", "Unique username", true);
_ = try schema.addString(allocator, "email", "Email address", true);
_ = try schema.addInteger(allocator, "age", "User's age (must be 18+)", false);
_ = try schema.addBoolean(allocator, "newsletter", "Subscribe to newsletter", false);
_ = try schema.addEnum(
allocator,
"plan",
"Subscription plan",
&.{ "free", "basic", "pro" },
true,
);
try server.addTool(.{
.name = "register_user",
.description = "Register a new user account",
.handler = registerHandler,
.inputSchema = try schema.toInputSchema(allocator),
});
return server;
}
fn registerHandler(
_: ?*anyopaque,
_: std.Io,
allocator: std.mem.Allocator,
args: ?std.json.Value,
) mcp.tools.ToolError!mcp.tools.ToolResult {
// Arguments are already validated against schema by client
const username = mcp.tools.getString(args, "username") orelse {
return error.InvalidArguments;
};
const email = mcp.tools.getString(args, "email") orelse {
return error.InvalidArguments;
};
const plan = mcp.tools.getString(args, "plan") orelse "free";
const message = try std.fmt.allocPrint(
allocator,
"User {s} registered with email {s} on {s} plan",
.{ username, email, plan },
);
return mcp.tools.textResult(allocator, message);
}Best Practices
Do
- Always define schemas for tools
- Use descriptive descriptions
- Mark required fields appropriately
- Use appropriate types (integer vs number)
Don't
- Skip validation in handlers
- Use overly permissive schemas
- Forget to document optional fields
Next Steps
- Tools Guide - Using schemas with tools
- Error Handling - Handle validation errors
- API Reference - Schema API details
