Document

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-cloud-firestore/json-schema/google-cloud-firestore-document-schema.json",
  "title": "Document",
  "description": "A Firestore document. Must not exceed 1 MiB - 4 bytes.",
  "x-generated": "2026-11-11",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/google-cloud-firestore-projects-api-openapi.yml#/components/schemas/Document",
  "type": "object",
  "properties": {
    "name": {
      "description": "The resource name of the document, for example `projects/{project_id}/databases/{database_id}/documents/{document_path}`.",
      "type": "string"
    },
    "fields": {
      "additionalProperties": {
        "$ref": "#/$defs/Value"
      },
      "description": "The document's fields. The map keys represent field names. Field names matching the regular expression `__.*__` are reserved. Reserved field names are forbidden except in certain documented contexts. The field names, represented as UTF-8, must not exceed 1,500 bytes and cannot be empty. Field paths may be used in other contexts to refer to structured fields defined here. For `map_value`, the field path is represented by a dot-delimited (`.`) string of segments. Each segment is either a simple field name (defined below) or a quoted field name. For example, the structured field `\"foo\" : { map_value: { \"x&y\" : { string_value: \"hello\" }}}` would be represented by the field path `` foo.`x&y` ``. A simple field name contains only characters `a` to `z`, `A` to `Z`, `0` to `9`, or `_`, and must not start with `0` to `9`. For example, `foo_bar_17`. A quoted field name starts and ends with `` ` `` and may contain any character. Some characters, including `` ` ``, must be escaped using a `\\`. For example, `` `x&y` `` represents `x&y` and `` `bak\\`tik` `` represents `` bak`tik ``.",
      "type": "object"
    },
    "createTime": {
      "format": "google-datetime",
      "type": "string",
      "description": "Output only. The time at which the document was created. This value increases monotonically when a document is deleted then recreated. It can also be compared to values from other documents and the `read_time` of a query."
    },
    "updateTime": {
      "type": "string",
      "format": "google-datetime",
      "description": "Output only. The time at which the document was last changed. This value is initially set to the `create_time` then increases monotonically with each change to the document. It can also be compared to values from other documents and the `read_time` of a query."
    }
  },
  "$defs": {
    "ArrayValue": {
      "type": "object",
      "description": "An array value.",
      "properties": {
        "values": {
          "items": {
            "$ref": "#/$defs/Value"
          },
          "type": "array",
          "description": "Values in the array."
        }
      }
    },
    "Function": {
      "description": "Represents an unevaluated scalar expression. For example, the expression `like(user_name, \"%alice%\")` is represented as: ``` name: \"like\" args { field_reference: \"user_name\" } args { string_value: \"%alice%\" } ```",
      "type": "object",
      "properties": {
        "args": {
          "description": "Optional. Ordered list of arguments the given function expects.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Value"
          }
        },
        "options": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/Value"
          },
          "description": "Optional. Optional named arguments that certain functions may support."
        },
        "name": {
          "type": "string",
          "description": "Required. The name of the function to evaluate. **Requires:** * must be in snake case (lower case with underscore separator)."
        }
      }
    },
    "LatLng": {
      "description": "An object that represents a latitude/longitude pair. This is expressed as a pair of doubles to represent degrees latitude and degrees longitude. Unless specified otherwise, this object must conform to the WGS84 standard. Values must be within normalized ranges.",
      "type": "object",
      "properties": {
        "latitude": {
          "description": "The latitude in degrees. It must be in the range [-90.0, +90.0].",
          "type": "number",
          "format": "double"
        },
        "longitude": {
          "format": "double",
          "type": "number",
          "description": "The longitude in degrees. It must be in the range [-180.0, +180.0]."
        }
      }
    },
    "MapValue": {
      "description": "A map value.",
      "type": "object",
      "properties": {
        "fields": {
          "description": "The map's fields. The map keys represent field names. Field names matching the regular expression `__.*__` are reserved. Reserved field names are forbidden except in certain documented contexts. The map keys, represented as UTF-8, must not exceed 1,500 bytes and cannot be empty.",
          "additionalProperties": {
            "$ref": "#/$defs/Value"
          },
          "type": "object"
        }
      }
    },
    "Pipeline": {
      "description": "A Firestore query represented as an ordered list of operations / stages.",
      "properties": {
        "stages": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/Stage"
          },
          "description": "Required. Ordered list of stages to evaluate."
        }
      },
      "type": "object"
    },
    "Stage": {
      "description": "A single operation within a pipeline. A stage is made up of a unique name, and a list of arguments. The exact number of arguments & types is dependent on the stage type. To give an example, the stage `filter(state = \"MD\")` would be encoded as: ``` name: \"filter\" args { function_value { name: \"eq\" args { field_reference_value: \"state\" } args { string_value: \"MD\" } } } ``` See public documentation for the full list.",
      "properties": {
        "name": {
          "type": "string",
          "description": "Required. The name of the stage to evaluate. **Requires:** * must be in snake case (lower case with underscore separator)."
        },
        "options": {
          "description": "Optional. Optional named arguments that certain functions may support.",
          "type": "object",
          "additionalProperties": {
            "$ref": "#/$defs/Value"
          }
        },
        "args": {
          "description": "Optional. Ordered list of arguments the given stage expects.",
          "type": "array",
          "items": {
            "$ref": "#/$defs/Value"
          }
        }
      },
      "type": "object"
    },
    "Value": {
      "description": "A message that can hold any of the supported value types.",
      "properties": {
        "booleanValue": {
          "description": "A boolean value.",
          "type": "boolean"
        },
        "stringValue": {
          "type": "string",
          "description": "A string value. In Standard edition databases: * The string, represented as UTF-8, must not exceed 1 MiB - 89 bytes. * Only the first 1,500 bytes of the UTF-8 representation are considered by queries. In Enterprise edition databases, there is no limit on the size of the value. However, it is still subject to document and index entry size limits."
        },
        "mapValue": {
          "$ref": "#/$defs/MapValue",
          "description": "A map value."
        },
        "bytesValue": {
          "description": "A bytes value. In Standard edition databases: * The value must not exceed 1 MiB - 89 bytes. * Only the first 1,500 bytes are considered by queries. In Enterprise edition databases, there is no limit on the size of the value. However, it is still subject to document and index entry size limits.",
          "format": "byte",
          "type": "string"
        },
        "geoPointValue": {
          "$ref": "#/$defs/LatLng",
          "description": "A geo point value representing a point on the surface of Earth."
        },
        "nullValue": {
          "type": "string",
          "enum": [
            "NULL_VALUE"
          ],
          "description": "A null value."
        },
        "pipelineValue": {
          "$ref": "#/$defs/Pipeline",
          "description": "A value that represents an unevaluated pipeline. **Requires:** * Not allowed to be used when writing documents."
        },
        "referenceValue": {
          "description": "A reference to a document. For example: `projects/{project_id}/databases/{database_id}/documents/{document_path}`.",
          "type": "string"
        },
        "functionValue": {
          "$ref": "#/$defs/Function",
          "description": "A value that represents an unevaluated expression. **Requires:** * Not allowed to be used when writing documents."
        },
        "fieldReferenceValue": {
          "description": "Value which references a field. This is considered relative (vs absolute) since it only refers to a field and not a field within a particular document. **Requires:** * Must follow field reference limitations. * Not allowed to be used when writing documents.",
          "type": "string"
        },
        "arrayValue": {
          "$ref": "#/$defs/ArrayValue",
          "description": "An array value. In Standard edition databases, an array value cannot directly contain another array value, though it can contain a map which contains another array. In Enterprise edition databases, an array value can contain another array value."
        },
        "doubleValue": {
          "format": "double",
          "type": "number",
          "description": "A double value."
        },
        "timestampValue": {
          "description": "A timestamp value. Precise only to microseconds. When stored, any additional precision is rounded down.",
          "type": "string",
          "format": "google-datetime"
        },
        "integerValue": {
          "type": "string",
          "format": "int64",
          "description": "An integer value."
        },
        "variableReferenceValue": {
          "type": "string",
          "description": "Pointer to a variable defined elsewhere in a pipeline. Unlike `field_reference_value` which references a field within a document, this refers to a variable, defined in a separate namespace than the fields of a document."
        }
      },
      "type": "object"
    }
  }
}