[#40642] fixed API spec merging issue with collection links

- https://community.openproject.org/work_packages/40642
- introduced new model `offset_paginated_collection`
- improved `_links` definition of projects and principals collection

docs/api/apiv3/components/schemas/collection_links.yml

@@ -0,0 +1,13 @@
+# Schema: CollectionLinks
+---
+type: object
+required:
+  - self
+properties:
+  self:
+    allOf:
+      - $ref: './link.yml'
+      - description: |-
+          This collection resource.
+          
+          **Resource**: Collection

docs/api/apiv3/components/schemas/collection_model.yml

@@ -20,14 +20,4 @@ properties:
     description: Actual amount of elements in this response.
     minimum: 0
   _links:
-    type: object
-    required:
-      - self
-    properties:
-      self:
-        allOf:
-          - $ref: './link.yml'
-          - description: |-
-              This collection resource.
-              
-              **Resource**: Collection
+    $ref: './collection_links.yml'

docs/api/apiv3/components/schemas/offset_paginated_collection_links.yml

@@ -0,0 +1,33 @@
+# Schema: OffsetPaginatedCollectionLinks
+---
+allOf:
+  - $ref: './collection_links.yml'
+  - type: object
+    required:
+      - jumpTo
+      - changeSize
+    properties:
+      jumpTo:
+        allOf:
+          - $ref: './link.yml'
+          - description: A templated link to jump to a given offset.
+      changeSize:
+        allOf:
+          - $ref: './link.yml'
+          - description: A templated link to change the current page size.
+      previousByOffset:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              A link to the previous page of the collection.
+              
+              # Conditions
+              - The collection is not on the first page.
+      nextByOffset:
+        allOf:
+          - $ref: './link.yml'
+          - description: |-
+              A link to the next page of the collection.
+              
+              # Conditions
+              - The collection is not on the last page.

docs/api/apiv3/components/schemas/offset_paginated_collection_model.yml

@@ -0,0 +1,22 @@
+# Schema: OffsetPaginatedCollectionModel
+---
+allOf:
+  - $ref: './collection_model.yml'
+  - type: object
+    required:
+      - pageSize
+      - offset
+      - _links
+    properties:
+      pageSize:
+        type: integer
+        description: |-
+          The amount of elements per page. If not set by the request this value defaults to the server's system
+          settings.
+        minimum: 0
+      offset:
+        type: integer
+        description: The page offset indicating on which page the element collection starts.
+        minimum: 0
+      _links:
+        $ref: './offset_paginated_collection_links.yml'

docs/api/apiv3/components/schemas/principal_collection_model.yml

@@ -1,25 +1,11 @@
 # Schema: PrincipalCollectionModel
 ---
 allOf:
-  - $ref: './collection_model.yml'
+  - $ref: './offset_paginated_collection_model.yml'
   - type: object
     required:
-      - _links
       - _embedded
     properties:
-      _links:
-        type: object
-        required:
-          - self
-          - representations
-        properties:
-          self:
-            allOf:
-              - $ref: "./link.yml"
-              - description: |-
-                  This principal collection
-                  
-                  **Resource**: Collection
       _embedded:
         type: object
         required:

docs/api/apiv3/components/schemas/project_collection_model.yml

@@ -1,32 +1,24 @@
 # Schema: ProjectCollectionModel
 ---
 allOf:
-  - $ref: './collection_model.yml'
+  - $ref: './offset_paginated_collection_model.yml'
   - type: object
     required:
       - _links
       - _embedded
     properties:
       _links:
-        type: object
-        required:
-          - self
-          - representations
-        properties:
-          self:
-            allOf:
-              - $ref: './link.yml'
-              - description: |-
-                  This project collection
-                  
-                  **Resource**: ProjectStorageCollectionModel
-          representations:
-            type: array
-            items:
-              allOf:
-                - $ref: './link.yml'
-                - description: |-
-                    A project collection representation in a specific file format.
+        allOf:
+          - $ref: './offset_paginated_collection_links.yml'
+          - type: object
+            properties:
+              representations:
+                type: array
+                items:
+                  allOf:
+                    - $ref: './link.yml'
+                    - description: |-
+                        A project collection representation in a specific file format.
       _embedded:
         type: object
         required:

docs/api/apiv3/openapi-spec.yml

@@ -607,6 +607,8 @@ components:
       "$ref": "./components/schemas/categories_by_project_model.yml"
     CategoryModel:
       "$ref": "./components/schemas/category_model.yml"
+    CollectionLinks:
+      "$ref": "./components/schemas/collection_links.yml"
     CollectionModel:
       "$ref": "./components/schemas/collection_model.yml"
     ConfigurationModel:
@@ -707,6 +709,10 @@ components:
       "$ref": "./components/schemas/oauth_client_credentials_read_model.yml"
     OAuthClientCredentialsWriteModel:
       "$ref": "./components/schemas/oauth_client_credentials_write_model.yml"
+    OffsetPaginatedCollectionLinks:
+      "$ref": "./components/schemas/offset_paginated_collection_links.yml"
+    OffsetPaginatedCollectionModel:
+      "$ref": "./components/schemas/offset_paginated_collection_model.yml"
     PaginatedCollectionModel:
       "$ref": "./components/schemas/paginated_collection_model.yml"
     PlaceholderUserCollectionModel: