api: types are sticky

1 files changed, 19 insertions, 1 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index 36c3ddc..6e106b9 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -118,6 +118,13 @@ paths:
 
         JSON maps and arrays become Automerge maps and lists; numbers become integers
         when they fit, floats otherwise; strings are plain strings (not text objects).
+        Types are sticky: plain JSON or text written over a value of a type JSON
+        doesn't have is stored as that type where it is its JSON form (a timestamp's
+        string, bytes' base64, a number over a float, uint or counter, a string over a
+        text; `api.md`, Types). A change of type is listed in `x-continuum-retyped`;
+        with `retype=false` it is `409` instead. Answers with what is there after the
+        write, read back.
+
         Typed JSON (`application/vnd.continuum.typed+json`) writes values of every
         type, tagged (`{"$timestamp": …}`, `{"$bytes": …}`, `{"$uint": …}`,
         `{"$counter": …}`, `{"$float": …}`, `{"$text": …}`, `{"$map": …}`).
@@ -126,6 +133,13 @@ paths:
         `.float`, `.boolean`, `.counter` (decimal or `true`/`false`), or
         `application/vnd.continuum.timestamp; format=rfc3339|unix|unix-ms|http-date`;
         a body that isn't one is `400`, saying why.
+      parameters:
+        - name: retype
+          in: query
+          description: Whether the write may change the type of what it writes over (default true); if not, a write that would is `409`.
+          schema:
+            type: boolean
+            default: true
       requestBody:
         required: true
         content:
@@ -154,7 +168,7 @@ paths:
         '403':
           description: Protocol data (`_continuum`) and the user isn't in `protocol-writers`, or epoch metadata or the swarm ID (`_continuum/epochs`, `_continuum/swarm`, never writable).
         '409':
-          description: The path crosses an existing non-map value.
+          description: The path crosses an existing non-map value, or with `retype=false` the write would change a type (the message says where).
         '415':
           description: Content-Type is none the API takes (`application/json`, the default; `text/plain`; a type's own, `api.md`, Types).
         '500':
@@ -1368,6 +1382,10 @@ components:
           description: SHA-256 of the body.
           schema:
             type: string
+        x-continuum-retyped:
+          description: 'On a write that changed the type of what it wrote over: where, and from what to what (`<path>: <from> -> <to>`, comma-separated, 16 at most, then `…`).'
+          schema:
+            type: string
         x-continuum-type:
           description: What the value is stored as (`map`, `list`, `text`, `string`, `bytes`, `int`, `uint`, `float`, `boolean`, `null`, `counter`, `timestamp`).
           schema: