In this article, you will find the best practices for working with package and their JSON code.

1. Follow the structure

Dawiso packages have a predefined structure which will be checked when validating a package:

  • Properties have to follow their nesting order.
  • Properties on the same level are interchangeable.

Nesting of properties has to be followed, but properties on the same level can be switched without any problems with package validation.

Tip

It is strongly recommended to follow the structure as suggested in the Structure of a package article. This ensures a standardized format, making it easier for others to understand and navigate the code.

2. Packages actions best practices

Naming a package

When naming a package, use the prefix cust_ (e.g., cust_packageName). This best practice allows you and the Dawiso Customer Success team to differentiate between your custom packages and Dawiso packages (identified using the core_ prefix).

Version comment

When creating a new version of a package, fill in the Version description field. This helps track changes and identify mistakes in the future.

3. Keys naming convention

Use simple and memorable names for keys in your package. This makes it easier to reference properties within the same package or from different packages.

Most properties in packages have a key property. These keys can call a property in a different place in the same package or from a different package using the following syntax:

{package_key}#{asset_key} or {package_key}_{asset_key}

Capitalization

Keys must start with lowercase characters, especially package keys. For better legibility, you can capitalize letters in the middle of the key (e.g. attributeName) but we recommend using an underscore or a dot (attribute_name or attribute.name).

Hash separator

When referencing a key from another package, the hash (#) separator is preferred as it provides immediate distinction that that the referenced asset belongs to a different package.

For example:

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

For attribute types that are defined in a core package and are often referenced, see Attribute types.

Commonly used keys

They following key names are recommended for clarity.

  • Application key: Use app as a simple and short key. The reason for this is that the full application identifier automatically includes the package key on the back-end (e.g., recipe_manager_app).
  • Space application overview: Define the app_overview object type and use it as a default object type of an application.

4. Put reusable assets in a separate package

When assets are reused across packages, it is recommended to install them in a separate package. This can apply to: components (including template-settings), relations, conditions.

Having reusable assets in one package allows you to make changes to all assets without having to manually edit all packages where they are used.

5. Use the components asset

In general, we recommend creating components in their own section to reference them in object type templates. A component is usually used at least in two places: the object page and object detail.

Tip

If you already know that the component will be used across packages, create the whole component asset in a separate package (see Best practice no. 4).

Alphabetical order

Ordering components alphabetically makes it easier to navigate and reference them when working on your package.

Naming convention

Establish and adhere to a naming convention for your component keys for consistency and clarity.

We recommend the following format: componentType_useDescription

For example:

  • table_objectTypes for a simple table component.
  • panel_table_objectTypes for a table component nested within a panel.

6. Packages with dependencies best practices

Validate a package with dependencies

Validating a patch package requires validating all connected packages (similar to the reinstallation process). Start by validating the base package, then proceed with all connected packages in the order specified by the runAfter property.

Reinstall a package with dependencies

Installing a patch package requires reinstalling all connected packages. Start by reinstalling the base package, then proceed with (re)installing all connected packages in the order specified by the runAfter property.

Rollback previous package with dependencies

Rolling back a package is not advised if it has patch packages or other dependent packages, as it may break those dependencies. If subsequent patch packages depend on the current package version, a rollback will not be possible.

Delete a package with dependencies

A package can’t be deleted if other patch packages or packages depend on it. Dependent packages must be deleted first.

7. Patch packages best practices

One change per patch

It is recommended for each patch package to contain only one type of change. E.g., patch A adds attribute types, patch B adds icons, etc.

For more information on the configuration, see Patch Packages.

Patch naming convention

We recommend naming a patch package by using the following template: cust_basePackageKey_patch_changeDescription. Using this formula, the key will immediately provide context about what package and what properties it patches.

  • E.g., cust_core_patch_attributeTypes