StediDOCS
GuidesAPI Reference
This product is in Developer Preview

Schemas

Getting Started

Schemas provides an interface for developers to define and store data schemas that can be programmatically accessed, enabling customers to validate any JSON data shape.

With Schemas, Stedi provides customers with a tool to define and store data schemas which can be seamlessly integrated with other Stedi services or 3rd party systems. Using Schema Service, developers can use JSONSchema - a human-readable vocabulary that allows customers to validate JSON documents - in order to verify their shape and assert consistency.

Authoring a Schema

Right now, Schemas support only JSONSchema using version 2020-12. Schemas can be created using Terminal, API or Formation.

Example Schema can look like this:

{
  "title": "Person",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The person's first name.",
    },
    "lastName": {
      "type": "string",
      "description": "The person's last name.",
    },
    "age": {
      "description": "Age in years which must be equal to or greater than zero.",
      "type": "integer",
      "minimum": 0,
    },
  },
};

A JSON object that would be correctly validated by this schema can look like this:

{
  "firstName": "John",
  "lastName": "Doe",
  "age": 99
}

Using Formation

Formation is Stedi's infrastructure as code product for automated provisioning and management of platform configuration. With Formation you can automate the provisioning of Schemas.

Minimal example of a Formation file setting up a single Schema:

MyCredentialsSchema:
  Type: "Stedi::Schema"
  Properties:
    Name: MyCredentialsSchema
    Schema:
      {
        "type": "object",
        "properties": { "integrationId": { "type": "string" }, "apiKey": { "type": "string", "modifier": "secret" } },
      }

Using the API

The Schemas API is a JSON REST API. Please consult Schemas HTTP Reference for the endpoints that are available.

Modifiers

Modifiers are special values that allow you to enrich a single schema field. To annotate a given field with a modifier, use modifier keyword:

{
  "properties": {
    "firstName": { "type": "string", "modifier": "MODIFIER_VALUE" }
  }
}

Currently, there are 2 modifier values available:

  • secret
  • tradingPartner

secret modifier

Parameters marked with a secret modifier will be stored in an encrypted representation in a database. When fetching a parameter, decryption will happen ad-hoc and automatically without an explicit need from an end-user to decrypt the value, same with encrypting when new value is being entered.

Moreover, in the Terminal, that parameter value will be rendered using password input field (value will be redacted) instead of a regular input field.

tradingPartner modifier

Parameters marked with a tradingPartner modifier will be presented with a 'Trading Partner picker' in the Terminal.

Limits

Schemas do not have a limitation on complexity. However, every Schema must:

  • be smaller than 400 Kb
  • contain at least one property
  • adhere to the version 2020-12 of JSONSchema
  • Terminal can only render schemas with a limited complexity (i.e. no nested arrays, no nesting above 3rd level, read more)

API Reference

Getting StartedAuthoring a SchemaUsing FormationUsing the APIModifierssecret modifiertradingPartner modifierLimits