v1.0.yaml

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.8
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
servers:
  - url: https://localhost:9200/graph
    description: OpenCloud Development Setup
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
  /v1.0/me/photo/$value:
    get:
      tags:
        - me.photo
      summary: Get the current user's profile photo
      operationId: GetOwnUserPhoto
      responses:
        '200':
          description: Retrieved profile photo
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/error'
    put:
      tags:
        - me.photo
      summary: Update the current user's profile photo
      operationId: UpdateOwnUserPhotoPut
      requestBody:
        description: New user photo
        content:
          image/jpeg:
            schema:
              type: string
              format: binary
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
    patch:
      tags:
        - me.photo
      summary: Update the current user's profile photo
      operationId: UpdateOwnUserPhotoPatch
      requestBody:
        description: New user photo
        content:
          image/jpeg:
            schema:
              type: string
              format: binary
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
    delete:
      tags:
        - me.photo
      summary: Delete the current user's profile photo
      operationId: DeleteOwnUserPhoto
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/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'
        - $ref: '#/components/parameters/drivesExpand'
        - $ref: '#/components/parameters/drivesSelect'
      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'
        - $ref: '#/components/parameters/drivesExpand'
        - $ref: '#/components/parameters/drivesSelect'
      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
  '/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
        - $ref: '#/components/parameters/drivesSelect'
      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'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/top'
      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.count':
                    type: integer
                    description: The total number of permissions available, only present if the `count` query parameter is set to true.
                  #'@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:
                      - user:
                          id: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c"
                          displayName: "Marie Skłodowska Curie"
                  - 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"
                  - id: "86765c0d-3905-444a-9b07-76201f8cf7df"
                    roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ]
                    grantedToV2:
                      - group:
                          id: "167cbee2-0518-455a-bfb2-031fe0621e5d"
                          displayName: "Philosophy Haters"
                  - 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" ]
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1beta1/drives/{drive-id}/root/permissions/{perm-id}':
    get:
      tags:
        - drives.root
      summary: Get a single sharing permission for the root item of a drive
      operationId: GetPermissionSpaceRoot
      description: |
        Return the effective sharing permission for a particular permission resource.

      # TODO do we need to implement inherited permissions from the start?
      #  Effective permissions of an item can come from two sources: permissions set directly on the item itself or permissions that are inherited from the item's ancestors.
      #
      #  Callers can differentiate if the permission is inherited or not by checking the `inheritedFrom` property. This property is an ItemReference resource referencing the ancestor that the permission is inherited from.
      #
      parameters:
        - name: drive-id
          in: path
          description: 'key: id of drive'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: drive
        - name: perm-id
          in: path
          description: 'key: id of permission'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: permission
      responses:
        '200':
          description: Retrieved resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/permission'
              examples:
                edit permission:
                  value:
                    id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474"
                    roles: [ "write" ]
                    grantedToV2:
                      - user:
                          id: "4c510ada-c86b-4815-8820-42cdf82c3d51"
                          displayName: "Albert Einstein"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    patch:
      tags:
        - drives.root
      summary: Update sharing permission
      operationId: UpdatePermissionSpaceRoot
      description: |
        Update the properties of a sharing permission by patching the permission resource.

        Only the `roles`, `expirationDateTime` and `password` properties can be modified this way.
      parameters:
        - name: drive-id
          in: path
          description: 'key: id of drive'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: drive
        - name: perm-id
          in: path
          description: 'key: id of permission'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: permission
        #- name: If-Match
        #  in: header
        #  description: |
        #    If this request header is included and the eTag (or cTag) provided does not match the current tag on the item,
        #    a `412 Precondition Failed`` response is returned and the item will not be updated.
        #  schema:
        #    type: string
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/permission'
            examples:
              update link:
                description: Updating a public link is done by setting the `type` property of the permission link.
                value:
                  link:
                    type: edit
              update invite:
                description: Updating an invite is done by setting the `roles` property of the permission.
                value:
                  roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]
        required: true
      responses:
        '200':
          description: Updated permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/permission'
              examples:
                update link:
                  value:
                    id: "a373c812-d786-42ae-a65f-ed87ee4abd49"
                    link:
                      type: "edit"
                      webUrl: "https://cloud.example.org/s/MlnTDkhcBlihNzO"
                update invite:
                  value:
                    id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474"
                    roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]
                    expirationDateTime: "2018-07-15T14:00:00.000Z"
                    grantedToV2:
                      - user:
                          id: "4c510ada-c86b-4815-8820-42cdf82c3d51"
                          displayName: "Albert Einstein"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
        - drives.root
      summary: Remove access to a Drive
      operationId: DeletePermissionSpaceRoot
      description: |
        Remove access to the root item of a drive.

        Only sharing permissions that are not inherited can be deleted. The `inheritedFrom` property must be `null`.
      parameters:
        - name: drive-id
          in: path
          description: 'key: id of drive'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: drive
        - name: perm-id
          in: path
          description: 'key: id of permission'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: permission
        #- name: If-Match
        #  in: header
        #  description: |
        #    If this request header is included and the eTag (or cTag) provided does not match the current tag on the item,
        #    a `412 Precondition Failed`` response is returned and the item will not be updated.
        #  schema:
        #    type: string
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1beta1/drives/{drive-id}/root/permissions/{perm-id}/setPassword':
    post:
      tags:
        - drives.root
      summary: Set sharing link password for the root item of a drive
      operationId: SetPermissionPasswordSpaceRoot
      description: |
        Set the password of a sharing permission.

        Only the `password` property can be modified this way.
      parameters:
        - name: drive-id
          in: path
          description: 'key: id of drive'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: drive
        - name: perm-id
          in: path
          description: 'key: id of permission'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: permission
        #- name: If-Match
        #  in: header
        #  description: |
        #    If this request header is included and the eTag (or cTag) provided does not match the current tag on the item,
        #    a `412 Precondition Failed`` response is returned and the item will not be updated.
        #  schema:
        #    type: string
      requestBody:
        description: New password value
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sharingLinkPassword'
            examples:
              set password:
                value:
                  password: "TestPassword123!"
              set empty password:
                value:
                  password: ""
        required: true
      responses:
        '200':
          description: Updated permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/permission'
              examples:
                set password on editor link with custom display name:
                  value:
                    - id: "7181275c-557e-4adf-8e44-abdcf5389b6a"
                      hasPassword: true
                      expirationDateTime: "2018-07-15T14:00:00.000Z"
                      link:
                        type: "edit"
                        displayName: "Homework"
                        webUrl: "https://cloud.example.org/s/fdleMyGeerkIZTJ"
                set empty password:
                  value:
                    - id: "765c9b7b-6ccf-46ff-a659-95501250229c"
                      hasPassword: false
                      link:
                        type: "view"
                        displayName: "Quick link"
                        quicklink: true
                        webUrl: "https://cloud.example.org/s/erjHgjKjkstTesG"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1beta1/drives/{drive-id}/items/{item-id}':
    get:
      tags:
        - driveItem
      summary: Get a DriveItem.
      operationId: GetDriveItem
      description: |
        Get a DriveItem by using its ID.
      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: $expand
          in: query
          description: Expand related entities
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - extensions
              type: string
      responses:
        "200":
          description: Retrieved driveItem
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/driveItem"
        default:
          $ref: "#/components/responses/error"
      x-ms-docs-operation-type: operation
    patch:
      tags:
        - driveItem
      summary: Update a DriveItem.
      operationId: UpdateDriveItem
      description: |
        Update a DriveItem.

        The request body must include a JSON object with the properties to update.
        Only the properties that are provided will be updated.

        Currently it supports updating the following properties:

        * `@UI.Hidden` - Hides the item from the UI.
      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
      requestBody:
        description: DriveItem properties to update
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/driveItem'
            examples:
              change visibility:
                value:
                  "@UI.Hidden": true
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/driveItem'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
        - driveItem
      summary: Delete a DriveItem.
      operationId: DeleteDriveItem
      description: |
        Delete a DriveItem by using its ID.

        Deleting items using this method moves the items to the recycle bin instead of permanently deleting the item.

        Mounted shares in the share jail are unmounted. The `@client.synchronize` property of the `driveItem` in the [sharedWithMe](#/me.drive/ListSharedWithMe) endpoint will change to false.
      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: If-Match
        #  in: header
        #  description: |
        #    If this request header is included and the eTag (or cTag) provided does not match the current tag on the item,
        #    a `412 Precondition Failed`` response is returned and the item will not be updated.
        #  schema:
        #    type: string
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1beta1/drives/{drive-id}/items/{item-id}/createLink':
    post:
      tags:
        - drives.permissions
      summary: Create a sharing link for a DriveItem
      operationId: CreateLink
      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
        - name: item-id
          in: path
          description: 'key: id of item'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
      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}/items/{item-id}/invite':
    post:
      tags:
        - drives.permissions
      summary: Send a sharing invitation
      operationId: Invite
      description: |
        Sends a sharing invitation for a `driveItem`. 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
        - name: item-id
          in: path
          description: 'key: id of item'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
      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}/items/{item-id}/permissions':
    get:
      tags:
        - drives.permissions
      summary: List the effective sharing permissions on a driveItem.
      operationId: ListPermissions
      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
        - name: item-id
          in: path
          description: 'key: id of item'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
        - $ref: '#/components/parameters/permissionsFilter'
        - $ref: '#/components/parameters/permissionsSelect'
        - $ref: '#/components/parameters/count'
        - $ref: '#/components/parameters/top'
      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.count':
                    type: integer
                    description: The total number of permissions available, only present if the `count` query parameter is set to true.
                  #'@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:
                      - user:
                          id: "f7fbf8c8-139b-4376-b307-cf0a8c2d0d9c"
                          displayName: "Marie Skłodowska Curie"
                  - 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"
                  - id: "86765c0d-3905-444a-9b07-76201f8cf7df"
                    roles: [ "312c0871-5ef7-4b3a-85b6-0e4074c64049" ]
                    grantedToV2:
                      - group:
                          id: "167cbee2-0518-455a-bfb2-031fe0621e5d"
                          displayName: "Philosophy Haters"
                  - 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" ]
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1beta1/drives/{drive-id}/items/{item-id}/permissions/{perm-id}':
    get:
      tags:
        - drives.permissions
      summary: Get sharing permission for a file or folder
      operationId: GetPermission
      description: |
        Return the effective sharing permission for a particular permission resource.

      # TODO do we need to implement inherited permissions from the start?
      #  Effective permissions of an item can come from two sources: permissions set directly on the item itself or permissions that are inherited from the item's ancestors.
      #
      #  Callers can differentiate if the permission is inherited or not by checking the `inheritedFrom` property. This property is an ItemReference resource referencing the ancestor that the permission is inherited from.
      #
      parameters:
        - name: drive-id
          in: path
          description: 'key: id of drive'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: drive
        - name: item-id
          in: path
          description: 'key: id of item'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
        - name: perm-id
          in: path
          description: 'key: id of permission'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: permission
      responses:
        '200':
          description: Retrieved resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/permission'
              examples:
                edit permission:
                  value:
                    id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474"
                    roles: [ "write" ]
                    grantedToV2:
                      - user:
                          id: "4c510ada-c86b-4815-8820-42cdf82c3d51"
                          displayName: "Albert Einstein"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    patch:
      tags:
        - drives.permissions
      summary: Update sharing permission
      operationId: UpdatePermission
      description: |
        Update the properties of a sharing permission by patching the permission resource.

        Only the `roles`, `expirationDateTime` and `password` properties can be modified this way.
      parameters:
        - name: drive-id
          in: path
          description: 'key: id of drive'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: drive
        - name: item-id
          in: path
          description: 'key: id of item'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
        - name: perm-id
          in: path
          description: 'key: id of permission'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: permission
        #- name: If-Match
        #  in: header
        #  description: |
        #    If this request header is included and the eTag (or cTag) provided does not match the current tag on the item,
        #    a `412 Precondition Failed`` response is returned and the item will not be updated.
        #  schema:
        #    type: string
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/permission'
            examples:
              update link:
                description: Updating a public link is done by setting the `type` property of the permission link.
                value:
                  link:
                    type: edit
              update invite:
                description: Updating an invite is done by setting the `roles` property of the permission.
                value:
                  roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]
        required: true
      responses:
        '200':
          description: Updated permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/permission'
              examples:
                update link:
                  value:
                    id: "a373c812-d786-42ae-a65f-ed87ee4abd49"
                    link:
                      type: "edit"
                      webUrl: "https://cloud.example.org/s/MlnTDkhcBlihNzO"
                update invite:
                  value:
                    id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474"
                    roles: [ "b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5" ]
                    expirationDateTime: "2018-07-15T14:00:00.000Z"
                    grantedToV2:
                      - user:
                          id: "4c510ada-c86b-4815-8820-42cdf82c3d51"
                          displayName: "Albert Einstein"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
        - drives.permissions
      summary: Remove access to a DriveItem
      operationId: DeletePermission
      description: |
        Remove access to a DriveItem.

        Only sharing permissions that are not inherited can be deleted. The `inheritedFrom` property must be `null`.
      parameters:
        - name: drive-id
          in: path
          description: 'key: id of drive'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: drive
        - name: item-id
          in: path
          description: 'key: id of item'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
        - name: perm-id
          in: path
          description: 'key: id of permission'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: permission
        #- name: If-Match
        #  in: header
        #  description: |
        #    If this request header is included and the eTag (or cTag) provided does not match the current tag on the item,
        #    a `412 Precondition Failed`` response is returned and the item will not be updated.
        #  schema:
        #    type: string
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1beta1/drives/{drive-id}/items/{item-id}/permissions/{perm-id}/setPassword':
    post:
      tags:
        - drives.permissions
      summary: Set sharing link password
      operationId: SetPermissionPassword
      description: |
        Set the password of a sharing permission.

        Only the `password` property can be modified this way.
      parameters:
        - name: drive-id
          in: path
          description: 'key: id of drive'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: drive
        - name: item-id
          in: path
          description: 'key: id of item'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
        - name: perm-id
          in: path
          description: 'key: id of permission'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: permission
        #- name: If-Match
        #  in: header
        #  description: |
        #    If this request header is included and the eTag (or cTag) provided does not match the current tag on the item,
        #    a `412 Precondition Failed`` response is returned and the item will not be updated.
        #  schema:
        #    type: string
      requestBody:
        description: New password value
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/sharingLinkPassword'
            examples:
              set password:
                value:
                  password: "TestPassword123!"
              set empty password:
                value:
                  password: ""
        required: true
      responses:
        '200':
          description: Updated permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/permission'
              examples:
                set password on editor link with custom display name:
                  value:
                    - id: "7181275c-557e-4adf-8e44-abdcf5389b6a"
                      hasPassword: true
                      expirationDateTime: "2018-07-15T14:00:00.000Z"
                      link:
                        type: "edit"
                        displayName: "Homework"
                        webUrl: "https://cloud.example.org/s/fdleMyGeerkIZTJ"
                set empty password:
                  value:
                    - id: "765c9b7b-6ccf-46ff-a659-95501250229c"
                      hasPassword: false
                      link:
                        type: "view"
                        displayName: "Quick link"
                        quicklink: true
                        webUrl: "https://cloud.example.org/s/erjHgjKjkstTesG"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1beta1/drives/{drive-id}/items/{item-id}/extensions':
    get:
      tags:
        - driveItem.extensions
      summary: List all extensions on a DriveItem
      operationId: ListExtensions
      description: |
        Get the collection of open extensions on the specified DriveItem.

        Each extension is identified by its `extensionName`, which follows a reverse DNS naming convention
        (e.g. `com.example.myApp`).
      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
      responses:
        "200":
          description: Retrieved extensions
          content:
            application/json:
              schema:
                title: Collection of openTypeExtensions
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/openTypeExtension'
              examples:
                list extensions:
                  value:
                    value:
                      - extensionName: "com.example.project"
                        status: "reviewed"
                        assignee: "alice"
                      - extensionName: "eu.opencloud.workflow"
                        step: "approval"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1beta1/drives/{drive-id}/items/{item-id}/extensions/{extensionName}':
    get:
      tags:
        - driveItem.extensions
      summary: Get an extension by name
      operationId: GetExtension
      description: |
        Get a specific open extension identified by the extension name.
      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: extensionName
          in: path
          description: "The unique name of the extension, using reverse DNS notation (e.g. com.example.myApp)"
          required: true
          schema:
            type: string
          example: com.example.project
      responses:
        "200":
          description: Retrieved extension
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/openTypeExtension'
              examples:
                get extension:
                  value:
                    extensionName: "com.example.project"
                    status: "reviewed"
                    assignee: "alice"
                    priority: 3
        "404":
          $ref: '#/components/responses/error'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    put:
      tags:
        - driveItem.extensions
      summary: Create or update an extension
      operationId: UpsertExtension
      description: |
        Create or update an open extension on the specified DriveItem.

        If the extension does not exist, it is created. If it already exists, the provided properties
        are merged with the existing data:

        * Properties included in the request body are added or updated.
        * Properties set to `null` are removed from the extension.
        * Properties not included in the request body remain unchanged.

        The extension name should follow reverse DNS naming conventions (e.g. `com.example.myApp`)
        to avoid collisions between applications.
      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: extensionName
          in: path
          description: "The unique name of the extension, using reverse DNS notation (e.g. com.example.myApp)"
          required: true
          schema:
            type: string
          example: com.example.project
      requestBody:
        description: |
          Extension properties to set. Use `null` values to remove individual properties.

          The `extensionName` is derived from the URL path parameter and must not be included
          in the request body. If present, it will be ignored.
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/openTypeExtensionUpdate'
            examples:
              create extension:
                value:
                  status: "reviewed"
                  assignee: "alice"
                  priority: 3
              update single property:
                value:
                  status: "approved"
              remove a property:
                value:
                  priority: null
      responses:
        "200":
          description: Extension updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/openTypeExtension'
        "201":
          description: Extension created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/openTypeExtension'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
        - driveItem.extensions
      summary: Delete an extension
      operationId: DeleteExtension
      description: |
        Delete an open extension from the specified DriveItem.

        This removes the extension and all its properties.
      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: extensionName
          in: path
          description: "The unique name of the extension, using reverse DNS notation (e.g. com.example.myApp)"
          required: true
          schema:
            type: string
          example: com.example.project
      responses:
        "204":
          description: Extension deleted
        "404":
          $ref: '#/components/responses/error'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1.0/drives/{drive-id}/root':
    get:
      tags:
        - drives.root
      summary: Get root from arbitrary space
      operationId: GetRoot
      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 resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/driveItem'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /v1.0/groups:
    get:
      tags:
        - groups
      summary: Get entities from groups
      operationId: ListGroups
      parameters:
        - $ref: '#/components/parameters/search'
        - name: $orderby
          in: query
          description: Order items by property values
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - displayName
                - displayName desc
              type: string
        - name: $select
          in: query
          description: Select properties to be returned
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - id
                - description
                - displayName
                - mail
                - members
              type: string
        - name: $expand
          in: query
          description: Expand related entities
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - members
              type: string
      responses:
        '200':
          description: Retrieved entities
          content:
            application/json:
              schema:
                title: Collection of group
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/group'
                  '@odata.nextLink':
                    type: string
        default:
          $ref: '#/components/responses/error'
      x-ms-pageable:
        nextLinkName: '@odata.nextLink'
        operationName: listMore
      x-ms-docs-operation-type: operation
    post:
      tags:
        - groups
      summary: Add new entity to groups
      operationId: CreateGroup
      requestBody:
        description: New entity
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/group'
        required: true
      responses:
        '201':
          description: Created entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/group'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1.0/groups/{group-id}':
    get:
      tags:
        - group
      summary: Get entity from groups by key
      operationId: GetGroup
      parameters:
        - name: group-id
          in: path
          description: 'key: id or name of group'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: group
        - name: $select
          in: query
          description: Select properties to be returned
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - id
                - description
                - displayName
                - members
              type: string
        - name: $expand
          in: query
          description: Expand related entities
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - members
              type: string
      responses:
        '200':
          description: Retrieved entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/group'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    patch:
      tags:
        - group
      summary: Update entity in groups
      operationId: UpdateGroup
      parameters:
        - name: group-id
          in: path
          description: 'key: id of group'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: group
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/group'
            examples:
              update name:
                value:
                  displayName: GroupName
              add multiple members:
                value:
                  '@members@odata.bind':
                    - "https://localhost:9200/graph/v1.0/users/4c510ada-c86b-4815-8820-42cdf82c3d51"
                    - "https://localhost:9200/graph/v1.0/users/c54b0588-7157-4521-bb52-c1c8ca84ea71"
        required: true
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
        - group
      summary: Delete entity from groups
      operationId: DeleteGroup
      parameters:
        - name: group-id
          in: path
          description: 'key: id of group'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: group
        - 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/groups/{group-id}/members':
    get:
      tags:
        - group
      summary: Get a list of the group's direct members
      operationId: ListMembers
      parameters:
        - name: group-id
          in: path
          description: 'key: id or name of group'
          required: true
          schema:
            type: string
            example: 86948e45-96a6-43df-b83d-46e92afd30de
      responses:
        '200':
          description: Retrieved group members
          content:
            application/json:
              schema:
                title: Collection of users
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/user'
              example:
                - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90
                  onPremisesSAMAccountName: max.mustermann
                  displayName: Max Mustermann
                  mail: max.musterman@example.org
        default:
          $ref: '#/components/responses/error'
  '/v1.0/groups/{group-id}/members/$ref':
    post:
      tags:
        - group
      summary: Add a member to a group
      operationId: AddMember
      parameters:
        - name: group-id
          in: path
          description: 'key: id of group'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: group
      requestBody:
        description: Object to be added as member
        content:
          application/json:
            schema:
              title: Member Reference
              type: object
              properties:
                '@odata.id':
                  type: string
        required: true
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1.0/groups/{group-id}/members/{directory-object-id}/$ref':
    delete:
      tags:
        - group
      summary: Delete member from a group
      operationId: DeleteMember
      parameters:
        - name: group-id
          in: path
          description: 'key: id of group'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: group
        - name: directory-object-id
          in: path
          description: 'key: id of group member to remove'
          required: true
          schema:
            type: string
        - 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/me/drive:
    get:
      tags:
        - me.drive
      summary: Get personal space for user
      operationId: GetHome
      responses:
        '200':
          description: Retrieved personal space
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/drive'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /v1.0/me/drive/root:
    get:
      tags:
        - me.drive.root
      summary: Get root from personal space
      operationId: HomeGetRoot
      responses:
        '200':
          description: Retrieved resource
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/driveItem'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /v1.0/me/drive/root/children:
    get:
      tags:
        - me.drive.root.children
      summary: Get children from drive
      operationId: HomeGetChildren
      responses:
        '200':
          description: Retrieved resource list
          content:
            application/json:
              schema:
                title: Collection of driveItems
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/driveItem'
                    maxItems: 100
                  '@odata.nextLink':
                    type: string
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /v1beta1/me/drive/sharedByMe:
    get:
      tags:
        - me.drive
      summary: Get a list of driveItem objects shared by the current user.
      operationId: ListSharedByMe
      description: |
        The `driveItems` returned from the `sharedByMe` method always include the `permissions` relation that indicates they are shared items.
      parameters:
        - name: $expand
          in: query
          description: Expand related entities
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - thumbnails
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: Collection of driveItems
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/driveItem'
                  #  maxItems: 20
                  #'@odata.nextLink':
                  #  type: string
              example:
                value:
                  - id: 78363031-03ef-4eda-84a2-243a691a13cd
                    createdDateTime: "2020-02-19T14:23:25.52Z"
                    # not yet supported by opencloud
                    #cTag: "adDpDMTI2NDRBMTRCMEE3NzUwITEzNzkuNjM3NjYyNzQ5NjU1MDMwMDAw"
                    eTag: "aQzEyNjQ0QTE0QjBBNzc1MCExMzc5LjQ"
                    lastModifiedDateTime: "2021-09-03T14:09:25.503Z"
                    name: "March Proposal.docx"
                    parentReference:
                      driveId: "1991210caf"
                      driveType: personal
                    permissions:
                      - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474"
                        roles: [ "write" ]
                        grantedToV2:
                          - user:
                              id: "4c510ada-c86b-4815-8820-42cdf82c3d51"
                              displayName: "Albert Einstein"
                      - id: "81d5bad3-3eff-410a-a2ea-eda2d14d4474"
                        roles: [ "read" ]
                        grantedToV2:
                          - user:
                              id: "48016357-346a-443e-bf7a-945c9448a99b"
                              displayName: "Marie Curie"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  /v1.0/me/drive/items/{item-id}/follow:
    post:
      tags:
        - me.drive
      summary: Follow a DriveItem
      description: Follow a DriveItem.
      operationId: FollowDriveItem
      parameters:
        - name: item-id
          in: path
          description: 'key: id of item'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
      responses:
        "201":
          description: Created
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/driveItem"
        default:
          $ref: "#/components/responses/error"
      x-ms-docs-operation-type: operation
  /v1.0/me/drive/following/{item-id}:
    delete:
      tags:
        - me.drive
      summary: Unfollow a DriveItem
      description: Unfollow a DriveItem.
      operationId: UnfollowDriveItem
      parameters:
        - name: item-id
          in: path
          description: "key: id of item"
          required: true
          schema:
            type: string
          x-ms-docs-key-type: item
      responses:
        "204":
          description: No Content
        default:
          $ref: "#/components/responses/error"
      x-ms-docs-operation-type: operation

  /v1beta1/me/drive/sharedWithMe:
    get:
      tags:
        - me.drive
      summary: Get a list of driveItem objects shared with the owner of a drive.
      operationId: ListSharedWithMe
      description: |
        The `driveItems` returned from the `sharedWithMe` method always include the `remoteItem` facet that indicates they are items from a different drive.
      parameters:
        - name: $expand
          in: query
          description: Expand related entities
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - thumbnails
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                title: Collection of driveItems
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/driveItem'
                  #  maxItems: 20
                  #'@odata.nextLink':
                  #  type: string
              example:
                value:
                  - id: 78363031-03ef-4eda-84a2-243a691a13cd
                    '@UI.hidden': false
                    '@client.synchronize': true
                    createdBy:
                      user:
                        displayName: "Albert Einstein"
                        id: "44feab10d55e9871"
                    cTag: "adDpDMTI2NDRBMTRCMEE3NzUwITEzNzkuNjM3NjYyNzQ5NjU1MDMwMDAw"
                    eTag: "aQzEyNjQ0QTE0QjBBNzc1MCExMzc5LjQ"
                    lastModifiedDateTime: "2021-09-03T14:09:25.503Z"
                    name: "March Proposal.docx"
                    parentReference:
                      driveId: "1991210caf"
                      driveType: personal
                    remoteItem:
                      id: 02d7a7df-a6f7-44cc-848a-3c98f7dd5046
                      name: "March Proposal.docx"
                      size: 19121
                      lastModifiedDateTime: "2021-09-03T14:09:25.503Z"
                      permissions:
                        - id: 7310e99f-377b-4cba-a1f0-ffa3331fd32c
                          roles:
                            - b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5
                          grantedToV2:
                            group:
                              displayName: "users"
                              id: 509a9dcd-bb37-4f4f-a01a-19dca27d9cfa
                          invitation:
                            invitedBy:
                              user:
                                displayName: "Albert Einstein"
                                id: "44feab10d55e9871"
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation

  /v1.0/invitations:
    post:
      tags:
        - invitations
      summary: Create a new invitation
      operationId: CreateInvitation
      requestBody:
        description: New invitation
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/invitation'
      responses:
        '201':
          description: Invitation created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invitation'
      x-ms-docs-operation-type: operation
    get:
      tags:
        - invitations
      summary: Get a list of invitations
      operationId: ListInvitations
      responses:
        '200':
          description: Retrieved invitations
          content:
            application/json:
              schema:
                title: Collection of invitations
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/invitation'

  /v1.0/invitations/{invitation-id}:
    get:
      tags:
        - invitations
      summary: Get an invitation by key
      operationId: GetInvitation
      parameters:
        - name: invitation-id
          in: path
          description: 'key: id of invitation'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Retrieved invitation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/invitation'

  /v1.0/users:
    get:
      tags:
        - users
      summary: Get entities from users
      operationId: ListUsers
      parameters:
        - $ref: '#/components/parameters/search'
        - $ref: '#/components/parameters/usersFilter'
        - name: $orderby
          in: query
          description: Order items by property values
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - displayName
                - displayName desc
                - mail
                - mail desc
                - onPremisesSamAccountName
                - onPremisesSamAccountName desc
              type: string
        - name: $select
          in: query
          description: Select properties to be returned
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - id
                - displayName
                - mail
                - memberOf
                - onPremisesSamAccountName
                - surname
              type: string
        - name: $expand
          in: query
          description: Expand related entities
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - drive
                - drives
                - memberOf
                - appRoleAssignments
              type: string
      responses:
        '200':
          description: Retrieved entities
          content:
            application/json:
              schema:
                title: Collection of user
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/user'
                  '@odata.nextLink':
                    type: string
        default:
          $ref: '#/components/responses/error'
      x-ms-pageable:
        nextLinkName: '@odata.nextLink'
        operationName: listMore
      x-ms-docs-operation-type: operation
    post:
      tags:
        - users
      summary: Add new entity to users
      operationId: CreateUser
      requestBody:
        description: New entity
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/user'
        required: true
      responses:
        '201':
          description: Created entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1.0/users/{user-id}':
    get:
      tags:
        - user
      summary: Get entity from users by key
      operationId: GetUser
      parameters:
        - name: user-id
          in: path
          description: 'key: id or name of user'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: user
        - name: $select
          in: query
          description: Select properties to be returned
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - id
                - displayName
                - drive
                - drives
                - mail
                - memberOf
                - onPremisesSamAccountName
                - surname
              type: string
        - name: $expand
          in: query
          description: Expand related entities
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - drive
                - drives
                - memberOf
                - appRoleAssignments
              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
    patch:
      tags:
        - user
      summary: Update entity in users
      operationId: UpdateUser
      parameters:
        - name: user-id
          in: path
          description: 'key: id of user'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: user
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/userUpdate'
            examples:
              change displayName:
                value:
                  displayName: "Marie Skłodowska Curie"
              change email:
                value:
                  mail: "marie@example.com"
              change preferred language:
                value:
                  preferredLanguage: "fr"
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/user'
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
    delete:
      tags:
        - user
      summary: Delete entity from users
      operationId: DeleteUser
      parameters:
        - name: user-id
          in: path
          description: 'key: id or name of user'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: user
        - 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/users/{user-id}/exportPersonalData':
    post:
      tags:
        - user
      summary: export personal data of a user
      operationId: ExportPersonalData
      parameters:
        - name: user-id
          in: path
          description: 'key: id or name of user'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: user
      requestBody:
        description: destination the file should be created at
        content:
          application/json:
            schema:
              properties:
                storageLocation:
                  type: string
                  description: the path where the file should be created in the users personal space
      responses:
        202:
          description: success
        default:
          $ref: '#/components/responses/error'
      x-ms-docs-operation-type: operation
  '/v1.0/users/{user-id}/appRoleAssignments':
    description: Provides operations to manage assignments of roles to users.
    get:
      tags:
        - user.appRoleAssignment
      summary: Get appRoleAssignments from a user
      description: Represents the global roles a user has been granted for an application.
      operationId: user.ListAppRoleAssignments
      responses:
        200:
          description: Retrieved appRoleAssignments
          content:
            application/json:
              schema:
                title: Collection of appRoleAssignments
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/appRoleAssignment'
                    maxItems: 100
                  '@odata.nextLink':
                    type: string
        default:
          $ref: '#/components/responses/error'
    post:
      tags:
        - user.appRoleAssignment
      summary: Grant an appRoleAssignment to a user
      description: |
        Use this API to assign a global role to a user. To grant an app role assignment to a user, you need three identifiers:
        * `principalId`: The `id` of the user to whom you are assigning the app role.
        * `resourceId`: The `id` of the resource `servicePrincipal` or `application` that has defined the app role.
        * `appRoleId`: The `id` of the `appRole` (defined on the resource service principal or application) to assign to the user.
      operationId: user.CreateAppRoleAssignments
      requestBody:
        description: New app role assignment value
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/appRoleAssignment'
        required: true
      responses:
        200:
          description: Created new app role assignment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/appRoleAssignment'
        default:
          $ref: '#/components/responses/error'
    parameters:
      - name: user-id
        in: path
        description: 'key: id of user'
        required: true
        style: simple
        schema:
          type: string
  '/v1.0/users/{user-id}/appRoleAssignments/{appRoleAssignment-id}':
    description: Provides operations to manage a global role for an assigned user.
    delete:
      tags:
        - user.appRoleAssignment
      summary: Delete the appRoleAssignment from a user
      operationId: user.DeleteAppRoleAssignments
      parameters:
        - name: If-Match
          in: header
          description: ETag
          style: simple
          schema:
            type: string
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
    parameters:
      - name: user-id
        in: path
        description: 'key: id of user'
        required: true
        style: simple
        schema:
          type: string
      - name: appRoleAssignment-id
        in: path
        description: 'key: id of appRoleAssignment. This is the concatenated {user-id}:{appRole-id} separated by a colon.'
        required: true
        style: simple
        schema:
          type: string
  '/v1.0/users/{user-id}/photo/$value':
    get:
      tags:
        - user.photo
      summary: Get the photo of a user
      operationId: GetUserPhoto
      parameters:
        - name: user-id
          in: path
          description: 'key: id or name of user'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: user
      responses:
        '200':
          description: Retrieved photo
          content:
            image/jpeg:
              schema:
                type: string
                format: binary
        default:
          $ref: '#/components/responses/error'
  /v1.0/education/users:
    get:
      tags:
        - educationUser
      summary: Get entities from education users
      description: |
        Retrieves a collection of education users with optional filtering, ordering, and expansion.

        **Filtering by external ID:**
        Use `$filter` to query users by their external identifier, for example:
        `$filter=externalId eq 'EX12345'`
      security:
        - bearerAuth: [ ]
      operationId: ListEducationUsers
      parameters:
        - name: $filter
          in: query
          description: |
            Filter items by property values. Supports a subset of OData filter expressions.

            **Supported filters:**
            - By external ID: `externalId eq 'ext_12345'`
          schema:
            type: string
          examples:
            externalId:
              value: externalId eq 'ext_12345'
              summary: Filter by external ID
        - name: $orderby
          in: query
          description: Order items by property values
          style: form
          explode: false
          schema:
            uniqueItems: true
            type: array
            items:
              enum:
                - displayName
                - displayName desc
                - mail
                - mail desc
                - onPremisesSamAccountName
                - onPremisesSamAccountName desc
              type: string
        - 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 entities
          content:
            application/json:
              schema:
                title: Collection of educationUser
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/educationUser'
              example:
                - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90
                  onPremisesSAMAccountName: max.mustermann
                  displayName: Max Mustermann
                  mail: max.musterman@example.org
                  primaryRole: student
                  identities:
                    - issuer: idp.school.com
                      issuerAssignedId: max.mustermann
                    - issuer: newidp.school.com
                      issuerAssignedId: ieZ2AeV5
        default:
          $ref: '#/components/responses/error'
    post:
      tags:
        - educationUser
      summary: Add new education user
      security:
        - bearerAuth: [ ]
      operationId: CreateEducationUser
      requestBody:
        description: New entity
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/educationUser'
            examples:
              student:
                $ref: '#/components/examples/educationUser_post'
              externalId:
                $ref: '#/components/examples/educationUser_post_externalId'
        required: true
      responses:
        '201':
          description: Created entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/educationUser'
              examples:
                student:
                  $ref: '#/components/examples/educationUser'
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/users/{user-id}':
    get:
      tags:
        - educationUser
      summary: Get properties of educationUser
      security:
        - bearerAuth: [ ]
      operationId: GetEducationUser
      parameters:
        - name: user-id
          in: path
          description: 'key: id or username of user'
          required: true
          schema:
            type: string
          examples:
            id:
              value: 90eedea1-dea1-90ee-a1de-ee90a1deee90
            name:
              value: max.mustermann
        - 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/educationUser'
              examples:
                student:
                  $ref: '#/components/examples/educationUser'
        default:
          $ref: '#/components/responses/error'
    patch:
      tags:
        - educationUser
      summary: Update properties of educationUser
      security:
        - bearerAuth: [ ]
      operationId: UpdateEducationUser
      parameters:
        - name: user-id
          in: path
          description: 'key: id or username of user'
          required: true
          schema:
            type: string
            example: 90eedea1-dea1-90ee-a1de-ee90a1deee90
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/educationUser'
            example:
              mail: max.mustermann@new.domain
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/educationUser'
              example:
                id: 90eedea1-dea1-90ee-a1de-ee90a1deee90
                onPremisesSAMAccountName: max.mustermann
                displayName: Max Mustermann
                surname: Mustermann
                givenName: Max
                mail: max.musterman@new.domain
                primaryRole: student
                identities:
                  - issuer: idp.school.com
                    issuerAssignedId: max.mustermann
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
    delete:
      tags:
        - educationUser
      summary: Delete educationUser
      description: |
        Deletes an education user by their internal ID.

        **To delete by external ID:**
        If you only have an external ID, you must first retrieve the user's internal ID:
        1. Call `GET /graph/v1.0/education/users?$filter=externalId eq '{value}'`
        2. Extract the `id` from the response
        3. Use that `id` in this DELETE endpoint

        See the [ListEducationUsers](#/educationUser/ListEducationUsers) operation for query details.
      security:
        - bearerAuth: [ ]
      operationId: DeleteEducationUser
      parameters:
        - name: user-id
          in: path
          description: |
            key: internal user id (UUID format) or username of user.

            **Note:** If you only have an external ID, first query the user
            with `GET /graph/v1.0/education/users?$filter=externalId eq '{value}'`
            to retrieve the internal ID.
          required: true
          schema:
            type: string
            example: 90eedea1-dea1-90ee-a1de-ee90a1deee90
      responses:
        '204':
          description: Success
        '404':
          description: User not found
        default:
          $ref: '#/components/responses/error'
  /v1.0/education/schools:
    get:
      tags:
        - educationSchool
      summary: Get a list of schools and their properties
      description: |
        Retrieves a collection of education schools with optional filtering and ordering.

        **Filtering by external ID:**
        Use `$filter` to query schools by their external identifier, for example:
        `$filter=externalId eq 'EX12345'`
      security:
        - bearerAuth: [ ]
      operationId: ListSchools
      parameters:
        - name: $filter
          in: query
          description: |
            Filter items by property values. Supports a subset of OData filter expressions.

            **Supported filters:**
            - By external ID: `externalId eq 'ext_12345'`
          schema:
            type: string
          examples:
            externalId:
              value: externalId eq 'ext_12345'
              summary: Filter by external ID
      responses:
        '200':
          description: Retrieved entities
          content:
            application/json:
              schema:
                title: Collection of schools
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/educationSchool'
              example:
                - id: 0e19303e-8144-44bd-86d8-35cc8ac9c255
                  displayName: Gymnasium Musterstadt
                  schoolNumber: '0123'
                  terminationDate: 2023-06-30T00:00:00Z
                - id: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
                  displayName: Realschule Musterstadt
                  schoolNumber: '1234'
        default:
          $ref: '#/components/responses/error'
    post:
      tags:
        - educationSchool
      summary: Add new school
      security:
        - bearerAuth: [ ]
      operationId: CreateSchool
      requestBody:
        description: New school
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/educationSchool'
            examples:
              school:
                $ref: '#/components/examples/educationSchool_post'
        required: true
      responses:
        '201':
          description: Created entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/educationSchool'
              examples:
                school:
                  $ref: '#/components/examples/educationSchool'
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/schools/{school-id}':
    get:
      tags:
        - educationSchool
      summary: Get the properties of a specific school
      security:
        - bearerAuth: [ ]
      operationId: GetSchool
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
      responses:
        '200':
          description: Retrieved entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/educationSchool'
              examples:
                school:
                  $ref: '#/components/examples/educationSchool'
        default:
          $ref: '#/components/responses/error'
    patch:
      tags:
        - educationSchool
      summary: Update properties of a school
      security:
        - bearerAuth: [ ]
      operationId: UpdateSchool
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/educationSchool'
            examples:
              schoolNumber:
                $ref: '#/components/examples/educationSchool_patchNumber'
              schoolTerminationDate:
                $ref: '#/components/examples/educationSchool_patchTerminationDate'
              deleteSchoolTerminationDate:
                $ref: '#/components/examples/educationSchool_deleteTerminationDate'
        required: true
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/educationSchool'
              examples:
                school:
                  $ref: '#/components/examples/educationSchool'
        default:
          $ref: '#/components/responses/error'
    delete:
      tags:
        - educationSchool
      summary: Delete school
      description: Deletes a school. A school can only be delete if it has the terminationDate property set. And if that termination Date is in the past.
      security:
        - bearerAuth: [ ]
      operationId: DeleteSchool
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/schools/{school-id}/users':
    get:
      tags:
        - educationSchool
      summary: Get the educationUser resources associated with an educationSchool
      security:
        - bearerAuth: [ ]
      operationId: ListSchoolUsers
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
      responses:
        '200':
          description: Retrieved educationUser
          content:
            application/json:
              schema:
                title: Collection of educationUser
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/educationUser'
              example:
                - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90
                  onPremisesSAMAccountName: max.mustermann
                  displayName: Max Mustermann
                  surname: Mustermann
                  givenName: Max
                  mail: max.musterman@example.org
                  primaryRole: student
                  identities:
                    - issuer: idp.school.com
                      issuerAssignedId: max.mustermann
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/schools/{school-id}/users/$ref':
    post:
      tags:
        - educationSchool
      summary: Assign a user to a school
      security:
        - bearerAuth: [ ]
      operationId: AddUserToSchool
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
      requestBody:
        description: educationUser to be added as member
        content:
          application/json:
            schema:
              title: EducationUser Reference
              type: object
              properties:
                '@odata.id':
                  type: string
                  example: "https://<hostname>/graph/v1.0/education/users/90eedea1-dea1-90ee-a1de-ee90a1deee90"
        required: true
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/schools/{school-id}/users/{user-id}/$ref':
    delete:
      tags:
        - educationSchool
      summary: Unassign user from a school
      security:
        - bearerAuth: [ ]
      operationId: DeleteUserFromSchool
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
        - name: user-id
          in: path
          description: 'key: id or username of the user to unassign from school'
          required: true
          schema:
            type: string
            example: 90eedea1-dea1-90ee-a1de-ee90a1deee90
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/schools/{school-id}/classes':
    get:
      tags:
        - educationSchool
      summary: Get the educationClass resources owned by an educationSchool
      security:
        - bearerAuth: [ ]
      operationId: ListSchoolClasses
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
      responses:
        '200':
          description: Retrieved classes
          content:
            application/json:
              schema:
                title: Collection of educationClass
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/educationClass'
              example:
                - id: 86948e45-96a6-43df-b83d-46e92afd30de
                  displayName: Mathematik
                  classification: course
                  externalId: ac528aea-978e-415c-a733-c4ba235d3388
                - id: 9097631c-24b6-4621-9635-36195a9c8d79
                  displayName: 10b
                  classification: class
                  externalId: 0123_10b
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/schools/{school-id}/classes/$ref':
    post:
      tags:
        - educationSchool
      summary: Assign a class to a school
      security:
        - bearerAuth: [ ]
      operationId: AddClassToSchool
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
      requestBody:
        description: educationClass to be added as member
        content:
          application/json:
            schema:
              title: Class Reference
              type: object
              properties:
                '@odata.id':
                  type: string
                  example: "https://<hostname>/graph/v1.0/education/classes/7e84a069-f374-479b-817d-71590117d443"
        required: true
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/schools/{school-id}/classes/{class-id}/$ref':
    delete:
      tags:
        - educationSchool
      summary: Unassign class from a school
      security:
        - bearerAuth: [ ]
      operationId: DeleteClassFromSchool
      parameters:
        - name: school-id
          in: path
          description: 'key: id or schoolNumber of school'
          required: true
          schema:
            type: string
            example: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
        - name: class-id
          in: path
          description: 'key: id or externalId of the class to unassign from school'
          required: true
          schema:
            type: string
            example: 7e84a069-f374-479b-817d-71590117d443
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  /v1.0/education/classes:
    get:
      tags:
        - educationClass
      summary: list education classes
      operationId: ListClasses
      security:
        - bearerAuth: [ ]
      responses:
        '200':
          description: Retrieved entities
          content:
            application/json:
              schema:
                title: Collection of class
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/educationClass'
              example:
                - id: 86948e45-96a6-43df-b83d-46e92afd30de
                  displayName: Mathematik
                  classification: course
                  externalId: ac528aea-978e-415c-a733-c4ba235d3388
                - id: 9097631c-24b6-4621-9635-36195a9c8d79
                  displayName: 10b
                  classification: class
                  externalId: 0123_10b
        default:
          $ref: '#/components/responses/error'
    post:
      tags:
        - educationClass
      summary: Add new education class
      security:
        - bearerAuth: [ ]
      operationId: CreateClass
      requestBody:
        description: New entity
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/educationClass'
            examples:
              class:
                $ref: '#/components/examples/educationClass_post'
        required: true
      responses:
        '201':
          description: Created entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/educationClass'
              examples:
                class:
                  $ref: '#/components/examples/educationClass'
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/classes/{class-id}':
    get:
      tags:
        - educationClass
      summary: Get class by key
      security:
        - bearerAuth: [ ]
      operationId: GetClass
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
            example: 86948e45-96a6-43df-b83d-46e92afd30de
      responses:
        '200':
          description: Retrieved entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/educationClass'
              examples:
                class:
                  $ref: '#/components/examples/educationClass'
        default:
          $ref: '#/components/responses/error'
    patch:
      tags:
        - educationClass
      summary: Update properties of a education class
      security:
        - bearerAuth: [ ]
      operationId: UpdateClass
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
            example: 86948e45-96a6-43df-b83d-46e92afd30de
      requestBody:
        description: New property values
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/educationClass'
            examples:
              update name:
                value:
                  displayName: Musik
              add multiple members:
                value:
                  '@members@odata.bind':
                    - "https://localhost:9200/graph/v1.0/education/users/4c510ada-c86b-4815-8820-42cdf82c3d51"
                    - "https://localhost:9200/graph/v1.0/education/users/c54b0588-7157-4521-bb52-c1c8ca84ea71"
        required: true
      responses:
        '200':
          description: New property values
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/educationClass'
              example:
                id: 86948e45-96a6-43df-b83d-46e92afd30de
                displayName: Musik
                classification: course
                externalId: cb766da3-bab1-478a-9615-f99d4c59c09a
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
    delete:
      tags:
        - educationClass
      summary: Delete education class
      security:
        - bearerAuth: [ ]
      operationId: DeleteClass
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
            example: 86948e45-96a6-43df-b83d-46e92afd30de
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/classes/{class-id}/members':
    get:
      tags:
        - educationClass
      summary: Get the educationClass resources owned by an educationSchool
      security:
        - bearerAuth: [ ]
      operationId: ListClassMembers
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
            example: 86948e45-96a6-43df-b83d-46e92afd30de
      responses:
        '200':
          description: Retrieved class members
          content:
            application/json:
              schema:
                title: Collection of educationUser
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/educationUser'
              example:
                - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90
                  onPremisesSAMAccountName: max.mustermann
                  displayName: Max Mustermann
                  surname: Mustermann
                  givenName: Max
                  mail: max.musterman@example.org
                  primaryRole: student
                  identities:
                    - issuer: idp.school.com
                      issuerAssignedId: max.mustermann
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/classes/{class-id}/members/$ref':
    post:
      tags:
        - educationClass
      summary: Assign a user to a class
      security:
        - bearerAuth: [ ]
      operationId: AddUserToClass
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
            example: 86948e45-96a6-43df-b83d-46e92afd30de
      requestBody:
        description: educationUser to be added as member
        content:
          application/json:
            schema:
              title: Class Member Reference
              type: object
              properties:
                '@odata.id':
                  type: string
                  example: "https://<hostname>/graph/v1.0/education/users/90eedea1-dea1-90ee-a1de-ee90a1deee90"
        required: true
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/classes/{class-id}/members/{user-id}/$ref':
    delete:
      tags:
        - educationClass
      summary: Unassign user from a class
      security:
        - bearerAuth: [ ]
      operationId: DeleteUserFromClass
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
        - name: user-id
          in: path
          description: 'key: id or username of the user to unassign from class'
          required: true
          schema:
            type: string
            example: 90eedea1-dea1-90ee-a1de-ee90a1deee90
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/classes/{class-id}/teachers':
    get:
      tags:
        - educationClass.teachers
      summary: Get the teachers for a class
      security:
        - bearerAuth: [ ]
      operationId: GetTeachers
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
            example: 86948e45-96a6-43df-b83d-46e92afd30de
      responses:
        '200':
          description: Retrieved class teachers
          content:
            application/json:
              schema:
                title: Collection of educationUser
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/educationUser'
              example:
                - id: 90eedea1-dea1-90ee-a1de-ee90a1deee90
                  onPremisesSAMAccountName: max.mustermann
                  displayName: Max Mustermann
                  surname: Mustermann
                  givenName: Max
                  mail: max.musterman@example.org
                  primaryRole: teacher
                  identities:
                    - issuer: idp.school.com
                      issuerAssignedId: max.mustermann
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/classes/{class-id}/teachers/$ref':
    post:
      tags:
        - educationClass.teachers
      summary: Assign a teacher to a class
      security:
        - bearerAuth: [ ]
      operationId: AddTeacherToClass
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
            example: 86948e45-96a6-43df-b83d-46e92afd30de
      requestBody:
        description: educationUser to be added as teacher
        content:
          application/json:
            schema:
              title: Class Teacher Reference
              type: object
              properties:
                '@odata.id':
                  type: string
                  example: "https://<hostname>/graph/v1.0/education/users/90eedea1-dea1-90ee-a1de-ee90a1deee90"
        required: true
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/education/classes/{class-id}/teachers/{user-id}/$ref':
    delete:
      tags:
        - educationClass.teachers
      summary: Unassign user as teacher of a class
      security:
        - bearerAuth: [ ]
      operationId: DeleteTeacherFromClass
      parameters:
        - name: class-id
          in: path
          description: 'key: id or externalId of class'
          required: true
          schema:
            type: string
        - name: user-id
          in: path
          description: 'key: id or username of the user to unassign as teacher'
          required: true
          schema:
            type: string
            example: 90eedea1-dea1-90ee-a1de-ee90a1deee90
      responses:
        '204':
          description: Success
        default:
          $ref: '#/components/responses/error'
  '/v1.0/extensions/org.libregraph/tags':
    get:
      tags:
        - tags
      summary: Get all known tags
      operationId: GetTags
      responses:
        '200':
          description: Retrieved tags
          content:
            application/json:
              schema:
                title: Collection of tags
                type: object
                properties:
                  value:
                    type: array
                    items:
                      type: string
        default:
          $ref: '#/components/responses/error'
    put:
      tags:
        - tags
      summary: Assign tags to a resource
      operationId: AssignTags
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tagAssignment'
            examples:
              assign:
                $ref: '#/components/examples/tags_put'
      responses:
        '200':
          description: No content
        default:
          $ref: '#/components/responses/error'
    delete:
      tags:
        - tags
      summary: Unassign tags from a resource
      operationId: UnassignTags
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/tagUnassignment'
            examples:
              unassign:
                $ref: '#/components/examples/tags_delete'
      responses:
        '200':
          description: No content
        default:
          $ref: '#/components/responses/error'
  /v1.0/applications:
    get:
      tags:
        - applications
      summary: Get all applications
      operationId: ListApplications
      responses:
        '200':
          description: Retrieved entities
          content:
            application/json:
              schema:
                title: Collection of applications
                type: object
                properties:
                  value:
                    type: array
                    items:
                      $ref: '#/components/schemas/application'
        default:
          $ref: '#/components/responses/error'
  /v1.0/applications/{application-id}:
    get:
      tags:
        - applications
      summary: Get application by id
      operationId: GetApplication
      parameters:
        - name: application-id
          in: path
          description: 'key: id of application'
          required: true
          schema:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/application'
        default:
          $ref: '#/components/responses/error'
  /v1beta1/roleManagement/permissions/roleDefinitions:
    get:
      tags:
        - roleManagement
      summary: List roleDefinitions
      operationId: ListPermissionRoleDefinitions
      description: |
        Get a list of `unifiedRoleDefinition` objects for the permissions provider. This list determines the roles that can be selected when creating sharing invites.
      responses:
        '200':
          description: A list of permission roles than can be used when sharing with users or groups.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/unifiedRoleDefinition'
              example:
                - id: b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5
                  description: "Allows reading the shared file or folder"
                  displayName: Viewer
                  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
        default:
          $ref: '#/components/responses/error'
  /v1beta1/roleManagement/permissions/roleDefinitions/{role-id}:
    get:
      tags:
        - roleManagement
      summary: Get unifiedRoleDefinition
      operationId: GetPermissionRoleDefinition
      description: |
        Read the properties and relationships of a `unifiedRoleDefinition` object.
      parameters:
        - name: role-id
          in: path
          description: 'key: id of roleDefinition'
          required: true
          schema:
            type: string
          x-ms-docs-key-type: roleDefinition
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unifiedRoleDefinition'
              examples:
                Viewer:
                  value:
                    id: b1e2218d-eef8-4d4c-b82d-0f1a1b48f3b5
                    description: "Allows reading the shared file or folder"
                    displayName: Viewer
                    rolePermissions:
                      - allowedResourceActions:
                          - libre.graph/driveItem/basic/read
                        condition: "exists @Resource.File"
                    '@libre.graph.weight': 1
                Editor:
                  value:
                    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
                Manager:
                  value:
                    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
                File Drop:
                  value:
                    id: 4916f47e-66d5-49bb-9ac9-748ad00334b
                    description: "Allows creating new files"
                    displayName: File Drop
                    rolePermissions:
                      - allowedResourceActions:
                          - libre.graph/driveItem/standard/create
                        condition: "exists @Resource.File"
                    '@libre.graph.weight': 4
        default:
          $ref: '#/components/responses/error'
components:
  schemas:
    tagAssignment:
      type: object
      required:
        - resourceId
        - tags
      properties:
        resourceId:
          type: string
        tags:
          type: array
          items:
            type: string
    tagUnassignment:
      type: object
      required:
        - resourceId
        - tags
      properties:
        resourceId:
          type: string
        tags:
          type: array
          items:
            type: string
    educationSchool:
      description: Represents a school
      type: object
      properties:
        id:
          type: string
          description: The unique identifier for an entity. Read-only.
          readOnly: true
        displayName:
          type: string
          description: The organization name
        schoolNumber:
          type: string
          description: School number
        externalId:
          type: string
          description: External identifier of the school
        terminationDate:
          type: string
          format: date-time
          nullable: true
          description: Date and time at which the service for this organization is scheduled to be terminated
    educationClass:
      description: And extension of group representing a class or course
      type: object
      required:
        - displayName
        - classification
      properties:
        # entity
        id:
          type: string
          description: Read-only.
          readOnly: true
        # group
        description:
          type: string
          description: 'An optional description for the group. Returned by default.'
        displayName:
          type: string
          description: 'The display name for the group. This property is required when a group is created and cannot be cleared during updates. Returned by default. Supports $search and $orderBy.'
        members:
          type: array
          items:
            $ref: '#/components/schemas/user'
          description: 'Users and groups that are members of this group. HTTP Methods: GET (supported for all groups), Nullable. Supports $expand.'
        'members@odata.bind':
          type: array
          items:
            type: string
          uniqueItems: true
          minItems: 1
          maxItems: 20
          description: A list of member references to the members to be added. Up to 20 members can be added with a single request
        classification:
          type: string
          enum: [ class, course ]
          description: 'Classification of the group, i.e. "class" or "course"'
        externalId:
          type: string
          description: An external unique ID for the class
    educationUser:
      description: An extension of user with education-specific attributes
      type: object
      properties:
        # entity
        id:
          type: string
          description: Read-only.
          readOnly: true
        # user
        accountEnabled:
          type: boolean
          description: 'Set to "true" when the account is enabled.'
        displayName:
          type: string
          description: 'The name displayed in the address book for the user. This value is usually the combination of the user''s first name, middle initial, and last name. This property is required when a user is created and it cannot be cleared during updates. Returned by default. Supports $orderby.'
        drives:
          type: array
          items:
            $ref: '#/components/schemas/drive'
          description: A collection of drives available for this user. Read-only.
          maxItems: 100
          readOnly: true
        drive:
          $ref: '#/components/schemas/drive'
          description: The personal drive of this user. Read-only.
          readOnly: true
        externalId:
          type: string
          description: An external unique ID for the user. Use it to associate a user in another system, such as a student or employee ID number.
        identities:
          description: Identities associated with this account.
          type: array
          items:
            $ref: '#/components/schemas/objectIdentity'
        mail:
          type: string
          description: 'The SMTP address for the user, for example, ''jeff@contoso.opencloud.com''. Returned by default.'
        memberOf:
          type: array
          items:
            $ref: '#/components/schemas/group'
          description: 'Groups that this user is a member of. HTTP Methods: GET (supported for all groups). Read-only. Nullable. Supports $expand.'
        onPremisesSamAccountName:
          type: string
          description: 'Contains the on-premises SAM account name synchronized from the on-premises directory. Read-only.'
        passwordProfile:
          $ref: '#/components/schemas/passwordProfile'
        surname:
          type: string
          description: The user's surname (family name or last name). Returned by default.
        givenName:
          type: string
          description: The user's givenName. Returned by default.
        primaryRole:
          type: string
          description: 'The user`s default role. Such as "student" or "teacher"'
        userType:
          type: string
          description: 'The user`s type. This can be either "Member" for regular user, "Guest" for guest users or "Federated" for users imported from a federated instance.'
    drive:
      description: The drive represents a space on the storage.
      required:
        - name
      allOf:
        - $ref: '#/components/schemas/driveUpdate'
    driveUpdate:
      description: The drive represents an update to a space on the storage.
      type: object
      properties:
        # entity
        id:
          type: string
          description: The unique identifier for this drive.
          readOnly: true
        # base item
        createdBy:
          $ref: '#/components/schemas/identitySet'
          description: 'Identity of the user, device, or application which created the item. Read-only.'
          readOnly: true
        createdDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: Date and time of item creation. Read-only.
          format: date-time
          readOnly: true
        description:
          type: string
          description: Provides a user-visible description of the item. Optional.
        eTag:
          type: string
          description: ETag for the item. Read-only.
          readOnly: true
        lastModifiedBy:
          $ref: '#/components/schemas/identitySet'
          description: 'Identity of the user, device, and application which last modified the item. Read-only.'
          readOnly: true
        lastModifiedDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: Date and time the item was last modified. Read-only.
          format: date-time
          readOnly: true
        name:
          type: string
          description: The name of the item. Read-write.
        parentReference:
          $ref: '#/components/schemas/itemReference'
          description: 'Parent information, if the item has a parent. Read-write.'
        webUrl:
          type: string
          description: URL that displays the resource in the browser. Read-only.
          readOnly: true
        # drive
        driveType:
          type: string
          description: Describes the type of drive represented by this resource. Values are "personal" for users home spaces, "project", "virtual" or "share". Read-only.
          readOnly: true
        driveAlias:
          type: string
          description: "The drive alias can be used in clients to make the urls user friendly. Example: 'personal/einstein'. This will be used to resolve to the correct driveID."
        owner:
          $ref: '#/components/schemas/identitySet'
        quota:
          $ref: '#/components/schemas/quota'
        items:
          type: array
          items:
            $ref: '#/components/schemas/driveItem'
          description: All items contained in the drive. Read-only. Nullable.
          readOnly: true
        root:
          $ref: '#/components/schemas/driveItem'
          description: Drive item describing the drive's root. Read-only.
        special:
          type: array
          items:
            $ref: '#/components/schemas/driveItem'
          description: A collection of special drive resources.
        '@libre.graph.hasTrashedItems':
          type: boolean
          description: Indicates whether the drive has items in the trash. Read-only.
          readOnly: true
    driveRecipient:
      type: object
      description: |
        Represents a person, group, or other recipient to share a drive item with using the invite action.

        When using invite to add permissions, the `driveRecipient` object would specify the `email`, `alias`,
        or `objectId` of the recipient. Only one of these values is required; multiple values are not accepted.
      properties:
        #alias:
        #  type: string
        #  description: The alias of the domain object, for cases where an email address is unavailable (e.g. groups).
        #email:
        #  type: string
        #  description: The email address for the recipient, if the recipient has an associated email address.
        objectId:
          type: string
          description: The unique identifier for the recipient in the directory.
        "@libre.graph.recipient.type":
          type: string
          description: When the recipient is referenced by objectId this annotation is used to differentiate `user` and `group` recipients.
          default: user
    identitySet:
      type: object
      description: Optional. User account.
      properties:
        application:
          $ref: '#/components/schemas/identity'
          description: Optional. The application associated with this action.
        device:
          $ref: '#/components/schemas/identity'
          description: Optional. The device associated with this action.
        user:
          $ref: '#/components/schemas/identity'
          description: Optional. The user associated with this action.
        # this is not part of the ms graph api. there, only the sharepointIdentitySet used in grantedToV2 has a group
        group:
          $ref: '#/components/schemas/identity'
          description: Optional. The group associated with this action.
    sharePointIdentitySet:
      type: object
      description: This resource is used to represent a set of identities associated with various events for an item, such as created by or last modified by.
      properties:
        user:
          $ref: '#/components/schemas/identity'
          description: Optional. The user associated with this action.
        group:
          $ref: '#/components/schemas/identity'
          description: Optional. The group associated with this action.

        # unused
        #application:
        #  $ref: '#/components/schemas/identity'
        #  description: Optional. The application associated with this action.

        # unused
        #device:
        #  $ref: '#/components/schemas/identity'
        #  description: Optional. The device associated with this action.
        # other properties omitted for now
    identity:
      type: object
      required:
        - displayName
      properties:
        displayName:
          type: string
          description: 'The identity''s display name. Note that this may not always be available or up to date. For example, if a user changes their display name, the API may show the new value in a future response, but the items associated with the user won''t show up as having changed when using delta.'
        id:
          type: string
          description: Unique identifier for the identity.
        '@libre.graph.userType':
          type: string
          description: 'The type of the identity. This can be either "Member" for regular user, "Guest" for guest users or "Federated" for users imported from a federated instance. Can be used by clients to indicate the type of user. For more details, clients should look up and cache the user at the /users endpoint.'
    invitation:
      type: object
      description: |
        Represents an invitation to a drive item.
      properties:
        invitedUserDisplayName:
          type: string
          description: The display name of the user being invited.
        invitedUserEmailAddress:
          type: string
          description: The email address of the user being invited. Required.
        invitedUserMessageInfo:
          $ref: '#/components/schemas/invitedUserMessageInfo'
          description: Additional information about the invitation message.
        sendInvitationMessage:
          type: boolean
          description: Indicates whether an invitation message should be sent to the user.
        inviteRedirectUrl:
          type: string
          description: The URL to which the user is redirected after accepting the invitation. Required.
        inviteRedeemUrl:
          type: string
          description: The URL that the user can use to redeem the invitation. Read-only.
          readOnly: true
        status:
          type: string
          description: The status of the invitation. Read-only.
          readOnly: true
        invitedUser:
          $ref: '#/components/schemas/user'
          description: The user object of the invited user. Read-only.
          readOnly: true
        invitedUserType:
          type: string
          description: The type of user being invited.
    invitedUserMessageInfo:
      type: object
      description: Additional information about the invitation message.
      properties:
        ccRecipients:
          type: array
          items:
            $ref: '#/components/schemas/recipient'
          description: Additional recipients who will receive a copy of the invitation message.
        customizedMessageBody:
          type: string
          description: The customized message body that will be included in the invitation message.
        messageLanguage:
          type: string
          description: The language of the invitation message.
    recipient:
      type: object
      description: Represents a recipient of an invitation.
      properties:
        emailAddress:
          $ref: '#/components/schemas/emailAddress'
          description: The email address of the recipient.
    emailAddress:
      type: object
      description: Represents an email address.
      properties:
        address:
          type: string
          description: The email address.
        name:
          type: string
          description: The name associated with the email address.

    objectIdentity:
      description: Represents an identity used to sign in to a user account
      type: object
      properties:
        issuer:
          description: domain of the Provider issuing the identity
          type: string
        issuerAssignedId:
          description: The unique id assigned by the issuer to the account
          type: string
    passwordProfile:
      description: Password Profile associated with a user
      type: object
      properties:
        forceChangePasswordNextSignIn:
          type: boolean
          description: If true the user is required to change their password upon the next login
          default: false
        password:
          type: string
          writeOnly: true
          description: The user's password
    sharingLink:
      description: |
        The `SharingLink` resource groups link-related data items into a single structure.

        If a `permission` resource has a non-null `sharingLink` facet, the permission represents a sharing link (as opposed to permissions granted to a person or group).
      type: object
      properties:
        type:
          $ref: '#/components/schemas/sharingLinkType'
        preventsDownload:
          type: boolean
          description: If `true` then the user can only use this link to view the item on the web, and cannot use it to download the contents of the item.
          readOnly: true
        webUrl:
          type: string
          description: A URL that opens the item in the browser on the website.
          readOnly: true
        '@libre.graph.displayName':
          type: string
          description: Provides a user-visible display name of the link. Optional. Libregraph only.
        '@libre.graph.quickLink':
          type: boolean
          description: The quicklink property can be assigned to only one link per resource. A quicklink can be used in the clients to provide a one-click copy to clipboard action. Optional. Libregraph only.
        # unused
        #webHtml:
        #  type: string
        #  description: For `embed` links, this property contains the HTML code for an `<iframe>` element that will embed the item in a webpage.

        # unused
        #application:
        #  description: The app the link is associated with.
        #  $ref: '#/components/schemas/identity'

        # unused
        #scope:
        #  type: string
        #  enum: [anonymous, organization, existingAccess, users]
        #  description: |
        #    The scope of the link represented by this permission. Value `anonymous` indicates the link is usable by anyone, `organization` indicates the link is only usable for users signed into the same tenant.
        #    | Value          | Description                                                                                                           |
        #    | -------------- | --------------------------------------------------------------------------------------------------------------------- |
        #    | anonymous      | Anyone with the link has access, without needing to sign in. This may include people outside of your organization.    |
        #    | organization   | Anyone signed into your organization (tenant) can use the link to get access.                                         |
        #    | existingAccess | Only people who have already been granted access to the item through other means can access the item using this link. |
        #    | users          | The link grants access only to a specific list of people.                                                             |
    signInActivity:
      description: Provides the last successful sign-in attempt for a user
      type: object
      properties:
        lastSuccessfulSignInDateTime:
          type: string
          format: date-time
          description: The date and time of the last successful sign-in for the user.
    user:
      description: Represents an Active Directory user object.
      required:
        - displayName
        - onPremisesSamAccountName
      allOf:
        - $ref: '#/components/schemas/userUpdate'
    userUpdate:
      description: Represents updates to an Active Directory user object.
      type: object
      properties:
        # entity
        id:
          type: string
          description: Read-only.
          readOnly: true
        accountEnabled:
          type: boolean
          description: 'Set to "true" when the account is enabled.'
        appRoleAssignments:
          type: array
          items:
            $ref: '#/components/schemas/appRoleAssignment'
          description: The apps and app roles which this user has been assigned.
          readOnly: true
        displayName:
          type: string
          description: 'The name displayed in the address book for the user. This value is usually the combination of the user''s first name, middle initial, and last name. This property is required when a user is created and it cannot be cleared during updates. Returned by default. Supports $orderby.'
        drives:
          type: array
          items:
            $ref: '#/components/schemas/drive'
          description: A collection of drives available for this user. Read-only.
          maxItems: 100
          readOnly: true
        drive:
          $ref: '#/components/schemas/drive'
          description: The personal drive of this user. Read-only.
          readOnly: true
        identities:
          description: Identities associated with this account.
          type: array
          items:
            $ref: '#/components/schemas/objectIdentity'
        mail:
          type: string
          description: 'The SMTP address for the user, for example, ''jeff@contoso.opencloud.com''. Returned by default.'
        memberOf:
          type: array
          items:
            $ref: '#/components/schemas/group'
          description: 'Groups that this user is a member of. HTTP Methods: GET (supported for all groups). Read-only. Nullable. Supports $expand.'
          readOnly: true
        onPremisesSamAccountName:
          type: string
          description: 'Contains the on-premises SAM account name synchronized from the on-premises directory.'
        passwordProfile:
          $ref: '#/components/schemas/passwordProfile'
        surname:
          type: string
          description: The user's surname (family name or last name). Returned by default.
        givenName:
          type: string
          description: The user's givenName. Returned by default.
        userType:
          type: string
          description: 'The user`s type. This can be either "Member" for regular user, "Guest" for guest users or "Federated" for users imported from a federated instance.'
          readOnly: true
        preferredLanguage:
          $ref: '#/components/schemas/language'
        signInActivity:
          readOnly: true
          $ref: '#/components/schemas/signInActivity'
    itemReference:
      type: object
      properties:
        driveId:
          type: string
          description: Unique identifier of the drive instance that contains the item. Read-only.
          readOnly: true
        driveType:
          type: string
          description: 'Identifies the type of drive. See [drive][] resource for values. Read-only.'
          readOnly: true
        id:
          type: string
          description: Unique identifier of the item in the drive. Read-only.
          readOnly: true
        name:
          type: string
          description: The name of the item being referenced. Read-only.
          readOnly: true
        path:
          type: string
          description: Path that can be used to navigate to the item. Read-only.
          readOnly: true
        # unused. this is the token but we reference shares, even links, by id
        #shareId:
        #  type: string
        #  description: 'A unique identifier for a shared resource that can be accessed via the [Shares][] API.'
    language:
      # https://www.rfc-editor.org/rfc/rfc2798.html#section-2.7
      # https://www.rfc-editor.org/rfc/rfc2068#section-14.4
      description: 'Represents the users language setting, ISO-639-1 Code'
      readOnly: false
      type: string
    activity:
      description: Represents activity.
      type: object
      required:
        - id
        - times
        - template
      properties:
        id:
          type: string
          description: Activity ID.
        times:
          type: object
          required:
            - recordedTime
          properties:
            recordedTime:
              type: string
              format: date-time
              description: Timestamp of the activity.
        template:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: Activity description.
            variables:
              type: object
              description: Activity description variables.
    driveItem:
      description: Represents a resource inside a drive. Read-only.
      readOnly: true
      type: object
      properties:
        # entity
        id:
          type: string
          description: Read-only.
          readOnly: true
        # base item
        createdBy:
          $ref: '#/components/schemas/identitySet'
          description: 'Identity of the user, device, or application which created the item. Read-only.'
          readOnly: true
        createdDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: Date and time of item creation. Read-only.
          format: date-time
          readOnly: true
        description:
          type: string
          description: Provides a user-visible description of the item. Optional.
        eTag:
          type: string
          description: ETag for the item. Read-only.
          readOnly: true
        lastModifiedBy:
          $ref: '#/components/schemas/identitySet'
          description: 'Identity of the user, device, and application which last modified the item. Read-only.'
          readOnly: true
        lastModifiedDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: Date and time the item was last modified. Read-only.
          format: date-time
          readOnly: true
        name:
          type: string
          description: The name of the item. Read-write.
        parentReference:
          $ref: '#/components/schemas/itemReference'
          description: 'Parent information, if the item has a parent. Read-write.'
        webUrl:
          type: string
          description: URL that displays the resource in the browser. Read-only.
          readOnly: true
        # driveItem
        content:
          type: string
          description: 'The content stream, if the item represents a file.'
          format: base64url
        cTag:
          type: string
          description: An eTag for the content of the item. This eTag is not changed if only the metadata is changed. Note This property is not returned if the item is a folder. Read-only.
          readOnly: true
        deleted:
          $ref: '#/components/schemas/deleted'
        file:
          $ref: '#/components/schemas/openGraphFile'
        fileSystemInfo:
          $ref: '#/components/schemas/fileSystemInfo'
        folder:
          $ref: '#/components/schemas/folder'
        image:
          $ref: '#/components/schemas/image'
        photo:
          description: Photo metadata, if the item is a photo. Read-only.
          $ref: '#/components/schemas/photo'
        location:
          description: Location metadata, if the item has location data. Read-only.
          $ref: '#/components/schemas/geoCoordinates'
        thumbnails:
          description: Collection containing ThumbnailSet objects associated with the item. Read-only. Nullable.
          type: array
          items:
            $ref: '#/components/schemas/thumbnailSet'
        root:
          $ref: '#/components/schemas/root'
        trash:
          $ref: '#/components/schemas/trash'
        specialFolder:
          $ref: '#/components/schemas/specialFolder'
        remoteItem:
          $ref: '#/components/schemas/remoteItem'
        size:
          type: integer
          description: Size of the item in bytes. Read-only.
          format: int64
          readOnly: true
        webDavUrl:
          type: string
          description: WebDAV compatible URL for the item. Read-only.
          readOnly: true
        children:
          type: array
          items:
            $ref: '#/components/schemas/driveItem'
          description: Collection containing Item objects for the immediate children of Item. Only items representing folders have children. Read-only. Nullable.
          readOnly: true
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/permission'
          description: The set of permissions for the item. Read-only. Nullable.
          readOnly: true
        audio:
          description: Audio metadata, if the item is an audio file. Read-only.
          $ref: '#/components/schemas/audio'
        video:
          description: Video metadata, if the item is a video. Read-only.
          $ref: '#/components/schemas/video'
        '@client.synchronize':
          description: Indicates if the item is synchronized with the underlying storage provider. Read-only.
          type: boolean
        # follows the SAP UI vocabulary: https://github.com/SAP/odata-vocabularies/blob/main/vocabularies/UI.md
        '@UI.Hidden':
          description: Properties or facets (see UI.Facet) annotated with this term will not be rendered if the annotation evaluates to true. Users can set this to hide permissions.
          type: boolean
        extensions:
          description: The collection of open extensions defined for this DriveItem. Nullable. Returned only on `$expand`.
          type: array
          items:
            $ref: '#/components/schemas/openTypeExtension'
          readOnly: true
    sharingLinkType:
      type: string
      enum: [ internal, view, upload, edit, createOnly, blocksDownload ]
      description: |
        The type of the link created.

        | Value          | Display name      | Description                                                     |
        | -------------- | ----------------- | --------------------------------------------------------------- |
        | internal       | Internal          | Creates an internal link without any permissions.               |
        | 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. |
      # there are more link types available in https://learn.microsoft.com/en-us/graph/api/driveitem-createlink?view=graph-rest-beta&tabs=http#link-types
      #  | review         | Creates a review link to the driveItem.                                                                                                                                                                               |
      #  | embed          | Creates an embeddable link to the driveItem.                                                                                                                                                                          |
      #  | addressBar     | Creates the default link that is shown in the browser address bars for newly created files. The organization admin configures whether this link type is supported, and what features are supported by this link type. |
      #  | adminDefault   | Creates the default link to the driveItem as determined by the administrator of the organization. The policy is enforced for the organization by the admin                                                            |
    driveItemCreateLink:
      type: object
      properties:
        type:
          $ref: '#/components/schemas/sharingLinkType'
        expirationDateTime:
          type: string
          description: Optional. A String with format of yyyy-MM-ddTHH:mm:ssZ of DateTime indicates the expiration time of the permission.
          format: date-time
        password:
          type: string
          description: Optional.The password of the sharing link that is set by the creator.
        displayName:
          type: string
          description: Provides a user-visible display name of the link. Optional. Libregraph only.
        '@libre.graph.quickLink':
          type: boolean
          description: The quicklink property can be assigned to only one link per resource. A quicklink can be used in the clients to provide a one-click copy to clipboard action. Optional. Libregraph only.
        # unused. we could add this to invite guests or specify which users should be sent the link
        #recipients:
        #  type: array
        #  items:
        #    $ref: '#/components/schemas/driveRecipient'
        #  description: A collection of recipients who will receive access and the sharing link.

        # unused. can be added later
        #scope:
        #  type: string
        #  description: Optional. The scope of link to create. Either `anonymous`, `organization`, or `users`.

        # unused. In opencloud recipients configure if they want to be notified
        #sendNotification:
        #  type: boolean
        #  description: Optional. If `true`, this method sends a sharing link in an email to users specified in recipients. The default value is `false`. Optional.

        # unused. not supported by opencloud
        #retainInheritedPermissions:
        #  type: boolean
        #  description: Optional. If `true` (default), any existing inherited permissions are retained on the shared item when sharing this item for the first time. If `false`, all existing permissions are removed when sharing for the first time.
    driveItemInvite:
      type: object
      properties:
        recipients:
          type: array
          items:
            $ref: '#/components/schemas/driveRecipient'
          description: A collection of recipients who will receive access and the sharing invitation. Currently, only internal users or groups are supported.
        roles:
          type: array
          items:
            type: string
          description: Specifies the roles that are to be granted to the recipients of the sharing invitation.
        '@libre.graph.permissions.actions':
          type: array
          items:
            type: string
          description: Specifies the actions that are to be granted to the recipients of the sharing invitation, in effect creating a custom role.
        expirationDateTime:
          type: string
          description: Specifies the dateTime after which the permission expires.
          format: date-time

        # Can be added later
        #message:
        #  type: string
        #  description: A plain text formatted message that is included in the sharing invitation.
        #  maxLength: 2000

        # Internal shares always require login
        #requireSignIn:
        #  type: boolean
        #  description: Specifies whether the recipient of the invitation is required to sign-in to view the shared item.

        # In opencloud recipients configure if they want to be notified
        #sendInvitation:
        #  type: boolean
        #  description: If `true`, a sharing link is sent to the recipient. Otherwise, a permission is granted directly without sending a notification.

        # internal shares do not have a password
        #password:
        #  type: string
        #  description: The password set on the invite by the creator. Optional.

        # not supported by opencloud
        #retainInheritedPermissions:
        #  type: boolean
        #  description: Optional. If `true` (default), any existing inherited permissions are retained on the shared item when sharing this item for the first time. If `false`, all existing permissions are removed when sharing for the first time.
    deleted:
      type: object
      description: Information about the deleted state of the item. Read-only.
      readOnly: true
      properties:
        state:
          type: string
          description: Represents the state of the deleted item.
    openGraphFile:
      type: object
      description: 'File metadata, if the item is a file. Read-only.'
      readOnly: true
      properties:
        hashes:
          $ref: '#/components/schemas/hashes'
        mimeType:
          type: string
          description: The MIME type for the file. This is determined by logic on the server and might not be the value provided when the file was uploaded. Read-only.
          readOnly: true
        processingMetadata:
          type: boolean
    fileSystemInfo:
      type: object
      description: File system information on client. Read-write.
      properties:
        createdDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: The UTC date and time the file was created on a client.
          format: date-time
        lastAccessedDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: The UTC date and time the file was last accessed. Available for the recent file list only.
          format: date-time
        lastModifiedDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: The UTC date and time the file was last modified on a client.
          format: date-time
    folder:
      type: object
      description: 'Folder metadata, if the item is a folder. Read-only.'
      readOnly: true
      properties:
        childCount:
          maximum: 2147483647
          type: integer
          description: Number of children contained immediately within this container.
          format: int32
        view:
          $ref: '#/components/schemas/folderView'
    image:
      type: object
      description: 'Image metadata, if the item is an image. Read-only.'
      readOnly: true
      properties:
        height:
          maximum: 2147483647
          type: integer
          description: 'Optional. Height of the image, in pixels. Read-only.'
          format: int32
          readOnly: true
        width:
          maximum: 2147483647
          type: integer
          description: 'Optional. Width of the image, in pixels. Read-only.'
          format: int32
          readOnly: true
    photo:
      type: object
      readOnly: true
      description: |
        The photo resource provides photo and camera properties, for example, EXIF metadata, on a driveItem.
      properties:
        cameraMake:
          type: string
          description: Camera manufacturer. Read-only.
        cameraModel:
          type: string
          description: Camera model. Read-only.
        exposureDenominator:
          type: number
          format: double
          description: The denominator for the exposure time fraction from the camera. Read-only.
        exposureNumerator:
          type: number
          format: double
          description: The numerator for the exposure time fraction from the camera. Read-only.
        fNumber:
          type: number
          format: double
          description: The F-stop value from the camera. Read-only.
        focalLength:
          type: number
          format: double
          description: The focal length from the camera. Read-only.
        iso:
          type: integer
          format: int32
          description: The ISO value from the camera. Read-only.
        orientation:
          type: integer
          format: int16
          description: The orientation value from the camera. Read-only.
        takenDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          format: date-time
          description: Represents the date and time the photo was taken. Read-only.
    geoCoordinates:
      type: object
      readOnly: true
      description: |
        The GeoCoordinates resource provides geographic coordinates and elevation of a location based on metadata contained within the file.
        If a DriveItem has a non-null location facet, the item represents a file with a known location associated with it.
      properties:
        altitude:
          type: number
          format: double
          description: The altitude (height), in feet, above sea level for the item. Read-only.
        latitude:
          type: number
          format: double
          description: The latitude, in decimal, for the item. Read-only.
        longitude:
          type: number
          format: double
          description: The longitude, in decimal, for the item. Read-only.
    thumbnail:
      type: object
      readOnly: true
      description: |
        The thumbnail resource type represents a thumbnail for an image, video, document, or any item that has a bitmap representation.
      properties:
        content:
          type: string
          format: base64url
          description: The content stream for the thumbnail.
        height:
          type: integer
          format: int32
          description: The height of the thumbnail, in pixels.
        sourceItemId:
          type: string
          description: The unique identifier of the item that provided the thumbnail. This is only available when a folder thumbnail is requested.
        url:
          type: string
          description: The URL used to fetch the thumbnail content.
        width:
          type: integer
          format: int32
          description: The width of the thumbnail, in pixels.
    thumbnailSet:
      type: object
      readOnly: true
      description: |
        The ThumbnailSet resource is a keyed collection of thumbnail resources.
        It's used to represent a set of thumbnails associated with a DriveItem.
      properties:
        id:
          type: string
          description: The ID within the item. Read-only.
        large:
          $ref: '#/components/schemas/thumbnail'
          description: A 1920x1920 scaled thumbnail.
        medium:
          $ref: '#/components/schemas/thumbnail'
          description: A 176x176 scaled thumbnail.
        small:
          $ref: '#/components/schemas/thumbnail'
          description: A 48x48 cropped thumbnail.
        source:
          $ref: '#/components/schemas/thumbnail'
          description: A custom thumbnail image or the original image used to generate other thumbnails.
    root:
      type: object
      description: 'If this property is non-null, it indicates that the driveItem is the top-most driveItem in the drive.'
    trash:
      type: object
      description: 'Metadata for trashed drive Items'
      readOnly: true
      properties:
        trashedBy:
          $ref: '#/components/schemas/identitySet'
          description: 'Identity of the user, device, or application which trashed the item. Read-only.'
          readOnly: true
        trashedDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: The UTC date and time the folder was marked as trashed.
          format: date-time
    specialFolder:
      type: object
      description: 'If the current item is also available as a special folder, this facet is returned. Read-only'
      readOnly: true
      properties:
        name:
          type: string
          description: The unique identifier for this item in the /drive/special collection
    remoteItem:
      title: remoteItem
      description: 'Remote item data, if the item is shared from a drive other than the one being accessed. Read-only.'
      type: object
      properties:
        createdBy:
          $ref: '#/components/schemas/identitySet'
        createdDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: Date and time of item creation. Read-only.
          format: date-time
        file:
          $ref: '#/components/schemas/openGraphFile'
        fileSystemInfo:
          $ref: '#/components/schemas/fileSystemInfo'
        folder:
          $ref: '#/components/schemas/folder'
        driveAlias:
          type: string
          description: "The drive alias can be used in clients to make the urls user friendly. Example: 'personal/einstein'. This will be used to resolve to the correct driveID."
        #driveType:
        # wie kommt man zum drive? web möchte im ui den pfad anzeigen, der wird aus dem driveAlias gebaut, aber die brauchen auch den driveType um das datenmodell konsistent zu haben
        # momentan machen sie einen ocs list shares request und sichen sich dann den mountpoint anhand der id raus, aber einige möchten IMMER den personal space dazu sehen, incl pfad
        path:
          type: string
          description: "The relative path of the item in relation to its drive root."
        rootId:
          type: string
          description: Unique identifier for the drive root of this item. Read-only.
        id:
          type: string
          description: Unique identifier for the remote item in its drive. Read-only.
        image:
          $ref: '#/components/schemas/image'
        lastModifiedBy:
          $ref: '#/components/schemas/identitySet'
        lastModifiedDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: Date and time the item was last modified. Read-only.
          format: date-time
        name:
          type: string
          description: Optional. Filename of the remote item. Read-only.
        eTag:
          type: string
          description: ETag for the item. Read-only.
          readOnly: true
        cTag:
          type: string
          description: An eTag for the content of the item. This eTag is not changed if only the metadata is changed. Note This property is not returned if the item is a folder. Read-only.
          readOnly: true
        parentReference:
          $ref: '#/components/schemas/itemReference'
        permissions:
          type: array
          items:
            $ref: '#/components/schemas/permission'
          description: The set of permissions for the item. Read-only. Nullable.
          readOnly: true
        size:
          type: integer
          description: Size of the remote item. Read-only.
          format: int64
        specialFolder:
          $ref: '#/components/schemas/specialFolder'
        webDavUrl:
          type: string
          description: DAV compatible URL for the item.
        webUrl:
          type: string
          description: URL that displays the resource in the browser. Read-only.
          title: shared
    quota:
      type: object
      description: Optional. Information about the drive's storage space quota. Read-only.
      readOnly: true
      properties:
        deleted:
          type: integer
          description: 'Total space consumed by files in the recycle bin, in bytes. Read-only.'
          format: int64
          readOnly: true
        remaining:
          type: integer
          description: 'Total space remaining before reaching the quota limit, in bytes. Read-only.'
          format: int64
          readOnly: true
        state:
          type: string
          description: Enumeration value that indicates the state of the storage space. Either "normal", "nearing", "critical" or "exceeded". Read-only.
          readOnly: true
        total:
          type: integer
          description: 'Total allowed storage space, in bytes. Read-only.'
          format: int64
          readOnly: true
        used:
          type: integer
          description: 'Total space used, in bytes. Read-only.'
          format: int64
          readOnly: true
    hashes:
      type: object
      description: 'Hashes of the file''s binary content, if available. Read-only.'
      readOnly: true
      properties:
        crc32Hash:
          type: string
          description: The CRC32 value of the file (if available). Read-only.
          maxLength: 8
        quickXorHash:
          type: string
          description: A proprietary hash of the file that can be used to determine if the contents of the file have changed (if available). Read-only.
        sha1Hash:
          type: string
          description: SHA1 hash for the contents of the file (if available). Read-only.
          maxLength: 40
        sha256Hash:
          type: string
          description: SHA256 hash for the contents of the file (if available). Read-only.
          maxLength: 160
    folderView:
      type: object
      description: A collection of properties defining the recommended view for the folder.
      properties:
        sortBy:
          type: string
          description: The method by which the folder should be sorted.
        sortOrder:
          type: string
          description: 'If true, indicates that items should be sorted in descending order. Otherwise, items should be sorted ascending.'
        viewType:
          type: string
          description: The type of view that should be used to represent the folder.
    group:
      type: object
      title: group
      properties:
        # entity
        id:
          type: string
          description: Read-only.
          readOnly: true
        description:
          type: string
          description: 'An optional description for the group. Returned by default.'
        displayName:
          type: string
          description: 'The display name for the group. This property is required when a group is created and cannot be cleared during updates. Returned by default. Supports $search and $orderBy.'
        groupTypes:
          description: 'Specifies the group types. In MS Graph a group can have multiple types, so this is an array. In libreGraph the possible group types deviate from the MS Graph. The only group type that we currently support is "ReadOnly", which is set for groups that cannot be modified on the current instance.'
          type: array
          items:
            type: string
        members:
          type: array
          items:
            $ref: '#/components/schemas/user'
          description: 'Users and groups that are members of this group. HTTP Methods: GET (supported for all groups), Nullable. Supports $expand.'
        'members@odata.bind':
          type: array
          items:
            type: string
          uniqueItems: true
          minItems: 1
          maxItems: 20
          description: A list of member references to the members to be added. Up to 20 members can be added with a single request
    permission:
      type: object
      description: |
        The Permission resource provides information about a sharing permission granted for a DriveItem resource.

        ### Remarks

        The Permission resource uses *facets* to provide information about the kind of permission represented by the resource.

        Permissions with a `link` facet represent sharing links created on the item. Sharing links contain a unique token that provides access to the item for anyone with the link.

        Permissions with a `invitation` facet represent permissions added by inviting specific users or groups to have access to the file.
      readOnly: true
      properties:
        id:
          type: string
          description: The unique identifier of the permission among all permissions on the item. Read-only.
          readOnly: true
        hasPassword:
          type: boolean
          description: |
            Indicates whether the password is set for this permission. This property only
            appears in the response. Optional. Read-only.
          readOnly: true
        expirationDateTime:
          type: string
          description: An optional expiration date which limits the permission in time.
          format: date-time
          nullable: true
        createdDateTime:
          type: string
          description: An optional creation date. Libregraph only.
          format: date-time
          nullable: true
        grantedToV2:
          # this is always a single identity set because a permission always is tied to a single recipient (which can be a group).
          description: For user type permissions, the details of the users and applications for this permission. Only part of responses. Use the invitation property when creating shares.
          $ref: '#/components/schemas/sharePointIdentitySet'
        link:
          description: Provides the link details of the current permission, if it is a link type permissions.
          $ref: '#/components/schemas/sharingLink'
        roles:
          type: array
          items:
            type: string
        grantedToIdentities:
          deprecated: true
          description: For link type permissions, the details of the identity to whom permission was granted. This could be used to grant access to a an external user that can be identified by email, aka guest accounts.
          type: array
          items:
            $ref: '#/components/schemas/identitySet'
        '@libre.graph.permissions.actions':
          description: Use this to create a permission with custom actions.
          type: array
          items:
            type: string
        invitation:
          description: |
            Details of any associated sharing invitation for this permission.
          $ref: '#/components/schemas/sharingInvitation'

        # unused. We could put public link token in here, but we currently only need the link property, anyway
        #shareId:
        #  description: A unique token that can be used to access this shared item via the shares API.
        #  readOnly: true
        #  type: string

        # unused. We could use grantedToIdentitiesV2 to share with guest or external members. 'Identities' here means that an external user is identified by an email aka a guest.
        #grantedToIdentitiesV2:
        #  description: For link type permissions, the details of the users to whom permission was granted. Read-only.
        #  type: array
        #  items:
        #    $ref: '#/components/schemas/sharePointIdentitySet'

        # unused. invites are created with the driveItemInvite resource
    sharingInvitation:
      type: object
      description: |
        invitation-related data items
      properties:
        invitedBy:
          description: Provides information about who sent the invitation that created this permission, if that information is available. Read-only.
          $ref: '#/components/schemas/identitySet'
    sharingLinkPassword:
      type: object
      description: |
        The sharing link password which should be set.
      properties:
        password:
          type: string
          description: Password. It may require a password policy.
    openTypeExtension:
      type: object
      description: |
        Represents an open extension on a DriveItem, providing a flexible way to attach
        untyped custom data to a resource.

        Extensions are identified by their `extensionName`, which should follow reverse DNS
        naming conventions (e.g. `com.example.myApp`) to avoid collisions between applications.
      properties:
        extensionName:
          type: string
          description: |
            The unique identifier of the extension. Use reverse DNS naming conventions
            (e.g. `com.example.myApp`).
          readOnly: true
      additionalProperties: true
      example:
        extensionName: "com.example.project"
        status: "reviewed"
        assignee: "alice"
        priority: 3
    openTypeExtensionUpdate:
      type: object
      description: |
        Properties to set or remove on an open extension.

        * Properties included in the request body are added or updated.
        * Properties set to `null` are removed from the extension.
        * Properties not included in the request body remain unchanged.
      additionalProperties:
        nullable: true
      example:
        status: "approved"
        priority: null
    audio:
      type: object
      description: |
        The Audio resource groups audio-related properties on an item into a single structure.

        If a DriveItem has a non-null audio facet, the item represents an audio file. The properties of the Audio resource are populated by extracting metadata from the file.
      properties:
        album:
          type: string
          description: The title of the album for this audio file.
        albumArtist:
          type: string
          description: The artist named on the album for the audio file.
        artist:
          type: string
          description: The performing artist for the audio file.
        bitrate:
          type: integer
          format: int64
          description: Bitrate expressed in kbps.
        composers:
          type: string
          description: The name of the composer of the audio file.
        copyright:
          type: string
          description: Copyright information for the audio file.
        disc:
          type: integer
          format: int16
          description: The number of the disc this audio file came from.
        discCount:
          type: integer
          format: int16
          description: The total number of discs in this album.
        duration:
          type: integer
          format: int64
          description: Duration of the audio file, expressed in milliseconds
        genre:
          type: string
          description: The genre of this audio file.
        hasDrm:
          type: boolean
          description: Indicates if the file is protected with digital rights management.
        isVariableBitrate:
          type: boolean
          description: Indicates if the file is encoded with a variable bitrate.
        title:
          type: string
          description: The title of the audio file.
        track:
          type: integer
          format: int32
          description: The number of the track on the original disc for this audio file.
        trackCount:
          type: integer
          format: int32
          description: The total number of tracks on the original disc for this audio file.
        year:
          type: integer
          format: int32
          description: The year the audio file was recorded.
    video:
      type: object
      description: |
        The video resource groups video-related data items into a single structure.

        If a driveItem has a non-null video facet, the item represents a video file. The properties of the video resource are populated by extracting metadata from the file.
      properties:
        audioBitsPerSample:
          type: integer
          format: int32
          description: Number of audio bits per sample.
        audioChannels:
          type: integer
          format: int32
          description: Number of audio channels.
        audioFormat:
          type: string
          description: Name of the audio format (AAC, MP3, etc.).
        audioSamplesPerSecond:
          type: integer
          format: int32
          description: Number of audio samples per second.
        bitrate:
          type: integer
          format: int32
          description: Bit rate of the video in bits per second.
        duration:
          type: integer
          format: int64
          description: Duration of the file in milliseconds.
        fourCC:
          type: string
          description: \"Four character code\" name of the video format.
        frameRate:
          type: number
          format: double
          description: Frame rate of the video.
        height:
          type: integer
          format: int32
          description: Height of the video, in pixels.
        width:
          type: integer
          format: int32
          description: Width of the video, in pixels.
    unifiedRoleDefinition:
      type: object
      description: |
        A role definition is a collection of permissions in libre graph listing the operations that can be performed
        and the resources against which they can performed.
      properties:
        description:
          description: The description for the unifiedRoleDefinition.
          #description: The description for the unifiedRoleDefinition. Read-only when **isBuiltIn** is `true`.
          type: string
        displayName:
          description: The display name for the unifiedRoleDefinition. Required. Supports $filter (`eq`, `in`).
          #description: The display name for the unifiedRoleDefinition. Read-only when **isBuiltIn** is `true`. Required. Supports $filter (`eq`, `in`).
          type: string
        id:
          description: The unique identifier for the role definition. Key, not nullable, Read-only. Inherited from entity. Supports $filter (`eq`, `in`).
          type: string
        rolePermissions:
          description: List of permissions included in the role.
          #description: List of permissions included in the role. Read-only when **isBuiltIn** is `true`.
          type: array
          items:
            $ref: '#/components/schemas/unifiedRolePermission'
        # follows the hugo weight
        '@libre.graph.weight':
          description: |
            When presenting a list of roles the weight can be used to order them in a meaningful way.
            Lower weight gets higher precedence. So content with lower weight will come first. If set,
            weights should be non-zero, as 0 is interpreted as an unset weight.
          type: integer

        # unused.
        #isBuiltIn:
        #  description: Flag indicating whether the role definition is part of the default set included in libre graph or a custom definition. Read-only. Supports $filter (`eq`, `in`).
        #  type: boolean

        # unused.
        #isEnabled:
        #  description: Flag indicating whether the role is enabled for assignment. If `false` the role is not available for assignment. Read-only when **isBuiltIn** is `true`.
        #  type: boolean

        # unused. already deprecated in msgraph and I do not think we need it right now
        #resourceScopes:
        #  type: string
        #  description: |
        #    List of the scopes or permissions the role definition applies to. Currently only / is supported.
        #    Read-only when isBuiltIn is true. DO NOT USE. This will be deprecated soon. Attach scope to role assignment.

        # unused. only useful for custom role definitions
        #templateId:
        #  description: |
        #    Custom template identifier that can be set when isBuiltIn is `false` but is read-only when isBuiltIn is `true`.
        #    This identifier is typically used if one needs an identifier to be the same across different directories.
        #  type: string

        # unused. only needed when versioning custom role definitions
        #version:
        #  description: Indicates version of the role definition. Read-only when **isBuiltIn** is `true`.
        #  type: string
    unifiedRolePermission:
      type: object
      description: |
        Represents a collection of allowed resource actions and the conditions that must be met for the action to be allowed.
        Resource actions are tasks that can be performed on a resource. For example, an application resource may support
        create, update, delete, and reset password actions.
      properties:
        allowedResourceActions:
          description: |
            Set of tasks that can be performed on a resource. Required.

            The following is the schema for resource actions:

            ```
               {Namespace}/{Entity}/{PropertySet}/{Action}
            ```

             For example: `libre.graph/applications/credentials/update`

             * *{Namespace}* - The services that exposes the task. For example, all tasks in libre graph use the namespace `libre.graph`.
             * *{Entity}* - The logical features or components exposed by the service in libre graph. For example, `applications`, `servicePrincipals`, or `groups`.
             * *{PropertySet}* - Optional. The specific properties or aspects of the entity for which access is being granted.
               For example, `libre.graph/applications/authentication/read` grants the ability to read the reply URL, logout URL,
               and implicit flow property on the **application** object in libre graph. The following are reserved names for common property sets:
               * `allProperties` - Designates all properties of the entity, including privileged properties.
                 Examples include `libre.graph/applications/allProperties/read` and `libre.graph/applications/allProperties/update`.
               * `basic` - Designates common read properties but excludes privileged ones.
                 For example, `libre.graph/applications/basic/update` includes the ability to update standard properties like display name.
               * `standard` - Designates common update properties but excludes privileged ones.
                 For example, `libre.graph/applications/standard/read`.
             * *{Actions}* - The operations being granted. In most circumstances, permissions should be expressed in terms of CRUD operations or allTasks. Actions include:
               * `create` - The ability to create a new instance of the entity.
               * `read` - The ability to read a given property set (including allProperties).
               * `update` - The ability to update a given property set (including allProperties).
               * `delete` - The ability to delete a given entity.
               * `allTasks` - Represents all CRUD operations (create, read, update, and delete).

             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` |

             Managing drives would be a different entity. A space manager role could be written as `libre.graph/drive/permission/allTasks`.

          # microsoft.directory namespace has these built in roles and permissions: https://learn.microsoft.com/en-us/azure/active-directory/roles/permissions-reference
          type: array
          items:
            type: string
        condition:
          description: |
            Optional constraints that must be met for the permission to be effective. Not supported for custom roles.

            Conditions define constraints that must be met. For example, a requirement that target resource must have a certain property.
            The following are the supported conditions:

            * Drive: `exists @Resource.Drive` - The target resource must be a drive/space
            * Folder: `exists @Resource.Folder` - The target resource must be a folder
            * File: `exists @Resource.File` - The target resource must be a file

            The following is an example of a role permission with a condition that the target resource is a folder:
            ```json
              "rolePermissions": [
                  {
                      "allowedResourceActions": [
                          "libre.graph/applications/basic/update",
                          "libre.graph/applications/credentials/update"
                      ],
                      "condition":  "exists @Resource.File"
                  }
              ]
            ```
            Conditions aren't supported for custom roles.
          type: string

        # unused. not even supported in ms graph
        #excludedResourceActions:
        #  description: Set of tasks that may not be performed on a resource. Not yet supported.
        #  type: array
        #  items:
        #    type: string
    odata.error:
      required:
        - error
      type: object
      properties:
        error:
          $ref: '#/components/schemas/odata.error.main'
    odata.error.main:
      required:
        - code
        - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type: string
        details:
          type: array
          items:
            $ref: '#/components/schemas/odata.error.detail'
        innererror:
          type: object
          description: The structure of this object is service-specific
    odata.error.detail:
      required:
        - code
        - message
      type: object
      properties:
        code:
          type: string
        message:
          type: string
        target:
          type: string
    appRole:
      title: appRole
      required:
        - id
      type: object
      properties:
        allowedMemberTypes:
          type: array
          items:
            type: string
          description: 'Specifies whether this app role can be assigned to users and groups (by setting to [''User'']), to other application''s (by setting to [''Application''], or both (by setting to [''User'', ''Application'']). App roles supporting assignment to other applications'' service principals are also known as application permissions. The ''Application'' value is only supported for app roles defined on application entities.'
        description:
          type: string
          description: 'The description for the app role. This is displayed when the app role is being assigned and, if the app role functions as an application permission, during  consent experiences.'
          nullable: true
        displayName:
          type: string
          description: Display name for the permission that appears in the app role assignment and consent experiences.
          nullable: true
        id:
          pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
          type: string
          description: 'Unique role identifier inside the appRoles collection. When creating a new app role, a new GUID identifier must be provided.'
          format: uuid
    appRoleAssignment:
      type: object
      required:
        - appRoleId
        - principalId
        - resourceId
      properties:
        # entity
        id:
          type: string
          description: The unique identifier for the object. 12345678-9abc-def0-1234-56789abcde. The value of the ID property is often, but not exclusively, in the form of a GUID. The value should be treated as an opaque identifier and not based in being a GUID. Null values are not allowed. Read-only.
          readOnly: true
        # directory object
        deletedDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])[Tt]([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?([Zz]|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          format: date-time
        appRoleId:
          pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
          type: string
          description: 'The identifier (id) for the app role which is assigned to the user. Required on create.'
          format: uuid
        createdDateTime:
          pattern: '^[0-9]{4,}-(0[1-9]|1[012])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]([.][0-9]{1,12})?(Z|[+-][0-9][0-9]:[0-9][0-9])$'
          type: string
          description: 'The time when the app role assignment was created. The Timestamp type represents date and time information using ISO 8601 format and is always in UTC time. For example, midnight UTC on Jan 1, 2014 is 2014-01-01T00:00:00Z. Read-only.'
          format: date-time
          nullable: true
        principalDisplayName:
          type: string
          description: 'The display name of the user, group, or service principal that was granted the app role assignment. Read-only.'
          nullable: true
        principalId:
          pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
          type: string
          description: 'The unique identifier (id) for the user, security group, or service principal being granted the app role. Security groups with dynamic memberships are supported. Required on create.'
          format: uuid
          nullable: true
        principalType:
          type: string
          description: 'The type of the assigned principal. This can either be User, Group, or ServicePrincipal. Read-only.'
          nullable: true
        resourceDisplayName:
          type: string
          description: The display name of the resource app's service principal to which the assignment is made.
          nullable: true
        resourceId:
          pattern: '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$'
          type: string
          description: The unique identifier (id) for the resource service principal for which the assignment is made. Required on create.
          format: uuid
          nullable: true
    application:
      type: object
      required:
        - id
      properties:
        # entity
        id:
          type: string
          description: The unique identifier for the object. 12345678-9abc-def0-1234-56789abcde. The value of the ID property is often, but not exclusively, in the form of a GUID. The value should be treated as an opaque identifier and not based in being a GUID. Null values are not allowed. Read-only.
          readOnly: true
        # properties
        appRoles:
          type: array
          description: 'The collection of roles defined for the application. With app role assignments, these roles can be assigned to users, groups, or service principals associated with other applications. Not nullable.'
          items:
            $ref: '#/components/schemas/appRole'
          nullable: false
        displayName:
          type: string
          description: 'The display name for the application.'
          nullable: true
  responses:
    error:
      description: error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/odata.error'
  parameters:
    top:
      name: $top
      in: query
      description: Show only the first n items
      schema:
        minimum: 0
        type: integer
      example: 50
    skip:
      name: $skip
      in: query
      description: Skip the first n items
      schema:
        minimum: 0
        type: integer
    search:
      name: $search
      in: query
      description: Search items by search phrases
      schema:
        type: string
    drivesFilter:
      name: $filter
      in: query
      description: Filter items by property values
      schema:
        type: string
      examples:
        filter by type:
          value: driveType eq 'project'
        filter by id:
          value: id eq 'uuid'
    drivesSelect:
      name: $select
      in: query
      description: Select properties to be returned. By default all properties are returned.
      style: form
      explode: false
      schema:
        uniqueItems: true
        type: array
        items:
          enum:
            - '@libre.graph.hasTrashedItems'
          type: string
    drivesExpand:
      name: $expand
      in: query
      description: Expand related entities
      schema:
        type: string
      examples:
        expand drive permissions:
          value: root($expand=permissions)
    usersFilter:
      name: $filter
      in: query
      description: Filter users by property values and relationship attributes
      schema:
        type: string
      examples:
        list all user of a group:
          value: memberOf/any(x:x/id eq 910367f9-4041-4db1-961b-d1e98f708eaf)
        list all users that are a member of both groups:
          value: memberOf/any(x:x/id eq 910367f9-4041-4db1-961b-d1e98f708eaf) and memberOf/any(x:x/id eq 4cceeace-b8ca-472a-9788-e73da11de14c)
        list all users that are a member of either one or both groups:
          value: memberOf/any(x:x/id eq 910367f9-4041-4db1-961b-d1e98f708eaf) or memberOf/any(x:x/id eq 4cceeace-b8ca-472a-9788-e73da11de14c)
        list all users with a specific role assigned:
          value: appRoleAssignments/any(x:x/appRoleId eq 910367f9-4041-4db1-961b-d1e98f708eaf)
        list all users that are a member of the group and have a specific role assigned:
          value: appRoleAssignments/any(x:x/appRoleId eq 910367f9-4041-4db1-961b-d1e98f708eaf) and memberOf/any(x:x/id eq 4cceeace-b8ca-472a-9788-e73da11de14c)
        list all users that are a member of any of groups and have a specific role assigned:
          value: (memberOf/any(x:x/id eq 910367f9-4041-4db1-961b-d1e98f708eaf) or memberOf/any(x:x/id eq 4cceeace-b8ca-472a-9788-e73da11de14c)) and appRoleAssignments/any(x:x/appRoleId eq 910367f9-4041-4db1-961b-d1e98f708eaf)
    permissionsFilter:
      name: $filter
      in: query
      description: Filter items by property values. By default all permissions are returned and the avalable sharing roles are limited to normal users. To get a list of sharing roles applicable to federated users use the example $select query and combine it with $filter to omit the list of permissions.
      schema:
        type: string
      examples:
        filter to see roles for ocm shares:
          value: "@libre.graph.permissions.roles.allowedValues/rolePermissions/any(p:contains(p/condition, '@Subject.UserType==\"Federated\"'))"
    permissionsSelect:
      name: $select
      in: query
      description: Select properties to be returned. By default all properties are returned. Select the roles property to fetch the available sharing roles without resolving all the permissions. Combine this with the $filter parameter to fetch the actions applicable to federated users.
      style: form
      explode: false
      schema:
        uniqueItems: true
        type: array
        items:
          enum:
            - "@libre.graph.permissions.actions.allowedValues"
            - "@libre.graph.permissions.roles.allowedValues"
            - "value"
          type: string
    count:
      name: $count
      in: query
      description: Include count of items
      schema:
        type: boolean
    orderby:
      name: $orderby
      in: query
      description: The $orderby system query option allows clients to request resources in either ascending order using asc or descending order using desc.
      schema:
        type: string
      examples:
        last modified descending:
          value: lastModifiedDateTime desc
        last modified ascending:
          value: lastModifiedDateTime asc
        name descending:
          value: name desc
        name ascending:
          value: name asc
  securitySchemes:
    openId:
      type: openIdConnect
      openIdConnectUrl: https://cloud.rolling.opencloud.rocks/.well-known/openid-configuration
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: plain
    basicAuth:
      description: HTTP Basic Authentication (discouraged for production environments)
      type: http
      scheme: basic
  examples:
    tags_put:
      value:
        resourceId: 7f92b0a9-06ad-49dc-890f-0e0a6eb4dea6$e9f01ca3-577f-4d1d-acd4-1cc44149ac25!5fb9f87c-a317-467b-9882-eb9f171564ac
        tags:
          - tag_to_assign_1
          - tag_to_assign_2
    tags_delete:
      value:
        resourceId: 7f92b0a9-06ad-49dc-890f-0e0a6eb4dea6$e9f01ca3-577f-4d1d-acd4-1cc44149ac25!5fb9f87c-a317-467b-9882-eb9f171564ac
        tags:
          - tag_to_unassign_1
          - tag_to_unassign_2
    educationUser:
      value:
        id: 90eedea1-dea1-90ee-a1de-ee90a1deee90
        onPremisesSAMAccountName: max.mustermann
        displayName: Max Mustermann
        surname: Mustermann
        givenName: Max
        mail: max.musterman@example.org
        primaryRole: student
        identities:
          - issuer: idp.school.com
            issuerAssignedId: max.mustermann
    educationUser_post:
      summary: Student User Creation
      description: |
        Example request body for creating a new student user.
      value:
        onPremisesSAMAccountName: max.mustermann
        displayName: Max Mustermann
        surname: Mustermann
        givenName: Max
        mail: max.musterman@example.org
        primaryRole: student
        identities:
          - issuer: idp.school.com
            issuerAssignedId: max.mustermann
    educationUser_post_externalId:
      summary: Users with externalId
      description: |
        Example for creating a user with an external ID.

        **Note:** To delete a user by externalId, first retrieve the user's ID using a filter query, then delete the user using that ID.
      value:
        onPremisesSAMAccountName: max.mustermann
        displayName: Max Mustermann
        externalId: EX12345
        surname: Mustermann
        givenName: Max
        mail: max.musterman@example.org
    educationSchool:
      value:
        id: 43b879c4-14c6-4e0a-9b3f-b1b33c5a4bd4
        displayName: Realschule Musterstadt
        schoolNumber: '1234'
    educationSchool_post:
      value:
        displayName: Realschule Musterstadt
        schoolNumber: '1234'
    educationSchool_patchNumber:
      value:
        schoolNumber: '1234'
      summary: Update Schoolnumber
    educationSchool_patchTerminationDate:
      value:
        terminationDate: 2023-06-30T00:00:00Z
      summary: Set a termination date for a school
    educationSchool_deleteTerminationDate:
      value:
        terminationDate: null
      summary: Delete termination date from school
    educationClass:
      value:
        id: 86948e45-96a6-43df-b83d-46e92afd30de
        displayName: Mathematik
        classification: course
        externalId: ac528aea-978e-415c-a733-c4ba235d3388
    educationClass_post:
      value:
        displayName: Mathematik
        classification: course
        externalId: ac528aea-978e-415c-a733-c4ba235d3388
security:
  - openId: [ ]
  - basicAuth: [ ]