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

The Bring Your Own framework is intended for developers who have a strong understanding of the Unqork Designer Platform and JavaScript JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser..

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 Programmatic namespacing is a way to group related code together under a common name so it doesn’t conflict with other code. It helps keep programs organized and prevents errors when different parts of a program use the same names. 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 string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		A unique identifier for the package. For example, MyCompanyNameAssets.
version	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		The semantic version number. For example, 1.0.0.
type	enum An enum, or enumeration type, is a data type that consists of a set of named constants that a variable can be assigned to.		The package type. Currently, the only supported value is custom.
productType	enum An enum, or enumeration type, is a data type that consists of a set of named constants that a variable can be assigned to.		The target platform feature. Currently, the only supported value is BYO.
description	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		A description that displays in the Admin Panel after installation.
main	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		The relative path to the JavaScript JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. entry file. For example, index.js.
components	array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects.<component-description>	Optional	A list of component definitions included in the package.
events	array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects.<event-description>	Optional	List of event definitions.
operations	array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects.<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 A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		The human-readable name. For example, My Custom Component. This value displays in the Admin Panel.
type	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		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, companyNameComponentName, where companyName is the abbreviated value of your company's name.
description	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		The human-readable description that displays in the Admin Panel after installation.
model	object An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.		Defines the configuration options available, and automatically generates a UI The UI (user interface) is a device's end-user interaction and communication point. It can include display screens, keyboards, and mouse. It is also how a user interacts with your application. for configurators in the Unqork Designer Platform. Supported data types include string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form., number Includes the Short Answer component, Long Answer component, Select Boxes, Radio component, Dropdown, Number component and Single Checkbox.,Boolean The Boolean data type accepts one of two values: true, or, false., array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects., object An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.. 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: Copy `{ "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 A string is an object that represents a sequence of characters. Strings typically hold data represented in text form., number Includes the Short Answer component, Long Answer component, Select Boxes, Radio component, Dropdown, Number component and Single Checkbox., and Boolean Includes the Short Answer component, Long Answer component, Select Boxes, Radio component, Dropdown, Number component and Single Checkbox..
events	array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects.<event-description>	Optional	List of event definitions.
operations	array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects.<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 Creators use Deisgner View to build and manage modules in the Unqork Designer Platform. to trigger platform operations. For example, SET_PROPERTY.

Field	Type	Description
name	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.	Displays a name for the event in Designer View.
type	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.	A unique event identifier. For example, myComponentClick. Prefix the value to avoid collisions.
description	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.	The description that displays in Designer View and the Admin Panel.
stability	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.	Indicates the component's status. Unqork recommends the following value: STABLE: General Availability (GA); fully supported.
model	object An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.	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: Copy `{ "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 A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		Displays a name for the operation in Designer View.
type	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		A unique event identifier. For example, myComponentOperation. Prefix the value to avoid collisions.
description	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		The description that displays in Designer View and the Admin Panel.
stability	string A string is an object that represents a sequence of characters. Strings typically hold data represented in text form.		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 An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.		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: Copy { "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 An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity.	Optional	When included, the contextModel must describe a result property A JavaScript property is a member of an object that associates a key with a value. A JavaScript object is a data structure that stores a collection of properties.. The result property can be a primitive A primitive is data that is not an object and has no methods or properties. There are seven primitive data types: string, number, bigint, boolean, undefined, symbol, and null., object An object is a type of data structure that represents a single, self-contained entity that acts as a container for the characteristics of that entity., or array An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. . The JSON schema Schema is a declarative language that defines the structure, content, and constraints of the data. should then reflect the expected result structure. If the operation does not have a result, do not include a contextModel. Copy `{ "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:

Copy

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
{
  "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"
          }
        }
      ]
    }
  ]
}