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.
| Type | Description |
|---|---|
| Array | An 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 |
| Boolean | A boolean type |
| Integer | An integer type |
| Number | A number type |
| Object | An object containing the specified items. Drag additional items into the object box |
| String | A string type with a range of predefined formatting options |
| All of | A container that indicates all of the items within it must be present |
| Any of | A container that indicates one or more of the items within it must be present |
| Not | A container that indicates none of the items within it are permitted |
| One of | A 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.
| Property | Description |
|---|---|
| Key | The 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 |
| Description | A description of the function of this parameter within the schema |
| Required | Indicates 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.
| Property | Description |
|---|---|
| Additional items | Indicates that additional items to those specified are permitted within the array |
| Minimum items | The minimum number of items that must be present |
| Maximum items | The maximum number of items that may be present |
| Unique items | Indicates 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.
| Property | Description |
|---|---|
| Minimum | The minimum permitted value |
| Exclusive minimum | Indicates that the minimum permitted value has to be greater than the Minimum |
| Maximum | The maximum permitted value |
| Exclusive maximum | Indicates that the maximum permitted value has to be less than the Maximum |
| Multiple of | Indicates that the value must divide by this value exactly |
Objects
The following settings apply to the Object type.
| Property | Description |
|---|---|
| Minimum properties | The minimum number of properties that must be present |
| Maximum properties | The maximum number of properties that are permitted |
| Additional properties | Indicates 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.
| Property | Description |
|---|---|
| Acceptable list | A 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 length | The minimum number of characters that must be present |
| Max length | The maximum number of characters that may be present |
| Pattern | A 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 |
| Format | The name of a permitted format. These built in formats are:
|
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
}
}
Share this page
