From 8e92a0ba52a98119ca7ea4497ddca1c771ec38b7 Mon Sep 17 00:00:00 2001
From: Jan Sandbrink <j.sandbrink@openproject.com>
Date: Wed, 10 Dec 2025 16:47:14 +0100
Subject: [PATCH] Improve formatting of schema

In YAML, null is interpreted as a literal null value,
but we intended to use it as the string "null".

For consistency the first element of the array was also formatted
in double quotes and the array is now also formatted across
multiple lines.
---
 .../components/schemas/attachment_model.yml   | 10 +++----
 .../apiv3/components/schemas/status_model.yml |  4 ++-
 .../apiv3/components/schemas/user_model.yml   |  4 ++-
 .../components/schemas/version_model.yml      |  8 ++++--
 .../components/schemas/work_package_model.yml | 28 ++++++++++++++-----
 5 files changed, 38 insertions(+), 16 deletions(-)

diff --git a/docs/api/apiv3/components/schemas/attachment_model.yml b/docs/api/apiv3/components/schemas/attachment_model.yml
index abb6d7f367b..b4bbf06498b 100644
--- a/docs/api/apiv3/components/schemas/attachment_model.yml
+++ b/docs/api/apiv3/components/schemas/attachment_model.yml
@@ -27,11 +27,11 @@ properties:
   status:
     type: string
     enum:
-    - uploaded
-    - prepared
-    - scanned
-    - quarantined
-    - rescan
+      - uploaded
+      - prepared
+      - scanned
+      - quarantined
+      - rescan
   contentType:
     type: string
     description: The files MIME-Type as determined by the server
diff --git a/docs/api/apiv3/components/schemas/status_model.yml b/docs/api/apiv3/components/schemas/status_model.yml
index 597896088bd..63c6c3d3553 100644
--- a/docs/api/apiv3/components/schemas/status_model.yml
+++ b/docs/api/apiv3/components/schemas/status_model.yml
@@ -17,7 +17,9 @@ properties:
     type: boolean
     description: Indicates, whether work package of this status are considered closed
   color:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: hex-code
     description: The color of the status
   isDefault:
diff --git a/docs/api/apiv3/components/schemas/user_model.yml b/docs/api/apiv3/components/schemas/user_model.yml
index 73f8640d270..99fe2cefac2 100644
--- a/docs/api/apiv3/components/schemas/user_model.yml
+++ b/docs/api/apiv3/components/schemas/user_model.yml
@@ -12,7 +12,9 @@ allOf:
         enum:
           - User
       avatar:
-        type: [string, null]
+        type:
+          - "string"
+          - "null"
         format: uri
         description: URL to user's avatar
       login:
diff --git a/docs/api/apiv3/components/schemas/version_model.yml b/docs/api/apiv3/components/schemas/version_model.yml
index 2ebbae7810a..6bff4982fa5 100644
--- a/docs/api/apiv3/components/schemas/version_model.yml
+++ b/docs/api/apiv3/components/schemas/version_model.yml
@@ -21,10 +21,14 @@ properties:
     - "$ref": "./formattable.yml"
     - {}
   startDate:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: date
   endDate:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: date
   status:
     type: string
diff --git a/docs/api/apiv3/components/schemas/work_package_model.yml b/docs/api/apiv3/components/schemas/work_package_model.yml
index 65ea7559c39..e2f9719f842 100644
--- a/docs/api/apiv3/components/schemas/work_package_model.yml
+++ b/docs/api/apiv3/components/schemas/work_package_model.yml
@@ -36,15 +36,21 @@ properties:
     type: boolean
     description: If true, the work package is in a readonly status so with the exception of the status, no other property can be altered.
   startDate:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: date
     description: Scheduled beginning of a work package
   dueDate:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: date
     description: Scheduled end of a work package
   date:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: date
     description: Date on which a milestone is achieved
   derivedStartDate:
@@ -62,18 +68,24 @@ properties:
       two dates can deviate.
     readOnly: true
   duration:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: duration
     description: |-
       **(NOT IMPLEMENTED)** The amount of time in hours the work package needs to be completed.
       Not available for milestone type of work packages.
     readOnly: true
   estimatedTime:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: duration
     description: Time a work package likely needs to be completed excluding its descendants
   derivedEstimatedTime:
-    type: [string, null]
+    type:
+      - "string"
+      - "null"
     format: duration
     description: Time a work package likely needs to be completed including its descendants
     readOnly: true
@@ -99,7 +111,9 @@ properties:
     minimum: 0
     maximum: 100
   derivedPercentageDone:
-    type: [integer, null]
+    type:
+      - "integer"
+      - "null"
     description: Amount of total completion for a work package derived from itself and its descendant work packages
     readOnly: true
     minimum: 0