feat(spec): driveItem creation under drives/items/children + recursive paths

api/openapi-spec/v1.0.yaml

@@ -468,10 +468,23 @@ paths:
     post:
       tags:
         - drives.root
-      summary: Create a drive item
+      summary: Create a new DriveItem at the drive root
       operationId: CreateDriveItem
       description: |
-        You can use the root childrens endpoint to mount a remoteItem in the share jail. The `@client.synchronize` property of the `driveItem` in the [sharedWithMe](#/me.drive/ListSharedWithMe) endpoint will change to true.
+        Create a new folder or DriveItem in a Drive with the drive root as the parent.
+
+        Modeled on the MS Graph create driveItem endpoint
+        (https://learn.microsoft.com/en-us/graph/api/driveitem-post-children).
+
+        The request body must specify exactly one of `folder` (set to `{}` to create a folder), `file` (to create a file item), or `remoteItem` (to mount a shared item; see [sharedWithMe](#/me.drive/ListSharedWithMe) for obtaining the source `remoteItem.id`). Requests with none of these, or with more than one, return 400. Mounting a share changes the `@client.synchronize` property of the `driveItem` in [sharedWithMe](#/me.drive/ListSharedWithMe) to true.
+
+        The `@libre.graph.conflictBehavior` query parameter controls what happens if a child with the same name already exists.
+
+        This endpoint also accepts the MS Graph colon-syntax URL form:
+
+            POST /v1beta1/drives/{drive-id}/root:/{path}:/children
+
+        OpenAPI cannot express the colon-delimited path segment, so this URL form is not represented as a separate operation in this specification. The server still accepts it, resolves `:/{path}:` as the parent of the new item, and applies `@libre.graph.missingParentsBehavior` to decide whether to create missing intermediate folders.
       parameters:
         - name: drive-id
           in: path
@@ -481,13 +494,41 @@ paths:
             type: string
           example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668
           x-ms-docs-key-type: drive
+        - name: '@libre.graph.conflictBehavior'
+          in: query
+          description: |
+            Controls what happens when a child with the same name already exists. `fail` (default) returns 409; `replace` overwrites the existing item. MS Graph's `rename` value is not supported.
+          schema:
+            type: string
+            enum:
+              - fail
+              - replace
+            default: fail
+        - name: '@libre.graph.missingParentsBehavior'
+          in: query
+          description: |
+            Controls what happens when a colon-syntax URL refers to a path whose intermediate folders don't all exist yet. `fail` (default) returns 404; `create` creates the missing intermediate folders before creating the final item. Only meaningful for colon-syntax URLs; ignored otherwise.
+          schema:
+            type: string
+            enum:
+              - fail
+              - create
+            default: fail
       requestBody:
-        description: In the request body, provide a JSON object with the following parameters. For mounting a share the necessary remoteItem id and permission id can be taken from the [sharedWithMe](#/me.drive/ListSharedWithMe) endpoint.
+        description: In the request body, provide a JSON object describing the new driveItem. Must specify exactly one of `folder`, `file`, or `remoteItem`. For mount-share, see [sharedWithMe](#/me.drive/ListSharedWithMe) for obtaining the source `remoteItem.id` and `permission` id.
         content:
           application/json:
             schema:
               $ref: '#/components/schemas/driveItem'
             examples:
+              create a folder:
+                value:
+                  name: Project Reports
+                  folder: {}
+              create a file:
+                value:
+                  name: notes.txt
+                  file: {}
               mount a shared remoteId:
                 value:
                   name: Einsteins project share
@@ -1310,6 +1351,88 @@ paths:
         default:
           $ref: '#/components/responses/error'
       x-ms-docs-operation-type: operation
+  '/v1beta1/drives/{drive-id}/items/{item-id}/children':
+    post:
+      tags:
+        - driveItem
+      summary: Create a new DriveItem under a parent item
+      operationId: CreateChildDriveItem
+      description: |
+        Create a new folder or DriveItem in a Drive with the specified parent item. The parent must exist and be a folder.
+
+        Modeled on the MS Graph create driveItem endpoint
+        (https://learn.microsoft.com/en-us/graph/api/driveitem-post-children).
+        Identical request and response shape to the [drive-root variant](#/drives.root/CreateDriveItem), just with an explicit parent item id rather than the drive root.
+
+        The request body must specify exactly one of `folder` (set to `{}` to create a folder) or `file` (to create a file item). Requests with none of these, or with both, return 400. The `@libre.graph.conflictBehavior` query parameter controls what happens if a child with the same name already exists.
+
+        This endpoint also accepts the MS Graph colon-syntax URL form:
+
+            POST /v1beta1/drives/{drive-id}/items/{item-id}:/{path}:/children
+
+        OpenAPI cannot express the colon-delimited path segment, so this URL form is not represented as a separate operation in this specification. The server still accepts it, resolves `:/{path}:` as the parent of the new item (relative to `item-id`), and applies `@libre.graph.missingParentsBehavior` to decide whether to create missing intermediate folders.
+      parameters:
+        - name: drive-id
+          in: path
+          description: 'key: id of drive'
+          required: true
+          schema:
+            type: string
+          example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668
+          x-ms-docs-key-type: drive
+        - name: item-id
+          in: path
+          description: 'key: id of item'
+          required: true
+          schema:
+            type: string
+          example: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!share-id
+          x-ms-docs-key-type: item
+        - name: '@libre.graph.conflictBehavior'
+          in: query
+          description: |
+            Controls what happens when a child with the same name already exists. `fail` (default) returns 409; `replace` overwrites the existing item. MS Graph's `rename` value is not supported.
+          schema:
+            type: string
+            enum:
+              - fail
+              - replace
+            default: fail
+        - name: '@libre.graph.missingParentsBehavior'
+          in: query
+          description: |
+            Controls what happens when a colon-syntax URL refers to a path whose intermediate folders don't all exist yet. `fail` (default) returns 404; `create` creates the missing intermediate folders before creating the final item. Only meaningful for colon-syntax URLs; ignored otherwise.
+          schema:
+            type: string
+            enum:
+              - fail
+              - create
+            default: fail
+      requestBody:
+        description: In the request body, provide a JSON object describing the new driveItem. Must specify exactly one of `folder` or `file`.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/driveItem'
+      responses:
+        '200':
+          description: The created DriveItem.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/driveItem'
+        '400':
+          $ref: '#/components/responses/error'
+        '403':
+          $ref: '#/components/responses/error'
+        '404':
+          $ref: '#/components/responses/error'
+        '409':
+          $ref: '#/components/responses/error'
+        default:
+          $ref: '#/components/responses/error'
+      x-ms-docs-operation-type: operation
   '/v1beta1/drives/{drive-id}/items/{item-id}/content':
     get:
       tags: