Document partial snapshot

openapi/components/schemas/diff.yaml

@@ -29,6 +29,19 @@ properties:
               type: array
               items:
                 type: object
+      systemFields:
+        type: array
+        items:
+          type: object
+          properties:
+            collection:
+              type: string
+            field:
+              type: string
+            diff:
+              type: array
+              items:
+                type: object
       relations:
         type: array
         items:

openapi/components/schemas/schema.yaml

@@ -2,6 +2,10 @@ type: object
 properties:
   version:
     type: integer
+    description: '`1` for a full snapshot, `2` for a partial snapshot.'
+    enum:
+    - 1
+    - 2
     example: 1
   directus:
     type: string
@@ -15,6 +19,21 @@ properties:
     type: array
     items:
       $ref: fields.yaml
+  systemFields:
+    type: array
+    description: Indexes defined on system fields.
+    items:
+      type: object
+      properties:
+        collection:
+          type: string
+        field:
+          type: string
+        schema:
+          type: object
+          properties:
+            is_indexed:
+              type: boolean
   relations:
     type: array
     items:

openapi/paths/schema/apply/schemaApply.yaml

@@ -1,7 +1,8 @@
 summary: Apply Schema Difference
-description: Update the instance's schema by passing the diff previously retrieved
-  via `/schema/diff` endpoint in the JSON request body or a JSON/YAML file. This endpoint
-  is only available to admin users.
+description: |
+  Update the instance's schema by passing the diff previously retrieved via `/schema/diff` endpoint in the JSON request body or a JSON/YAML file. This endpoint is only available to admin users.
+
+  Only the operations in the diff are applied, so a diff from a partial snapshot leaves everything outside its scope untouched. The `hash` is always checked against the full schema.
 operationId: schemaApply
 parameters:
 - name: force

openapi/paths/schema/diff/schemaDiff.yaml

@@ -5,6 +5,8 @@ description: |
   Alternatively, upload a JSON or YAML schema file.
 
   Does not allow different Directus versions and database vendors by default. You can opt in to bypass these checks by passing the `force` query parameter.
+
+  Accepts partial snapshots, in which case the diff is scoped to the collections the snapshot references.
 operationId: schemaDiff
 parameters:
 - name: force
@@ -13,6 +15,17 @@ parameters:
   required: false
   schema:
     type: boolean
+- name: mode
+  description: |
+    `mirror` (default) returns all operations. `merge` returns an additive diff that excludes deletions.
+  in: query
+  required: false
+  schema:
+    type: string
+    enum:
+    - merge
+    - mirror
+    default: mirror
 requestBody:
   required: true
   content:
@@ -104,6 +117,8 @@ x-codeSamples:
     			},
     		],
     		relations: [],
+    	}, {
+    		mode: 'merge',
     	})
     );
 

openapi/paths/schema/snapshot/schemaSnapshot.yaml

@@ -1,9 +1,36 @@
 summary: Retrieve Schema Snapshot
-description: Retrieve the current schema. This endpoint is only available to admin
-  users.
+description: |
+  Retrieve the current schema. This endpoint is only available to admin users.
+
+  Returns a full snapshot (version `1`) by default. Pass `includeCollections` or `excludeCollections` to scope it to a subset of collections, which returns a partial snapshot (version `2`).
 operationId: schemaSnapshot
 parameters:
 - $ref: ../../../components/parameters.yaml#/Export
+- name: includeCollections
+  description: |
+    Restrict the snapshot to these collections. Unknown names are ignored. Mutually exclusive with `excludeCollections`.
+  in: query
+  required: false
+  explode: false
+  schema:
+    type: array
+    items:
+      type: string
+  example:
+  - articles
+  - authors
+- name: excludeCollections
+  description: |
+    Snapshot every collection except these. Mutually exclusive with `includeCollections`.
+  in: query
+  required: false
+  explode: false
+  schema:
+    type: array
+    items:
+      type: string
+  example:
+  - articles
 responses:
   '200':
     description: Successful request
@@ -16,6 +43,8 @@ responses:
         schema:
           type: string
           format: binary
+  '400':
+    $ref: ../../../components/responses.yaml#/BadRequestError
   '403':
     $ref: ../../../components/responses.yaml#/UnauthorizedError
 security: []
@@ -30,6 +59,11 @@ x-codeSamples:
     const client = createDirectus('directus_project_url').with(rest());
 
     const result = await client.request(schemaSnapshot());
+
+    // Partial snapshot
+    const partial = await client.request(
+      schemaSnapshot({ includeCollections: ['articles', 'authors'] })
+    );
 - label: GraphQL
   lang: GraphQL
   source: |