From 32e8e2f9d7980f9ae69f1daa9f653f5258666cda Mon Sep 17 00:00:00 2001
From: Richard Weyer <info@richardweyer.de>
Date: Fri, 13 Mar 2026 21:25:12 +0100
Subject: [PATCH] feat(spec): add optional order property for UI ordering
 (Issue #27)

---
 v1/specification/json-schemas/gdd/README.md   | 34 ++++++++++++++++++-
 v1/specification/json-schemas/gdd/object.json |  4 +++
 2 files changed, 37 insertions(+), 1 deletion(-)

diff --git a/v1/specification/json-schemas/gdd/README.md b/v1/specification/json-schemas/gdd/README.md
index 1aa0173..2195149 100644
--- a/v1/specification/json-schemas/gdd/README.md
+++ b/v1/specification/json-schemas/gdd/README.md
@@ -166,7 +166,8 @@ All properties share these definitions: ([JSON-schema definition](https://json-s
   "label": string, // [Optional] Short label to name the property
   "description": string, // [Optional] Longer description of the property
   "gddType": string, // [Optional unless required by GDD Type] A string containing the GDD Type name, see below
-  "gddOptions": object // [Optional unless required by GDD Type] An object containing options for a certain GDD Type, see below
+  "gddOptions": object, // [Optional unless required by GDD Type] An object containing options for a certain GDD Type, see below
+  "order": number // [Optional] Hint for UI ordering; lower means earlier
 }
 ```
 
@@ -450,6 +451,37 @@ Example:
 }
 ```
 
+## Property order
+
+To provide a stable and author-controlled ordering in UIs, each property MAY define an `order` value:
+
+- Properties with a lower `order` value SHOULD be rendered before properties with a higher `order` value.
+- Properties with an `order` value SHOULD be rendered before properties without an `order` value.
+- Properties without an `order` value MAY be ordered in an implementation-defined way.
+
+Example:
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "title": {
+      "type": "string",
+      "order": 1
+    },
+    "subtitle": {
+      "type": "string",
+      "order": 2
+    },
+    "internalNotes": {
+      "type": "string"
+    }
+  }
+}
+```
+
+In a GUI, `title` SHOULD be displayed before `subtitle`, while `internalNotes` (which has no `order`) can be placed after them in an implementation-defined position.
+
 ## For GUI Developers
 
 ### Getting started
diff --git a/v1/specification/json-schemas/gdd/object.json b/v1/specification/json-schemas/gdd/object.json
index d0c6c21..b211f61 100644
--- a/v1/specification/json-schemas/gdd/object.json
+++ b/v1/specification/json-schemas/gdd/object.json
@@ -19,6 +19,10 @@
     },
     "gddOptions": {
       "type": "object"
+    },
+    "order": {
+      "type": "number",
+      "description": "For UI ordering, lower values should be displayed first"
     }
   },
   "required": ["type"],