Bring Your Own (BYO): Understanding the manifest.json File

The Bring Your Own feature is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript.

Overview

The manifest.json file defines the metadata and structure of a BYO package. It acts as the primary contract between a package and the Unqork platform. The manifest file informs the system on how to register components, load assets, and expose functionality to the Designer and runtime engine.

Unqork does not enforce programmatic name spacing for custom asset types. All type values for components, operations, and events must be globally unique. If multiple custom assets share the same type, or if a custom asset uses a type that conflicts with a native Unqork type, the runtime will render or execute only the first matching definition. Doing so leads to unpredictable behavior, asset shadowing, or broken functionality—especially when bundling or importing multiple packages.
It is the responsibility of the developer to ensure type uniqueness to prevent collisions. Component, operation, and event types require a unique name to avoid collision issues.
To avoid namespace issues, prefix custom components with a name unique to your company or application. For example, if a company named ABC creates a Card Panel component. The component's name space could be abcCardPanel.

File Specification

The following fields are required at the root level of the manifest:

Field	Type	Required	Description
`name`	string		A unique identifier for the package. For example, `MyCompanyNameAssets`.
`version`	string		The semantic version number. For example, `1.0.0`.
`type`	enum		The package type. Currently, the only supported value is custom.
`productType`	enum		The target platform feature. Currently, the only supported value is BYO.
`description`	string		A description that displays in the Admin Panel after installation.
`main`	string		The relative path to the JavaScript entry file. For example, index.js.
`components`	array<component-description>	Optional	A list of component definitions included in the package.
`events`	array<event-description>	Optional	List of event definitions.
`operations`	array<operation-description>	Optional	List of operation definitions.

Iterate the version value every time an update is made to a package. While version number value is up to the developer, it's important to iterate the value and save a copy of the package version. Developers can use the copy if a version revert is necessary.

Component Definition

Each entry in the components array defines a single, custom component available in the Designer and runtime engine.

Field	Type	Required	Description
`name`	string		The human-readable name. For example, `My Custom Component`. This value displays in the Admin Panel.
`type`	string		A unique identifier. This value must match a named export in the main JavaScript file. To avoid potential namespace conflicts with existing or future components, Unqork recommends prefixing the component type with a value specific to your business. For example, companyName`ComponentName`, where companyName is the abbreviated value of your company's name.
`description`	string		The human-readable description that displays in the Admin Panel after installation.
`model`	object		Defines the configuration options available, and automatically generates a UI for configurators in the Unqork Designer Platform. Supported data types include string, number, Boolean, array, and object. Nested objects are not supported. Required fields must be explicitly listed in the schema, and are enforced by the Unqork Designer Platform. Below is an example model schema: `{"type": "object","properties": { "text": { "type": "string" }, "color": { "type": "string" }},"required": ["text", "color"]}` At this time, you can only define top-level properties. Nested objects are not supported. The supported properties types are string, number, and Boolean.
`events`	array<event-description>	Optional	List of event definitions.
`operations`	array<operation-description>	Optional	List of operation definitions.

Event Definition

Use the event definition to define custom events that a component can emit. These events can be configured in Designer View to trigger platform operations. For example, SET_PROPERTY.

Field	Type	Description
`name`	string	Displays a name for the event in Designer View.
`type`	string	A unique event identifier. For example, `myComponentClick`. Prefix the value to avoid collisions.
`description`	string	The description that displays in Designer View and the Admin Panel.
`stability`	string	Indicates the component's status. Unqork recommends the following value: `STABLE`: General Availability (GA); fully supported.
`model`	object	The event model must include a name property that defines the unique event type. It must also define a `payload` object and its properties, which provide the data structure for the event. For example: `{"type": "object","properties": { "name": { "const": "eventsOnly", "type": "string" }, "payload": { "type": "object", "properties": { "data": { "description": "Sample property", "type": "string" } } }}}`

Operation Definition

Use the operation definition to define custom operations that events can trigger.

Field	Type	Required	Description
`name`	string		Displays a name for the operation in Designer View.
`type`	string		A unique event identifier. For example, `myComponentOperation`. Prefix the value to avoid collisions.
`description`	string		The description that displays in Designer View and the Admin Panel.
`stability`	string		Indicates the operation's status. Possible values include: `ALPHA`: Use for internal testing phases that might be unstable and subject to breaking changes. `BETA`: Use for stable and internally validated; available for early access. `STABLE`: General Availability (GA); fully supported. `TO_DEPRECATE`: Currently supported, but planned for removal.
`model`	object		The model must include a type property that defines the unique operation type. It must also describe an `options` object and its properties.. For example: {"definitions": { "OperationOptions": { "type": "object", "properties": { "input": { "description": "Input component for the operation.", "type": "string" }, "output": { "description": "Output component for the operation.", "type": "string" } }, "required": ["input"] }},"properties": { "options": { "$ref": "#/definitions/OperationOptions" }, "type": { "const": "operationsOnly", "type": "string" }},"required": ["options"],"type": "object"}
`contextModel`	object	Optional	When included, the contextModel must describe a result property. The result property can be a primitive, object, or array . The JSON schema should then reflect the expected result structure. If the operation does not have a result, do not include a contextModel. `{"type": "object","properties": { "result": { "type": "object", "properties": { "transformed": { "type": "string", "description": "Transformation result" } } }}}`

Example `manifest.json`

Below is an example of a manifest.json containing multiple custom components:

{"name": "kitchenSink","version": "1.0.0","main": "kitchenSink.js","type": "custom","productType": "BYO","description": "Asset with general and component-specific items.","operations": [
    {
      "name": "General Operation With Context",
      "type": "kitchenSinkGeneralOpWithContext",
      "description": "A general operation that defines its result model.",
      "stability": "STABLE",
      "model": {
        "definitions": {
          "OperationOptions": {
            "type": "object",
            "properties": {
              "input": {
                "description": "Input component for the operation.",
                "type": "string"
              },
              "output": {
                "description": "Output component for the operation.",
                "type": "string"
              }
            },
            "required": ["input"]
          }
        },
        "properties": {
          "options": {
            "$ref": "#/definitions/OperationOptions"
          },
          "type": {
            "const": "operationsOnly",
            "type": "string"
          }
        },
        "required": ["options"],
        "type": "object"
      },
      "contextModel": {
        "type": "object",
        "properties": {
          "result": {
            "type": "object",
            "properties": {
              "transformed": { "type": "string", "description": "Transformation result" }
            }
          }
        }
      }
    }],"events": [
    {
      "name": "General Event",
      "type": "kitchenSinkGeneralEvent",
      "description": "A top-level event.",
      "stability": "STABLE"
    },
    {
      "name": "General Event Two",
      "type": "kitchenSinkGeneralEventTwo",
      "description": "A top-level event.",
      "stability": "STABLE",
      "model": {
        "type": "object",
        "properties": {
          "name": { "type": "string", "const": "kitchenSinkGeneralEventTwo" },
          "payload": {
            "type": "object",
            "description": "The event payload.",
            "properties": {
              "property1": { "type": "string", "description": "A sample string property." },
              "property2": { "type": "number", "default": 0, "description": "A sample number property." }
            },
            "required": ["property1", "property2"]
          }
        }
      }
    }],"components": [
    {
      "name": "My Test Component",
      "type": "kitchenSinkMyTestComponent",
      "description": "A custom component with its own operations.",
      "model": {
        "type": "object",
        "properties": { "value": { "name": "Data", "type": "string" } }
      },
      "operations": [
        {
          "name": "Component-Specific Operation",
          "type": "kitchenSinkMyTestComponentCompSpecificOp",
          "description": "An operation tied to My Test Component.",
          "stability": "STABLE",
          "model": {
            "definitions": {
              "OperationOptions": {
                "type": "object",
                "properties": {
                  "targetId": {
                    "description": "Target for the operation.",
                    "type": "string"
                  }
                },
                "required": ["targetId"]
              }
            },
            "properties": {
              "options": {
                "$ref": "#/definitions/OperationOptions"
              },
              "type": {
                "const": "kitchenSinkMyTestComponentCompSpecificOp",
                "type": "string"
              }
            },
            "required": ["options"],
            "type": "object"
          }
        }
      ]
    }]}

Bring Your Own (BYO): Understanding the manifest.json File

Overview

File Specification

Component Definition

Event Definition

Operation Definition

Example `manifest.json`

Resources

Bring Your Own (BYO) Framework Landing Page

Introduction to the Bring Your Own (BYO) Framework

Create a BYO Package

Understanding the BYO Runtime Engine API

Custom Component

Custom Component SDK

Custom Events

Custom Operations

Event Payloads

BYO Implementation Examples

BYO Best Practices

BYO General FAQ

Bring Your Own (BYO): Understanding the manifest.json File

Overview

File Specification

Component Definition

Event Definition

Operation Definition

Example manifest.json

Resources

Example `manifest.json`