PayloadMetadata

Trait PayloadMetadata 

Source
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§

Source

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

Source

fn input_metadata() -> InputMetadata

Returns the InputMetadata. The default implementation returns metadata suitable for JSON payloads.

Source

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.

Implementations on Foreign Types§

Source§

impl PayloadMetadata for bool

Source§

impl PayloadMetadata for f32

Source§

impl PayloadMetadata for f64

Source§

impl PayloadMetadata for i8

Source§

impl PayloadMetadata for i16

Source§

impl PayloadMetadata for i32

Source§

impl PayloadMetadata for i64

Source§

impl PayloadMetadata for i128

Source§

impl PayloadMetadata for u8

Source§

impl PayloadMetadata for u16

Source§

impl PayloadMetadata for u32

Source§

impl PayloadMetadata for u64

Source§

impl PayloadMetadata for u128

Source§

impl PayloadMetadata for String

Source§

impl PayloadMetadata for Vec<u8>

Source§

impl PayloadMetadata for Bytes

Source§

impl<T: PayloadMetadata> PayloadMetadata for Option<T>

Implementors§