Merge branch 'main' into DDOC-690-storage-policy-admin

.spelling

@@ -58,4 +58,5 @@ period
 uri
 url 
 dropdown
-special
+special
+org

content/attributes/metadata_field--readable.yml

@@ -0,0 +1,75 @@
+---
+title: Metadata Field (Read)
+
+description: |-
+  A field within a metadata template. Fields can be a basic text, date, or
+  number field, or a list of options.
+
+required:
+  - type
+  - key
+  - displayName
+
+type: object
+
+properties:
+  type:
+    type: string
+    example: string
+    description: |-
+      The type of field. The basic fields are a `string` field for text, a
+      `float` field for numbers, and a `date` fields to present the user with a
+      date-time picker.
+
+      Additionally, metadata templates support an `enum` field for a basic list
+      of items, and ` multiSelect` field for a similar list of items where the
+      user can select more than one value.
+
+      **Note**: The `integer` value is deprecated.
+      It is still present in the response,
+      but cannot be used in the POST request.
+    enum:
+      - string
+      - float
+      - date
+      - enum
+      - multiSelect
+      - integer
+
+  key:
+    type: string
+    example: category
+    description: |-
+      A unique identifier for the field. The identifier must
+      be unique within the template to which it belongs.
+    maxLength: 256
+
+  displayName:
+    type: string
+    example: Category
+    description: |-
+      The display name of the field as it is shown to the user in the web and
+      mobile apps.
+    maxLength: 4096
+
+  description:
+    type: string
+    example: The category
+    description: |-
+      A description of the field. This is not shown to the user.
+    maxLength: 4096
+
+  hidden:
+    type: boolean
+    example: true
+    description: |-
+      Whether this field is hidden in the UI for the user and can only be set
+      through the API instead.
+
+  options:
+    description: |-
+      A list of options for this field. This is used in combination with the
+      `enum` and `multiSelect` field types.
+    type: array
+    items:
+      $ref: "../attributes/metadata_option--writable.yml"

content/attributes/sort.yml

@@ -0,0 +1,42 @@
+---
+name: sort
+description: |-
+  Defines the **second** attribute by which items
+  are sorted.
+
+  The folder type affects the way the items
+  are sorted:
+
+    * **Standard folder**:
+    Items are always sorted by
+    their `type` first, with
+    folders listed before files,
+    and files listed
+    before web links.
+
+    * **Root folder**:
+    This parameter is not supported
+    for marker-based pagination
+    on the root folder
+
+    (the folder with an `id` of `0`).
+
+    * **Shared folder with parent path
+    to the associated folder visible to
+    the collaborator**:
+    Items are always sorted by
+    their `type` first, with
+    folders listed before files,
+    and files listed
+    before web links.
+
+in: query
+required: false
+example: id
+schema:
+  type: string
+  enum:
+    - id
+    - name
+    - date
+    - size

content/paths/collaborations__post_collaborations.yml

@@ -42,9 +42,6 @@ requestBody:
             type: object
             description: |-
               The item to attach the comment to.
-            required:
-              - id
-              - type
             properties:
               type:
                 type: string

content/paths/comments__post_comments.yml

@@ -22,6 +22,7 @@ requestBody:
         type: object
         required:
           - message
+          - item
         properties:
           message:
             type: string

content/paths/downloads__get_files_id_content.yml

@@ -54,6 +54,22 @@ parameters:
       type: string
 
 responses:
+
+  200:
+    description: |-
+      Returns the requested file if the client has the **follow
+      redirects** setting enabled to automatically
+      follow HTTP `3xx` responses as redirects. If not, the request
+      will return `302` instead.
+      For details, see
+      the [download file guide](g://downloads/file#download-url).
+    content:
+      application/octet-stream:
+        schema:
+          type: string
+          format: binary
+          description: |-
+            The binary content of the file
   202:
     description: |-
       If the file is not ready to be downloaded yet `Retry-After` header will
@@ -71,11 +87,11 @@ responses:
 
   302:
     description: |-
-      If the file is available to be downloaded the response will include a
+      If the file is available for download the response will include a
       `Location` header for the file on `dl.boxcloud.com`.
 
       The `dl.boxcloud.com` URL is not persistent and clients will need
-      to follow the redirect in order to actually download the file.
+      to follow the redirect to actually download the file.
     headers:
       Location:
         description: |-

content/paths/file_metadata__get_files_id_metadata_id_id.yml

@@ -27,7 +27,7 @@ responses:
     content:
       application/json:
         schema:
-          $ref: '#/components/schemas/Metadata'
+          $ref: '#/components/schemas/Metadata--Full'
 
   403:
     description: |-

content/paths/files__put_files_id.yml

@@ -18,7 +18,6 @@ parameters:
   - $ref: '../attributes/file_id.yml'
   - $ref: '../attributes/fields.yml'
   - $ref: '../attributes/if_match.yml'
-
 requestBody:
   content:
     application/json:
@@ -110,6 +109,23 @@ requestBody:
                   - open
                   - company
 
+          collections:
+            type: array
+            description: |-
+              An array of collections to make this file
+              a member of. Currently
+              we only support the `favorites` collection.
+
+              To get the ID for a collection, use the
+              [List all collections][1] endpoint.
+
+              Passing an empty array `[]` or `null` will remove
+              the file from all collections.
+
+              [1]: e://get-collections
+            items:
+              $ref: "../attributes/reference.yml"
+
           tags:
             $ref: "../attributes/tags.yml"
 

content/paths/folders__get_folders_id.yml

@@ -14,21 +14,34 @@ description: |-
   Retrieves details for a folder, including the first 100 entries
   in the folder.
 
-  To fetch more items within the folder, please use the
+  Passing `sort`, `direction`, `offset`, and `limit`
+  parameters in query allows you to manage the
+  list of returned
+  [folder items](r://folder--full#param-item-collection).
+
+  To fetch more items within the folder, use the
   [Get items in a folder](#get-folders-id-items) endpoint.
 
 parameters:
   - $ref: '../attributes/folder_id.yml'
   - $ref: '../attributes/fields--with_metadata.yml'
   - $ref: '../attributes/if_none_match.yml'
   - $ref: '../attributes/boxapi_header.yml'
+  - $ref: '../attributes/sort.yml'
+  - $ref: '../attributes/direction.yml'
+  - $ref: '../attributes/offset.yml'
+  - $ref: '../attributes/limit.yml'
+
 
 responses:
   200:
     description: |-
       Returns a folder, including the first 100 entries in the folder.
+      If you used query parameters like
+      `sort`, `direction`, `offset`, or `limit`
+      the *folder items list* will be affected accordingly.
 
-      To fetch more items within the folder, please use the
+      To fetch more items within the folder, use the
       [Get items in a folder](#get-folders-id-items) endpoint.
 
       Not all available fields are returned by default. Use the

content/paths/folders__get_folders_id_items.yml

@@ -15,7 +15,7 @@ description: |-
   folders, and web links.
 
   To request more information about the folder itself, like its size,
-  please use the [Get a folder](#get-folders-id) endpoint instead.
+  use the [Get a folder](#get-folders-id) endpoint instead.
 
 parameters:
   - $ref: '../attributes/folder_id.yml'
@@ -25,40 +25,7 @@ parameters:
   - $ref: '../attributes/offset.yml'
   - $ref: '../attributes/limit.yml'
   - $ref: '../attributes/boxapi_header.yml'
-  # yamllint disable rule:line-length
-  - name: sort
-    description: |-
-      Defines the **second** attribute by which items
-      are sorted.
-
-      The folder type affects the way the items
-      are sorted:
-
-      * **Standard folder**:
-        Items are always sorted by their `type` first, with
-        folders listed before files, and files listed
-        before web links.
-
-      * **Root folder**:
-        This parameter is not supported for marker-based pagination
-        on the root folder (the folder with an `id` of `0`).
-
-      * **Shared folder with parent path to the associated folder visible to the collaborator**:
-        Items are always sorted by their `type` first, with
-        folders listed before files, and files listed
-        before web links.
-
-    in: query
-    required: false
-    example: id
-    schema:
-      type: string
-      enum:
-        - id
-        - name
-        - date
-        - size
-  # yamllint disable rule:line-length
+  - $ref: '../attributes/sort.yml'
   - $ref: '../attributes/direction.yml'
 
 responses:

content/paths/folders__put_folders_id.yml

@@ -88,7 +88,7 @@ requestBody:
               Passing an empty array `[]` or `null` will remove
               the folder from all collections.
 
-              [1]: ../advanced-files-and-folders/#get-collections
+              [1]: e://get-collections
             items:
               $ref: "../attributes/reference.yml"
 

content/paths/memberships__post_group_memberships.yml

@@ -70,7 +70,7 @@ requestBody:
               Setting these permissions overwrites the default
               access levels of an admin.
 
-              Specifying a value of "null" for this object will disable
+              Specifying a value of "null" for this object will deactivate
               all configurable permissions. Specifying permissions will set
               them accordingly, omitted permissions will be enabled by default.
             additionalProperties:

content/paths/memberships__put_group_memberships_id.yml

@@ -43,7 +43,7 @@ requestBody:
               Setting these permissions overwrites the default
               access levels of an admin.
 
-              Specifying a value of "null" for this object will disable
+              Specifying a value of "null" for this object will deactivate
               all configurable permissions. Specifying permissions will set
               them accordingly, omitted permissions will be enabled by default.
             additionalProperties:

content/paths/tasks__post_tasks.yml

@@ -25,9 +25,6 @@ requestBody:
             type: object
             description: |-
               The file to attach the task to.
-            required:
-              - id
-              - type
             properties:
               id:
                 type: string