The Null input type

In JSON Schema, the null type is used to represent a single acceptable value of null. It is particularly useful when you want to explicitly state that a property may have no value, or to control the editing interface of Component Service without exposing an additional input field.

For more information about the Null type in JSON schema, read JSON Schema - Null.

Schema definition

To define a property as a null in JSON Schema, you use the "type" keyword with the value "null".

"input": {
    "type": "object",
    "properties": {
        "nullFieldName": {
            "title": "example null input",
            "type": "null",
            "description": "an explanation of what this field is."
        }
    },
    "required": []
},

This example also demonstrates how to provide a description and title to the null field for use within the editing interface.

Null field as the 'none' option

The Null type can be useful in cases where its expected an input is either a specific type or nothing. For example, you can configure a required field that must either be a string, or is null. This can be achieved using the JSON Schema Composition keyword and a null type option.

"input": {
    "type": "object",
    "properties": {
        {
            "type": "object",
            "properties": {
                "stringOrNullField": {
                "oneOf": [
                    { "type": "string" },
                    { "type": "null" }
                ]
                },
            },
            "required": ["stringOrNullField"]
        }
    }
},

Editing interface

This image shows an example of the Null type input field in the editing interface.
Figure 1. The Null input types editing interface field.

Input object structure

The Null input type is available to consume in the main function through the input object, although it is of limited use outside of checking for the existence of a real value.

const input = {
  nullField: null
};

module.exports = async function (input) {
  const isNullReallyNull = input.nullField === null ? "It is null" : "It is not null";

  return `
      <div>
        <h1>Is it null?</h1>
        <p>${isNullReallyNull}</p>
      </div>`;
};

Full manifest definition

Expand to see the manifest.json file with a null input field
{
  "$schema": "http://localhost:3000/schemas/v1.json",
  "name": "mynull",
  "version": "1.0.0",
  "mainFunction": "main",
  "displayName": "Null example",
  "namespace": "null-component",
  "icon": {
  "id": "list_alt",
  "color": {
    "type": "hex",
    "value": "#2D2D2D"
    }
  },
  "description": "This component is set up as a demonstration component for documentation purposes.",
  "functions": [
    {
      "name": "main",
      "entry": "main.js",
      "input": {
        "type": "object",
        "properties": {
          "boolField": {
            "type": "null",
          }
        },
        "required": []
      },
      "output": { "responseType": "html" }
    }
  ],
  "previews":
    {
      "firstpreview": {
        "functionData": {
          "main": {
            "inputData": {
              "type": "inline",
              "value": {
                "nullField": null
              }
            },
            "wrapper": {
              "path": "preview-wrapper.html"
            }
          }
        }
      }
    }
   }