Skip to main content

Schema

Derive Macro Schema 

Source
#[derive(Schema)]
{
    // Attributes available to this derive:
    #[simple]
}
Expand description

Constraints on the members of an action’s types, re-exported.

The derive lives in its own crate, because a crate that defines a procedural macro may export only macros. An action never names that crate: it depends on this one, whose default derive feature brings the derive in and puts it here and in the prelude, so use simpleplatform_sdk::prelude::*; is still the whole import list. The simple helper attribute comes with it.

An action that writes no constraints turns the feature off with default-features = false, and then compiles no procedural macro at all. Constraints on the members of an action’s input or output type.

use simpleplatform_sdk_macros::Schema;

#[derive(Schema)]
struct Payload {
    /// Doc comment becomes the description.
    #[simple(length(min = 1, max = 500))]
    ids: Vec<String>,

    /// How many days back to look.
    #[simple(range(min = 1, max = 90))]
    days: u32,

    /// Only keys starting here.
    #[simple(pattern = "^KNOW", length(max = 64))]
    prefix: String,
}

§What this derive generates

Nothing. It expands to an empty token stream, so a member that carries constraints costs a built module exactly what a member without them costs. Its whole job is the two things a derive is uniquely able to do: register simple as an inert helper attribute, so writing one is legal Rust, and read what was written, so a mistake in one is a compile error at the span that holds it.

§The constraints

writtenapplies tobecomes
range(min = …, max = …)numbersminimum / maximum
length(min = …, max = …)strings and collectionsminLength / maxLength on a string, minItems / maxItems on a collection
pattern = "…"stringspattern
format = "…"stringsformat
default = …any memberdefault
example = …any memberexample
deprecatedany memberdeprecated

length is type-directed: the same two bounds mean characters on a String and elements on a Vec<T>, so there is one length to remember rather than two.

Several constraints go in one attribute, separated by commas, or in attributes of their own — #[simple(pattern = "^KNOW", length(max = 64))] and #[simple(pattern = "^KNOW")] #[simple(length(max = 64))] are the same thing. Either way each constraint is written once per member.

§What is not written here

  • The description is the doc comment. /// Collection identifiers. above the member is the description, and there is one place to write it.
  • Requiredness is the type. A member is optional when it is Option<T> or carries #[serde(default)], and required otherwise, so the signature and the schema cannot disagree.
  • The property name is what serde says it is. #[serde(rename = "…")] and #[serde(rename_all = "…")] name the property, so the name on the wire and the name serde reads are the same name.