From 84de71a9a64aeb9d3ff3f47d7d4f55e229a38120 Mon Sep 17 00:00:00 2001
From: Andrew Fiddian-Green <software@whitebear.ch>
Date: Wed, 4 Mar 2026 18:49:48 +0000
Subject: [PATCH] Schema update for configuration description (#5372)

* add schema options for context

Signed-off-by: Andrew Fiddian-Green <software@whitebear.ch>
---
 .../schema/config-description-1.0.0.xsd       | 52 ++++++++++++++-
 .../core/ConfigDescriptionParameter.java      | 65 +++++++++----------
 2 files changed, 82 insertions(+), 35 deletions(-)

diff --git a/bundles/org.openhab.core.config.core/schema/config-description-1.0.0.xsd b/bundles/org.openhab.core.config.core/schema/config-description-1.0.0.xsd
index 40db9b3b9..d02e90723 100644
--- a/bundles/org.openhab.core.config.core/schema/config-description-1.0.0.xsd
+++ b/bundles/org.openhab.core.config.core/schema/config-description-1.0.0.xsd
@@ -37,7 +37,7 @@
 
 	<xs:complexType name="parameter">
 		<xs:all>
-			<xs:element name="context" type="xs:string" minOccurs="0"/>
+			<xs:element name="context" type="config-description:contextType" minOccurs="0"/>
 			<!-- deprecated element "required" -->
 			<xs:element name="required" type="xs:boolean" default="false" minOccurs="0"/>
 			<xs:element name="default" type="xs:string" minOccurs="0"/>
@@ -68,7 +68,7 @@
 		<xs:all>
 			<xs:element name="label" type="xs:string" minOccurs="0"/>
 			<xs:element name="description" type="xs:string" minOccurs="0"/>
-			<xs:element name="context" type="xs:string" minOccurs="0"/>
+			<xs:element name="context" type="config-description:contextType" minOccurs="0"/>
 			<xs:element name="advanced" type="xs:boolean" minOccurs="0"/>
 		</xs:all>
 		<xs:attribute name="name" type="xs:string" use="required"/>
@@ -162,4 +162,52 @@
 		<xs:attribute name="uri" type="config-description:uriRestrictionPattern" use="required"/>
 	</xs:complexType>
 
+	<xs:simpleType name="contextType">
+		<xs:union>
+			<xs:simpleType>
+				<!-- old behavior: allow any non empty string -->
+				<xs:restriction base="xs:string">
+					<xs:minLength value="1"/>
+				</xs:restriction>
+			</xs:simpleType>
+			<xs:simpleType>
+				<!-- enhanced behavior: allow "special meaning" options (so IDE can suggest them) -->
+				<xs:restriction base="xs:string">
+					<xs:enumeration value="channel"/>
+					<xs:enumeration value="channel-type"/>
+					<xs:enumeration value="color"/>
+					<xs:enumeration value="cronexpression"/>
+					<xs:enumeration value="date"/>
+					<xs:enumeration value="datetime"/>
+					<xs:enumeration value="dayOfWeek"/>
+					<xs:enumeration value="email"/>
+					<xs:enumeration value="group"/>
+					<xs:enumeration value="item"/>
+					<xs:enumeration value="location"/>
+					<xs:enumeration value="mac-address"/>
+					<xs:enumeration value="month"/>
+					<xs:enumeration value="network-address"/>
+					<xs:enumeration value="network-interface"/>
+					<xs:enumeration value="page"/>
+					<xs:enumeration value="password"/>
+					<xs:enumeration value="password-create"/>
+					<xs:enumeration value="persistence-service"/>
+					<xs:enumeration value="props"/>
+					<xs:enumeration value="qrcode"/>
+					<xs:enumeration value="rule"/>
+					<xs:enumeration value="script"/>
+					<xs:enumeration value="serial-port"/>
+					<xs:enumeration value="service"/>
+					<xs:enumeration value="tag"/>
+					<xs:enumeration value="telephone"/>
+					<xs:enumeration value="thing"/>
+					<xs:enumeration value="time"/>
+					<xs:enumeration value="url"/>
+					<xs:enumeration value="week"/>
+					<xs:enumeration value="widget"/>
+				</xs:restriction>
+			</xs:simpleType>
+		</xs:union>
+	</xs:simpleType>
+
 </xs:schema>
diff --git a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameter.java b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameter.java
index 47977805f..29dcd6961 100644
--- a/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameter.java
+++ b/bundles/org.openhab.core.config.core/src/main/java/org/openhab/core/config/core/ConfigDescriptionParameter.java
@@ -313,48 +313,47 @@ public class ConfigDescriptionParameter {
      * A context is a hint for user interfaces and input validators.
      * <p>
      * <p>
-     * Any string can be used, but the following have a special meaning:
+     * Any non empty string can be used, but the following have a special meaning, and will be suggested first by the IDE:
      * </p>
      *
      * <ul>
+     * <!-- @formatter:off -->
+     * <li><b>channel</b>: A valid channel UID. A UI would probably show a channel selection widget.</li>
+     * <li><b>channel-type</b>: A valid channel type UID. A UI would probably show a channel type selection widget.</li>
+     * <li><b>color</b>: This value represents an RGB color value like #000000 - #ffffff or 12,12,12.</li>
+     * <li><b>cronexpression</b>: A cron expression like "* * * * *". A user interface would probably show a cron expression generator.</li>
+     * <li><b>date</b>: A date string in the format "YYYY-MM-DD"</li>
+     * <li><b>datetime</b>: A date and time string in the format "YYYY-MM-DD'T'hh:mm:ss", e.g. "2019-12-31T23:59:59"</li>
+     * <li><b>dayOfWeek</b>: A day of week [MON, TUE, WED, THU, FRI, SAT, SUN]</li>
+     * <li><b>email</b>: The configuration value represents an email address, e.g. username@domain.com</li>
+     * <li><b>group</b>: A valid group item "name". A UI would probably show an item selection widget.</li>
+     * <li><b>item</b>: A valid item "name". A UI would probably show an item selection widget.</li>
+     * <li><b>location</b>: A latitude,longitude[,altitude] GPS location. A UI would probably render a world map for selection.</li>
+     * <li><b>mac-address</b>: The configuration value represents a MAC address.</li>
+     * <li><b>month</b>: A month of year [1-12]</li>
      * <li><b>network-address</b>: The configuration value represents an IPv4 or IPv6 address or domain name.</li>
      * <li><b>network-interface</b>: The configuration value represents a network interface name, e.g. eth0, wlan0.</li>
+     * <li><b>page</b>: A valid page UID. A UI would probably show a page selection widget.</li>
+     * <li><b>password</b>: An alphanumeric password value (a UI might obscure the visible value)</li>
+     * <li><b>password-create</b>: An alphanumeric password generator widget might be shown</li>
+     * <li><b>persistence-service</b>: A valid persistence service ID. A UI would probably show a persistence service selection widget.</li>
+     * <li><b>props</b>: A set of name = value properties.</li>
+     * <li><b>qrcode</b>: A text that is presented as a QR-Code image</li>
+     * <li><b>rule</b>: A valid rule uid. A UI would probably show a rule selection widget.</li>
+     * <li><b>script</b>: The configuration value represents a script (JavaScript, Python etc). A UI would probably render a multi line editor.</li>
      * <li><b>serial-port</b>: The configuration value represents a serial port name, e.g. COM1, /dev/ttyS0.</li>
-     * <li><b>password</b>: A alphanumeric password value (a user-interface might obscure the visible value)</li>
-     * <li><b>password-create</b>: A alphanumeric passwort generator widget might be shown</li>
-     * <li><b>color</b>: This value represents an RGB color value like #000000 - #ffffff or 12,12,12.</li>
-     * <li><b>date</b>: A date string in the format "YYYY-MM-DD"</li>
-     * <li><b>datetime</b>: A date and time string in the format "YYYY-MM-DD'T'hh:mm:ss", e.g.
-     * "2019-12-31T23:59:59"</li>
-     * <li><b>cronexpression</b>: A cron expression like "* * * * *". A user interface would probably show a cron
-     * expression generator.</li>
-     * <li><b>email</b>: The configuration value represents an email address, e.g. username@domain.com</li>
-     * <li><b>month</b>: A month of year [1-12]</li>
-     * <li><b>week</b>: A week of year [0-52]</li>
-     * <li><b>dayOfWeek</b>: A day of week [MON, TUE, WED, THU, FRI, SAT, SUN]</li>
-     * <li><b>time</b>: A time string in the format "hh:mm:ss" or as milliseconds since epoch</li>
-     * <li><b>telephone</b>: A tel no</li>
-     * <li><b>url</b>: A web address</li>
+     * <li><b>service</b>: A valid service ID. A UI would probably show a service selection widget.</li>
      * <li><b>tag</b>: One tag or multiple tags separated by comma.</li>
-     * <li><b>item</b>: A valid item "name". A user-interface would probably show an item selection widget.</li>
-     * <li><b>thing</b>: A valid thing UID. A user-interface would probably show a thing selection widget.</li>
-     * <li><b>group</b>: A valid group item "name". A user-interface would probably show an item selection widget.</li>
-     * <li><b>service</b>: A valid service ID. A user-interface would probably show a service selection widget.</li>
-     * <li><b>persistenceService</b>: A valid persistence service ID. A user-interface would probably show a persistence
-     * service selection widget.</li>
-     * <li><b>channel</b>: A valid channel UID. A user-interface would probably show a channel selection widget.</li>
-     * <li><b>channeltype</b>: A valid channel type UID. A user-interface would probably show a channel type selection
-     * widget.</li>
-     * <li><b>rule</b>: A valid rule uid. A user-interface would probably show a rule selection widget.</li>
-     * <li><b>script</b>: The configuration value represents a script (javascript, python etc). A user-interface would
-     * probably render a multi line editor.</li>
-     * <li><b>page</b>: A valid page UID. A user-interface would probably show a page selection widget.</li>
-     * <li><b>widget</b>: A valid widget UID. A user-interface would probably show a widget selection widget.</li>
-     * <li><b>location</b>: A latitude,longitude[,altitude] GPS location. A user-interface would probably render a world
-     * map for selection.</li>
+     * <li><b>telephone</b>: A tel no</li>
+     * <li><b>thing</b>: A valid thing UID. A UI would probably show a thing selection widget.</li>
+     * <li><b>time</b>: A time string in the format "hh:mm:ss" or as milliseconds since epoch</li>
+     * <li><b>url</b>: A web address</li>
+     * <li><b>week</b>: A week of year [0-52]</li>
+     * <li><b>widget</b>: A valid widget UID. A UI would probably show a widget selection widget.</li>
+     * <!-- @formatter:on -->
      * </ul>
      *
-     * @return the context of the configuration parameter (could be empty)
+     * @return the context of the configuration parameter (could be null)
      */
     public @Nullable String getContext() {
         return this.context;