pub trait PayloadMetadata {
// Provided methods
fn json_schema() -> Option<Value> { ... }
fn input_metadata() -> InputMetadata { ... }
fn output_metadata() -> OutputMetadata { ... }
}
Expand description
§Payload metadata and Json Schemas
The SDK propagates during discovery some metadata to restate-server service catalog. This includes:
- The JSON schema of the payload. See below for more details.
- The InputMetadata used to instruct restate how to accept requests.
- The OutputMetadata used to instruct restate how to send responses out.
There are three approaches for generating JSON Schemas for handler inputs and outputs:
§1. Primitive Types
Primitive types (like String
, u32
, bool
) have built-in schema implementations
that work automatically without additional code:
use restate_sdk::prelude::*;
#[restate_sdk::service]
trait SimpleService {
async fn greet(name: String) -> HandlerResult<u32>;
}
§2. Using Json<T>
with schemars
For complex types wrapped in Json<T>
, you need to add the schemars
feature and derive JsonSchema
:
use restate_sdk::prelude::*;
#[derive(serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
struct User {
name: String,
age: u32,
}
#[restate_sdk::service]
trait UserService {
async fn register(user: Json<User>) -> HandlerResult<Json<User>>;
}
To enable rich schema generation with Json<T>
, add the schemars
feature to your dependency:
[dependencies]
restate-sdk = { version = "0.3", features = ["schemars"] }
schemars = "1.0.0-alpha.17"
§3. Custom Implementation
You can also implement the PayloadMetadata trait directly for your types to provide
custom schemas without relying on the schemars
feature:
use restate_sdk::serde::{PayloadMetadata, Serialize, Deserialize};
#[derive(serde::Serialize, serde::Deserialize)]
struct User {
name: String,
age: u32,
}
// Implement PayloadMetadata directly and override the json_schema implementation
impl PayloadMetadata for User {
fn json_schema() -> Option<serde_json::Value> {
Some(serde_json::json!({
"type": "object",
"properties": {
"name": {"type": "string"},
"age": {"type": "integer", "minimum": 0}
},
"required": ["name", "age"]
}))
}
}
Trait encapsulating JSON Schema information for the given serializer/deserializer.
This trait allows types to provide JSON Schema information that can be used for documentation, validation, and client generation.
§Behavior with schemars
Feature Flag
When the schemars
feature is enabled, implementations for complex types use
the schemars
crate to automatically generate rich, JSON Schema 2020-12 conforming schemas.
When the feature is disabled, primitive types still provide basic schemas,
but complex types return empty schemas, unless manually implemented.
Provided Methods§
Sourcefn json_schema() -> Option<Value>
fn json_schema() -> Option<Value>
Generate a JSON Schema for this type.
Returns a JSON value representing the schema for this type. When the schemars
feature is enabled, this returns an auto-generated JSON Schema 2020-12 conforming schema. When the feature is disabled,
this returns an empty schema for complex types, but basic schemas for primitives.
If returns none, no schema is provided. This should be used when the payload is not expected to be json
Sourcefn input_metadata() -> InputMetadata
fn input_metadata() -> InputMetadata
Returns the InputMetadata. The default implementation returns metadata suitable for JSON payloads.
Sourcefn output_metadata() -> OutputMetadata
fn output_metadata() -> OutputMetadata
Returns the OutputMetadata. The default implementation returns metadata suitable for JSON payloads.
Dyn Compatibility§
This trait is not dyn compatible.
In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.