Toggle menu

End Point Parameter and Return Schema

You'll need to check the "validate parameters" and "validate return" checkboxes on the Target tab for the schema you design here to be used. The Schema knowledge base article includes examples of the different schema types.

What is a Schema?

End points, like many of the services provided by the API Server, receive requests and return results as as JSON objects.

At its simplest, the request to your end point, the parameters passed to it, could be a JSON object with a single key-value pair:

{
    "articleID": 1
}

The response, the return, is also a JSON object:

{
    "jsonrpc": "2.0",
    "id": 66,
    "result": {
        "result": {
            "data": {
                "itemData": {
                    "_ItemClass": "CSArticle",
                    "ArticleHeading": "Home Page"
                }
            },
            "success": true
        },
        "id": "_44",
        "jsonrpc": "2.0"
    }
}

The parameters and return will always be JSON objects, but the data structure within them can be in any valid JSON format. For example, your parameter object could include an array, boolean, string, number or other nested objects.

A schema allows you to check that the data passed to and returned from your end point are in the structure you expect.

Designing a Schema

iCM end points use JSON Schema (opens new window) to validate their parameters and return.

JSON Schema is itself written in JSON. It is an object that describes the structure of data in another JSON object.

To make designing a schema easier, the end point editor uses a drag and drop designer, similar to the forms designer. "Types" are dragged onto the design area, and can only be placed in valid positions. Each type has a range of settings that let you set minimum and maximum values, whether it is required or not, and the key the type applies to.

The designer will only let you write valid schema. Types in invalid positions will be highlighted in red and you will not be able to publish your end point.

Understanding JSON Schema (opens new window) is a really good, easy to understand guide. It provides an excellent introduction and describes all of the key concepts.

Be aware that JSON Schema allows you to express schema that, although valid, may not make any sense in the real world. For example, you can create a schema that will actually reject all input due to conflicting, mutually exclusive, requirements.

Schema Settings

The Schema Settings section of the design toolbox only has a single property.

"Additional properties" can be either true or false. This lets you control whether additional properties to those defined in your schema are permitted within the parameter or return object. The default is false, which prevents additional properties. This is normally what you would want, so that any unexpected input/output is rejected.

Types

Types are the items and logical groups that form the building blocks of your schema. Items represent the possible basic types. Logical Groups can be dragged into any of the types to create a specification for the permitted values.

TypeDescription
ArrayAn array of items defined by the single specified type, or, an array of multiple item types in the order in which they should appear. Drag additional items into the array box
BooleanA boolean type
IntegerAn integer type
NumberA number type
ObjectAn object containing the specified items. Drag additional items into the object box
StringA string type with a range of predefined formatting options
All ofA container that indicates all of the items within it must be present
Any ofA container that indicates one or more of the items within it must be present
NotA container that indicates none of the items within it are permitted
One ofA container that indicates one of the items within it must be present

Type Settings

To configure the behaviour of an item type, click to highlight it in the schema designer and change the values of the properties in the right hand "Type settings" panel.

Common Properties

The following properties apply to the Array, Boolean, Integer, Number and Object types.

PropertyDescription
KeyThe JSON key for this item within its containing object (including the top-level of the schema, which equates to the request Params or Return object). This must be unique. For non-Objects, this setting is not present
DescriptionA description of the function of this parameter within the schema
RequiredIndicates that this item must be present. This is only applicable to items contained within an Object, since it relies on identifying the required items by their Key

Arrays

The following settings apply to the Array type.

PropertyDescription
Additional itemsIndicates that additional items to those specified are permitted within the array
Minimum itemsThe minimum number of items that must be present
Maximum itemsThe maximum number of items that may be present
Unique itemsIndicates that the items in the array must be unique within the array

Integers and Numbers

The following settings apply to the Integer and Number types.

PropertyDescription
MinimumThe minimum permitted value
Exclusive minimumIndicates that the minimum permitted value has to be greater than the Minimum
MaximumThe maximum permitted value
Exclusive maximumIndicates that the maximum permitted value has to be less than the Maximum
Multiple ofIndicates that the value must divide by this value exactly

Objects

The following settings apply to the Object type.

PropertyDescription
Minimum propertiesThe minimum number of properties that must be present
Maximum propertiesThe maximum number of properties that are permitted
Additional propertiesIndicates that additional properties to those specified are permitted within the object. The default of this setting is true, ie, change this to false if you want to prevent additional properties

Strings

The following settings apply to the String type.

PropertyDescription
Acceptable listA list of permitted values. This is an Enumeration (ENUM) of permitted values. A list box opens to let you type the list of values, one item per line
Min lengthThe minimum number of characters that must be present
Max lengthThe maximum number of characters that may be present
PatternA regular expression that the string must match to be permitted. A regular expression editor and tester opens to help you enter a working regular expression
FormatThe name of a permitted format. These built in formats are:
  • credit-card-number - A string instance is valid against this attribute if it is in the format of a credit card number including a final single check digit calculated using the Luhn algorithm . Card numbers can be up to 19 digits including the check digit.  For example, a valid number for testing is 4958453282727705.
  • date - A string instance is valid against this attribute if it is a valid date representation of the form Year, Month, Day, like so: YYYY-MM-DD. For example 2016-01-23.
  • date-time - A string instance is valid against this attribute if it is a valid date representation as defined by RFC 3339, section 5.6. For example 2014-05-02T12:59:29+00:00
  • duration - A string instance is valid against this attribute if it is a valid duration representation as defined by  ISO 8601 . For example, P1DT12H for 1.5 days.
  • email - A string instance is valid against this attribute if it is a valid Internet email address as defined by RFC 5322, section 3.4.1. For example name@example.com
  • hostname - A string instance is valid against this attribute if it is a valid representation for an Internet host name, as defined by RFC 1034, section 3.1. For example www.example.com
  • uri - A string instance is valid against this attribute if it is a valid URI, according to RFC3986. For example ftp://ftp.is.co.za/rfc/rfc1808.txt or ./export.xml
  • url - A string instance is valid against this attribute if it is a valid URI, according to RFC3986. For example http://www.ietf.org/rfc/rfc2396.txt

Viewing the JSON

You can view the raw JSON schema generated by your design at any time by clicking "Preview this schema" in the action panel.

Invalid Parameters

Once a schema has been set up, and your end point has been told to validate against it, what happens if parameters are passed to it that are invalid?

Parameters are checked against your schema before they reach the end point's JavaScript function. If the parameters are valid, the end point will do whatever you have designed it to do.

If the parameters don't meet the schema, you'll receive an error response. This error will include information about the invalid parameters, for example:

{
    "jsonrpc": "2.0",
    "id": 69,
    "error": {
        "message": "Server error: Parameters: Multiple errors. (1) Missing required property: article; (2) Additional properties not allowed at /searchTerm",
        "code": -32099
    }
}

Last modified on January 23, 2024

Share this page

Facebook icon Twitter icon email icon

Print

print icon