@panneau/protocol 5.0.0-alpha.3 → 5.0.0-alpha.5

package/schema/openapi.json

@@ -686,6 +686,94 @@
                 }
             }
         },
+        "/resources/{resource}/fields/{field}/check": {
+            "parameters": [
+                {
+                    "name": "resource",
+                    "in": "path",
+                    "required": true,
+                    "description": "Resource id.",
+                    "schema": {
+                        "type": "string"
+                    }
+                },
+                {
+                    "name": "field",
+                    "in": "path",
+                    "required": true,
+                    "description": "Name of a field with `check`.",
+                    "schema": {
+                        "type": "string"
+                    }
+                }
+            ],
+            "post": {
+                "operationId": "checkField",
+                "summary": "Checks a value as it is typed: whether a slug is available, and its URL. With the permission to create, or to update the item `id`.",
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/FieldCheckRequest"
+                            }
+                        }
+                    }
+                },
+                "responses": {
+                    "200": {
+                        "description": "What the backend says about the value.",
+                        "content": {
+                            "application/json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/FieldCheckResponse"
+                                }
+                            }
+                        }
+                    },
+                    "401": {
+                        "description": "Not authenticated.",
+                        "content": {
+                            "application/problem+json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Problem"
+                                }
+                            }
+                        }
+                    },
+                    "403": {
+                        "description": "Not allowed.",
+                        "content": {
+                            "application/problem+json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Problem"
+                                }
+                            }
+                        }
+                    },
+                    "404": {
+                        "description": "Not found.",
+                        "content": {
+                            "application/problem+json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Problem"
+                                }
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "Invalid values: messages are in `errors`, keyed by dot path.",
+                        "content": {
+                            "application/problem+json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Problem"
+                                }
+                            }
+                        }
+                    }
+                }
+            }
+        },
         "/actions/runs": {
             "get": {
                 "operationId": "listActionRuns",
@@ -831,77 +919,27 @@
                 }
             }
         },
-        "/media": {
-            "get": {
-                "operationId": "listMedia",
-                "parameters": [
-                    {
-                        "name": "page",
-                        "in": "query",
-                        "required": false,
-                        "description": "Page number, from 1.",
-                        "schema": {
-                            "type": "integer",
-                            "minimum": 1
-                        }
-                    },
-                    {
-                        "name": "perPage",
-                        "in": "query",
-                        "required": false,
-                        "description": "Items per page.",
-                        "schema": {
-                            "type": "integer",
-                            "minimum": 1
-                        }
-                    },
-                    {
-                        "name": "sort",
-                        "in": "query",
-                        "required": false,
-                        "description": "Comma-separated fields; a `-` prefix sorts descending.",
-                        "schema": {
-                            "type": "string"
-                        }
-                    },
-                    {
-                        "name": "filter",
-                        "in": "query",
-                        "required": false,
-                        "style": "deepObject",
-                        "explode": true,
-                        "description": "`filter[status]=published`; `filter[tags][]=a&filter[tags][]=b` for any of several values; `filter[published_at][from]=2026-01-01&filter[published_at][to]=2026-01-31` for the inclusive bounds of a range filter (`date-range`), without the open end.",
-                        "schema": {
-                            "type": "object",
-                            "additionalProperties": true
-                        }
-                    },
-                    {
-                        "name": "q",
-                        "in": "query",
-                        "required": false,
-                        "description": "Search.",
-                        "schema": {
-                            "type": "string"
-                        }
-                    },
-                    {
-                        "name": "fields",
-                        "in": "query",
-                        "required": false,
-                        "description": "Comma-separated fields to include in each item.",
-                        "schema": {
-                            "type": "string"
+        "/uploads/sign": {
+            "post": {
+                "operationId": "signUpload",
+                "summary": "Signs a request of the browser's S3 client. The first request of a file creates its upload.",
+                "requestBody": {
+                    "required": true,
+                    "content": {
+                        "application/json": {
+                            "schema": {
+                                "$ref": "#/components/schemas/UploadSignRequest"
+                            }
                         }
                     }
-                ],
+                },
                 "responses": {
                     "200": {
-                        "description": "A page of media.",
+                        "description": "The presigned request.",
                         "content": {
                             "application/json": {
                                 "schema": {
-                                    "$ref": "#/components/schemas/MediaListResponse"
+                                    "$ref": "#/components/schemas/UploadSignResponse"
                                 }
                             }
                         }
@@ -925,33 +963,55 @@
                                 }
                             }
                         }
+                    },
+                    "404": {
+                        "description": "Not found.",
+                        "content": {
+                            "application/problem+json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Problem"
+                                }
+                            }
+                        }
+                    },
+                    "422": {
+                        "description": "Invalid values: messages are in `errors`, keyed by dot path.",
+                        "content": {
+                            "application/problem+json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Problem"
+                                }
+                            }
+                        }
                     }
                 }
-            },
+            }
+        },
+        "/uploads/{upload}/complete": {
+            "parameters": [
+                {
+                    "name": "upload",
+                    "in": "path",
+                    "required": true,
+                    "description": "Upload id: `upl_…`.",
+                    "schema": {
+                        "type": "string"
+                    }
+                }
+            ],
             "post": {
-                "operationId": "uploadMedia",
+                "operationId": "completeUpload",
+                "summary": "Once the browser completed the upload in storage, checks the object and gives the upload, which values reference.",
                 "requestBody": {
-                    "required": true,
+                    "required": false,
                     "content": {
-                        "multipart/form-data": {
+                        "application/json": {
                             "schema": {
                                 "type": "object",
-                                "required": [
-                                    "file"
-                                ],
                                 "properties": {
-                                    "file": {
-                                        "type": "string",
-                                        "contentMediaType": "application/octet-stream"
-                                    },
                                     "name": {
-                                        "type": "string"
-                                    },
-                                    "tags": {
-                                        "type": "array",
-                                        "items": {
-                                            "type": "string"
-                                        }
+                                        "type": "string",
+                                        "description": "The file's name, which the key doesn't keep, since the backend chose it."
                                     }
                                 }
                             }
@@ -959,12 +1019,12 @@
                     }
                 },
                 "responses": {
-                    "201": {
-                        "description": "The created media.",
+                    "200": {
+                        "description": "The upload.",
                         "content": {
                             "application/json": {
                                 "schema": {
-                                    "$ref": "#/components/schemas/MediaResponse"
+                                    "$ref": "#/components/schemas/UploadResponse"
                                 }
                             }
                         }
@@ -989,46 +1049,8 @@
                             }
                         }
                     },
-                    "422": {
-                        "description": "Invalid values: messages are in `errors`, keyed by dot path.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        },
-        "/media/tags": {
-            "get": {
-                "operationId": "listMediaTags",
-                "responses": {
-                    "200": {
-                        "description": "Tags in use.",
-                        "content": {
-                            "application/json": {
-                                "schema": {
-                                    "type": "object",
-                                    "required": [
-                                        "data"
-                                    ],
-                                    "properties": {
-                                        "data": {
-                                            "type": "array",
-                                            "items": {
-                                                "type": "string"
-                                            }
-                                        }
-                                    }
-                                }
-                            }
-                        }
-                    },
-                    "401": {
-                        "description": "Not authenticated.",
+                    "404": {
+                        "description": "Not found.",
                         "content": {
                             "application/problem+json": {
                                 "schema": {
@@ -1037,8 +1059,8 @@
                             }
                         }
                     },
-                    "403": {
-                        "description": "Not allowed.",
+                    "422": {
+                        "description": "Invalid values: messages are in `errors`, keyed by dot path.",
                         "content": {
                             "application/problem+json": {
                                 "schema": {
@@ -1050,334 +1072,16 @@
                 }
             }
         },
-        "/media/{id}": {
-            "parameters": [
-                {
-                    "name": "id",
-                    "in": "path",
-                    "required": true,
-                    "description": "Media id.",
-                    "schema": {
-                        "type": "string"
-                    }
-                }
-            ],
+        "/auth/session": {
             "get": {
-                "operationId": "getMedia",
+                "operationId": "getSession",
                 "responses": {
                     "200": {
-                        "description": "The media.",
+                        "description": "The current user.",
                         "content": {
                             "application/json": {
                                 "schema": {
-                                    "$ref": "#/components/schemas/MediaResponse"
-                                }
-                            }
-                        }
-                    },
-                    "401": {
-                        "description": "Not authenticated.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "403": {
-                        "description": "Not allowed.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "404": {
-                        "description": "Not found.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    }
-                }
-            },
-            "patch": {
-                "operationId": "updateMedia",
-                "description": "Updates metadata, tags or the image `transform`.",
-                "requestBody": {
-                    "required": true,
-                    "content": {
-                        "application/json": {
-                            "schema": {
-                                "type": "object",
-                                "additionalProperties": true
-                            }
-                        }
-                    }
-                },
-                "responses": {
-                    "200": {
-                        "description": "The updated media.",
-                        "content": {
-                            "application/json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/MediaResponse"
-                                }
-                            }
-                        }
-                    },
-                    "401": {
-                        "description": "Not authenticated.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "403": {
-                        "description": "Not allowed.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "404": {
-                        "description": "Not found.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "422": {
-                        "description": "Invalid values: messages are in `errors`, keyed by dot path.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    }
-                }
-            },
-            "delete": {
-                "operationId": "deleteMedia",
-                "responses": {
-                    "204": {
-                        "description": "Moved to the trash."
-                    },
-                    "401": {
-                        "description": "Not authenticated.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "403": {
-                        "description": "Not allowed.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "404": {
-                        "description": "Not found.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "409": {
-                        "description": "Conflict with a business rule.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        },
-        "/media/{id}/file": {
-            "parameters": [
-                {
-                    "name": "id",
-                    "in": "path",
-                    "required": true,
-                    "description": "Media id.",
-                    "schema": {
-                        "type": "string"
-                    }
-                }
-            ],
-            "post": {
-                "operationId": "replaceMediaFile",
-                "requestBody": {
-                    "required": true,
-                    "content": {
-                        "multipart/form-data": {
-                            "schema": {
-                                "type": "object",
-                                "required": [
-                                    "file"
-                                ],
-                                "properties": {
-                                    "file": {
-                                        "type": "string",
-                                        "contentMediaType": "application/octet-stream"
-                                    }
-                                }
-                            }
-                        }
-                    }
-                },
-                "responses": {
-                    "200": {
-                        "description": "The media.",
-                        "content": {
-                            "application/json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/MediaResponse"
-                                }
-                            }
-                        }
-                    },
-                    "401": {
-                        "description": "Not authenticated.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "403": {
-                        "description": "Not allowed.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "404": {
-                        "description": "Not found.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "422": {
-                        "description": "Invalid values: messages are in `errors`, keyed by dot path.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        },
-        "/media/{id}/restore": {
-            "parameters": [
-                {
-                    "name": "id",
-                    "in": "path",
-                    "required": true,
-                    "description": "Media id.",
-                    "schema": {
-                        "type": "string"
-                    }
-                }
-            ],
-            "post": {
-                "operationId": "restoreMedia",
-                "responses": {
-                    "200": {
-                        "description": "The restored media.",
-                        "content": {
-                            "application/json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/MediaResponse"
-                                }
-                            }
-                        }
-                    },
-                    "401": {
-                        "description": "Not authenticated.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "403": {
-                        "description": "Not allowed.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    },
-                    "404": {
-                        "description": "Not found.",
-                        "content": {
-                            "application/problem+json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Problem"
-                                }
-                            }
-                        }
-                    }
-                }
-            }
-        },
-        "/auth/session": {
-            "get": {
-                "operationId": "getSession",
-                "responses": {
-                    "200": {
-                        "description": "The current user.",
-                        "content": {
-                            "application/json": {
-                                "schema": {
-                                    "$ref": "#/components/schemas/Session"
+                                    "$ref": "#/components/schemas/Session"
                                 }
                             }
                         }
@@ -1797,7 +1501,30 @@
                         "name": "q",
                         "in": "query",
                         "required": true,
-                        "description": "Search terms.",
+                        "description": "Search terms, trimmed.",
+                        "schema": {
+                            "type": "string",
+                            "minLength": 2,
+                            "maxLength": 255
+                        }
+                    },
+                    {
+                        "name": "limit",
+                        "in": "query",
+                        "required": false,
+                        "description": "Items per resource.",
+                        "schema": {
+                            "type": "integer",
+                            "minimum": 1,
+                            "maximum": 20,
+                            "default": 5
+                        }
+                    },
+                    {
+                        "name": "resources",
+                        "in": "query",
+                        "required": false,
+                        "description": "Comma-separated ids of the searchable resources to search. Defaults to every one.",
                         "schema": {
                             "type": "string"
                         }
@@ -1805,7 +1532,7 @@
                 ],
                 "responses": {
                     "200": {
-                        "description": "Results grouped by resource.",
+                        "description": "Results grouped by resource, in the order of the definition: at most `limit` items per resource, and 20 in all.",
                         "content": {
                             "application/json": {
                                 "schema": {
@@ -1823,6 +1550,26 @@
                                 }
                             }
                         }
+                    },
+                    "422": {
+                        "description": "Invalid values: messages are in `errors`, keyed by dot path.",
+                        "content": {
+                            "application/problem+json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Problem"
+                                }
+                            }
+                        }
+                    },
+                    "429": {
+                        "description": "Too many requests: `Retry-After` gives the seconds to wait.",
+                        "content": {
+                            "application/problem+json": {
+                                "schema": {
+                                    "$ref": "#/components/schemas/Problem"
+                                }
+                            }
+                        }
                     }
                 }
             }
@@ -2198,6 +1945,43 @@
                         ],
                         "additionalProperties": {}
                     },
+                    {
+                        "type": "object",
+                        "properties": {
+                            "rule": {
+                                "type": "string",
+                                "const": "crop"
+                            },
+                            "value": {
+                                "type": "object",
+                                "properties": {
+                                    "ratios": {
+                                        "description": "A crop must have one of them: its height is within one pixel of its width divided by the ratio, after its rotation.",
+                                        "type": "array",
+                                        "items": {
+                                            "type": "string",
+                                            "pattern": "^[1-9][0-9]*:[1-9][0-9]*$",
+                                            "description": "An aspect ratio, as `width:height`: `16:9`."
+                                        }
+                                    },
+                                    "required": {
+                                        "description": "Each image needs a crop for this use.",
+                                        "type": "boolean"
+                                    }
+                                },
+                                "additionalProperties": {}
+                            },
+                            "message": {
+                                "description": "Message shown when the rule fails, instead of the default one.",
+                                "type": "string"
+                            }
+                        },
+                        "required": [
+                            "rule",
+                            "value"
+                        ],
+                        "additionalProperties": {}
+                    },
                     {
                         "type": "object",
                         "properties": {
@@ -2216,7 +2000,7 @@
                         "description": "A rule added in a later version of the protocol. Clients that don't know it ignore it; the server still enforces it."
                     }
                 ],
-                "description": "A portable validation rule. `min` and `max` apply to numbers, and to the length of text and arrays. `accept` lists MIME types (`image/*`). `maxSize` is in bytes."
+                "description": "A portable validation rule. `min` and `max` apply to numbers, and to the length of text and arrays. `accept` lists MIME types (`image/*`). `maxSize` is in bytes. `crop` checks the transform of each image of an `image` or `media` value (decision 0031)."
             },
             "BlockType": {
                 "type": "object",
@@ -2280,41 +2064,84 @@
                     "updateOnly": {
                         "type": "boolean"
                     },
-                    "rules": {
+                    "rules": {
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/Rule"
+                        }
+                    },
+                    "visibleWhen": {
+                        "$ref": "#/components/schemas/Condition"
+                    },
+                    "options": {
+                        "description": "`select`: the choices.",
+                        "type": "array",
+                        "items": {
+                            "$ref": "#/components/schemas/Option"
+                        }
+                    },
+                    "multiple": {
+                        "description": "`select`, `relation`, `media`, `image`, `file`: the value is an array.",
+                        "type": "boolean"
+                    },
+                    "resource": {
+                        "description": "`relation`: id of the related resource. `media`, `image`: id of a resource of kind `media`, or a list of them; without it, every library of the definition (decision 0027).",
+                        "anyOf": [
+                            {
+                                "type": "string",
+                                "minLength": 1
+                            },
+                            {
+                                "minItems": 1,
+                                "type": "array",
+                                "items": {
+                                    "type": "string",
+                                    "minLength": 1
+                                }
+                            }
+                        ]
+                    },
+                    "accept": {
+                        "description": "`media`, `image`, `file`: accepted MIME types. `image` defaults to `image/*`.",
                         "type": "array",
                         "items": {
-                            "$ref": "#/components/schemas/Rule"
+                            "type": "string"
                         }
                     },
-                    "visibleWhen": {
-                        "$ref": "#/components/schemas/Condition"
-                    },
-                    "options": {
-                        "description": "`select`: the choices.",
+                    "ratios": {
+                        "description": "`image`: ratios the editor suggests. The `crop` rule enforces ratios (decision 0031).",
                         "type": "array",
                         "items": {
-                            "$ref": "#/components/schemas/Option"
+                            "type": "string",
+                            "pattern": "^[1-9][0-9]*:[1-9][0-9]*$",
+                            "description": "An aspect ratio, as `width:height`: `16:9`."
                         }
                     },
-                    "multiple": {
-                        "description": "`select`, `relation`, `media`: the value is an array.",
+                    "rotate": {
+                        "description": "`image`: whether the editor offers rotation and flips. Defaults to true.",
                         "type": "boolean"
                     },
-                    "resource": {
-                        "description": "`relation`: id of the related resource.",
-                        "type": "string"
+                    "focalPoint": {
+                        "description": "`image`: whether the editor offers the focal point. Defaults to true.",
+                        "type": "boolean"
                     },
-                    "accept": {
-                        "description": "`media`: accepted MIME types.",
-                        "type": "array",
-                        "items": {
-                            "type": "string"
-                        }
+                    "transformBase": {
+                        "description": "`image`: what a transform for one use starts from: the media's own transform (`media`, the default), the original file, or the user's choice in the editor (decision 0031).",
+                        "type": "string",
+                        "enum": [
+                            "media",
+                            "original",
+                            "choose"
+                        ]
                     },
                     "from": {
                         "description": "`slug`: the field the slug is generated from.",
                         "type": "string"
                     },
+                    "check": {
+                        "description": "The client checks the value with the backend as it is typed, with `POST /resources/{resource}/fields/{field}/check`: whether a `slug` is available, and its URL. A field at the top of the resource only.",
+                        "type": "boolean"
+                    },
                     "display": {
                         "description": "Display used in lists, when it differs from the default one of the type.",
                         "type": "string"
@@ -2720,7 +2547,7 @@
                         ]
                     },
                     "search": {
-                        "description": "Whether the resource is in the global search.",
+                        "description": "Whether the resource is in the global search. Defaults to whether its list has a search (`list.search`).",
                         "type": "boolean"
                     }
                 },
@@ -2733,6 +2560,11 @@
                         "type": "string",
                         "minLength": 1
                     },
+                    "kind": {
+                        "description": "What the resource is. `media`: a library of media (decision 0026), with a `file` field and a `media` on each item. Without it, an ordinary resource. Clients treat a kind they don't know as an ordinary resource.",
+                        "type": "string",
+                        "minLength": 1
+                    },
                     "label": {
                         "type": "object",
                         "properties": {
@@ -2759,6 +2591,14 @@
                         "description": "The field used as the title of an item, in lists and pickers.",
                         "type": "string"
                     },
+                    "itemSubtitle": {
+                        "description": "The field shown under the title of an item, in search results, cards and pickers.",
+                        "type": "string"
+                    },
+                    "itemImage": {
+                        "description": "The field that holds the image of an item (a media or a URL), in search results, cards and pickers.",
+                        "type": "string"
+                    },
                     "fields": {
                         "type": "array",
                         "items": {
@@ -2832,6 +2672,10 @@
                     },
                     "abilities": {
                         "$ref": "#/components/schemas/Abilities"
+                    },
+                    "resource": {
+                        "description": "The resource of users: its item with this `id` is the profile of the user. Without it, clients look for a resource `users`.",
+                        "type": "string"
                     }
                 },
                 "required": [
@@ -3019,9 +2863,11 @@
                             "multipart",
                             "tus",
                             "presigned"
-                        ]
+                        ],
+                        "description": "`multipart`: files go through `POST /media` and the requests that take them. `presigned`: the browser also sends files to storage itself, with URLs that `POST /uploads/sign` signs, then `POST /uploads/{upload}/complete` gives an upload that values reference."
                     },
                     "endpoint": {
+                        "description": "`presigned`: the base URL of the upload routes, when they are not `{api.baseUrl}/uploads`.",
                         "type": "string"
                     },
                     "maxSize": {
@@ -3950,153 +3796,418 @@
                             }
                         ]
                     },
-                    "result": {
-                        "description": "Set once the run has finished.",
-                        "$ref": "#/components/schemas/ActionResult"
+                    "result": {
+                        "description": "Set once the run has finished.",
+                        "$ref": "#/components/schemas/ActionResult"
+                    },
+                    "createdAt": {
+                        "type": "string"
+                    },
+                    "finishedAt": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    }
+                },
+                "required": [
+                    "id",
+                    "action",
+                    "resource",
+                    "status",
+                    "progress",
+                    "total"
+                ],
+                "additionalProperties": {}
+            },
+            "ActionRunResponse": {
+                "type": "object",
+                "properties": {
+                    "run": {
+                        "$ref": "#/components/schemas/ActionRun"
+                    }
+                },
+                "required": [
+                    "run"
+                ],
+                "additionalProperties": {}
+            },
+            "MediaTransform": {
+                "type": "object",
+                "properties": {
+                    "crop": {
+                        "description": "In whole pixels of the upright original image (after its EXIF orientation), from its top left corner.",
+                        "type": "object",
+                        "properties": {
+                            "x": {
+                                "type": "integer",
+                                "minimum": 0,
+                                "maximum": 9007199254740991
+                            },
+                            "y": {
+                                "type": "integer",
+                                "minimum": 0,
+                                "maximum": 9007199254740991
+                            },
+                            "width": {
+                                "type": "integer",
+                                "exclusiveMinimum": 0,
+                                "maximum": 9007199254740991
+                            },
+                            "height": {
+                                "type": "integer",
+                                "exclusiveMinimum": 0,
+                                "maximum": 9007199254740991
+                            }
+                        },
+                        "required": [
+                            "x",
+                            "y",
+                            "width",
+                            "height"
+                        ],
+                        "additionalProperties": {}
+                    },
+                    "rotate": {
+                        "description": "Clockwise, in degrees.",
+                        "anyOf": [
+                            {
+                                "type": "number",
+                                "const": 0
+                            },
+                            {
+                                "type": "number",
+                                "const": 90
+                            },
+                            {
+                                "type": "number",
+                                "const": 180
+                            },
+                            {
+                                "type": "number",
+                                "const": 270
+                            }
+                        ]
+                    },
+                    "flipX": {
+                        "description": "Mirrors left to right (horizontal).",
+                        "type": "boolean"
+                    },
+                    "flipY": {
+                        "description": "Mirrors top to bottom (vertical).",
+                        "type": "boolean"
+                    },
+                    "focalPoint": {
+                        "description": "From 0 to 1, relative to the width and height of the upright original image, not of the crop: changing the crop does not move it. Renderers map it into the transformed image and clamp it to the crop.",
+                        "type": "object",
+                        "properties": {
+                            "x": {
+                                "type": "number",
+                                "minimum": 0,
+                                "maximum": 1
+                            },
+                            "y": {
+                                "type": "number",
+                                "minimum": 0,
+                                "maximum": 1
+                            }
+                        },
+                        "required": [
+                            "x",
+                            "y"
+                        ],
+                        "additionalProperties": {}
+                    },
+                    "base": {
+                        "description": "What a transform for one use starts from: the original file by default, or the media's own transform (`media`). With `media`, the crop and the focal point are relative to the media's version instead of the original (decision 0031).",
+                        "type": "string",
+                        "enum": [
+                            "media",
+                            "original"
+                        ]
+                    },
+                    "baseTransform": {
+                        "description": "With `base: \"media\"`: the media's own transform this one was made on. When the media's transform is no longer the same, clients ask to check the crop, and renderers clamp it.",
+                        "$ref": "#/components/schemas/MediaTransform"
+                    }
+                },
+                "additionalProperties": {},
+                "description": "Non-destructive edits of an image, applied in this order: crop, then rotate, then flip. Renderers ignore the keys they don't know, which editor tools can add."
+            },
+            "StoredFile": {
+                "type": "object",
+                "properties": {
+                    "name": {
+                        "type": "string",
+                        "description": "The name of the file, as the user knows it."
+                    },
+                    "url": {
+                        "description": "Where to download it. A private file gets a temporary URL.",
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "mime": {
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "size": {
+                        "anyOf": [
+                            {
+                                "type": "integer",
+                                "minimum": 0,
+                                "maximum": 9007199254740991
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ]
+                    }
+                },
+                "required": [
+                    "name"
+                ],
+                "additionalProperties": {},
+                "description": "A file stored by the backend: the value of a `file` field in items. Requests send it back to keep the file, `{ \"upload\" }` to replace it, or `null` to remove it."
+            },
+            "UploadReference": {
+                "type": "object",
+                "properties": {
+                    "upload": {
+                        "type": "string",
+                        "minLength": 1
+                    }
+                },
+                "required": [
+                    "upload"
+                ],
+                "additionalProperties": {},
+                "description": "A file uploaded directly to storage, by the id of its upload: in a file value, such as the `file` of a media, or an action parameter."
+            },
+            "Upload": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "The id of the upload: `upl_…`."
+                    },
+                    "key": {
+                        "description": "The key of the object in storage.",
+                        "type": "string"
+                    },
+                    "name": {
+                        "type": "string"
+                    },
+                    "mime": {
+                        "type": "string"
+                    },
+                    "size": {
+                        "type": "integer",
+                        "minimum": 0,
+                        "maximum": 9007199254740991
+                    }
+                },
+                "required": [
+                    "id"
+                ],
+                "additionalProperties": {},
+                "description": "A file the browser uploaded to storage, before it becomes a media, an import or another value."
+            },
+            "UploadResponse": {
+                "type": "object",
+                "properties": {
+                    "data": {
+                        "$ref": "#/components/schemas/Upload"
+                    }
+                },
+                "required": [
+                    "data"
+                ],
+                "additionalProperties": {}
+            },
+            "UploadSignRequest": {
+                "type": "object",
+                "properties": {
+                    "method": {
+                        "type": "string",
+                        "enum": [
+                            "GET",
+                            "POST",
+                            "PUT",
+                            "DELETE"
+                        ]
+                    },
+                    "key": {
+                        "type": "string",
+                        "minLength": 1
+                    },
+                    "uploadId": {
+                        "description": "The S3 multipart upload.",
+                        "type": "string"
+                    },
+                    "partNumber": {
+                        "type": "integer",
+                        "exclusiveMinimum": 0,
+                        "maximum": 9007199254740991
                     },
-                    "createdAt": {
+                    "contentType": {
                         "type": "string"
                     },
-                    "finishedAt": {
-                        "type": [
-                            "string",
-                            "null"
-                        ]
+                    "expiresIn": {
+                        "type": "integer",
+                        "exclusiveMinimum": 0,
+                        "maximum": 9007199254740991
                     }
                 },
                 "required": [
-                    "id",
-                    "action",
-                    "resource",
-                    "status",
-                    "progress",
-                    "total"
+                    "method",
+                    "key"
                 ],
-                "additionalProperties": {}
+                "additionalProperties": {},
+                "description": "A request of the browser's S3 client to sign (Uppy 6's `signRequest`)."
             },
-            "ActionRunResponse": {
+            "UploadSignResponse": {
                 "type": "object",
                 "properties": {
-                    "run": {
-                        "$ref": "#/components/schemas/ActionRun"
+                    "url": {
+                        "type": "string"
+                    },
+                    "key": {
+                        "description": "The key the backend chose, for the first request of a file.",
+                        "type": "string"
+                    },
+                    "headers": {
+                        "description": "Headers the URL was signed with, which the browser sends.",
+                        "type": "object",
+                        "propertyNames": {
+                            "type": "string"
+                        },
+                        "additionalProperties": {
+                            "type": "string"
+                        }
+                    },
+                    "upload": {
+                        "description": "The upload the first request of a file created: `upl_…`.",
+                        "type": "string"
                     }
                 },
                 "required": [
-                    "run"
+                    "url"
                 ],
-                "additionalProperties": {}
+                "additionalProperties": {},
+                "description": "A presigned request."
             },
-            "MediaTransform": {
+            "FieldCheckRequest": {
                 "type": "object",
                 "properties": {
-                    "crop": {
-                        "description": "In pixels of the original image.",
-                        "type": "object",
-                        "properties": {
-                            "x": {
-                                "type": "number"
-                            },
-                            "y": {
-                                "type": "number"
-                            },
-                            "width": {
-                                "type": "number"
-                            },
-                            "height": {
-                                "type": "number"
-                            }
-                        },
-                        "required": [
-                            "x",
-                            "y",
-                            "width",
-                            "height"
-                        ],
-                        "additionalProperties": {}
+                    "value": {
+                        "type": "string",
+                        "description": "The value to check, as it is typed."
                     },
-                    "rotate": {
+                    "locale": {
+                        "description": "The locale of the value, for a localized field.",
+                        "type": "string"
+                    },
+                    "id": {
+                        "description": "The item being edited, or null when creating one.",
                         "anyOf": [
                             {
-                                "type": "number",
-                                "const": 0
-                            },
-                            {
-                                "type": "number",
-                                "const": 90
-                            },
-                            {
-                                "type": "number",
-                                "const": 180
+                                "$ref": "#/components/schemas/Id"
                             },
                             {
-                                "type": "number",
-                                "const": 270
+                                "type": "null"
                             }
                         ]
                     },
-                    "flipX": {
-                        "type": "boolean"
-                    },
-                    "flipY": {
-                        "type": "boolean"
-                    },
-                    "focalPoint": {
-                        "description": "Relative to the width and height, from 0 to 1.",
+                    "values": {
+                        "description": "The form's current values, as they would be sent to save, for what the check depends on (a page's parent).",
                         "type": "object",
-                        "properties": {
-                            "x": {
-                                "type": "number",
-                                "minimum": 0,
-                                "maximum": 1
-                            },
-                            "y": {
-                                "type": "number",
-                                "minimum": 0,
-                                "maximum": 1
-                            }
+                        "propertyNames": {
+                            "type": "string"
                         },
-                        "required": [
-                            "x",
-                            "y"
-                        ],
                         "additionalProperties": {}
                     }
                 },
-                "additionalProperties": {}
+                "required": [
+                    "value"
+                ],
+                "additionalProperties": {},
+                "description": "A value of a field with `check`, to check with the backend."
             },
-            "Media": {
+            "FieldCheckResponse": {
                 "type": "object",
                 "properties": {
-                    "id": {
-                        "$ref": "#/components/schemas/Id"
+                    "available": {
+                        "type": "boolean",
+                        "description": "Whether no other item of the resource, in its scope and the same locale, has the value."
                     },
-                    "version": {
-                        "description": "Changes on every update. `null` when the backend has no versions.",
+                    "suggestion": {
+                        "description": "An available value close to the one checked, when it is taken.",
                         "type": [
                             "string",
                             "null"
                         ]
                     },
-                    "abilities": {
-                        "$ref": "#/components/schemas/Abilities"
+                    "prefix": {
+                        "description": "What the field shows in front of the value: the start of its URL.",
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "url": {
+                        "description": "The URL the value gives the item, which the field links to.",
+                        "type": [
+                            "string",
+                            "null"
+                        ]
                     },
+                    "disabled": {
+                        "description": "The field doesn't apply to this item (the home page has no slug): the field is read-only.",
+                        "type": "boolean"
+                    }
+                },
+                "required": [
+                    "available"
+                ],
+                "additionalProperties": {},
+                "description": "What the backend says about a value: not authoritative, since saving still validates it."
+            },
+            "MediaInfo": {
+                "type": "object",
+                "properties": {
                     "type": {
                         "type": "string",
-                        "description": "`image`, `video`, `audio`, `document`, `font`, or another type."
-                    },
-                    "name": {
-                        "type": "string"
+                        "description": "`image`, `video`, `audio`, `document`, `font`, or another type the backend knows."
                     },
                     "mime": {
-                        "type": "string"
+                        "type": [
+                            "string",
+                            "null"
+                        ]
                     },
                     "size": {
-                        "type": "integer",
-                        "minimum": 0,
-                        "maximum": 9007199254740991
+                        "anyOf": [
+                            {
+                                "type": "integer",
+                                "minimum": 0,
+                                "maximum": 9007199254740991
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ]
                     },
                     "url": {
-                        "type": "string"
+                        "description": "The main file to show or play: a rendition, or the original until it exists.",
+                        "type": [
+                            "string",
+                            "null"
+                        ]
                     },
                     "thumbnailUrl": {
                         "type": [
@@ -4105,6 +4216,7 @@
                         ]
                     },
                     "variants": {
+                        "description": "Named renditions: sizes of an image, qualities of a video.",
                         "type": "object",
                         "propertyNames": {
                             "type": "string"
@@ -4128,6 +4240,35 @@
                             "additionalProperties": {}
                         }
                     },
+                    "width": {
+                        "type": [
+                            "number",
+                            "null"
+                        ]
+                    },
+                    "height": {
+                        "type": [
+                            "number",
+                            "null"
+                        ]
+                    },
+                    "duration": {
+                        "description": "In seconds.",
+                        "type": [
+                            "number",
+                            "null"
+                        ]
+                    },
+                    "status": {
+                        "description": "Where the processing of the file is: `pending` and `processing` until its renditions are made, then `ready` or `failed`. Without it, the media is ready.",
+                        "type": "string",
+                        "enum": [
+                            "pending",
+                            "processing",
+                            "ready",
+                            "failed"
+                        ]
+                    },
                     "metadata": {
                         "type": "object",
                         "propertyNames": {
@@ -4136,6 +4277,7 @@
                         "additionalProperties": {}
                     },
                     "transform": {
+                        "description": "The media's own transform, from its library, which clients need to draw a transform for one use made over it (decision 0031).",
                         "anyOf": [
                             {
                                 "$ref": "#/components/schemas/MediaTransform"
@@ -4144,56 +4286,77 @@
                                 "type": "null"
                             }
                         ]
-                    },
-                    "tags": {
-                        "type": "array",
-                        "items": {
-                            "type": "string"
-                        }
                     }
                 },
                 "required": [
-                    "id",
-                    "version",
-                    "abilities",
-                    "type",
-                    "name",
-                    "mime",
-                    "size",
-                    "url"
+                    "type"
                 ],
-                "additionalProperties": {}
+                "additionalProperties": {},
+                "description": "What the backend computed about the file of a media item: the `media` of the items of a `media` resource, and of the values of `media` fields. Read-only: the editable properties of a media are the fields of its resource."
             },
-            "MediaResponse": {
+            "MediaItem": {
                 "type": "object",
                 "properties": {
-                    "data": {
-                        "$ref": "#/components/schemas/Media"
+                    "id": {
+                        "$ref": "#/components/schemas/Id"
+                    },
+                    "version": {
+                        "description": "Changes on every update. `null` when the backend has no versions.",
+                        "type": [
+                            "string",
+                            "null"
+                        ]
+                    },
+                    "abilities": {
+                        "$ref": "#/components/schemas/Abilities"
+                    },
+                    "media": {
+                        "$ref": "#/components/schemas/MediaInfo"
                     }
                 },
                 "required": [
-                    "data"
+                    "id",
+                    "version",
+                    "abilities",
+                    "media"
                 ],
-                "additionalProperties": {}
+                "additionalProperties": {},
+                "description": "An item of a resource of kind `media`: the values of its fields (`file`, the original, and those of the project), and the `media` the backend computed."
             },
-            "MediaListResponse": {
+            "MediaReference": {
                 "type": "object",
                 "properties": {
-                    "data": {
-                        "type": "array",
-                        "items": {
-                            "$ref": "#/components/schemas/Media"
-                        }
+                    "id": {
+                        "$ref": "#/components/schemas/Id"
                     },
-                    "meta": {
-                        "$ref": "#/components/schemas/Pagination"
+                    "resource": {
+                        "description": "The library of the media. Required for a field that allows several libraries, since ids are unique only within their resource (decision 0027).",
+                        "type": "string"
+                    },
+                    "label": {
+                        "description": "The `itemTitle` of the media.",
+                        "type": "string"
+                    },
+                    "media": {
+                        "$ref": "#/components/schemas/MediaInfo"
+                    },
+                    "transform": {
+                        "description": "The edits of the image for this use only: from the original file, or over the media's own transform with `base: \"media\"`.",
+                        "anyOf": [
+                            {
+                                "$ref": "#/components/schemas/MediaTransform"
+                            },
+                            {
+                                "type": "null"
+                            }
+                        ]
                     }
                 },
                 "required": [
-                    "data",
-                    "meta"
+                    "id"
                 ],
-                "additionalProperties": {}
+                "additionalProperties": {},
+                "description": "The value of a `media` or `image` field in items: the media, with what lists and fields show, and its edits for this use. Requests send the id, or `{ id, resource, transform }`: `resource` is required when the field allows several libraries."
             },
             "Session": {
                 "type": "object",
@@ -4216,7 +4379,8 @@
                             "type": "object",
                             "properties": {
                                 "resource": {
-                                    "type": "string"
+                                    "type": "string",
+                                    "description": "The id of the resource."
                                 },
                                 "items": {
                                     "type": "array",
@@ -4225,6 +4389,7 @@
                                     }
                                 },
                                 "total": {
+                                    "description": "How many items of the resource match, when the backend counts them: the list of the resource, searched, shows them all.",
                                     "type": "integer",
                                     "minimum": 0,
                                     "maximum": 9007199254740991
@@ -4241,7 +4406,8 @@
                 "required": [
                     "data"
                 ],
-                "additionalProperties": {}
+                "additionalProperties": {},
+                "description": "The results of the global search: the resources with results, in the order of the definition."
             },
             "PreviewResponse": {
                 "type": "object",