docs(kno-13411): add number, color and list input field types to schema references (#1460)

emisilvacab · web-flow · commit 29e72a0ec335 · 2026-06-04T09:59:56.000-04:00
* docs: add number, color and list input field types to schema references

* fix: update link references

* fix: use title property

* docs: update list example
diff --git a/content/in-app-ui/message-types/schema-reference.mdx b/content/in-app-ui/message-types/schema-reference.mdx
@@ -217,6 +217,114 @@ A checkbox that returns either true or false (checked or unchecked).
 }
 ```
 
+### Number
+
+A numeric input field with optional min/max bounds and a unit label shown next to the input.
+
+#### Settings
+
+<Attributes>
+  <Attribute
+    name="required"
+    type="boolean"
+    description="Indicates this field is required"
+  />
+  <Attribute
+    name="description"
+    type="string"
+    description="An optional friendly description"
+  />
+  <Attribute
+    name="placeholder"
+    type="string"
+    description="An optional placeholder to display in the input"
+  />
+  <Attribute
+    name="default"
+    type="number"
+    description="The default numeric value"
+  />
+  <Attribute
+    name="min"
+    type="number"
+    description="The inclusive minimum allowed value"
+  />
+  <Attribute
+    name="max"
+    type="number"
+    description="The inclusive maximum allowed value"
+  />
+  <Attribute
+    name="unitLabel"
+    type="string"
+    description="A short label shown after the input (e.g. `px`, `kg`)"
+  />
+</Attributes>
+
+#### Example
+
+```json
+{
+  "type": "number",
+  "key": "ship_number",
+  "label": "Ship number",
+  "settings": {
+    "description": "Displayed next to the hull ID",
+    "placeholder": "0",
+    "required": true,
+    "default": 42,
+    "min": 0,
+    "max": 999999,
+    "unitLabel": "TEU"
+  }
+}
+```
+
+### Color
+
+A hex color input field that accepts values in `#RGB` or `#RRGGBB` format. Editors can also pick a color from the [branding variables](/template-editor/branding) defined on the environment, in which case the value is stored as a reference to that variable (e.g. `{{ vars.branding.primary_color }}`).
+
+#### Settings
+
+<Attributes>
+  <Attribute
+    name="required"
+    type="boolean"
+    description="Indicates this field is required"
+  />
+  <Attribute
+    name="description"
+    type="string"
+    description="An optional friendly description"
+  />
+  <Attribute
+    name="placeholder"
+    type="string"
+    description="An optional placeholder to display in the input"
+  />
+  <Attribute
+    name="default"
+    type="string"
+    description="The default hex color value"
+  />
+</Attributes>
+
+#### Example
+
+```json
+{
+  "type": "color",
+  "key": "accent_color",
+  "label": "Accent color",
+  "settings": {
+    "description": "A hex color for the accent",
+    "placeholder": "#000000",
+    "required": true,
+    "default": "#FF0000"
+  }
+}
+```
+
 ### Select
 
 A single select box that defines a static list of options for editors to pick from.
@@ -551,3 +659,78 @@ A JSON input field with schema validation.
   }
 }
 ```
+
+### List
+
+A list of items, with an optional <a href="https://json-schema.org/" target="_blank">JSON Schema</a> that validates the structure of each item in the list.
+
+#### Settings
+
+<Attributes>
+  <Attribute
+    name="required"
+    type="boolean"
+    description="Indicates this field is required"
+  />
+  <Attribute
+    name="description"
+    type="string"
+    description="An optional friendly description"
+  />
+  <Attribute name="default" type="array" description="The default list value" />
+  <Attribute
+    name="itemSchema"
+    type="object"
+    description="A JSON Schema object that validates the structure of each item in the list."
+  />
+</Attributes>
+
+#### Example
+
+```json
+{
+  "type": "list",
+  "key": "faqs",
+  "label": "FAQs",
+  "settings": {
+    "description": "Frequently asked questions",
+    "required": true,
+    "default": [],
+    "itemSchema": {
+      "type": "object",
+      "properties": {
+        "question": { "type": "string", "title": "Question" },
+        "answer": { "type": "string", "title": "Answer" }
+      },
+      "required": ["question", "answer"]
+    }
+  }
+}
+```
+
+#### Usage
+
+When a list input is referenced in a template, its value is decoded into a Liquid array so you can iterate over it and access each item's fields.
+
+The most common pattern is to loop over the items:
+
+```liquid title="Iterating over a list field"
+<dl>
+  {% for faq in faqs %}
+    <dt>{{ faq.question }}</dt>
+    <dd>{{ faq.answer }}</dd>
+  {% endfor %}
+</dl>
+```
+
+You can also access a single item by index:
+
+```liquid title="Accessing a list item by index"
+{{ faqs[0].question }}
+```
+
+Note that printing the array directly with `{{ faqs }}` only works when the items are primitives (strings, numbers). For lists of objects, use the `json` filter to render the full value:
+
+```liquid title="Rendering a list of objects"
+{{ faqs | json }}
+```
diff --git a/content/template-editor/partials/overview.mdx b/content/template-editor/partials/overview.mdx
@@ -148,30 +148,32 @@ Click a custom block to open the inspect panel to edit variable values. You can
 
     You have two options, depending on your use case:
 
-    **1. Create a schema for your HTML partial and set the variable's input type to JSON.**
+    **1. Create a schema for your HTML partial and set the variable's input type to list or JSON.**
 
-    When you create a [schema](/template-editor/partials/schema-reference) for your HTML partial, you can set the input type for a given variable to `json`. This will preserve the structure of the object or array of items that is passed in.
+    When you create a [schema](/template-editor/partials/schema-reference) for your HTML partial, you can pick an input type that preserves the structure of the data passed in:
 
-    For example, if you want a partial to render a list of items, you can create a schema for your partial and pass your list to the partial input like this:
+    - Use the [`list`](/template-editor/partials/schema-reference#list) input type when you want to pass an array of items (for example, a list of products or line items).
+    - Use the [`json`](/template-editor/partials/schema-reference#json) input type when you want to pass a single object (for example, a user profile or other structured payload).
+
+    **Working with a list of items**
+
+    If you want a partial to render a list of items, you can define a `list` field in your schema and pass your array to the partial input.
 
     ```json title="A schema for an HTML partial's 'items' variable"
     [{
-      "type": "json",
+      "type": "list",
       "key": "items",
       "label": "Items list",
       "settings": {
         "required": true,
         "description": "A list of items to render",
-        "schema": {
-          "type": "array",
-          "items": {
-            "type": "object",
-            "properties": {
-              "name": { "type": "string" },
-              "value": { "type": "string" }
-            },
-            "required": ["name", "value"]
-          }
+        "itemSchema": {
+          "type": "object",
+          "properties": {
+            "name": { "type": "string" },
+            "value": { "type": "string" }
+          },
+          "required": ["name", "value"]
         }
       }
     }]
@@ -180,16 +182,56 @@ Click a custom block to open the inspect panel to edit variable values. You can
     ```liquid title="Passing a list of items to the partial's 'items' input"
     {{ data.items_list }}
     ```
-    Then, in the partial you can reference the list of items directly:
-    ```liquid title="Partial content with structured data"
+
+    Then, in the partial you can iterate over the items directly:
+
+    ```liquid title="Partial content with a list of items"
     <ul>
       {% for item in items %}
         <li>{{ item.name }}: {{ item.value }}</li>
       {% endfor %}
     </ul>
     ```
+
+    **Working with a single JSON object**
+
+    If you want a partial to render a single structured object, you can define a `json` field in your schema and pass your object to the partial input.
+
+    ```json title="A schema for an HTML partial's 'user' variable"
+    [{
+      "type": "json",
+      "key": "user",
+      "label": "User",
+      "settings": {
+        "required": true,
+        "description": "The user profile to render",
+        "schema": {
+          "properties": {
+            "name": { "type": "string" },
+            "email": { "type": "string" },
+            "company": { "type": "string" }
+          },
+          "required": ["name", "email"]
+        }
+      }
+    }]
+    ```
+
+    ```liquid title="Passing an object to the partial's 'user' input"
+    {{ recipient }}
+    ```
+
+    Then, in the partial you can reference the object's properties directly:
+
+    ```liquid title="Partial content with a JSON object"
+    <p>Hello {{ user.name }}</p>
+    <p>Email: {{ user.email }}</p>
+    {% if user.company != blank %}
+      <p>Company: {{ user.company }}</p>
+    {% endif %}
+    ```
     <br />
-    You can follow a similar pattern for working with your full `data` payload, `recipient`, or other object [variables](/template-editor/variables) that are available in the workflow run scope; simply pass a Liquid reference to the variable into the partial input (i.e. `{{data}}`), then reference the object's properties within the partial content.
+    You can follow a similar pattern for working with your full `data` payload, `recipient`, or other object [variables](/template-editor/variables) that are available in the workflow run scope; pass a Liquid reference to the variable into the partial input (i.e. `{{ data }}`), then reference the object's properties within the partial content.
     <br/>
     **2. Use Knock's Liquid helpers to transform your input data into a JSON string.**
 
diff --git a/content/template-editor/partials/schema-reference.mdx b/content/template-editor/partials/schema-reference.mdx
