ovsdb/SPECS

   1          ===================================================
   2           Open vSwitch Configuration Database Specification
   3          ===================================================
   4
   5 Basic Notation
   6 --------------
   7
   8 The descriptions below use the following shorthand notations for JSON
   9 values.  Additional notation is presented later.
  10
  11 <string>
  12
  13     A JSON string.  Any Unicode string is allowed, as specified by RFC
  14     4627.  Implementations may disallowed null bytes.
  15
  16 <id>
  17
  18     A JSON string matching [a-zA-Z_][a-zA-Z0-9_]*.
  19
  20     <id>s that begin with _ are reserved to the implementation and may
  21     not be used by the user.
  22
  23 <boolean>
  24
  25     A JSON true or false value.
  26
  27 <number>
  28
  29     A JSON number.
  30
  31 <integer>
  32
  33     A JSON number with an integer value, within a certain range
  34     (currently -2**63...+2**63-1).
  35
  36 <value>
  37
  38     Any JSON value.
  39
  40 Schema Format
  41 -------------
  42
  43 An Open vSwitch configuration database consists of a set of tables,
  44 each of which has a number of columns and zero or more rows.  A schema
  45 is represented by <database-schema>, as described below.
  46
  47 <database-schema>
  48
  49     A JSON object with the following members:
  50
  51         "name": <id>                            required
  52         "comment": <string>                     optional
  53         "tables": {<id>: <table-schema>, ...}   required
  54
  55     The "name" identifies the database as a whole.  The "comment"
  56     optionally provides more information about the database.  The
  57     value of "tables" is a JSON object whose names are table names and
  58     whose values are <table-schema>s.
  59
  60 <table-schema>
  61
  62     A JSON object with the following members:
  63
  64         "comment": <string>                       optional
  65         "columns": {<id>: <column-schema>, ...}   required
  66
  67     The "comment" optionally provides information about this table for
  68     a human reader.  The value of "columns" is a JSON object whose
  69     names are column names and whose values are <column-schema>s.
  70
  71     Every table has the following columns whose definitions are not
  72     included in the schema:
  73
  74         "_uuid": This column, which contains exactly one UUID value,
  75         is initialized to a random value by the database engine when
  76         it creates a row.  It is read-only, and its value never
  77         changes during the lifetime of a row.
  78
  79         "_version": Like "_uuid", this column contains exactly one
  80         UUID value, initialized to a random value by the database
  81         engine when it creates a row, and it is read-only.  However,
  82         its value changes to a new random value whenever any other
  83         field in the row changes.  Furthermore, its value is
  84         ephemeral: when the database is closed and reopened, or when
  85         the database process is stopped and then started again, each
  86         "_version" also changes to a new random value.
  87
  88 <column-schema>
  89
  90     A JSON object with the following members:
  91
  92         "comment": <string>                       optional
  93         "type": <type>                            required
  94         "ephemeral": <boolean>                    optional
  95
  96     The "comment" optionally provides information about this column
  97     for a human reader.  The "type" specifies the type of data stored
  98     in this column.  If "ephemeral" is specified as true, then this
  99     column's values are not guaranteed to be durable; they may be lost
 100     when the database restarts.
 101
 102 <type>
 103
 104     The type of a database column.  Either an <atomic-type> or a JSON
 105     object that describes the type of a database column, with the
 106     following members:
 107
 108         "key": <atomic-type>               required
 109         "value": <atomic-type>             optional
 110         "min": <integer>                   optional
 111         "max": <integer> or "unlimited"    optional
 112
 113     If "min" or "max" is not specified, each defaults to 1.  If "max"
 114     is specified as "unlimited", then there is no specified maximum
 115     number of elements, although the implementation will enforce some
 116     limit.  After considering defaults, "min" must be at least 0,
 117     "max" must be at least 1, and "max" must be greater than or equal
 118     to "min".
 119
 120     If "min" and "max" are both 1 and "value" is not specified, the
 121     type is the scalar type specified by "key".
 122
 123     If "min" is not 1 or "max" is not 1, or both, and "value" is not
 124     specified, the type is a set of scalar type "key".
 125
 126     If "value" is specified, the type is a map from type "key" to type
 127     "value".
 128
 129 <atomic-type>
 130
 131     One of the strings "integer", "real", "boolean", "string", or
 132     "uuid", representing the specified scalar type.
 133
 134 Wire Protocol
 135 -------------
 136
 137 The database wire protocol is implemented in JSON-RPC 1.0.  We
 138 encourage use of JSON-RPC over stream connections instead of JSON-RPC
 139 over HTTP, for these reasons:
 140
 141     * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server
 142       protocol, which is a poor match.  Thus, JSON-RPC over HTTP
 143       requires the client to periodically poll the server to receive
 144       server requests.
 145
 146     * HTTP is more complicated than stream connections and doesn't
 147       provide any corresponding advantage.
 148
 149     * The JSON-RPC specification for HTTP transport is incomplete.
 150
 151 The database wire protocol consists of the following JSON-RPC methods:
 152
 153 get_schema
 154 ..........
 155
 156 Request object members:
 157
 158     "method": "get_schema"            required
 159     "params": []                      required
 160     "id": any JSON value except null  required
 161
 162 Response object members:
 163
 164     "result": <database-schema>
 165     "error": null
 166     "id": same "id" as request
 167
 168 This operation retrieves a <database-schema> that describes the
 169 hosted database.
 170
 171 transact
 172 ........
 173
 174 Request object members:
 175
 176     "method": "transact"              required
 177     "params": [<operation>*]          required
 178     "id": any JSON value except null  required
 179
 180 Response object members:
 181
 182     "result": [<object>*]
 183     "error": null
 184     "id": same "id" as request
 185
 186 The "params" array for this method consists of zero or more JSON
 187 objects, each of which represents a single database operation.  The
 188 "Operations" section below describes the valid operations.
 189
 190 The value of "id" must be unique among all in-flight transactions
 191 within the current JSON-RPC session.  Otherwise, the server may return
 192 a JSON-RPC error.
 193
 194 The database server executes each of the specified operations in the
 195 specified order, except that if an operation fails, then the remaining
 196 operations are not executed.
 197
 198 The set of operations is executed as a single atomic, consistent,
 199 isolated transaction.  The transaction is committed only if every
 200 operation succeeds.  Durability of the commit is not guaranteed unless
 201 the "commit" operation, with "durable" set to true, is included in the
 202 operation set (see below).
 203
 204 Regardless of whether errors occur, the response is always a JSON-RPC
 205 response with null "error" and a "result" member that is an array with
 206 the same number of elements as "params".  Each element of the "result"
 207 array corresponds to the same element of the "params" array.  The
 208 "result" array elements may be interpreted as follows:
 209
 210     - A JSON object that does not contain an "error" member indicates
 211       that the operation completed successfully.  The specific members
 212       of the object are specified below in the descriptions of
 213       individual operations.  Some operations do not produce any
 214       results, in which case the object will have no members.
 215
 216     - A JSON object that contains an "error" member indicates that the
 217       operation completed with an error.  The value of the "error"
 218       member is a short string, specified in this document, that
 219       broadly indicates the class of the error.  Besides the ones
 220       listed for a specific operation, any operation may result in one
 221       the following "error"s:
 222
 223       "error": "resources exhausted"
 224
 225           The operation or the transaction requires more resources
 226           (memory, disk, CPU, etc.) than are currently available to
 227           the database server.
 228
 229       "error": "syntax error"
 230
 231           The operation is not specified correctly: a required request
 232           object member is missing, an unknown or unsupported request
 233           object member is present, the operation attempts to act on a
 234           table that does not exist, the operation modifies a
 235           read-only table column, etc.
 236
 237       Database implementations may use "error" strings not specified
 238       in this document to indicate errors that do not fit into any of
 239       the specified categories.
 240
 241       Optionally, the object may include a "details" member, whose
 242       value is a string that describes the error in more detail for
 243       the benefit of a human user or administrator.  The object may
 244       also have other members that describe the error in more detail.
 245       This document does not specify the names or values of these
 246       members.
 247
 248     - A JSON null value indicates that the operation was not attempted
 249       because a prior operation failed.
 250
 251 In general, "result" contains some number of successful results,
 252 possibly followed by an error, in turn followed by enough JSON null
 253 values to match the number of elements in "params".  There is one
 254 exception: if all of the operations succeed, but the results cannot be
 255 committed (e.g. due to I/O errors), then "result" will have one more
 256 element than "params", with the additional element describing the
 257 error.
 258
 259 If "params" contains one or more "wait" operations, then the
 260 transaction may take an arbitrary amount of time to complete.  The
 261 database implementation must be capable of accepting, executing, and
 262 replying to other transactions and other JSON-RPC requests while a
 263 transaction or transactions containing "wait" operations are
 264 outstanding on the same or different JSON-RPC sessions.
 265
 266 The section "Notation for the Wire Protocol" below describes
 267 additional notation for use with the wire protocol.  After that, the
 268 "Operations" section describes each operation.
 269
 270 cancel
 271 ......
 272
 273 Request object members:
 274
 275     "method": "cancel"                              required
 276     "params": [the "id" for an outstanding request] required
 277     "id": null                                      required
 278
 279 Response object members:
 280
 281     <no response>
 282
 283 This JSON-RPC notification instructs the database server to
 284 immediately complete or cancel the "transact" request whose "id" is
 285 the same as the notification's "params" value.
 286
 287 If the "transact" request can be completed immediately, then the
 288 server sends a response in the form described for "transact", above.
 289 Otherwise, the server sends a JSON-RPC error response of the following
 290 form:
 291
 292     "result": null
 293     "error": "canceled"
 294     "id": the request "id" member
 295
 296 The "cancel" notification itself has no reply.
 297
 298 monitor
 299 .......
 300
 301 Request object members:
 302
 303     "method": "monitor"                        required
 304     "params": [<value>, <monitor-requests>]    required
 305     "id": any JSON value except null           required
 306
 307 <monitor-requests> is an object that maps from a table name to a
 308 <monitor-request>.
 309
 310 Each <monitor-request> is an object with the following members:
 311
 312     "columns": [<column>*]            optional
 313     "select": <monitor-select>        optional
 314
 315 <monitor-select> is an object with the following members:
 316
 317     "initial": <boolean>              optional
 318     "insert": <boolean>               optional
 319     "delete": <boolean>               optional
 320     "modify": <boolean>               optional
 321
 322 Response object members:
 323
 324     "result": <table-updates>
 325     "error": null
 326     "id": same "id" as request
 327
 328 This JSON-RPC request enables a client to replicate tables or subsets
 329 of tables.  Each <monitor-request> specifies a table to be replicated.
 330 The JSON-RPC response to the "monitor" includes the initial contents
 331 of each table.  Afterward, when changes to those tables are committed,
 332 the changes are automatically sent to the client using the "update"
 333 monitor notification.  This monitoring persists until the JSON-RPC
 334 session terminates or until the client sends a "monitor_cancel"
 335 JSON-RPC request.
 336
 337 Each <monitor-request> describes how to monitor a table:
 338
 339     The circumstances in which an "update" notification is sent for a
 340     row within the table are determined by <monitor-select>:
 341
 342         If "initial" is omitted or true, every row in the table is
 343         sent as part of the reply to the "monitor" request.
 344
 345         If "insert" is omitted or true, "update" notifications are
 346         sent for rows newly inserted into the table.
 347
 348         If "delete" is omitted or true, "update" notifications are
 349         sent for rows deleted from the table.
 350
 351         If "modify" is omitted or true, "update" notifications are
 352         sent whenever when a row in the table is modified.
 353
 354     The "columns" member specifies the columns whose values are
 355     monitored.  If "columns" is omitted, all columns in the table,
 356     except for "_uuid", are monitored.
 357
 358 The "result" in the JSON-RPC response to the "monitor" request is a
 359 <table-updates> object (see below) that contains the contents of the
 360 tables for which "initial" rows are selected.  If no tables' initial
 361 contents are requested, then "result" is an empty object.
 362
 363 update
 364 ......
 365
 366 Notification object members:
 367
 368     "method": "update"
 369     "params": [<value>, <table-updates>]
 370     "id": null
 371
 372 The <value> in "params" is the same as the value passed as the <value>
 373 in "params" for the "monitor" request.
 374
 375 <table-updates> is an object that maps from a table name to a
 376 <table-update>.
 377
 378 A <table-update> is an object that maps from the row's UUID (as a
 379 36-byte string) to a <row-update> object.
 380
 381 A <row-update> is an object with the following members:
 382
 383     "old": <row>         present for "delete" and "modify" updates
 384     "new": <row>         present for "initial", "insert", and "modify" updates
 385
 386 This JSON-RPC notification is sent from the server to the client to
 387 tell it about changes to a monitored table (or the initial state of a
 388 modified table).  Each table in which one or more rows has changed (or
 389 whose initial view is being presented) is represented in "updates".
 390 Each row that has changed (or whose initial view is being presented)
 391 is represented in its <table-update> as a member with its name taken
 392 from the row's _uuid member.  The corresponding value is a
 393 <row-update>:
 394
 395     The "old" member is present for "delete" and "modify" updates.
 396     For "delete" updates, each monitored column is included.  For
 397     "modify" updates, the prior value of each monitored column whose
 398     value has changed is included (monitored columns that have not
 399     changed are represented in "new").
 400
 401     The "new" member is present for "initial", "insert", and "modify"
 402     updates.  For "initial" and "insert" updates, each monitored
 403     column is included.  For "modify" updates, the new value of each
 404     monitored column is included.
 405
 406 monitor_cancel
 407 ..............
 408
 409 Request object members:
 410
 411     "method": "monitor_cancel"                              required
 412     "params": [<value>]                                     required
 413     "id": any JSON value except null                        required
 414
 415 Response object members:
 416
 417     "result": {}
 418     "error": null
 419     "id": the request "id" member
 420
 421 Cancels the ongoing table monitor request, identified by the <value>
 422 in "params" matching the <value> in "params" for an ongoing "monitor"
 423 request.  No more "update" messages will be sent for this table
 424 monitor.
 425
 426 echo
 427 ....
 428
 429 Request object members:
 430
 431     "method": "echo"                                required
 432     "params": JSON array with any contents          required
 433     "id": <value>                                   required
 434
 435 Response object members:
 436
 437     "result": same as "params"
 438     "error": null
 439     "id": the request "id" member
 440
 441 Both the JSON-RPC client and the server must implement this request.
 442
 443 This JSON-RPC request and response can be used to implement connection
 444 keepalives, by allowing the server to check that the client is still
 445 there or vice versa.
 446
 447
 448 Notation for the Wire Protocol
 449 ------------------------------
 450
 451 <table>
 452
 453     An <id> that names a table.
 454
 455 <column>
 456
 457     An <id> that names a table column.
 458
 459 <row>
 460
 461     A JSON object that describes a table row or a subset of a table
 462     row.  Each member is the name of a table column paired with the
 463     <value> of that column.
 464
 465 <value>
 466
 467     A JSON value that represents the value of a column in a table row,
 468     one of <atom>, a <set>, or a <map>.
 469
 470 <atom>
 471
 472     A JSON value that represents a scalar value for a column, one of
 473     <string>, <number>, <boolean>, <uuid>, <named-uuid>.
 474
 475 <set>
 476
 477     A 2-element JSON array that represents a database set value.  The
 478     first element of the array must be the string "set" and the second
 479     element must be an array of zero or more <atom>s giving the values
 480     in the set.  All of the <atom>s must have the same type.
 481
 482 <map>
 483
 484     A 2-element JSON array that represents a database map value.  The
 485     first element of the array must be the string "map" and the second
 486     element must be an array of zero or more <pair>s giving the values
 487     in the map.  All of the <pair>s must have the same key and value
 488     types.
 489
 490     (JSON objects are not used to represent <map> because JSON only
 491     allows string names in an object.)
 492
 493 <pair>
 494
 495     A 2-element JSON array that represents a pair within a database
 496     map.  The first element is an <atom> that represents the key, the
 497     second element is an <atom> that represents the value.
 498
 499 <uuid>
 500
 501     A 2-element JSON array that represents a UUID.  The first element
 502     of the array must be the string "uuid" and the second element must
 503     be a 36-character string giving the UUID in the format described
 504     by RFC 4122.  For example, the following <uuid> represents the
 505     UUID 550e8400-e29b-41d4-a716-446655440000:
 506
 507         ["uuid", "550e8400-e29b-41d4-a716-446655440000"]
 508
 509 <named-uuid>
 510
 511     A 2-element JSON array that represents the UUID of a row inserted
 512     in a previous "insert" operation within the same transaction.  The
 513     first element of the array must be the string "named-uuid" and the
 514     second element must be the string specified on this "insert"
 515     operation's "uuid-name" or on a preceding "insert" within the same
 516     transaction.  For example, if this or a previous "insert"
 517     operation specified a "uuid-name" of "myrow", the following
 518     <named-uuid> represents the UUID created by that operation:
 519
 520         ["named-uuid", "myrow"]
 521
 522     A <named-uuid> may be used anywhere a <uuid> is valid.
 523
 524 <condition>
 525
 526     A 3-element JSON array of the form [<column>, <function>,
 527     <value>] that represents a test on a column value.
 528
 529     Except as otherwise specified below, <value> must have the same
 530     type as <column>.
 531
 532     The meaning depends on the type of <column>:
 533
 534         integer
 535         real
 536
 537             <function> must be "<", "<=", "==", "!=", ">=", ">",
 538             "includes", or "excludes".
 539
 540             The test is true if the column's value satisfies the
 541             relation <function> <value>, e.g. if the column has value
 542             1 and <value> is 2, the test is true if <function> is "<",
 543             "<=" or "!=", but not otherwise.
 544
 545             "includes" is equivalent to "=="; "excludes" is equivalent
 546             to "!=".
 547
 548         boolean
 549         string
 550         uuid
 551
 552             <function> must be "!=", "==", "includes", or "excludes".
 553
 554             If <function> is "==" or "includes", the test is true if
 555             the column's value equals <value>.  If <function> is "!="
 556             or "excludes", the test is inverted.
 557
 558         set
 559         map
 560
 561             <function> must be "!=", "==", "includes", or "excludes".
 562
 563             If <function> is "==", the test is true if the column's
 564             value contains exactly the same values (for sets) or pairs
 565             (for maps).  If <function> is "!=", the test is inverted.
 566
 567             If <function> is "includes", the test is true if the
 568             column's value contains all of the values (for sets) or
 569             pairs (for maps) in <value>.  The column's value may also
 570             contain other values or pairs.
 571
 572             If <function> is "excludes", the test is true if the
 573             column's value does not contain any of the values (for
 574             sets) or pairs (for maps) in <value>.  The column's value
 575             may contain other values or pairs not in <value>.
 576
 577             If <function> is "includes" or "excludes", then the
 578             required type of <value> is slightly relaxed, in that it
 579             may have fewer than the minimum number of elements
 580             specified by the column's type.  If <function> is
 581             "excludes", then the required type is additionally relaxed
 582             in that <value> may have more than the maximum number of
 583             elements specified by the column's type.
 584
 585 <function>
 586
 587     One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes".
 588
 589 Operations
 590 ----------
 591
 592 Each of the available operations is described below.
 593
 594 insert
 595 ......
 596
 597 Request object members:
 598
 599     "op": "insert"          required
 600     "table": <table>        required
 601     "row": <row>            required
 602     "uuid-name": <id>       optional
 603
 604 Result object members:
 605
 606     "uuid": <uuid>
 607
 608 Semantics:
 609
 610     Inserts "row" into "table".  If "row" does not specify values
 611     for all the columns in "table", those columns receive default
 612     values.
 613
 614     If "uuid-name" is not supplied, the new row receives a new,
 615     randomly generated UUID.
 616
 617     If "uuid-name" is supplied, then it is an error if <id> has
 618     previously appeared as the "uuid-name" in an "insert" operation.
 619
 620     If "uuid-name" is supplied and its <id> previously appeared as the
 621     "uuid-name" in a "declare" operation, then the new row receives
 622     the UUID associated with that "uuid-name".
 623
 624     If "uuid-name" is supplied and its <id> has not previously
 625     appeared as the "uuid-name" in a "declare" operation, then the new
 626     row also receives a new, randomly generated UUID.  This UUID is
 627     also made available under that name to this operation and later
 628     operations within the same transaction.
 629
 630     The UUID for the new row is returned as the "uuid" member of the
 631     result.
 632
 633 Errors:
 634
 635     "error": "duplicate uuid-name"
 636
 637         The same "uuid-name" appeared on an earlier "insert" operation
 638         within this transaction.
 639
 640 select
 641 ......
 642
 643 Request object members:
 644
 645     "op": "select"                required
 646     "table": <table>              required
 647     "where": [<condition>*]       required
 648     "columns": [<column>*]        optional
 649
 650 Result object members:
 651
 652     "rows": [<row>*]
 653
 654 Semantics:
 655
 656     Searches "table" for rows that match all the conditions specified
 657     in "where".  If "where" is an empty array, every row in "table" is
 658     selected.
 659
 660     The "rows" member of the result is an array of objects.  Each
 661     object corresponds to a matching row, with each column
 662     specified in "columns" as a member, the column's name as the
 663     member name and its value as the member value.  If "columns"
 664     is not specified, all the table's columns are included.  If
 665     two rows of the result have the same values for all included
 666     columns, only one copy of that row is included in "rows".
 667     Specifying "_uuid" within "columns" will avoid dropping
 668     duplicates, since every row has a unique UUID.
 669
 670     The ordering of rows within "rows" is unspecified.
 671
 672 update
 673 ......
 674
 675 Request object members:
 676
 677     "op": "update"                required
 678     "table": <table>              required
 679     "where": [<condition>*]       required
 680     "row": <row>                  required
 681
 682 Result object members:
 683
 684     "count": <integer>
 685
 686 Semantics:
 687
 688     Updates rows in a table.
 689
 690     Searches "table" for rows that match all the conditions
 691     specified in "where".  For each matching row, changes the
 692     value of each column specified in "row" to the value for that
 693     column specified in "row".
 694
 695     The "_uuid" and "_version" columns of a table may not be directly
 696     updated with this operation.  Columns designated read-only in the
 697     schema also may not be updated.
 698
 699     The "count" member of the result specifies the number of rows
 700     that matched.
 701
 702 delete
 703 ......
 704
 705 Request object members:
 706
 707     "op": "delete"                required
 708     "table": <table>              required
 709     "where": [<condition>*]       required
 710
 711 Result object members:
 712
 713     "count": <integer>
 714
 715 Semantics:
 716
 717     Deletes all the rows from "table" that match all the conditions
 718     specified in "where".
 719
 720     The "count" member of the result specifies the number of deleted
 721     rows.
 722
 723 wait
 724 ....
 725
 726 Request object members:
 727
 728     "op": "wait"                        required
 729     "timeout": <integer>                optional
 730     "table": <table>                    required
 731     "where": [<condition>*]             required
 732     "columns": [<column>*]              required
 733     "until": "==" or "!="               required
 734     "rows": [<row>*]                    required
 735
 736 Result object members:
 737
 738     none
 739
 740 Semantics:
 741
 742     Waits until a condition becomes true.
 743
 744     If "until" is "==", checks whether the query on "table" specified
 745     by "where" and "columns", which is evaluated in the same way as
 746     specified for "select", returns the result set specified by
 747     "rows".  If it does, then the operation completes successfully.
 748     Otherwise, the entire transaction rolls back.  It is automatically
 749     restarted later, after a change in the database makes it possible
 750     for the operation to succeed.  The client will not receive a
 751     response until the operation permanently succeeds or fails.
 752
 753     If "until" is "!=", the sense of the test is negated.  That is, as
 754     long as the query on "table" specified by "where" and "columns"
 755     returns "rows", the transaction will be rolled back and restarted
 756     later.
 757
 758     If "timeout" is specified, then the transaction aborts after the
 759     specified number of milliseconds.  The transaction is guaranteed
 760     to be attempted at least once before it aborts.  A "timeout" of 0
 761     will abort the transaction on the first mismatch.
 762
 763 Errors:
 764
 765     "error": "not supported"
 766
 767         One or more of the columns in this table do not support
 768         triggers.  This error will not occur if "timeout" is 0.
 769
 770     "error": "timed out"
 771
 772         The "timeout" was reached before the transaction was able to
 773         complete.
 774
 775 commit
 776 ......
 777
 778 Request object members:
 779
 780     "op": "commit"                      required
 781     "durable": <boolean>                required
 782
 783 Result object members:
 784
 785     none
 786
 787 Semantics:
 788
 789     If "durable" is specified as true, then the transaction, if it
 790     commits, will be stored durably (to disk) before the reply is sent
 791     to the client.
 792
 793 Errors:
 794
 795     "error": "not supported"
 796
 797         When "durable" is true, this database implementation does not
 798         support durable commits.
 799
 800 abort
 801 .....
 802
 803 Request object members:
 804
 805     "op": "abort"                      required
 806
 807 Result object members:
 808
 809     (never succeeds)
 810
 811 Semantics:
 812
 813     Aborts the transaction with an error.  This may be useful for
 814     testing.
 815
 816 Errors:
 817
 818     "error": "aborted"
 819
 820         This operation always fails with this error.
 821
 822 declare
 823 .......
 824
 825 Request object members:
 826
 827     "op": "declare"                    required
 828     "uuid-name": <id>                  required
 829
 830 Result object members:
 831
 832     none
 833
 834 Semantics:
 835
 836     Predeclares a UUID named <id> that may be referenced in later
 837     operations as ["named-uuid", <id>] or (at most once) in an
 838     "insert" operation as "uuid-name".
 839
 840     It is an error if <id> has appeared as the "uuid-name" in a prior
 841     "insert" or "declare" operation within this transaction.
 842
 843     The generated UUID is returned as the "uuid" member of the result.
 844
 845 Result object members:
 846
 847     "uuid": <uuid>
 848
 849 Errors:
 850
 851     "error": "duplicate uuid-name"
 852
 853         The same "uuid-name" appeared on an earlier "insert" or
 854         "declare" operation within this transaction.