openapi: 3.0.1

info:

title: Libre Graph API

description: Libre Graph is a free API for cloud collaboration inspired by the MS Graph API.

version: v1.0.4

license:

name: Apache 2.0

url: https://www.apache.org/licenses/LICENSE-2.0.html

servers:

- url: https://ocis.ocis.rolling.owncloud.works/graph

description: ownCloud Infinite Scale Rolling Release

- url: https://localhost:9200/graph

description: ownCloud Infinite Scale Development Setup

# commented for now because it is unrelated to the PR but allows describing and linking to external docs

# tags:

# - name: roleManagement

# description: Manage roles and permissions

# externalDocs:

# url: https://owncloud.dev/ocis/roles-and-permissions

paths:

'/v1.0/me':

patch:

tags:

- me.user

summary: Update the current user

operationId: UpdateOwnUser

requestBody:

description: New user values

content:

application/json:

schema:

$ref: '#/components/schemas/userUpdate'

examples:

change preferred language:

value:

preferredLanguage: "en"

responses:

'200':

description: Success

content:

application/json:

schema:

$ref: '#/components/schemas/user'

default:

$ref: '#/components/responses/error'

get:

tags:

- me.user

summary: Get current user

operationId: GetOwnUser

parameters:

- name: $expand

in: query

description: Expand related entities

style: form

explode: false

schema:

uniqueItems: true

type: array

items:

enum:

- memberOf

type: string

responses:

'200':

description: Retrieved entity

content:

application/json:

schema:

$ref: '#/components/schemas/user'

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

/v1.0/me/changePassword:

post:

tags:

- me.changepassword

summary: Change your own password

operationId: ChangeOwnPassword

requestBody:

description: Password change request

content:

application/json:

schema:

title: Password change

type: object

required:

- currentPassword

- newPassword

properties:

currentPassword:

type: string

newPassword:

type: string

required: true

responses:

'204':

description: Success

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

'/v1beta1/extensions/org.libregraph/activities':

get:

tags:

- activities

summary: Get activities

operationId: GetActivities

parameters:

- in: query

name: kql

schema:

type: string

example: resourceid:a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668 depth:2

responses:

'200':

description: Found activities

content:

application/json:

schema:

title: Collection of activities

type: object

properties:

value:

type: array

items:

$ref: '#/components/schemas/activity'

examples:

item activities:

value:

- id: "34646ab6-be32-43c9-89e6-987e0c237e9b"

times:

recordedTime: "2023-09-14T12:27:15"

template:

message: "{user} shared {resource}"

variables:

user:

id: "4c510ada-c86b-4815-8820-42cdf82c3d51"

displayName: "Albert Einstein"

resource:

id: "7f92b0a9-06ad-49dc-890f-0e0a6eb4dea6$e9f01ca3-577f-4d1d-acd4-1cc44149ac25!5fb9f87c-a317-467b-9882-eb9f171564ac"

name: "secret stuff"

default:

$ref: '#/components/responses/error'

'/v1beta1/me/drives':

# $ref is buggy in the openapi-generator v7.0.1

# $ref: '#/paths/~1v1.0~1me~1drives'

get:

tags:

- me.drives

summary: Alias for '/v1.0/drives', the difference is that grantedtoV2 is used and roles contain unified roles instead of cs3 roles

operationId: ListMyDrivesBeta

parameters:

- $ref: '#/components/parameters/orderby'

- $ref: '#/components/parameters/drivesFilter'

responses:

'200':

description: Retrieved spaces

content:

application/json:

schema:

title: Collection of drives

type: object

properties:

value:

type: array

items:

$ref: '#/components/schemas/drive'

maxItems: 100

'@odata.nextLink':

type: string

links:

root:

operationId: HomeGetRoot

default:

$ref: '#/components/responses/error'

x-ms-pageable:

nextLinkName: '@odata.nextLink'

operationName: listMore

x-ms-docs-operation-type: operation

/v1.0/me/drives:

get:

tags:

- me.drives

summary: Get all drives where the current user is a regular member of

operationId: ListMyDrives

parameters:

- $ref: '#/components/parameters/orderby'

- $ref: '#/components/parameters/drivesFilter'

responses:

'200':

description: Retrieved spaces

content:

application/json:

schema:

title: Collection of drives

type: object

properties:

value:

type: array

items:

$ref: '#/components/schemas/drive'

maxItems: 100

'@odata.nextLink':

type: string

links:

root:

operationId: HomeGetRoot

default:

$ref: '#/components/responses/error'

x-ms-pageable:

nextLinkName: '@odata.nextLink'

operationName: listMore

x-ms-docs-operation-type: operation

'/v1beta1/drives':

# $ref is buggy in the openapi-generator v7.0.1

# $ref: '#/paths/~1v1.0~1drives'

get:

tags:

- drives.GetDrives

summary: Alias for '/v1.0/drives', the difference is that grantedtoV2 is used and roles contain unified roles instead of cs3 roles

operationId: ListAllDrivesBeta

parameters:

- $ref: '#/components/parameters/orderby'

- $ref: '#/components/parameters/drivesFilter'

responses:

'200':

description: Retrieved spaces

content:

application/json:

schema:

title: Collection of drives

type: object

properties:

value:

type: array

items:

$ref: '#/components/schemas/drive'

links:

root:

operationId: GetRoot

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

post:

tags:

- drives

summary: Create a new drive of a specific type. Alias for '/v1.0/drives', the difference is that grantedtoV2 is used and roles contain unified roles instead of cs3 roles.

operationId: CreateDriveBeta

requestBody:

description: New space property values

content:

application/json:

schema:

$ref: '#/components/schemas/drive'

examples:

multiple values:

value:

name: Mars

quota:

total: 1000000000

description: Team space mars project

minimal:

value:

name: Venus

required: true

responses:

'201':

description: Created

content:

application/json:

schema:

$ref: '#/components/schemas/drive'

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

'/v1beta1/drives/{drive-id}':

get:

tags:

- drives

summary: Get drive by id. Alias for '/v1.0/drives', the difference is that grantedtoV2 is used and roles contain unified roles instead of cs3 roles

operationId: GetDriveBeta

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

responses:

'200':

description: Retrieved drive

content:

application/json:

schema:

$ref: '#/components/schemas/drive'

links:

root:

operationId: GetRoot

parameters:

drive-id: $request.path.drive-id

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

patch:

tags:

- drives

summary: Update the drive. Alias for '/v1.0/drives', the difference is that grantedtoV2 is used and roles contain unified roles instead of cs3 roles

operationId: UpdateDriveBeta

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

requestBody:

description: New space values

content:

application/json:

schema:

$ref: '#/components/schemas/driveUpdate'

examples:

change quota:

value:

quota:

total: 1000000000

change name:

value:

name: Physics

change description:

value:

description: Marketing team collaboration area

change drive image:

value:

special:

id: 408f26e3-d6d8-4aa4-bd5c-3fd6f5032b51$aba2bafc-e1a0-421e-a37a-9acf5f655f83!14fd3432-e8d9-42a7-9446-2e3fd621afca

specialFolder:

name: image

change drive readme:

value:

special:

id: 408f26e3-d6d8-4aa4-bd5c-3fd6f5032b51$aba2bafc-e1a0-421e-a37a-9acf5f655f83!14fd3432-e8d9-42a7-9446-2e3fd621afca

specialFolder:

name: readme

required: true

responses:

'200':

description: Success

content:

application/json:

schema:

$ref: '#/components/schemas/drive'

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

delete:

tags:

- drives

summary: Delete a specific space. Alias for '/v1.0/drives'.

operationId: DeleteDriveBeta

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

- name: If-Match

in: header

description: ETag

schema:

type: string

responses:

'204':

description: Success

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

'/v1.0/drives':

get:

tags:

- drives.GetDrives

summary: Get all available drives

operationId: ListAllDrives

parameters:

- $ref: '#/components/parameters/orderby'

- $ref: '#/components/parameters/drivesFilter'

responses:

'200':

description: Retrieved spaces

content:

application/json:

schema:

title: Collection of drives

type: object

properties:

value:

type: array

items:

$ref: '#/components/schemas/drive'

links:

root:

operationId: GetRoot

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

post:

tags:

- drives

summary: Create a new drive of a specific type

operationId: CreateDrive

requestBody:

description: New space property values

content:

application/json:

schema:

$ref: '#/components/schemas/drive'

examples:

multiple values:

value:

name: Mars

quota:

total: 1000000000

description: Team space mars project

minimal:

value:

name: Venus

required: true

responses:

'201':

description: Created

content:

application/json:

schema:

$ref: '#/components/schemas/drive'

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

'/v1.0/drives/{drive-id}':

get:

tags:

- drives

summary: Get drive by id

operationId: GetDrive

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

responses:

'200':

description: Retrieved drive

content:

application/json:

schema:

$ref: '#/components/schemas/drive'

links:

root:

operationId: GetRoot

parameters:

drive-id: $request.path.drive-id

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

patch:

tags:

- drives

summary: Update the drive

operationId: UpdateDrive

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

requestBody:

description: New space values

content:

application/json:

schema:

$ref: '#/components/schemas/driveUpdate'

examples:

change quota:

value:

quota:

total: 1000000000

change name:

value:

name: Physics

change description:

value:

description: Marketing team collaboration area

change drive image:

value:

special:

id: 408f26e3-d6d8-4aa4-bd5c-3fd6f5032b51$aba2bafc-e1a0-421e-a37a-9acf5f655f83!14fd3432-e8d9-42a7-9446-2e3fd621afca

specialFolder:

name: image

change drive readme:

value:

special:

id: 408f26e3-d6d8-4aa4-bd5c-3fd6f5032b51$aba2bafc-e1a0-421e-a37a-9acf5f655f83!14fd3432-e8d9-42a7-9446-2e3fd621afca

specialFolder:

name: readme

required: true

responses:

'200':

description: Success

content:

application/json:

schema:

$ref: '#/components/schemas/drive'

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

delete:

tags:

- drives

summary: Delete a specific space

operationId: DeleteDrive

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

- name: If-Match

in: header

description: ETag

schema:

type: string

responses:

'204':

description: Success

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

'/v1beta1/drives/{drive-id}/root/children':

post:

tags:

- drives.root

summary: Create a drive item

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.

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

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.

content:

application/json:

schema:

$ref: '#/components/schemas/driveItem'

examples:

mount a shared remoteId:

value:

name: Einsteins project share

remoteItem:

id: a-storage-provider-id$a-space-id!a-node-id

responses:

'200':

description: Response

content:

application/json:

schema:

$ref: '#/components/schemas/driveItem'

example:

name: Einsteins project share

id: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!share-id

remoteItem:

id: a-storage-provider-id$a-space-id!a-node-id

name: Project

parentReference:

driveID: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668

id: a0ca6a90-a365-4782-871e-d44447bbc668$a0ca6a90-a365-4782-871e-d44447bbc668!a0ca6a90-a365-4782-871e-d44447bbc668

default:

$ref: '#/components/responses/error'

x-ms-docs-operation-type: operation

'/v1beta1/drives/{drive-id}/root/createLink':

post:

tags:

- drives.root

summary: Create a sharing link for the root item of a Drive

operationId: CreateLinkSpaceRoot

description: |

You can use the createLink action to share a driveItem via a sharing link.

The response will be a permission object with the link facet containing the created link details.

## Link types

For now, The following values are allowed for the type parameter.

| Value | Display name | Description |

| -------------- | ----------------- | --------------------------------------------------------------- |

| view | View | Creates a read-only link to the driveItem. |

| upload | Upload | Creates a read-write link to the folder driveItem. |

| edit | Edit | Creates a read-write link to the driveItem. |

| createOnly | File Drop | Creates an upload-only link to the folder driveItem. |

| blocksDownload | Secure View | Creates a read-only link that blocks download to the driveItem. |

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

requestBody:

description: In the request body, provide a JSON object with the following parameters.

content:

application/json:

schema:

$ref: '#/components/schemas/driveItemCreateLink'

examples:

create viewer link:

value:

type: "view"

create editor link with custom display name:

value:

type: "edit"

displayName: "Homework"

create editor link with expiry:

value:

type: "edit"

expirationDateTime: "2018-07-15T14:00:00.000Z"

responses:

'200':

description: Response

content:

application/json:

schema:

$ref: '#/components/schemas/permission'

examples:

create viewer link:

value:

- id: "7181275c-557e-4adf-8e44-abdcf5389b6a"

link:

type: "view"

webUrl: "https://cloud.example.org/s/YlaySZdHCRHUDeE"

create editor link with custom display name:

value:

- id: "7181275c-557e-4adf-8e44-abdcf5389b6a"

link:

type: "edit"

displayName: "Homework"

webUrl: "https://cloud.example.org/s/fdleMyGeerkIZTJ"

create editor link with expiry:

value:

- id: "a373c812-d786-42ae-a65f-ed87ee4abd49"

link:

type: "edit"

webUrl: "https://cloud.example.org/s/MlnTDkhcBlihNzO"

'207':

# FIXME describe partial success response

description: Partial success response TODO

default:

$ref: '#/components/responses/error'

# TODO add SendNotification errors as per https://learn.microsoft.com/en-us/graph/api/driveitem-invite?view=graph-rest-beta&tabs=http#sendnotification-errors

x-ms-docs-operation-type: operation

'/v1beta1/drives/{drive-id}/root/invite':

post:

tags:

- drives.root

summary: Send a sharing invitation

operationId: InviteSpaceRoot

description: |

Sends a sharing invitation for the root of a `drive`. A sharing invitation provides permissions to the

recipients and optionally sends them an email with a sharing link.

The response will be a permission object with the grantedToV2 property containing the created grant details.

## Roles property values

For now, roles are only identified by a uuid. There are no hardcoded aliases like `read` or `write` because role actions can be completely customized.

# FIXME we should add isBuiltIn and isEnabled to unifiedRoleDefinition so we can use speaking role ids in examples and establish a well defined set of roles.

# By throwing around only uuids we increase the risk of someone choosing an ambiguous or misleading displayname. We will have to define a set of default

# sharing permissions. For those we should use speaking ids.

#

# For now, the following roles are considered built in:

#

# | Role | Value | Description |

# | ------- | ------- | --------------------------------------------------------------------------------------------------------------------- |

# | Viewer | `read` | Provides the ability to read the metadata and contents of the item. |

# | Editor | `write` | Provides the ability to read and modify the metadata and contents of the item. |

# | Manager | `owner` | For project drives this represents the Manager role to mimic ms graph |

#

# More built in roles will be added with a speaking value but clients **MUST** treat the value as an

# opaque identifier as custom roles will be using UUIDs.

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

requestBody:

description: In the request body, provide a JSON object with the following parameters. To create a custom role submit a list of actions instead of roles.

content:

application/json:

schema:

$ref: '#/components/schemas/driveItemInvite'

examples:

send viewer invite:

value:

recipients:

- '@libre.graph.recipient.type': user

objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51"

roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]

send viewer invite to multiple recipients:

value:

recipients:

- '@libre.graph.recipient.type': user

objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51"

- '@libre.graph.recipient.type': user

objectId: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c"

roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]

send editor invite with expiry:

value:

recipients:

- '@libre.graph.recipient.type': user

objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51"

roles: [ "fb6c3e19-e378-47e5-b277-9732f9de6e21" ]

expirationDateTime: "2018-07-15T14:00:00.000Z"

send manager invite to group:

description: "Sharing with a groups requires setting the @libre.graph.recipient.type annotation."

value:

recipients:

- '@libre.graph.recipient.type': group

objectId: "167cbee2-0518-455a-bfb2-031fe0621e5d"

roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ]

send invite to user granting custom actions:

description: "A Custom role is just a collection of actions, in this case allowing the user to stat and move driveItems"

value:

recipients:

- objectId: "4c510ada-c86b-4815-8820-42cdf82c3d51"

'@libre.graph.permissions.actions': [ "libre.graph/driveItem/basic/read", "libre.graph/driveItem/path/update" ]

responses:

'200':

description: Response

content:

application/json:

schema:

title: Collection of permissions

type: object

properties:

value:

type: array

items:

$ref: '#/components/schemas/permission'

examples:

send viewer invite:

value:

- id: "34646ab6-be32-43c9-89e6-987e0c237e9b"

roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]

grantedToV2:

- user:

id: "4c510ada-c86b-4815-8820-42cdf82c3d51"

displayName: "Albert Einstein"

send viewer invite to multiple recipients:

description: multiple permissions are returned as each has received a dedicated sharing id

value:

- id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474"

roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]

grantedToV2:

- user:

id: "4c510ada-c86b-4815-8820-42cdf82c3d51"

displayName: "Albert Einstein"

- id: "b470677e-a7f5-4304-8ef5-f5056a21fff1"

roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]

grantedToV2:

- user:

id: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c"

displayName: "Marie Skłodowska Curie"

send editor invite with expiry:

value:

- id: "453b02be-4ec2-4e7d-b576-09fc153de812"

roles: [ "fb6c3e19-e378-47e5-b277-9732f9de6e21" ]

grantedToV2:

- user:

id: "4c510ada-c86b-4815-8820-42cdf82c3d51"

displayName: "Albert Einstein"

expirationDateTime: "2018-07-15T14:00:00.000Z"

send manager invite to group:

value:

- id: "86765c0d-3905-444a-9b07-76201f8cf7df"

roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ]

grantedToV2:

- group:

id: "167cbee2-0518-455a-bfb2-031fe0621e5d"

displayName: "Philosophy Haters"

send invite to user granting custom actions:

value:

- id: "c42b5cbd-2d65-42cf-b0b6-fb6d2b762256"

grantedToV2:

- user:

id: "4c510ada-c86b-4815-8820-42cdf82c3d51"

displayName: "Albert Einstein"

'@libre.graph.permissions.actions': [ "libre.graph/driveItem/basic/read", "libre.graph/driveItem/path/update" ]

'207':

# FIXME describe partial success response

description: Partial success response TODO

'400':

description: Bad request

content:

application/json:

schema:

$ref: '#/components/schemas/odata.error'

examples:

secureSharingInvalidRequest:

description: If the recipient was given via email, but does not belong to a known user account.

value:

- error:

- code: invalidRequest

message: Some users in the request cannot be invited securely.

innerError:

- code: secureSharingInvalidRequest

date: "2023-09-14T12:27:15"

request-id: b49f582d-9a0f-4731-ab0c-b9e50246ef58

client-request-id: 832c7206-1a40-395c-e0d9-e85649b8b0b0

default:

$ref: '#/components/responses/error'

# TODO add SendNotification errors as per https://learn.microsoft.com/en-us/graph/api/driveitem-invite?view=graph-rest-beta&tabs=http#sendnotification-errors

x-ms-docs-operation-type: operation

'/v1beta1/drives/{drive-id}/root/permissions':

get:

tags:

- drives.root

summary: List the effective permissions on the root item of a drive.

operationId: ListPermissionsSpaceRoot

description: |

The permissions collection includes potentially sensitive information and may not be available for every caller.

* For the owner of the item, all sharing permissions will be returned. This includes co-owners.

* For a non-owner caller, only the sharing permissions that apply to the caller are returned.

* Sharing permission properties that contain secrets (e.g. `webUrl`) are only returned for callers that are able to create the sharing permission.

All permission objects have an `id`. A permission representing

* a link has the `link` facet filled with details.

* a share has the `roles` property set and the `grantedToV2` property filled with the grant recipient details.

# TODO hm, the ms graph api seems to always fill the `roles` property to indicate the actions granted by the link.

# | Value | Display name | Description | role? |

# | -------------- | ----------------- | --------------------------------------------------------------- | -------------- |

# | view | View | Creates a read-only link to the driveItem. | viewer |

# | upload | Upload | Creates a read-write link to the folder driveItem. | uploader |

# | edit | Edit | Creates a read-write link to the driveItem. | editor |

# | createOnly | File Drop | Creates an upload-only link to the folder driveItem. | createOnly |

# | blocksDownload | Secure View | Creates a read-only link that blocks download to the driveItem. | blocksDownload |

# AFAICT we will have to define the actions granted by a link type when we start to implement this

# but e.g. a createOnly role and blocksDownload should not show up in the drop down for sharing files internally ...

# when we need to hardcode this anyway ... we should indicate that by using the buildIn flag ... but how do we prevent some roles from showing up in the internal sharing dialog ...

# for now leave out the roles property and hardcode the actions allowed by the link type

parameters:

- name: drive-id

in: path

description: 'key: id of drive'

required: true

schema:

type: string

x-ms-docs-key-type: drive

- $ref: '#/components/parameters/permissionsFilter'

- $ref: '#/components/parameters/permissionsSelect'

responses:

'200':

description: Retrieved resource

content:

application/json:

schema:

title: Collection of permissions with allowed values

type: object

properties:

'@libre.graph.permissions.roles.allowedValues':

type: array

description: A list of role definitions that can be chosen for the resource.

items:

$ref: '#/components/schemas/unifiedRoleDefinition'

'@libre.graph.permissions.actions.allowedValues':

type: array

description: |

A list of actions that can be chosen for a custom role.

Following the CS3 API we can represent the CS3 permissions by mapping them to driveItem properties or relations like this:

| [CS3 ResourcePermission](https://cs3org.github.io/cs3apis/#cs3.storage.provider.v1beta1.ResourcePermissions) | action | comment |

| ------------------------------------------------------------------------------------------------------------ | ------ | ------- |

| `stat` | `libre.graph/driveItem/basic/read` | `basic` because it does not include versions or trashed items |

| `get_quota` | `libre.graph/driveItem/quota/read` | read only the `quota` property |

| `get_path` | `libre.graph/driveItem/path/read` | read only the `path` property |

| `move` | `libre.graph/driveItem/path/update` | allows updating the `path` property of a CS3 resource |

| `delete` | `libre.graph/driveItem/standard/delete` | `standard` because deleting is a common update operation |

| `list_container` | `libre.graph/driveItem/children/read` | |

| `create_container` | `libre.graph/driveItem/children/create` | |

| `initiate_file_download` | `libre.graph/driveItem/content/read` | `content` is the property read when initiating a download |

| `initiate_file_upload` | `libre.graph/driveItem/upload/create` | `uploads` are a separate property. postprocessing creates the `content` |

| `add_grant` | `libre.graph/driveItem/permissions/create` | |

| `list_grant` | `libre.graph/driveItem/permissions/read` | |

| `update_grant` | `libre.graph/driveItem/permissions/update` | |

| `remove_grant` | `libre.graph/driveItem/permissions/delete` | |

| `deny_grant` | `libre.graph/driveItem/permissions/deny` | uses a non CRUD action `deny` |

| `list_file_versions` | `libre.graph/driveItem/versions/read` | `versions` is a `driveItemVersion` collection |

| `restore_file_version` | `libre.graph/driveItem/versions/update` | the only `update` action is restore |

| `list_recycle` | `libre.graph/driveItem/deleted/read` | reading a driveItem `deleted` property implies listing |

| `restore_recycle_item` | `libre.graph/driveItem/deleted/update` | the only `update` action is restore |

| `purge_recycle` | `libre.graph/driveItem/deleted/delete` | allows purging deleted `driveItems` |

items:

type: string

value:

type: array

items:

$ref: '#/components/schemas/permission'

# maxItems: 100

#'@odata.nextLink':

# type: string

example:

'@libre.graph.permissions.roles.allowedValues':

- id: b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5

description: "Allows reading the shared file or folder"

displayName: Viewer

# we don't want to reproduce all the individual role permissions, that is what the /roleManagement/permissions/roleDefinitions endpoint is for

# to build a custom role

#rolePermissions:

# - allowedResourceActions:

# - libre.graph/driveItem/basic/read

# - libre.graph/driveItem/permissions/read

# - libre.graph/driveItem/upload/create

# condition: "exists @Resource.File"

'@libre.graph.weight': 1

- id: fb6c3e19-e378-47e5-b277-9732f9de6e21

description: "Allows reading and writing the shared file or folder"

displayName: Editor

#rolePermissions:

# - allowedResourceActions:

# - libre.graph/driveItem/standard/allTasks

# condition: "exists @Resource.File"

'@libre.graph.weight': 2

- id: 312c0871-5ef7-4b3a-85b6-0e4074c64049

description: "Allows managing a space"

displayName: Manager

#rolePermissions:

# - allowedResourceActions:

# - libre.graph/drive/standard/allTasks

# condition: "exists @Resource.File"

'@libre.graph.weight': 3

- id: 4916f47e-66d5-49bb-9ac9-748ad00334b

description: "Allows creating new files"

displayName: File Drop

#rolePermissions:

# - allowedResourceActions:

# libre.graph/driveItem/upload/create

# condition: "exists @Resource.File"

'@libre.graph.weight': 4

'@libre.graph.permissions.actions.allowedValues': [

"libre.graph/driveItem/basic/read",

"libre.graph/driveItem/permissions/read",

"libre.graph/driveItem/upload/create",

"libre.graph/driveItem/standard/allTasks",

"libre.graph/driveItem/upload/create"

]

value:

- id: "67445fde-a647-4dd4-b015-fc5dafd2821d"

link:

type: "view"

webUrl: "https://cloud.example.org/s/fhGBMIkKFEHWysj"

- id: "34646ab6-be32-43c9-89e6-987e0c237e9b"

roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]

grantedToV2:

- user:

id: "4c510ada-c86b-4815-8820-42cdf82c3d51"

displayName: "Albert Einstein"

- id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474"

roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]

grantedToV2:

- user:

id: "4c510ada-c86b-4815-8820-42cdf82c3d51"

displayName: "Albert Einstein"

- id: "b470677e-a7f5-4304-8ef5-f5056a21fff1"

roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]

grantedToV2: