@camunda/zeebe-element-templates-json-schema 0.31.1 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@camunda/zeebe-element-templates-json-schema",
-  "version": "0.31.1",
+  "version": "0.32.0",
   "description": "JSON Schema for (Zeebe) Element Templates",
   "files": [
     "resources"
@@ -26,5 +26,5 @@
     "camunda"
   ],
   "license": "MIT",
-  "gitHead": "80bad2f6487b25ec41762234b605bf1f9318f03b"
+  "gitHead": "092e8fa005c236f5fa02bb3e359a5132ea48b43e"
 }

package/resources/deprecated-warnings.json

@@ -0,0 +1,17 @@
+[
+  {
+    "path": [
+      "definitions",
+      "properties",
+      "allOf",
+      1,
+      "items",
+      "allOf",
+      25,
+      "then",
+      "anyOf",
+      2
+    ],
+    "warningMessage": "Hidden property must specify either \"value\" or \"generatedValue\""
+  }
+]

package/resources/schema.json

@@ -7,7 +7,7 @@
       "allOf": [
         {
           "type": "array",
-          "description": "List of properties of the element template.",
+          "description": "List of the template's properties.",
           "allOf": [
             {
               "examples": [
@@ -56,19 +56,21 @@
                       "type": {
                         "$id": "#/condition/type",
                         "const": "simple",
-                        "description": "The type of the condition.",
+                        "description": "Defines the type of the condition (always \"simple\").",
                         "default": "simple"
                       },
                       "property": {
                         "$id": "#/condition/property",
                         "type": "string",
-                        "description": "The id of the property to check."
+                        "description": "Reference to the property used to evaluate the condition."
                       }
                     },
                     "oneOf": [
                       {
+                        "description": "Checks if the referenced property's value is in the list of values defined in the condition.",
                         "properties": {
                           "equals": {
+                            "description": "Checks if the referenced property's value is equal to the value defined in the condition.",
                             "type": [
                               "string",
                               "number",
@@ -100,7 +102,7 @@
                         "properties": {
                           "isActive": {
                             "type": "boolean",
-                            "description": "For `true`, activates the property when given property is active"
+                            "description": "Checks if the referenced property is currently active and not hidden by other conditions."
                           }
                         },
                         "required": [
@@ -148,11 +150,11 @@
                 "properties": {
                   "id": {
                     "type": "string",
-                    "description": "Unique identifier of the property."
+                    "description": "Unique identifier of the property. Can be used to, for example, reference the property for checks."
                   },
                   "condition": {
                     "type": "object",
-                    "description": "Condition(s) to activate the binding.",
+                    "description": "Object that defines when a property should be displayed in the properties panel and its value should be included in the XML.",
                     "allOf": [
                       {
                         "examples": [
@@ -203,7 +205,8 @@
                             "items": {
                               "$ref": "#/definitions/properties/allOf/0/items/allOf/1/definitions/condition"
                             },
-                            "minItems": 1
+                            "minItems": 1,
+                            "description": "List of conditions that must all be met for the property to be active."
                           }
                         },
                         "required": [
@@ -266,7 +269,8 @@
                 "then": {
                   "properties": {
                     "placeholder": {
-                      "type": "string"
+                      "type": "string",
+                      "description": "Placeholder text shown in the property input field when it is empty. Can be used to show example input."
                     }
                   }
                 },
@@ -287,17 +291,17 @@
                   "number",
                   "boolean"
                 ],
-                "description": "The value of a control field."
+                "description": "Default value to be used if the user does not provide a value or if the type is Hidden."
               },
               "description": {
                 "$id": "#/properties/property/description",
                 "type": "string",
-                "description": "The description of a control field."
+                "description": "Hint text shown below the property input field."
               },
               "label": {
                 "$id": "#/properties/property/label",
                 "type": "string",
-                "description": "The label of a control field."
+                "description": "Label text shown above the property input field."
               },
               "type": {
                 "$id": "#/properties/property/type",
@@ -307,12 +311,12 @@
               "editable": {
                 "$id": "#/properties/property/editable",
                 "type": "boolean",
-                "description": "Indicates whether a control field is editable or not."
+                "description": "Defines whether users can edit the property in the properties panel. By default, all non-hidden properties are editable."
               },
               "choices": {
                 "$id": "#/properties/property/choices",
                 "type": "array",
-                "description": "The choices for dropdown fields.",
+                "description": "List of choices for a dropdown field.",
                 "default": [],
                 "items": {
                   "$id": "#/properties/property/choices/item",
@@ -322,12 +326,12 @@
                     "name": {
                       "$id": "#/properties/property/choices/item/name",
                       "type": "string",
-                      "description": "The name of a choice."
+                      "description": "Display name for a choice in a dropdown field. Shown to the user."
                     },
                     "value": {
                       "$id": "#/properties/property/choices/item/value",
                       "type": "string",
-                      "description": "The value of a choice."
+                      "description": "Value for a choice in a dropdown field. Stored in the XML."
                     },
                     "condition": {
                       "$ref": "#/definitions/properties/allOf/0/items/allOf/1/properties/condition"
@@ -342,7 +346,7 @@
               "constraints": {
                 "$id": "#/properties/property/constraints",
                 "type": "object",
-                "description": "The validation constraints of a control field.",
+                "description": "Object that contains rules to validate user input to the template.",
                 "allOf": [
                   {
                     "examples": [
@@ -370,7 +374,7 @@
                   },
                   "pattern": {
                     "$id": "#/properties/property/constraints/pattern",
-                    "description": "A regular expression pattern for a constraint.",
+                    "description": "String or object that defines a regular expression that the user's input must match.",
                     "oneOf": [
                       {
                         "type": "object",
@@ -379,12 +383,12 @@
                           "value": {
                             "$id": "#/properties/property/constraints/pattern/value",
                             "type": "string",
-                            "description": "The regular expression of a pattern."
+                            "description": "The value of the regular expression."
                           },
                           "message": {
                             "$id": "#/properties/property/constraints/pattern/message",
                             "type": "string",
-                            "description": "The validation message of a pattern."
+                            "description": "Custom error message to show when the user's input does not match the regular expression."
                           }
                         }
                       },
@@ -398,7 +402,7 @@
               "group": {
                 "$id": "#/properties/property/group",
                 "type": "string",
-                "description": "The custom group of a control field."
+                "description": "Group in the properties panel that the property belongs to."
               }
             }
           }
@@ -1920,22 +1924,22 @@
                   "name": {
                     "$id": "#/properties/property/binding/name",
                     "type": "string",
-                    "description": "The name of a property binding."
+                    "description": "The name of the property binding."
                   },
                   "source": {
                     "$id": "#/properties/property/binding/source",
                     "type": "string",
-                    "description": "The source value of a property binding (zeebe:output)."
+                    "description": "Source of the output parameter for an output mapping (created with zeebe:output)."
                   },
                   "key": {
                     "$id": "#/properties/property/binding/key",
                     "type": "string",
-                    "description": "The key value of a property binding (zeebe:taskHeader)."
+                    "description": "Key of a task header (created with zeebe:taskHeader)."
                   },
                   "property": {
                     "$id": "#/properties/property/binding/property",
                     "type": "string",
-                    "description": "The name of the property defined in the binding."
+                    "description": "Name of a binding property."
                   },
                   "linkName": {
                     "$id": "#/properties/property/binding/linkName",
@@ -1952,7 +1956,7 @@
               "feel": {
                 "$id": "#/properties/property/feel",
                 "type": "string",
-                "description": "Indicates whether the property can be a feel expression",
+                "description": "Defines whether the property supports FEEL expressions. Values can be \"optional\" (toggle), \"required\", or \"static\" (for Boolean/Number fields, persisted as FEEL).",
                 "enum": [
                   "optional",
                   "required",
@@ -1967,15 +1971,16 @@
               "generatedValue": {
                 "$id": "#/properties/property/generatedValue",
                 "type": "object",
+                "description": "Sets property to a generated value according to given scheme.",
                 "required": [
                   "type"
                 ],
                 "properties": {
                   "type": {
-                    "const": "uuid"
+                    "const": "uuid",
+                    "description": "Value is generated as UUID."
                   }
-                },
-                "description": "Sets property to a generated value according to given scheme."
+                }
               },
               "tooltip": {
                 "$id": "#/properties/property/tooltip",
@@ -1998,25 +2003,30 @@
             "properties"
           ],
           "properties": {
+            "$schema": {
+              "$id": "#/$schema",
+              "type": "string",
+              "description": "Reference to the Element Template JSON schema this document follows."
+            },
             "name": {
               "$id": "#/name",
               "type": "string",
-              "description": "The name of the element template."
+              "description": "Template name. Shown during template selection and editing of a templated element. Required."
             },
             "id": {
               "$id": "#/id",
               "type": "string",
-              "description": "The identifier of the element template."
+              "description": "Template identifier. Required."
             },
             "description": {
               "$id": "#/description",
               "type": "string",
-              "description": "The description of the element template."
+              "description": "Template description. Shown during template selection and editing of a templated element."
             },
             "version": {
               "$id": "#/version",
               "type": "integer",
-              "description": "Optional version of the template. If you add a version to a template it will be considered unique based on its ID and version. Two templates can have the same ID if their version is different."
+              "description": "Optional version of the template. If you add a version to a template, it will be considered unique based on its ID and version. Two templates can have the same ID if their versions are different."
             },
             "isDefault": {
               "$id": "#/isDefault",
@@ -2029,7 +2039,7 @@
                 "boolean",
                 "object"
               ],
-              "description": "Indicates whether the element template is deprecated.",
+              "description": "Marks the template as deprecated. Value can be either a boolean or an object with a message and a link to migration documentation.",
               "properties": {
                 "message": {
                   "$id": "#/deprecated/message",
@@ -2040,14 +2050,14 @@
                   "$id": "#/deprecated/documentationRef",
                   "type": "string",
                   "pattern": "^(https|http)://.*",
-                  "description": "Optional link to migration documentation."
+                  "description": "URL pointing to template documentation. Must be a valid http(s) URL."
                 }
               }
             },
             "appliesTo": {
               "$id": "#/appliesTo",
               "type": "array",
-              "description": "List of BPMN types the template can be applied to.",
+              "description": "List of BPMN types the template can be applied to. Required.",
               "default": [],
               "items": {
                 "$id": "#/appliesTo/items",
@@ -2070,7 +2080,7 @@
             "elementType": {
               "$id": "#/elementType",
               "type": "object",
-              "description": "The BPMN type the element will be transformed into.",
+              "description": "Object that sets the type of the element. Some properties require a specific value for elementType.",
               "default": {},
               "required": [
                 "value"
@@ -2080,6 +2090,7 @@
                   "$id": "#/elementType/value",
                   "type": "string",
                   "pattern": "^[\\w\\d]+:[\\w\\d]+$",
+                  "description": "Specifies the target BPMN element type. The element is replaced with the specified type when a user applies the template. Required if using elementType.",
                   "allOf": [
                     {
                       "examples": [
@@ -2106,18 +2117,18 @@
               "items": {
                 "type": "string"
               },
-              "description": "List of keywords to describe the element template.",
+              "description": "List of keywords to help users find the template. Used in search and filtering, but not displayed in the UI.",
               "default": []
             },
             "entriesVisible": {
               "$id": "#/entriesVisible",
               "type": "boolean",
-              "description": "Select whether non-template entries are visible in the properties panel."
+              "description": "Defines whether all property input fields are shown, even those normally hidden by the template."
             },
             "groups": {
               "$id": "#/groups",
               "type": "array",
-              "description": "Custom fields can be ordered together via groups.",
+              "description": "List of custom groups to organize related fields in the properties panel.",
               "allOf": [
                 {
                   "examples": [
@@ -2142,12 +2153,12 @@
                   "id": {
                     "$id": "#/groups/group/id",
                     "type": "string",
-                    "description": "The id of the custom group"
+                    "description": "Uniquely identifies a group object. Required if using groups."
                   },
                   "label": {
                     "$id": "#/groups/group/label",
                     "type": "string",
-                    "description": "The label of the custom group"
+                    "description": "The label of the group, shown as a section header in the properties panel. Required if using groups."
                   }
                 }
               }
@@ -3688,7 +3699,7 @@
         "engines": {
           "$id": "#/engines",
           "type": "object",
-          "description": "Defines the compatibility of this element template with different engines. Keys are engine names, values are semantic version ranges.",
+          "description": "Dictionary of environments compatible with the template. Environment version is specified with semantic versions range.",
           "default": {},
           "examples": [
             {
@@ -3699,7 +3710,19 @@
             "camunda": {
               "$id": "#/engines/camunda",
               "type": "string",
-              "description": "A semantic version range that denotes compatible Camunda versions.",
+              "description": "Defines compatibility with Camunda orchestration cluster versions.",
+              "default": ""
+            },
+            "camundaDesktopModeler": {
+              "$id": "#/engines/camundaDesktopModeler",
+              "type": "string",
+              "description": "Defines compatibility with Desktop Modeler versions.",
+              "default": ""
+            },
+            "camundaWebModeler": {
+              "$id": "#/engines/camundaWebModeler",
+              "type": "string",
+              "description": "Defines compatibility with Web Modeler versions.",
               "default": ""
             }
           }
@@ -3707,7 +3730,7 @@
         "category": {
           "$id": "#/category",
           "type": "object",
-          "description": "A custom category to semantically group element templates",
+          "description": "Object that defines a custom category for grouping templates, for example, in a selection modal. If not defined, defaults to Templates.",
           "default": {},
           "example": {
             "id": "custom-category",
@@ -3717,12 +3740,12 @@
             "id": {
               "$id": "#/category/id",
               "type": "string",
-              "description": "The unique identifier of the category."
+              "description": "Unique identifier for a category object. Required if using category."
             },
             "name": {
               "$id": "#/category/name",
               "type": "string",
-              "description": "The name of the category."
+              "description": "Display name of the category. Shown in the template selection modal. Required if using category."
             }
           },
           "required": [
@@ -3733,7 +3756,7 @@
         "icon": {
           "$id": "#/icon",
           "type": "object",
-          "description": "Custom icon to be shown on the element",
+          "description": "Custom icon shown in the element template selection modal and the properties panel. Must be a valid data URI or HTTP(s) URL. Square icons recommended.",
           "default": {},
           "properties": {
             "contents": {
@@ -3755,6 +3778,7 @@
                   "properties": {
                     "eventDefinition": {
                       "$id": "#/elementType/eventDefinition",
+                      "description": "If templating a message event, set this key's value to \"bpmn:MessageEventDefinition\". Otherwise, ignore.",
                       "enum": [
                         "bpmn:MessageEventDefinition"
                       ]
@@ -3793,12 +3817,13 @@
             "properties": {
               "tooltip": {
                 "$id": "#/groups/group/tooltip",
-                "type": "string"
+                "type": "string",
+                "description": "Tooltip shown when hovering over the group name in the properties panel."
               },
               "openByDefault": {
                 "$id": "#/groups/group/openByDefault",
                 "type": "boolean",
-                "description": "Specifies whether the Group should be opened when first viewed. Defaults to false.",
+                "description": "Controls whether the group is initially expanded in the properties panel. Optional; default is false.",
                 "default": false
               }
             }