diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/openapi.yaml | 20 |
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: |