.. Licensed under the Apache License, Version 2.0 (the "License"); you may not
.. use this file except in compliance with the License. You may obtain a copy of
.. the License at
..
..   http://www.apache.org/licenses/LICENSE-2.0
..
.. Unless required by applicable law or agreed to in writing, software
.. distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
.. WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
.. License for the specific language governing permissions and limitations under
.. the License.

========================
JSON Structure Reference
========================

The following appendix provides a quick reference to all the JSON structures
that you can supply to CouchDB, or get in return to requests.

All Database Documents
======================

+-----------------------+------------------------------------------+
| Field                 | Description                              |
+=======================+==========================================+
| total_rows            | Number of documents in the database/view |
+-----------------------+------------------------------------------+
| offset                | Offset where the document list started   |
+-----------------------+------------------------------------------+
| update_seq (optional) | Current update sequence for the database |
+-----------------------+------------------------------------------+
| rows [array]          | Array of document object                 |
+-----------------------+------------------------------------------+

Bulk Document Response
======================

+--------------+-----------------------------------+
| Field        | Description                       |
+==============+===================================+
| docs [array] | Bulk Docs Returned Documents      |
+--------------+-----------------------------------+
| id           | Document ID                       |
+--------------+-----------------------------------+
| error        | Error type                        |
+--------------+-----------------------------------+
| reason       | Error string with extended reason |
+--------------+-----------------------------------+

Bulk Documents
==============

+---------------------+----------------------------------------+
| Field               | Description                            |
+=====================+========================================+
| docs [array]        | Bulk Documents Document                |
+---------------------+----------------------------------------+
| _id (optional)      | Document ID                            |
+---------------------+----------------------------------------+
| _rev (optional)     | Revision ID (when updating an existing |
|                     | document)                              |
+---------------------+----------------------------------------+
| _deleted (optional) | Whether the document should be deleted |
+---------------------+----------------------------------------+

Changes information for a database
==================================

+-----------------+-------------------------------------------+
| Field           | Description                               |
+=================+===========================================+
| last_seq        | Last update sequence                      |
+-----------------+-------------------------------------------+
| pending         | Count of remaining items in the feed      |
+-----------------+-------------------------------------------+
| results [array] | Changes made to a database                |
+-----------------+-------------------------------------------+
| seq             | Update sequence                           |
+-----------------+-------------------------------------------+
| id              | Document ID                               |
+-----------------+-------------------------------------------+
| changes [array] | List of changes, field-by-field, for this |
|                 | document                                  |
+-----------------+-------------------------------------------+

CouchDB Document
================

+-----------------+----------------------------------------+
| Field           | Description                            |
+=================+========================================+
| _id (optional)  | Document ID                            |
+-----------------+----------------------------------------+
| _rev (optional) | Revision ID (when updating an existing |
|                 | document)                              |
+-----------------+----------------------------------------+

CouchDB Error Status
====================

+--------+-----------------------------------+
| Field  | Description                       |
+========+===================================+
| id     | Document ID                       |
+--------+-----------------------------------+
| error  | Error type                        |
+--------+-----------------------------------+
| reason | Error string with extended reason |
+--------+-----------------------------------+

.. _dbinfo_object:

CouchDB database information object
===================================

+----------------------+----------------------------------------------+
| Field                | Description                                  |
+======================+==============================================+
| db_name              | The name of the database.                    |
+----------------------+----------------------------------------------+
| committed_update_seq | The number of committed updates.             |
+----------------------+----------------------------------------------+
| doc_count            | The number of documents in the database.     |
+----------------------+----------------------------------------------+
| doc_del_count        | The number of deleted documents.             |
+----------------------+----------------------------------------------+
| compact_running      | Set to true if the database compaction       |
|                      | routine is operating on this database.       |
+----------------------+----------------------------------------------+
| disk_format_version  | The version of the physical format used for  |
|                      | the data when it is stored on hard disk.     |
+----------------------+----------------------------------------------+
| disk_size            | Size in bytes of the data as stored on disk. |
|                      | View indexes are not included in the         |
|                      | calculation.                                 |
+----------------------+----------------------------------------------+
| instance_start_time  | Timestamp indicating when the database was   |
|                      | opened, expressed in microseconds since the  |
|                      | epoch.                                       |
+----------------------+----------------------------------------------+
| purge_seq            | The number of purge operations on the        |
|                      | database.                                    |
+----------------------+----------------------------------------------+
| update_seq           | Current update sequence for the database.    |
+----------------------+----------------------------------------------+

Design Document
===============

+-------------------+--------------------------+
| Field             | Description              |
+===================+==========================+
| _id               | Design Document ID       |
+-------------------+--------------------------+
| _rev              | Design Document Revision |
+-------------------+--------------------------+
| views             | View                     |
+-------------------+--------------------------+
| viewname          | View Definition          |
+-------------------+--------------------------+
| map               | Map Function for View    |
+-------------------+--------------------------+
| reduce (optional) | Reduce Function for View |
+-------------------+--------------------------+

Design Document Information
===========================

+-----------------+----------------------------------------------+
| Field           | Description                                  |
+=================+==============================================+
| name            | Name/ID of Design Document                   |
+-----------------+----------------------------------------------+
| view_index      | View Index                                   |
+-----------------+----------------------------------------------+
| compact_running | Indicates whether a compaction routine is    |
|                 | currently running on the view                |
+-----------------+----------------------------------------------+
| disk_size       | Size in bytes of the view as stored on disk  |
+-----------------+----------------------------------------------+
| language        | Language for the defined views               |
+-----------------+----------------------------------------------+
| purge_seq       | The purge sequence that has been processed   |
+-----------------+----------------------------------------------+
| signature       | MD5 signature of the views for the design    |
|                 | document                                     |
+-----------------+----------------------------------------------+
| update_seq      | The update sequence of the corresponding     |
|                 | database that has been indexed               |
+-----------------+----------------------------------------------+
| updater_running | Indicates if the view is currently being     |
|                 | updated                                      |
+-----------------+----------------------------------------------+
| waiting_clients | Number of clients waiting on views from this |
|                 | design document                              |
+-----------------+----------------------------------------------+
| waiting_commit  | Indicates if there are outstanding commits   |
|                 | to the underlying database that need to      |
|                 | processed                                    |
+-----------------+----------------------------------------------+

Document with Attachments
=========================

+-------------------------+-----------------------------------------+
| Field                   | Description                             |
+=========================+=========================================+
| _id (optional)          | Document ID                             |
+-------------------------+-----------------------------------------+
| _rev (optional)         | Revision ID (when updating an existing  |
|                         | document)                               |
+-------------------------+-----------------------------------------+
| _attachments (optional) | Document Attachment                     |
+-------------------------+-----------------------------------------+
| filename                | Attachment information                  |
+-------------------------+-----------------------------------------+
| content_type            | MIME Content type string                |
+-------------------------+-----------------------------------------+
| data                    | File attachment content, Base64 encoded |
+-------------------------+-----------------------------------------+

List of Active Tasks
====================

+---------------+---------------------+
| Field         | Description         |
+===============+=====================+
| tasks [array] | Active Tasks        |
+---------------+---------------------+
| pid           | Process ID          |
+---------------+---------------------+
| status        | Task status message |
+---------------+---------------------+
| task          | Task name           |
+---------------+---------------------+
| type          | Operation Type      |
+---------------+---------------------+

.. _replication-settings:

Replication Settings
====================

+--------------------------------+---------------------------------------------+
| Field                          | Description                                 |
+================================+=============================================+
| source                         | Source database name or URL.                |
+--------------------------------+---------------------------------------------+
| target                         | Target database name or URL.                |
+--------------------------------+---------------------------------------------+
| cancel (optional)              | Cancels the replication.                    |
+--------------------------------+---------------------------------------------+
| checkpoint_interval (optional) | Specifies the checkpoint interval in ms.    |
+--------------------------------+---------------------------------------------+
| continuous (optional)          | Configure the replication to be continuous. |
+--------------------------------+---------------------------------------------+
| create_target (optional)       | Creates the target database.                |
+--------------------------------+---------------------------------------------+
| doc_ids (optional)             | Array of document IDs to be synchronized.   |
+--------------------------------+---------------------------------------------+
| filter (optional)              | name of the filter function in the form of  |
|                                | ``ddoc/myfilter``.                          |
+--------------------------------+---------------------------------------------+
| source_proxy (optional)        | Address of a proxy server through which     |
|                                | replication from the source should occur.   |
+--------------------------------+---------------------------------------------+
| target_proxy (optional)        | Address of a proxy server through which     |
|                                | replication to the target should occur.     |
+--------------------------------+---------------------------------------------+
| query_params (optional)        | Query parameter that are passed to the      |
|                                | filter function; the value should be a      |
|                                | document containing parameters as members.  |
+--------------------------------+---------------------------------------------+
| selector (optional)            | Select the documents included in the        |
|                                | replication. This option provides           |
|                                | performance benefits compared with using    |
|                                | the ``filter`` option.                      |
+--------------------------------+---------------------------------------------+
| since_seq (optional)           | Sequence from which the replication should  |
|                                | start.                                      |
+--------------------------------+---------------------------------------------+
| use_checkpoints (optional)     | Whether to use replication checkpoints      |
|                                | or not.                                     |
+--------------------------------+---------------------------------------------+
| winning_revs_only (optional)   | Replicate only the winning revisions.       |
+--------------------------------+---------------------------------------------+

.. _replication-status:

Replication Status
==================

+--------------------+-------------------------------------------+
| Field              | Description                               |
+====================+===========================================+
| ok                 | Replication status                        |
+--------------------+-------------------------------------------+
| session_id         | Unique session ID                         |
+--------------------+-------------------------------------------+
| source_last_seq    | Last sequence number read from the source |
|                    | database                                  |
+--------------------+-------------------------------------------+
| history [array]    | Replication History                       |
+--------------------+-------------------------------------------+
| session_id         | Session ID for this replication operation |
+--------------------+-------------------------------------------+
| recorded_seq       | Last recorded sequence number             |
+--------------------+-------------------------------------------+
| docs_read          | Number of documents read                  |
+--------------------+-------------------------------------------+
| docs_written       | Number of documents written to target     |
+--------------------+-------------------------------------------+
| doc_write_failures | Number of document write failures         |
+--------------------+-------------------------------------------+
| start_time         | Date/Time replication operation started   |
+--------------------+-------------------------------------------+
| start_last_seq     | First sequence number in changes stream   |
+--------------------+-------------------------------------------+
| end_time           | Date/Time replication operation completed |
+--------------------+-------------------------------------------+
| end_last_seq       | Last sequence number in changes stream    |
+--------------------+-------------------------------------------+
| missing_checked    | Number of missing documents checked       |
+--------------------+-------------------------------------------+
| missing_found      | Number of missing documents found         |
+--------------------+-------------------------------------------+
| bulk_get_attempts  | Number of attempted _bulk_get fetches     |
+--------------------+-------------------------------------------+
| bulk_get_docs      | Number of documents read with _bulk_get   |
+--------------------+-------------------------------------------+

.. _request_object:

Request object
==============

+----------------+---------------------------------------------+
| Field          | Description                                 |
+================+=============================================+
| body           | Request body data as `string`.              |
|                | If the request method is `GET` this field   |
|                | contains the value ``"undefined"``. If the  |
|                | method is `DELETE` or `HEAD` the value is   |
|                | ``""`` (empty string).                      |
+----------------+---------------------------------------------+
| cookie         | Cookies `object`.                           |
+----------------+---------------------------------------------+
| form           | Form data `object`.                         |
|                | Contains the decoded body as key-value      |
|                | pairs if the `Content-Type` header was      |
|                | ``application/x-www-form-urlencoded``.      |
+----------------+---------------------------------------------+
| headers        | Request headers `object`.                   |
+----------------+---------------------------------------------+
| id             | Requested document id `string` if it was    |
|                | specified or ``null`` otherwise.            |
+----------------+---------------------------------------------+
| info           | :ref:`Database information <dbinfo_object>` |
+----------------+---------------------------------------------+
| method         | Request method as `string` or `array`.      |
|                | String value is a method as one of: `HEAD`, |
|                | `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`,  |
|                | and `TRACE`. Otherwise it will be           |
|                | represented as an array of char codes.      |
+----------------+---------------------------------------------+
| path           | List of requested path sections.            |
+----------------+---------------------------------------------+
| peer           | Request source IP address.                  |
+----------------+---------------------------------------------+
| query          | URL query parameters `object`.              |
|                | Note that multiple keys are not supported   |
|                | and the last key value suppresses others.   |
+----------------+---------------------------------------------+
| requested_path | List of actual requested path section.      |
+----------------+---------------------------------------------+
| raw_path       | Raw requested path `string`.                |
+----------------+---------------------------------------------+
| secObj         | :ref:`security_object`.                     |
+----------------+---------------------------------------------+
| userCtx        | :ref:`userctx_object`.                      |
+----------------+---------------------------------------------+
| uuid           | Generated UUID by a specified algorithm in  |
|                | the config file.                            |
+----------------+---------------------------------------------+

.. code-block:: javascript

    {
        "body": "undefined",
        "cookie": {
            "AuthSession": "cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
            "m": "3234"
        },
        "form": {},
        "headers": {
            "Accept": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
            "Accept-Charset": "ISO-8859-1,utf-8;q=0.7,*;q=0.3",
            "Accept-Encoding": "gzip,deflate,sdch",
            "Accept-Language": "en-US,en;q=0.8",
            "Connection": "keep-alive",
            "Cookie": "m=3234:t|3247:t|6493:t|6967:t|34e2:|18c3:t|2c69:t|5acb:t|ca3:t|c01:t|5e55:t|77cb:t|2a03:t|1d98:t|47ba:t|64b8:t|4a01:t; AuthSession=cm9vdDo1MDZBRjQzRjrfcuikzPRfAn-EA37FmjyfM8G8Lw",
            "Host": "127.0.0.1:5984",
            "User-Agent": "Mozilla/5.0 (Windows NT 5.2) AppleWebKit/535.7 (KHTML, like Gecko) Chrome/16.0.912.75 Safari/535.7"
        },
        "id": "foo",
        "info": {
            "committed_update_seq": 2701412,
            "compact_running": false,
            "db_name": "mailbox",
            "disk_format_version": 6,
            "doc_count": 2262757,
            "doc_del_count": 560,
            "instance_start_time": "1347601025628957",
            "purge_seq": 0,
            "sizes": {
              "active": 7580843252,
              "disk": 14325313673,
              "external": 7803423459
            },
            "update_seq": 2701412
        },
        "method": "GET",
        "path": [
            "mailbox",
            "_design",
            "request",
            "_show",
            "dump",
            "foo"
        ],
        "peer": "127.0.0.1",
        "query": {},
        "raw_path": "/mailbox/_design/request/_show/dump/foo",
        "requested_path": [
            "mailbox",
            "_design",
            "request",
            "_show",
            "dump",
            "foo"
        ],
        "secObj": {
            "admins": {
                "names": [
                    "Bob"
                ],
                "roles": []
            },
            "members": {
                "names": [
                    "Mike",
                    "Alice"
                ],
                "roles": []
            }
        },
        "userCtx": {
            "db": "mailbox",
            "name": "Mike",
            "roles": [
                "user"
            ]
        },
        "uuid": "3184f9d1ea934e1f81a24c71bde5c168"
    }

.. _request2_object:

Request2 object
===============

+----------------+---------------------------------------------+
| Field          | Description                                 |
+================+=============================================+
| body           | Request body data as `string`.              |
|                | If the request method is `GET` this field   |
|                | contains the value ``"undefined"``. If the  |
|                | method is `DELETE` or `HEAD` the value is   |
|                | ``""`` (empty string).                      |
+----------------+---------------------------------------------+
| cookie         | Cookies `object`.                           |
+----------------+---------------------------------------------+
| headers        | Request headers `object`.                   |
+----------------+---------------------------------------------+
| method         | Request method as `string` or `array`.      |
|                | String value is a method as one of: `HEAD`, |
|                | `GET`, `POST`, `PUT`, `DELETE`, `OPTIONS`,  |
|                | and `TRACE`. Otherwise it will be           |
|                | represented as an array of char codes.      |
+----------------+---------------------------------------------+
| path           | List of requested path sections.            |
+----------------+---------------------------------------------+
| peer           | Request source IP address.                  |
+----------------+---------------------------------------------+
| query          | URL query parameters `object`.              |
|                | Note that multiple keys are not supported   |
|                | and the last key value suppresses others.   |
+----------------+---------------------------------------------+
| requested_path | List of actual requested path section.      |
+----------------+---------------------------------------------+
| raw_path       | Raw requested path `string`.                |
+----------------+---------------------------------------------+
| secObj         | :ref:`security_object`.                     |
+----------------+---------------------------------------------+
| userCtx        | :ref:`userctx_object`.                      |
+----------------+---------------------------------------------+

.. _response_object:

Response object
===============

+---------+--------------------------------------------+
| Field   | Description                                |
+=========+============================================+
| code    | HTTP status code `number`.                 |
+---------+--------------------------------------------+
| json    | JSON encodable `object`.                   |
|         | Implicitly sets `Content-Type` header as   |
|         | ``application/json``.                      |
+---------+--------------------------------------------+
| body    | Raw response text `string`.                |
|         | Implicitly sets `Content-Type` header as   |
|         | ``text/html; charset=utf-8``.              |
+---------+--------------------------------------------+
| base64  | Base64 encoded `string`.                   |
|         | Implicitly sets `Content-Type` header as   |
|         | ``application/binary``.                    |
+---------+--------------------------------------------+
| headers | Response headers `object`.                 |
|         | `Content-Type` header from this object     |
|         | overrides any implicitly assigned one.     |
+---------+--------------------------------------------+
| stop    | `boolean` signal to stop iteration over    |
|         | view result rows (for list functions only) |
+---------+--------------------------------------------+

.. warning::
    The ``body``, ``base64`` and ``json`` object keys are overlapping each other
    where the last one wins. Since most realizations of key-value objects do
    not preserve the key order or if they are mixed, confusing situations can
    occur. Try to use only one of them.

.. note::
    Any custom property makes CouchDB raise an internal exception. Furthermore,
    the `Response object` could be a simple string value which would be
    implicitly wrapped into a ``{"body": ...}`` object.

Returned CouchDB Document with Detailed Revision Info
=====================================================

+--------------------+-----------------------------------------+
| Field              | Description                             |
+====================+=========================================+
| _id (optional)     | Document ID                             |
+--------------------+-----------------------------------------+
| _rev (optional)    | Revision ID (when updating an existing  |
|                    | document)                               |
+--------------------+-----------------------------------------+
| _revs_info [array] | CouchDB document extended revision info |
+--------------------+-----------------------------------------+
| rev                | Full revision string                    |
+--------------------+-----------------------------------------+
| status             | Status of the revision                  |
+--------------------+-----------------------------------------+

Returned CouchDB Document with Revision Info
============================================

+-----------------+-----------------------------------------+
| Field           | Description                             |
+=================+=========================================+
| _id (optional)  | Document ID                             |
+-----------------+-----------------------------------------+
| _rev (optional) | Revision ID (when updating an existing  |
|                 | document)                               |
+-----------------+-----------------------------------------+
| _revisions      | CouchDB document revisions              |
+-----------------+-----------------------------------------+
| ids [array]     | Array of valid revision IDs, in reverse |
|                 | order (latest first)                    |
+-----------------+-----------------------------------------+
| start           | Prefix number for the latest revision   |
+-----------------+-----------------------------------------+

Returned Document with Attachments
==================================

+-------------------------+--------------------------------------------+
| Field                   | Description                                |
+=========================+============================================+
| _id (optional)          | Document ID                                |
+-------------------------+--------------------------------------------+
| _rev (optional)         | Revision ID (when updating an existing     |
|                         | document)                                  |
+-------------------------+--------------------------------------------+
| _attachments (optional) | Document attachment                        |
+-------------------------+--------------------------------------------+
| filename                | Attachment                                 |
+-------------------------+--------------------------------------------+
| stub                    | Indicates whether the attachment is a stub |
+-------------------------+--------------------------------------------+
| content_type            | MIME Content type string                   |
+-------------------------+--------------------------------------------+
| length                  | Length (bytes) of the attachment data      |
+-------------------------+--------------------------------------------+
| revpos                  | Revision where this attachment exists      |
+-------------------------+--------------------------------------------+

.. _security_object:

Security Object
===============

+---------------+---------------------------------------+
| Field         | Description                           |
+===============+=======================================+
| admins        | Roles/Users with admin privileges     |
+---------------+---------------------------------------+
| roles [array] | List of roles with parent privilege   |
+---------------+---------------------------------------+
| names [array] | List of users with parent privilege   |
+---------------+---------------------------------------+
| members       | Roles/Users with non-admin privileges |
+---------------+---------------------------------------+
| roles [array] | List of roles with parent privilege   |
+---------------+---------------------------------------+
| names [array] | List of users with parent privilege   |
+---------------+---------------------------------------+

.. code-block:: javascript

    {
        "admins": {
            "names": [
                "Bob"
            ],
            "roles": []
        },
        "members": {
            "names": [
                "Mike",
                "Alice"
            ],
            "roles": []
        }
    }

.. _userctx_object:

User Context Object
===================

+-------+-------------------------------------+
| Field | Description                         |
+=======+=====================================+
| db    | Database name in the context of the |
|       | provided operation.                 |
+-------+-------------------------------------+
| name  | User name.                          |
+-------+-------------------------------------+
| roles | List of user roles.                 |
+-------+-------------------------------------+

.. code-block:: javascript

    {
        "db": "mailbox",
        "name": null,
        "roles": [
            "_admin"
        ]
    }

.. _view_head_info_object:

View Head Information
=====================

+------------+----------------------------------------+
| Field      | Description                            |
+============+========================================+
| total_rows | Number of documents in the view        |
+------------+----------------------------------------+
| offset     | Offset where the document list started |
+------------+----------------------------------------+

.. code-block:: javascript

    {
        "total_rows": 42,
        "offset": 3
    }