JSON Schemas for Dynamic Web Forms

Overview

The NGINX Instance Manager’s web form builder uses JSON schemas to guide and validate user inputs when creating NGINX configurations from templates. This structured input method simplifies the configuration process and ensures adherence to NGINX configuration requirements.

JSON Schema

JSON Schema is a standard explained in detail at json-schema.org.

In NGINX Instance Manager, we support a specific set of common features from the JSON Schema:

  • Type: This defines the kind of data a field can hold. More information is available at Type Definitions.

    Supported types include:

  • Title: A descriptive, user-friendly name for each form field that lets users know what’s required. For further details, refer to Generic Keywords.

  • Description: Text to help guide users on what to enter in the form fields. For details, see Generic Keywords.

  • Examples: Examples show what valid data looks like so anyone filling out the form knows what to enter. You should give at least one example so users understand the schema’s purpose and requirements. More information can be found at Generic Keywords.

Writing effective JSON schema titles and descriptions
The title and description fields are a key part of the user experience for templates. We recommend making sure that your title and description fields are predictably formatted and provide clear, concise guidance to the user.

Example http-server.json

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "HTTP Server Inputs",
  "type": "object",
  "properties": {
    "templateInput": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "serverName": {
          "title": "Server name",
          "type": "string",
          "description": "Specifies the HTTP server name.",
          "examples": [
            "foo.com"
          ]
        },
        "id": {
			  "title": "Server ID",
			  "type": "string",
			  "description": "Case-sensitive, alphanumeric ID used for specifying augment placement.",
			  "examples": [
				"main_server"
			  ]
			}
      },
      "required": ["serverName", "id"]
    }
  },
  "required": []
}

Type-Specific Features

Each data type in a JSON schema comes with its own set of features that define how the data can be structured and validated. Understanding these features is important for building robust and user-friendly web forms in NGINX Instance Manager. This section explains the characteristics and functionality of each data type so you can use the schema’s capabilities for accurate data representation and validation.

Boolean field

String field

Examples

  • Regular string field with pattern and length constraints:

    {
  "test": {
    "type": "string",
    "pattern": "^[A-Za-z0-9\\s]*$",
    "minLength": 1,
    "maxLength": 140,
    "examples": ["value 1", "value 2"]
  }
}

  • String Select field with enumerated values:

    {
  "method": {
    "type": "string",
    "enum": ["GET", "POST", "PUT", "DELETE"]
  }
}

  • String MultiSelect field within an array:

    {
  "method": {
    "type": "array",
    "items": {
      "type": "string",
      "enum": ["GET", "POST", "PUT", "DELETE"]
    }
  }
}

Numeric field

Examples

  • Regular numeric field with validation criteria:

    {
  "proxyTimeout": {
    "type": "number",
    "multipleOf": 10,
    "minimum": 10,
    "maximum": 1000,
    "examples": [50, 120, 870]
  }
}

  • Numeric Select field for predefined numerical values:

    {
  "proxyTimeout": {
    "type": "number",
    "enum": [10, 20, 30, 40, 50]
  }
}

  • Numeric MultiSelect field within an array:

    {
  "proxyTimeout": {
    "type": "array",
    "items": {
      "type": "number",
      "enum": [10, 20, 30, 40, 50]
    }
  }
}

Object field

  • Supported Features: Nested object structures with required fields.

  • Usage: Complex configurations involving nested parameters.

  • Full spec: https://json-schema.org/understanding-json-schema/reference/object.html

  • Example:

    {
  "server": {
    "type": "object",
    "properties": {
      "isBackup": { "type": "boolean" },
      "weight": { "type": "integer" },
      "service": { "type": "string" }
    },
    "required": ["service"]
  }
}

Array field

  • Supported Features: Minimum and maximum item counts, uniqueness constraints.

  • Usage: Lists or collections of configuration items.

  • Full spec: https://json-schema.org/understanding-json-schema/reference/array.html

  • Example:

    {
  "headers": {
    "type": "array",
    "items": {
      "type": "object",
      "properties": {
        "name": { "type": "string" },
        "value": { "type": "string" }
      },
      "required": []
    }
  }
}

Additional Templating Resources

Concepts

  • Understand Config Templates: Learn about config template types, publication targets, and the template submission process.

  • F5 Global Default Base Template: Learn about the F5 Global Default Base Template, including its key components and usage. Discover how augment templates can be used to segment portions of the base template.

  • Augment Templates: Learn how augment templates can be combined with base templates to add specific features like OIDC authentication, or segment (compartmentalize) configuration elements like location and server blocks.

  • Template Resource Files: Learn about template resource files, including config template files, JSON schemas, and auxiliary files.

  • JSON Schemas for Template Inputs: Learn how to use JSON schemas for template input and validation in the dynamic web form builder.

How-Tos