Validating Settings Using Schema

This post is intended for extension developers who already have at least a basic understanding of what an Adobe Experience Platform Launch extension can do and how it is composed. If you’re unfamiliar with extension development, I recommend starting out by reading our extension development documentation or watching this video on extension development.

The case for settings schema

To allow users to adjust how an extension behaves, an extension will most likely provide views that have input fields for tweaking settings. These views are shown within the Launch user interface. Such a view can be shown for event types, condition types, action types, data element types, or extension configuration (“extension configuration” refers to high-level or “global” settings). When the user saves settings, the settings are then stored to Launch’s database. These settings are later emitted in build output and shipped to the customer website (in the case of a web property) or mobile app (in the case of a mobile property). At runtime, the extension’s library modules then receive the settings and act on them as necessary. Our extension flow documentation describes this process in more depth.

Because an extension has full control over what happens in its views, it also controls how user input is validated. Let’s assume we’re building a Send Beacon action type that requires a campaign ID and, in the case of our particular technology, campaign IDs must always be 16 characters long. We can set up validation within our extension view that prevents the settings from being saved unless the user has provided a campaign name that is 16 characters long. See our view documentation for more information on performing validation.

But what happens if the user is creating a rule using Launch APIs instead of the Launch user interface? In case you weren’t already aware, anything users can accomplish through the user interface can also be done using APIs by sending HTTP requests directly to our servers. If a user creates a rule using APIs, then the user will not be using our extension view and the logic we’ve written that validates user input will never be run. This means a user could save an action using our extension’s action type with a campaign ID that is not 16 characters long. In fact, the user could save the action without any campaign ID at all!

If our extension’s library module were to receive settings with no campaign ID defined or with a value that wasn’t exactly 16 characters long, what would happen? Would the extension not send a beacon? Would it send a beacon with an invalid value? Would it break entirely? While we could find the answers to these questions and while the result may not be catastrophic, it would be best if we never reached this situation in the first place. Instead, let’s tell users they’ve provided invalid data right when they attempt to save the action. For this purpose, we define schema.

Defining schema

To ensure that settings are always valid when they are saved, regardless of whether they’re saved using the user interface or APIs, we can define schema in our extension manifest (extension.json). Schema describes how a piece of data should be structured. Just like there are various ways to describe music or photography, there are also various ways to describe data. In our case, we specifically use JSON Schema to describe data. JSON Schema is a popular vocabulary used by many projects to validate that a JSON object has a particular structure. As it turns out, JSON schema is written in JSON as well.

As an extension developer, you get to choose what goes into a settings object and how it’s structured. Launch doesn’t care; it really depends on how you’ve built your extension’s library module (the part that will run on the user’s website) and how it consumes the settings object. For our example extension, let’s say that whenever a settings object is saved for our Send Beacon action type, we need it to look like this.

{
"campaignId": "A4YQE3XR974312DV"
}

The campaign ID value will vary, but the rest should always be the same. We’ve also stated previously that a campaign ID must always be provided and must be 16 characters long.

JSON Schema that would describe this structure would look like this:

{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"campaignId": {
"type": "string",
"minLength": 16,
"maxLength": 16
}
},
"required": [
"campaignId"
],
"additionalProperties": false
}

Let’s break it down:

"$schema": "http://json-schema.org/draft-04/schema#",

This states which version of JSON Schema we’re using.

"type": "object",

The settings must be an object (rather than merely a string, number or boolean). This is currently a requirement of Launch and will be the case with all settings saved by extensions.

"properties": {
"campaignId": {
"type": "string",
"minLength": 16,
"maxLength": 16
}
},

If the object has a campaignId property, it must be a string that is 16 characters long.

"required": [
"campaignId"
]

The object must have a campaignId property.

"additionalProperties": false

The object must not have any property other than than those defined in the properties block. In our case, this means the only property a settings object can have is campaignId.

Adding schema to the extension manifest

Now let’s take our resulting schema and put it into our extension manifest. The result of our extension.json file would look something like this:

{
...
"viewBasePath": "src/view/",
"actions": [
{
"name": "send-beacon",
"displayName": "Send Beacon",
"schema": {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"campaignId": {
"type": "string",
"minLength": 16,
"maxLength": 16
}
},
"required": [
"campaignId"
],
"additionalProperties": false
},
"libPath": "src/lib/actions/sendBeacon.js",
"viewPath": "actions/sendBeacon.html"
}
]
}

Testing schema

While we could certainly tweak our schema and then test our extension out using the Sandbox development tool or upload our extension to Launch’s integration environment and try it out there, that can be tedious and time-consuming if we have to repeat the cycle several times. Instead, we recommend trying out online tools like jsonschemavalidator.net. You provide the JSON schema and the JSON that should comply with that schema and it will report the results. Once you’ve fine-tuned your schema, you can copy it to your extension manifest and be on your way.

Learning JSON schema

If you’d like to learn more about JSON Schema, we recommend starting with Understanding JSON Schema.

Have questions? Let us know in the comments below.