StediDOCS
GuidesAPI Reference
This product is in Developer Preview

Parameter Forms

This document describes how Parameters can leverage Schemas in order to automatically generate intuitive Parameter Forms in Stedi UI.

Constraints

JSON Schema allows for creation of a potentially infinitely nested object, as such Parameters impose constraints on a JSON Schema that can be used to generate a form. If those constraints are not met, the UI will default to rendering a JSON-based editor instead.

Constraint #1: No deeply nested objects. Only two levels of nesting are allowed

Allowed: JSON Schema describes only one level of nesting within the object property type.

{
  "type": "object",
  "properties": {
    "firstName": { "type": "string" }
  }
}

Allowed: JSON Schema describes two levels of nesting within the object property type.

{
  "type": "object",
  "properties": {
    "person": {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" },
        "lastName": { "type": "string" }
      }
    }
  }
}

Invalid: JSON Schema describes three levels of nesting within the object property type.

{
  "type": "object",
  "properties": {
    "person": {
      "type": "object",
      "properties": {
        "firstName": { "type": "string" },
        "lastName": { "type": "string" },
        "address": {
          // This part of the definition makes the schema invalid.
          "type": "object",
          "properties": {
            "streetName": { "type": "string" }
          }
        }
      }
    }
  }
}

Constraint #2: Either properties or patternProperties are supported. Specifying both is not allowed

Allowed: only properties are specified.

{
  "type": "object",
  "properties": {
    "firstName": { "type": "string" }
  }
}

Allowed: only patternProperties are specified.

{
  "type": "object",
  "patternProperties": {
    "^.*$": {
      "type": "string"
    }
  }
}

Invalid: both patternProperties and properties are specified.

{
  "type": "object",
  "properties": {
    "firstName": { "type": "string" }
  },
  "patternProperties": {
    "^.*$": {
      "type": "string"
    }
  }
}

For more information on patternProperties and properties, please consult the patternProperties vs. properties section of this document.

Constraint #3: The array of boolean type is not supported

Invalid: the items of array type are of type boolean

"netsuite_ids_to_ignore": {
  "type": "array",
  "items": {
    "type": "boolean" // type "boolean" is not supported
  }
}

Available input types

  • Text field:
"name": {
    "type": "string"
}

  • Secret text field
"password": {
    "type": "string",
    "modifier": "secret" // mark the field as a secret (e.g. password/key)
}

  • Trading Partner field
"partner": {
    "type": "string",
    "modifier": "tradingPartner" // Present a 'Trading Partner picker' in the UI
}

  • Number field
"age": {
    "type": "number"
}

  • Boolean field
"isAdmin": {
    "type": "boolean"
}

  • Dropdown field
"city": {
    "type": "string",
    "enum": [
        "Poznan",
        "San Francisco",
        "New York"
    ]
}

  • MultiSelect field
"service_levels": {
  "type": "array",
  "items": {
    "type": "string",
    "enum": [
      "priority",
      "overnight",
      "saturday"
    ]
  }
}

  • Multitext field
"netsuite_ids_to_ignore": {
  "type": "array",
  "items": {
    "type": "string"
  }
}

properties vs. patternProperties

Use properties in order to create a parameter with explicitly defined key-value properties:

{
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "surname": {
        "type": "string"
      },
      "city": {
        "type": "string"
      }
    }
  }
}

Use patternProperties in order to create a parameter with an opaque key property, resulting in a a list of potential parameter values (note the remove/add row buttons):

Schema:

{
  "schema": {
    "type": "object",
    "patternProperties": {
      "^.*$": {
        "additionalProperties": false,
        "type": "object",
        "properties": {
          "type": {
            "type": "string",
            "enum": ["scac", "duns_plus_four", "assigned_by_buyer", "assigned_by_originator", "mutually_defined"]
          },
          "service_levels": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["priority", "overnight", "saturday"]
            }
          },
          "carrier": {
            "type": "string"
          }
        }
      }
    },
    "additionalProperties": false
  }
}

Controlling the field labels

By default, the label for a given field is derived from the key's name that corresponds to that field.

If you wish to control the text displayed as a label for a given field, specify the title attribute on that field.

Please refer to the fields with custom labels example.

Controlling the Parameter Set menu title

By default, the text under which a given schema is displayed within the Parameter menu, is derived from the name property of a Schema.

If you wish to control the text under which a given schema is displayed within the Parameters menu, specify the title attribute for the whole schema object.

Please refer to the schema with a custom menu title example.

Examples

Single string property

Schema:

{
  "name": "single_string_property",
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      }
    }
  }
}

UI:

Multiple string properties

Schema:

{
  "name": "multiple_string_properties",
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "type": "string"
      },
      "surname": {
        "type": "string"
      },
      "city": {
        "type": "string"
      }
    }
  }
}

UI:

Fields with custom field labels

Schema:

{
  "name": "overriding_labels",
  "schema": {
    "type": "object",
    "properties": {
      "name": {
        "title": "MyCustomLabelForName",
        "type": "string"
      },
      "surname": {
        "title": "MyCustomLabelForSurname",
        "type": "string"
      },
      "city": {
        "type": "string"
      }
    }
  }
}

UI:

Schema with custom menu title

Schema:

{
  "name": "custom_menu_title",
  "schema": {
    "title": "MY_CUSTOM_MENU_TITLE",
    "type": "object",
    "properties": {
      "city": {
        "type": "string"
      }
    }
  }
}

UI:

Dropdowns and number properties

Schema:

{
  "name": "dropdowns_and_numbers",
  "schema": {
    "type": "object",
    "properties": {
      "age": {
        "type": "number"
      },
      "name": {
        "type": "string"
      },
      "city": {
        "type": "string",
        "enum": ["Poznan", "San Francisco", "New York"]
      }
    }
  }
}

UI:

Multiselect & multitext fields

Schema:

{
  "name": "multiselect_fields",
  "schema": {
    "type": "object",
    "properties": {
      "netsuite_ids_to_ignore": {
        "type": "array",
        "items": {
          "type": "string"
        }
      },
      "service_levels": {
        "type": "array",
        "items": {
          "type": "string",
          "enum": ["priority", "overnight", "saturday"]
        }
      }
    }
  }
}

UI:

Object property

Schema:

{
  "name": "object_field",
  "schema": {
    "type": "object",
    "properties": {
      "person": {
        "type": "object",
        "properties": {
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "isPremiumUser": {
            "type": "boolean"
          }
        }
      }
    },
    "additionalProperties": false
  }
}

UI:

Using patternProperties #01

Schema:

{
  "name": "pattern_properties_01",
  "schema": {
    "type": "object",
    "patternProperties": {
      "^.*$": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string"
          },
          "premium_user": {
            "type": "boolean"
          }
        }
      }
    }
  }
}

UI:

Using patternProperties #02

Schema:

{
  "name": "pattern_properties_02",
  "schema": {
    "type": "object",
    "patternProperties": {
      "^.*": {
        "type": "object",
        "properties": {
          "people": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "firstName": {
                  "type": "string"
                },
                "lastName": {
                  "type": "string"
                },
                "favoritePet": {
                  "type": "string",
                  "enum": ["cat", "dog"]
                },
                "sports": {
                  "type": "array",
                  "items": {
                    "type": "string",
                    "enum": ["football", "skateboarding", "basketball"]
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}

UI:

JSON Schema validation

Schema is validated using Ajv with allErrors , strict and strictTypes flags turned on. Please consult the official Ajv documentation for more information.

References

API Reference

ConstraintsConstraint #1: No deeply nested objects. Only two levels of nesting are allowedConstraint #2: Either properties or patternProperties are supported. Specifying both is not allowedConstraint #3: The array of boolean type is not supportedAvailable input typesproperties vs. patternPropertiesControlling the field labelsControlling the Parameter Set menu titleExamplesSingle string propertyMultiple string propertiesFields with custom field labelsSchema with custom menu titleDropdowns and number propertiesMultiselect & multitext fieldsObject propertyUsing patternProperties #01Using patternProperties #02JSON Schema validationReferences