Help Center

Menu

manifest.json reference

The manifest.json file defines metadata that tells the Component Service how to execute the component. It follows the JSON Schema specification.

The following example shows the structure of a basic manifest.json file.

{
  "$schema": "http://localhost:3000/schemas/v1.json#", (1)
  "version": "1.0.0", (2)
  "name": "helloworld1", (3)
  "displayName": "Hello World test component",  (4)
  "namespace": "test-components",  (5)
  "icon": {  (6)
    "id": "list_alt", (7)
    "color": { (8)
      "type": "hex", (9)
      "value": "#2D2D2D" (10)
      }
  },
  "description": "A demonstration component for Hello World tutorial.", (11)
  "mainFunction": "main", (12)
  "type": "edge", (13)
  "functions": [ (14)
    {
      "name": "main", (15)
      "entry": "main.cjs", (16)
      "input": { (17)
        "type": "object",
        "properties": { (18)
          "entryfield": {
            "type": "string"
          }
        },
        "required": ["entryfield"] (19)
      },
      "output": { "responseType": "html" } (20)
    }
  ]
}
1 The JSON schema location. This schema defines the allowed and required fields for the manifest.json file. See Schema Location for details.
2 Component version number. See Versioning for versioning guidelines.
3 Component name. See Naming for naming conventions.
4 Display name for the component. This is the friendly name that will be shown in the Squiz Content Management Service interface.
5 Component namespace. See Namespaces for namespace usage guidelines.
6 Icon configuration. See Icon Configuration for icon options.
7 Material UI icon ID.
8 Icon color configuration. See Icon Configuration for available color options and formats.
9 Color type (hex or enum).
10 Color value (hex code or preset color).
11 Component description. This should be one to two sentences that explain the component’s purpose and functionality.
12 Main function name. See Main Function for details.
13 Runtime type. See Runtime Types for available options.
14 Function definitions. See Function Definitions for details.
15 Function name. This should always be in lowercase, without spaces. The default function should be called main.
16 Entry file name. See Entry Files for file conventions.
17 Input schema. See Input Schema for schema configuration.
18 The Component Service supports all standard JSON Schema features in the input field, including $ref for schema references. See Schema References for detailed information.
19 Required fields. See Required Fields for field requirements.
20 Output configuration. See Output Configuration for response types.

Detailed Configuration

Schema Location

The JSON schema location defines the allowed and required fields for the manifest.json file. Depending on your development tool, you may get auto-complete and intellisense after you have added the schema location.

Versioning

Follow Semantic Versioning (MAJOR.MINOR.PATCH) for your component version numbers. Change this value each time you deploy the component.

Naming

Component names must use only lowercase letters and no spaces.

Namespaces

Use namespaces to prevent conflicts between components with the same name across different systems. For example, a Squiz-produced 'accordion' component that might conflict with a customer-built 'accordion' component.

Icon Configuration

The icon configuration uses the Material UI Two Tone icon set. Colors can be specified using either:

  • Hexadecimal color codes (type: "hex")

  • Preset colors (type: "enum"):

    • "gray"

    • "blue"

    • "green"

    • "orange"

    • "red"

    • "purple"

    • "teal"

    • "yellow"

    • "pink"

Main Function

The Component Service executes the mainFunction at the base URL of the component and additional functions at sub-paths of the URL.

There MUST be a function specified in mainFunction, and it must refer to a function in manifest file functions array.

Runtime Types

To use Squiz’s Components at Edge runtime implementation, see the Make changes to manifest.json documentation for information on this property.

Function Definitions

A set of named functions that can be used to render the component or API endpoints of the component. Name your default function 'main' to render your component and its editing interface in Squiz Content Management Service.

Entry Files

The entry file should be a CommonJS (CJS) JavaScript file. Read common.js for more information about expected module conventions.

Input Schema

Define your component’s data model in the input field. You can use most JSON schema configurations to generate data structures that will be used to create the editing experience for editors automatically.

The Component Service supports all standard JSON Schema features in the input field, including $ref for schema references. When using $ref, references are resolved relative to the input object, not the root of the manifest.

See the Schema References section for detailed information and examples.

Required Fields

The required field is mandatory on all objects: if you create objects inside an array, you must provide a required field for them. It is important to consider which fields should be required and which are optional, as you may get unintended consequences if you do not have required fields set.

Output Configuration

Response types: * "html" - Returns HTML content * "json" - Returns a JSON endpoint (requires a "definition" field)

Example JSON output configuration:

"output": {
    "responseType": "json",
    "definition": {
      "properties": {
        "my-prop": {
          "type": "string"
        }
      },
      "required": ["my-prop"]
    }
}

Schema References

The Component Service supports JSON Schema references using the $ref keyword. References are resolved relative to the input object, not the root of the manifest.

Reference Types

In addition to basic JSON Schema references, the Component Service supports:

  • Remote schema references for custom types (for example, FormattedText, SquizImage, SquizLink)

  • References to primitive types and their resolvable variants

{
  "input": {
    "type": "object",
    "properties": {
      "formattedContent": {
        "$ref": "#/definitions/FormattedText"  // Internal reference
      },
      "image": {
        "type": "SquizImage"  // Remote schema reference
      }
    }
  }
}

Reference Resolution Rules

When using references, keep in mind:

  • References must be valid JSON Schema URI references

  • Circular references are not supported

  • References to undefined schemas will cause validation errors

  • References can be used in combination with other JSON Schema keywords (allOf, anyOf, oneOf)

  • References to custom types (FormattedText, SquizImage, SquizLink) are automatically resolved to their full schemas

{
  "input": {
    "type": "object",
    "properties": {
      "complexField": {
        "allOf": [
          { "$ref": "#/definitions/BaseType" },
          { "type": "object", "required": ["additionalField"] }
        ]
      }
    }
  }
}

Reference Error Handling

The Component Service will throw validation errors in the following cases:

  • Invalid reference paths

  • Missing referenced schemas

  • Circular references

  • Invalid schema combinations

Example error message:

Error resolving JSON at #/properties/myField: Reference #/definitions/MissingType not found

Best Practices for Schema References

  • Use references to avoid schema duplication

  • Keep reference paths as short as possible

  • Use meaningful names for referenced schemas

  • Document complex reference structures

  • Test reference resolution with validation tools

  • Use references for common patterns across multiple components