From e06dc22d13d14f09c1dac1d6f9daf0c970e4294e Mon Sep 17 00:00:00 2001 From: Dominik Schmidt Date: Mon, 11 May 2026 16:05:46 +0200 Subject: [PATCH 1/2] feat(spec): generalize driveItem creation under drives/items/children Broaden /v1beta1/drives/{drive-id}/root/children to describe the general MS Graph create-driveItem semantics (folder/file/remoteItem) rather than only share-mounting, and add a sibling /v1beta1/drives/{drive-id}/items/{item-id}/children POST (operationId: CreateChildDriveItem) for creation under a non-root parent. Both endpoints accept a @libre.graph.conflictBehavior query parameter (enum fail|replace, default fail) controlling same-name child collisions, matching the MS Graph convention of passing conflict behavior in the URL rather than the body. MS Graph's third value 'rename' is intentionally omitted from this enum. --- api/openapi-spec/v1.0.yaml | 97 ++++++++++++++++++++++++++++++++++++-- 1 file changed, 94 insertions(+), 3 deletions(-) diff --git a/api/openapi-spec/v1.0.yaml b/api/openapi-spec/v1.0.yaml index 534c09e..bd550ed 100644 --- a/api/openapi-spec/v1.0.yaml +++ b/api/openapi-spec/v1.0.yaml @@ -468,10 +468,17 @@ 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. parameters: - name: drive-id in: path @@ -481,13 +488,31 @@ 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 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 +1335,72 @@ 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. + 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 + 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: From 6f128411056d73fd13c3d02576ebbf3c7b1ffcd4 Mon Sep 17 00:00:00 2001 From: Dominik Schmidt Date: Mon, 11 May 2026 16:10:26 +0200 Subject: [PATCH 2/2] feat(spec): support recursive path creation and colon-syntax URLs Document the MS Graph colon-syntax URL forms POST /v1beta1/drives/{drive-id}/root:/{path}:/children POST /v1beta1/drives/{drive-id}/items/{item-id}:/{path}:/children on both create-item operations. OpenAPI cannot express the colon-delimited path segment, so the URL forms aren't represented as separate operations, but the description makes clear the server accepts them. Add a @libre.graph.missingParentsBehavior query parameter (enum fail|create, default fail) controlling recursive creation of missing intermediate folders along a colon-syntax path. Libregraph extension; ignored for non-colon URLs. --- api/openapi-spec/v1.0.yaml | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/api/openapi-spec/v1.0.yaml b/api/openapi-spec/v1.0.yaml index bd550ed..a883d6f 100644 --- a/api/openapi-spec/v1.0.yaml +++ b/api/openapi-spec/v1.0.yaml @@ -479,6 +479,12 @@ paths: 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 @@ -498,6 +504,16 @@ paths: - 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`, `file`, or `remoteItem`. For mount-share, see [sharedWithMe](#/me.drive/ListSharedWithMe) for obtaining the source `remoteItem.id` and `permission` id. content: @@ -1349,6 +1365,12 @@ paths: 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 @@ -1376,6 +1398,16 @@ paths: - 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