Schema Validator Tool

Introduction

This document aims to cover the schema standards that component authors should follow. Failing to follow these guidelines may result in odd behaviors when using the JSON Editor feature. Enforcing schema standards will lead to better property management, user experience, and open many opportunities to improve data management throughout the platform.

Following these guidelines, tools and protocol will ensure components can not only be JSON UI Editor compliant, but also give their consumers the best design time / property configuration experience.

Current issues

• Component schemas do not follow a specific standard which may cause inconsistent behavior in the new JSON UI editor feature.
• There is no JSON Schema validation in the tectonic validation scripts.
• There are keywords being used that are not supported in JSON Editor.
• Arbitrary usage of the ServiceNow specific property, nowUIType

Problem areas

• Events
• Event handlers
• Data resources (input and output values)
• Data resource intellisense usability is dependent on these being available and accurate
• Toolbox components
• App Shell Configuration

Lessons learned

• The development of JSON UI Editor wasn't as smooth as it could have been.
• Having a standard for the schemas can make future feature work more predictable & smoother.
• Hooking into component compilation process to validate schemas with a library like AJV will help drive the future of ServiceNow products because we rely so heavily on structured data.

Goals

• Have every component be compliant with the schema rules that will be listed in this document
• Partner with the tectonic team and create a plugin (embeddable) that will validate component schemas when compiled
• Have a streamlined way for authors to create standardized schemas (Potentially a Schema Builder)
• Potentially validate all of now-ui.json for component's opting in to UIB to comply with an evolving configurable ruleset defined by the DoD.
• Custom shared library of schemas so component authors can reuse commonly used schemas.

Proposal:

• use AJV for json schema validation.

• Hook into tectonic validation scripts to validate.

• JSON Editor will support JSON Schema drafts 04, 06, 07, with an exception of a few features. These are some keywords that component authors currently use that are not supported by JSON editor just yet:

  • Dependencies
  • $refs / $ids
  • patternProperties
  • additionalProperties

If 'type: 'object', then properties needs to be defined and non-empty.

• It's best to provide some properties to let users know what the object is expecting in order to work.

Good:

{
    "type": "object",
    "properties": {
        "label": {
            "type": "string",
            "translatable": true
        },
        "icon": {
            "type": "string"
        }
    }
}

Bad:

{
  "type": "object",
}

If 'type: 'array', then 'items' must be defined and non-empty.

• It's best to provide information to the users on the shape of items the array may contain.

Good:

{
    "type": "array",
    "items": {
        "type": "object",
        "properties": {
            "view": {
                "type": "string"
            },
            "viewProvider": {
                "type": "string"
            },
            "label": {
                "type": "string",
                "translatable": true
            }
        }
    }
}

Bad:

{
  "type": "array",
}

If translatable keyword is used in property, then type must be string.

• It doesn't make sense to translate the other types. This rule will help keep the schema clean.

Good:

{
    "type": "string",
    "translatable": true
}

Bad:

{
    "type": "number",
    "translatable": true
}

Disabled property should be a Boolean

• Design choice: "disabled" is always used as a boolean. Unless there is a specific case where we want a different type for this property, this rule will help keep the schema cleaner.

Good:

"disabled": {
    "type": "boolean"
}

Bad:

"disabled": {
    "type": "string"
}

If properties field is empty, additionalProperties must also be set to true.

• It's best to provide information that let users know that this object can take any property in.

Good:

{
    "type": "object",
    "properties": {},
    "additionalProperties": true
}

Bad:

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

If enum keyword is used, then length should be > 1 and be of types: [string, number]. Otherwise, use const.

• Currently, json editor will render a dropdown for enums. It doesn't make sense to have a dropdown with one item. We recommend using the "const" property if that is the case.

Good:

{
    "type": "string",
    "enum": [
        "placeholder1",
        "placeholder2",
    ]
}

Bad:

{
    "type": "string",
    "enum": [
        "placeholder"
    ]
}

All values in enum must match provided type.

• Failing to match provided type may result in unexpected error handling.

Good:

{
    "type": "string",
    "enum": [
        "available",
        "busy",
        "away",
    ]
}

Bad:

{
    "type": "string",
    "enum": [
        "available",
        "busy",
        "away",
        true
    ]
}

All required values must exist inside properties.

• Schemas should be fully fleshed out. It is not recommended to have required properties be free form.

Good:

{
    "type": "object",
    "properties": {
        "id": {
            "nowUIType": "string",
            "type": [
                "string",
                "number"
            ]
        },
        "label": {
            "type": "string",
            "translatable": true
        },
    },
    "required": [
        "id",
        "label"
    ]
}

Bad:

{
    "type": "object",
    "properties": {
        "id": {
            "nowUIType": "string",
            "type": [
                "string",
                "number"
            ]
        },
        "label": {
            "type": "string",
            "translatable": true
        },
    },
    "required": [
        "id",
        "label",
        "unknownProperty",
    ]
}

If oneOf or anyOf is used, the length should be > 1.

• Currently, json editor will render a dropdown for these properites. It doesn't make sense to have a dropdown with one item.

Good:

{
    "oneOf": [
        {
            "const": "target"
        },
        {
            "type": "number"
        }
    ]
}

Bad:

{
    "oneOf": [
        {
            "type": "number"
        }
    ]
}

If 'type' is an array, the length should be > 1.

• Schemas with multiple types will typically be rendered in a dropdown. It doesn't make sense to have a dropdown with one item.

Good:

{
    "type": [
        "string",
        "number"
    ]
}

Bad:

{
    "type": [
        "string"
    ]
}

If schema has a 'nowUIType' property, it cannot be a primitive type (string, number, boolean, etc)

• nowUIType is a custom property that should be reserved for special types.

Good:

{
    "nowUIType": "CustomType"
}

Bad:

{
    "nowUIType": "string"
}

How to add / modify custom rules for schema validation

In customRules.js, there is an array of objects that represent each custom rule. You can add or modify rules here.

| Key | Description | Type | | ----------- | ----------- | ----------- | | description | Description of rule | String | | validate | Function to be called on each schema / subschema. Return true if schema is valid. False if invalid. | function | | level | One of values: "off", "warn", "error". Off will not log if the rule is violated. Warn will log if rule is violated. Error will stop the packing process if violated | string |

Findings

• According to Ugur, there is no JSON Schema standard among component authors right now. But from looking at existing schemas, they are in line with JSON Schema drafts 06 and 07.

• Currently, there is no JSON Schema validation in the tectonic validation scripts. Tectonic uses Joi, a framework to create and validate object schemas, for its validation of now-ui.json, which doesn't serve our needs for JSON Schema validation.

Message Abe Hu, Avanish Pathak, Gerald Lou Berzuela