--- title: "Bring Your Own (BYO): Understanding the manifest.json File" slug: "bring-your-own-byo-understanding-the-manifestjson-file" updated: 2025-09-26T06:51:09Z published: 2025-09-26T06:51:09Z canonical: "docs.unqork.io/bring-your-own-byo-understanding-the-manifestjson-file" --- > ## Documentation Index > Fetch the complete documentation index at: https://docs.unqork.io/llms.txt > Use this file to discover all available pages before exploring further. # Bring Your Own (BYO): Understanding the manifest.json File > [!WARNING] > The [Bring Your Own](/v1/docs/introduction-to-the-bring-your-own-byo-framework) 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](/v1/docs/bring-your-own-byo-create-a-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. > [!WARNING] > 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 | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | A unique identifier for the package. For example, `MyCompanyNameAssets`. | | `version` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | The semantic version number. For example, `1.0.0`. | | `type` | enum | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | The package type. Currently, the only supported value is custom. | | `productType` | enum | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | The target platform feature. Currently, the only supported value is BYO. | | `description` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | A description that displays in the Admin Panel after installation. | | `main` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | The relative path to the JavaScript entry file. For example, index.js. | | `components` | array | Optional | A list of component definitions included in the package. | | `events` | array | Optional | List of event definitions. | | `operations` | array | Optional | List of operation definitions. | > [!WARNING] > 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](/v1/docs/best-practices-bring-your-own-byo-framework) 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 | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | The human-readable name. For example, `My Custom Component`. This value displays in the Admin Panel. | | `type` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | A unique identifier. This value must match a named export in the main JavaScript file. > [!WARNING] > 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 | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | The human-readable description that displays in the Admin Panel after installation. | | `model` | object | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | 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: ```json {"type": "object","properties": { "text": { "type": "string" }, "color": { "type": "string" }},"required": ["text", "color"]} ``` > [!WARNING] > 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 | Optional | List of event definitions. | | `operations` | array | 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 | Required | Description | | --- | --- | --- | --- | | `name` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | Displays a name for the event in Designer View. | | `type` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | A unique event identifier. For example, `myComponentClick`. > [!TIP] > Prefix the value to avoid collisions. | | `description` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | The description that displays in Designer View and the Admin Panel. | | `stability` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | Indicates the component's status. Unqork recommends the following value: - `STABLE`: General Availability (GA); fully supported. | | `model` | object | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | 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: ```json {"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 | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | Displays a name for the operation in Designer View. | | `type` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | A unique event identifier. For example, `myComponentOperation`. > [!TIP] > Prefix the value to avoid collisions. | | `description` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | The description that displays in Designer View and the Admin Panel. | | `stability` | string | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | 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 | ![Checked Box Icon](https://cdn.us.document360.io/15548f06-2fba-434c-b0c1-5df88317dbd7/Images/Documentation/checkedDummy.jpg?sv=2026-02-06&spr=https&st=2026-11-07T22%3A08%3A01Z&se=2026-11-07T23%3A08%3A01Z&sr=c&sp=r&sig=tc0UpZfIdBmWSKZMpwcuXq6DxMp7t7wFWFXTMy9i%2BSI%3D) | 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: ```json {"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. > [!NOTE] > If the operation does not have a result, do not include a contextModel. ```json {"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: ```json {"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"           }         }       ]     }]} ``` ## Resources ### [Bring Your Own (BYO) Framework Landing Page](/v1/docs/bring-your-own-byo-framework-landingpage) Find all the resources needed to build your own components here. ### [Introduction to the Bring Your Own (BYO) Framework](/v1/docs/introduction-to-the-bring-your-own-byo-framework) Get started building your own custom assets, including components, events, and operations. ### [Create a BYO Package](/v1/docs/bring-your-own-byo-create-a-package) Discover the structure and content of a BYO Package ### [Understanding the BYO Runtime Engine API](/v1/docs/bring-your-own-byo-understanding-runtime-engine-api) Discover the interface between your custom BYO components and the Unqork platform. ### [Custom Component](/v1/docs/bring-your-own-byo-custom-component) Understand the state, interface, and events of a custom component. ### [Custom Component SDK](/v1/docs/bring-your-own-byo-component-sdk-software-development-kit) Extend component functionality in the Unqork Designer Platform. ### [Custom Events](/v1/docs/bring-your-own-byo-custom-events) Learn more about creating custom events for use in the Operations Builder. ### [Custom Operations](/v1/docs/bring-your-own-byo-custom-operations) Learn more about creating custom operations for use in the Operations Builder. ### [Event Payloads](/v1/docs/bring-your-own-byo-726-event-payloads) Learn more about viewing and using event payloads with the Operations Builder. ### [BYO Implementation Examples](/v1/docs/bring-your-own-byo-726-implementation-examples) Discover examples of component implementation using the Unqork Designer Platform. ### [BYO Best Practices](/v1/docs/best-practices-bring-your-own-byo-framework) Learn about best practices for implementing and using BYO assets. ### [BYO General FAQ](/v1/docs/bring-your-own-byo-general-faq-frequently-asked-questions) Learn about the Bring Your Own Framework and discover frequently asked questions. JavaScript is an object-oriented computer programming language. It is most-commonly used for interactive effects in the browser. 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. A string is an object that represents a sequence of characters. Strings typically hold data represented in text form. An enum, or enumeration type, is a data type that consists of a set of named constants that a variable can be assigned to. An array is a type of object that stores one or more data types. Data types supported in arrays include numbers, strings, and objects. 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 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. The Number data type accepts integer or floating point values. The number data type does not use quotes around numerical values. The Boolean data type accepts one of two values: true, or, false. Creators use Deisgner View to build and manage modules in the Unqork Designer Platform. 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. 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. Schema is a declarative language that defines the structure, content, and constraints of the data.