Now that you are ready to create your application, it is time to build your package by defining the structure and essential elements of your app.

Getting Started

Use a text editor like Visual Studio Code or the Dawiso built-in editor (Settings > Resources > Packages > + New Package) to write your package. To enable helpful tooltips and error-checking, include the following line at the top of your package file:

{
    "$schema": "https://schema.dawiso.com/package-schema.json"
}

You can begin in one of two ways:

Copy an Existing Package

  1. Select any existing package from Settings > Resources > Packages. Click three dots on the right and select Version History.
  2. Copy the contents and paste them into a new package or a Visual Studio Code file.
  3. Remove all translations, as these will likely differ.
  4. Delete properties and components you don’t understand or need.
  5. Keep only the elements relevant to your application to simplify the structure.
Tip

Although this method is faster, make sure you remove all unnecessary properties. It is easy to overlook elements that don’t belong in your package.

Use a Basic JSON Template

Here’s a blank JSON template to use as your foundation:

{
    "$schema": "https://schema.dawiso.com/package-schema.json",
    "package": {
        "key": "",
        "name": "",
        "settings": { },
        //"dependsOn": [ ],
        "assets": {
            "applications": [ ],
            "attributeTypes": [ ],
            // "userRelationTypes": [ ],
            // "relationTypes": [ ],
            "components": [ ],
            "objectTypes": [ ],
            "objectTypeRelations": [ ],
            // "workflowStates": [ ],
            // "workflows": [ ],
            "colors": [ ],
            "translations": [ ]
        }
    }
}

The asset order in the package is intentional, reflecting dependencies.

  1. Define foundational elements:
  • attributeTypes, userRelationTypes, and relationTypes are referenced in components and object types.

2. Build object types:

  • attributeTypes are assigned to object types, while components define the object type page’s structure and displayed information.

3. Establish relations:

  • objectTypeRelations define how object types connect to one another.

4. Specify functionality:

  • workflowStates are used to create workflows.

5. Finalize with static assets:

  • colors and translations are listed last, as you need to define them only once.

Understanding the Package Structure

PropertyPurpose

key A unique identifier for your package. The package key is a primary key, used for referencing its assets in other packages.

For organizational purposes, we recommend using cust_ prefix for your packages. This practice allows you and the Dawiso Customer Success team to differentiate between your custom packages and Dawiso packages (identified using the core_ prefix).

Keep in mind that if you change the key of an installed application package, the application will be removed from your space along with all stored objects. The key can be changed only before the initial package installation.

Tip

Each asset in a package (e.g., object types, components, attributes) has a unique key, which is used to reference it within the package. For example, an object type key is required to assign the object type to an application.

When referencing assets within the same package, no prefix is needed. However, when referencing assets from another package, the following format is used:

{package_key}#{asset_key}

or

{package_key}_{asset_key}

The hash (#) separator is preferred because it clearly indicates that the referenced asset belongs to a different package. For example:

  • Within the same package: attribute_key From another package: core#attribute_key

name

  • The name of the package, used mainly under the Resources > Packages section.

settings

  • (Optional) Global settings for your package. Typically, settings are defined at the application or asset level and this field is less commonly used.

dependsOn

  • (Optional) Specifies any dependencies your package has on other existing packages. These packages must be installed first for compatibility. For example, if your package references Code List object types, the Code Lists application must be installed first to provide the necessary structure.
Danger

Declaring dependencies is critical when your package relies on components, attributes, or relations from another package. Failure to install dependencies first may result in missing references, errors, or incomplete functionality.

assets

  • The core of the package, where you define all the elements (applications, components, object types, and more) that make up your app.
  • As assets are the key section to your package, let’s take a look at what assets a basic package needs.

Exploring the Assets

The assets section is where you define the building blocks of your package. Here is an overview of the basic key assets:

AssetPurpose
applicationsDefines the application’s general configuration, such as its hierarchy and color, and assigns object types to it. While it is technically possible to define multiple applications within a single package, we strongly recommend against it for maintainability and clarity. Keeping each application in its own package ensures better organization and avoids unnecessary complexity.
colorsSpecifies colors used in the package, typically referenced in the applications asset.
componentsDefines elements like tables, diagrams, or charts that appear on object type pages or dashboards. If these elements are defined in core, you can reference them directly under objectTypes > templates.
attributeTypesDefines the type of data which can be later assigned to individual object types, such as text, numbers, dates, or checkboxes. Each object type typically requires unique attributes, but some, mainly descriptions (core#description), are often shared across multiple object types.
objectTypesCreates object types and defines the attributes and components on their pages. Objects are the foundation of any app.
objectTypeRelationsSpecifies the relations between object types, including parent-child hierarchies.
translationsSpecifies how translation keys of title properties are displayed in the UI.

Keep in Mind: Translations

Although called translations, this asset does not directly translate text from one language to another. Instead, it maps translation keys (which act as references) to their corresponding text values in the UI.

For example, instead of storing static text like “Dashboard”, the system uses a translation key such as title.Dashboard. The translations asset then defines how this key appears in the UI. Each translation key can have multiple values, categorized by language keys, enabling multi-language support.

Tip

Unlike the name property, which appears exactly as written, title properties are translation keys that must be defined in this asset. If a specific string of text is used for a title without a corresponding translation, the UI will typically display it with the package key instead. For example, "title": "Comment Section" will be displayed as package_key_comment section in the UI.

Whenever you use a translation key, it is advised to immediately define it in the translations. The following properties use translation keys:

  • title: Headings and labels of components and other assets.
  • toolTipKey: Translation key of a tooltip that appears when hovering over the property.

Here is a blank template for translations:

"translations": [
    {
        "key": "",
        "values": [
            {
                "name": "",
                "languageKey": ""
            }
        ]
    },
],
PropertyPurpose
keyUnique identifier for a translation, typically used for title or toolTipKey properties that reference translations.
valuesArray of translations for the translation key. Each value requires a specified language key, enabling multi-language support in your environment. See nested properties.

Value nested properties:

PropertyPurpose
nameText string displayed in the UI.
languageKeyLanguage for which the value is valid, written in the language tag format [language code]-[country code] (e.g., en-GB, cs-CZ, pl-PL).

Custom Assets

For enhanced customization, Dawiso allows you to define your own custom assets. While many predefined assets are available in the core package, you can create your own to meet specific needs. For a comprehensive list of available assets, see this article.

AssetPurpose
relationTypesDefines custom relations not included in Dawiso’s core, including their reverse relations if applicable. This is also where you define parent-child relations by specifying whether a relation is one-directional using the isOriented property.
userRelationTypesDefines governance roles assignable to object users, controlling permissions, responsibilities, and edit rights by workflow state (for example, Data Owners can edit/approve in any state, while others can edit only before Approved).
workflowStatesDefine the stages an object goes through during its lifecycle. Each state can have specific rules or permissions attached. You can assign different initial workflow states to selected object types.
workflowsCreate workflows by linking the created workflow states and defining transitions between them. For example, you might allow objects to move from Draft to Review, but restrict transitions from Approved to Draft to Admin users.

Optional Step: Specify Your Application’s Basics

Once your template is ready, you can start filling it in. For example, you can start with general information about your application. We will explain this section in detail again in the article on application configuration, so feel free to skip to the next article.

As usual, there are many properties you can define in this asset. Let’s start with a blank template with properties every applications asset should contain.

"applications": [
    {
        "key": "app",
        "name": "",
        "shortcut": "",
        "description": ".",
        "colorKey": "",
        "defaultObjectTypeKey": "app_overview",
        "objectTypeKeys": [ ],
        "hierarchyDefinitions": [
            {
                "hierarchyDefinitionKey": "core#object",
                "isDefault": true
            }
        ],
        "search": [
            {
                "isSearchable": true
            }
        ],
        "settings": [
            {
                "key": "excel_export_enabled",
                "value": true
            },
            {
                "key": "excel_import_enabled",
                "value": true
            }
        ]
        "templates": { }
    }
],

Some properties are straightforward and can be filled in immediately, while others depend on components, attributes, and object types that you will define later. Leaving these properties blank at first ensures consistency in naming and referencing as your package evolves.

We separated these properties into three categories:

Define NowDefine Now or LaterBest Defined Last
key: A unique identifier for your application. A short, simple name like app is enough, as the full identifier will automatically include the package key (e.g., cust_recipe_manager_app).objectTypeKeys: Specifies all object types that belong to your app. Assign them now to ensure all required object types are listed, making it easier to catch any missing ones during validation later.templates: Configures the application overview page using components and attributes.
name: The display name for your app in Dawiso’s UI.colorKey: Links to a color defined in the colors asset. Use predefined colors from Settings > Configuration > Colors for consistency across devices and updates.search: Specifies default search settings, e.g., determines whether all objects can show up in search.
shortcut: An abbreviation shown in the UI when no custom icon is provided.defaultObjectTypeKey: Specifies the default object type, also called space application overview (its key is usually app_overview).
description: A brief explanation of your app, useful for documentation or UI tooltips.settings: Specifies default application settings such as import/export, tokenization, etc. See the full list of configurable settings.
hierarchyDefinitions: Determines how the left-side navigation will display object types. Use core#object for default behavior. Custom hierarchy definitions are mostly used for ingestion apps. For more details, see our Ingestion Apps tutorials.
Tip

If you decide to use a custom color, make sure to define it in the colors asset. "colors": [ { "key": "", "name": "", "colorHex": "" } ],

Example Configuration of the applications Asset

For our Recipe Manager app, the applications asset would be defined in the following way:

Click here to show the example.
"applications": [
    {
        "key": "app",
        "name": "Recipe Manager (Tutorial app)",
        "shortcut": "RM",
        "description": "An application for managing recipes and their ingredients.",
        "colorKey": "core_app_light_blue",
        "defaultObjectTypeKey": "app_overview",
        "objectTypeKeys": [
            "cuisine",
            "recipe",
            "ingredient_category",
            "ingredient"
        ],
        "hierarchyDefinitions": [
            {
                "hierarchyDefinitionKey": "core#object",
                "isDefault": true
            }
        ],
        "search": [
            {
                "isSearchable": true
            }
        ],
        "settings": [
            {
                "key": "excel_export_enabled",
                "value": true
            },
            {
                "key": "excel_import_enabled",
                "value": true
            }
        ],
        "templates": { }
    }
],

As you can see, in the example, the following properties have been configured:

  • hierarchyDefinitions: Left-side navigation will display the hierarchy of objects.
  • search: When isSearchable is defined on this level, all objects created in the app will be searchable by default.
  • settings: The set of settings allows export, import, as well as more advanced configuration like autolinking/tokenization in text. We will take a look at these in other tutorials!