{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/google-cloud-firestore/json-schema/google-cloud-firestore-google-firestore-admin-v1-field-schema.json",
  "title": "GoogleFirestoreAdminV1Field",
  "description": "Represents a single field in the database. Fields are grouped by their \"Collection Group\", which represent all collections in the database with the same ID.",
  "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/GoogleFirestoreAdminV1Field",
  "type": "object",
  "properties": {
    "name": {
      "description": "Required. A field name of the form: `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/fields/{field_path}` A field path can be a simple field name, e.g. `address` or a path to fields within `map_value` , e.g. `address.city`, or a special field path. The only valid special field is `*`, which represents any field. Field paths can be quoted using `` ` `` (backtick). The only character that must be escaped within a quoted field path is the backtick character itself, escaped using a backslash. Special characters in field paths that must be quoted include: `*`, `.`, `` ` `` (backtick), `[`, `]`, as well as any ascii symbolic characters. Examples: `` `address.city` `` represents a field named `address.city`, not the map key `city` in the field `address`. `` `*` `` represents a field named `*`, not any field. A special `Field` contains the default indexing settings for all fields. This field's resource name is: `projects/{project_id}/databases/{database_id}/collectionGroups/__default__/fields/*` Indexes defined on this `Field` will be applied to all fields which do not have their own `Field` index configuration.",
      "type": "string"
    },
    "indexConfig": {
      "$ref": "#/$defs/GoogleFirestoreAdminV1IndexConfig",
      "description": "The index configuration for this field. If unset, field indexing will revert to the configuration defined by the `ancestor_field`. To explicitly remove all indexes for this field, specify an index config with an empty list of indexes."
    },
    "ttlConfig": {
      "$ref": "#/$defs/GoogleFirestoreAdminV1TtlConfig",
      "description": "The TTL configuration for this `Field`. Setting or unsetting this will enable or disable the TTL for documents that have this `Field`."
    }
  },
  "$defs": {
    "GoogleFirestoreAdminV1FlatIndex": {
      "type": "object",
      "description": "An index that stores vectors in a flat data structure, and supports exhaustive search.",
      "properties": {}
    },
    "GoogleFirestoreAdminV1Index": {
      "type": "object",
      "properties": {
        "apiScope": {
          "description": "The API scope supported by this index.",
          "type": "string",
          "enum": [
            "ANY_API",
            "DATASTORE_MODE_API",
            "MONGODB_COMPATIBLE_API"
          ]
        },
        "fields": {
          "items": {
            "$ref": "#/$defs/GoogleFirestoreAdminV1IndexField"
          },
          "description": "The fields supported by this index. At most 100 fields may be specified. In Standard edition databases only: - At least 2 fields must be specified. - The last field entry is always for the field path `__name__`. If, on creation, `__name__` was not specified as the last field, it will be added automatically with the same direction as that of the last field defined. If the final field in the index is not directional, the `__name__` will be ordered ASCENDING (unless explicitly specified).",
          "type": "array"
        },
        "state": {
          "description": "Output only. The serving state of the index.",
          "type": "string",
          "enum": [
            "STATE_UNSPECIFIED",
            "CREATING",
            "READY",
            "NEEDS_REPAIR"
          ]
        },
        "queryScope": {
          "description": "Indexes with a collection query scope specified allow queries against a collection that is the child of a specific document, specified at query time, and that has the same collection ID. Indexes with a collection group query scope specified allow queries against all collections descended from a specific document, specified at query time, and that have the same collection ID as this index.",
          "type": "string",
          "enum": [
            "QUERY_SCOPE_UNSPECIFIED",
            "COLLECTION",
            "COLLECTION_GROUP",
            "COLLECTION_RECURSIVE"
          ]
        },
        "unique": {
          "description": "Optional. Whether it is an unique index. Unique index ensures all values for the indexed field(s) are unique across documents.",
          "type": "boolean"
        },
        "searchIndexOptions": {
          "$ref": "#/$defs/GoogleFirestoreAdminV1SearchIndexOptions",
          "description": "Optional. Options for search indexes that are at the index definition level. This field is only currently supported for indexes with MONGODB_COMPATIBLE_API ApiScope."
        },
        "name": {
          "type": "string",
          "description": "A server-defined name for this index. Output only. When used in the google.firestore.admin.v1.Index resource, the value is of the form: `projects/{project_id}/databases/{database_id}/collectionGroups/{collection_id}/indexes/{index_id}` When used in the google.firestore.admin.v1.Field resource, the value is empty."
        },
        "shardCount": {
          "format": "int32",
          "description": "Optional. The number of physical shards for the index. In Cloud Firestore, data and index entries are stored in contiguous, ordered key ranges called splits. While document keys within a collection are hashed to distribute write traffic across splits, secondary index entries are ordered lexicographically by their indexed field values. When an index contains fields with sequential or monotonically increasing or decreasing values (such as timestamps or auto-incrementing IDs), every incoming index write targets the boundary of the index keyspace on a single split. Because sequential writes continuously advance to the newest split at the edge of the range, automatic load-based splitting cannot divide the write traffic across storage servers. Under high write rates, this concentration creates an append hotspot on that single split, resulting in elevated write latency, contention errors, and transaction aborts. Sharded indexes solve this write bottleneck by hash partitioning the secondary index keyspace. When `shard_count` is configured to N, Firestore automatically prepends a virtual computed shard field (with values from 0 to N-1) as the leading field of the index. This splits a single sequential key range into N independent key ranges, uniformly scattering adjacent writes across distinct splits and storage servers to enable linear write scaling. Query trade-offs: Hash partitioning trades query performance for write throughput. Because matching index entries are scattered across all shards, queries executing against a sharded index cannot read from a single contiguous range. The query engine must fan out parallel seeks across all N shards and merge the ordered results. Even index point lookups and queries with `LIMIT 1` must seek across all N shards. Sizing and best practices: - Indexes cannot be updated in-place. `shard_count` is immutable once an index is created; to \"reshard\" an index, create a new index with the desired `shard_count` and delete the original index. - Use sharded indexes only for indexes experiencing write bottlenecks (typically exceeding 500-1,000 writes/sec) on sequential or timestamp fields. - Do not shard indexes on uniformly distributed fields (such as UUIDs or hash tokens), where writes naturally spread across splits without sharding. Sharding uniform indexes adds query overhead without improving write throughput. - Do not shard read-heavy or low-write collections. - Size `shard_count` based on expected peak write throughput. Because a single split sustains roughly 500-1,000 writes/sec on sequential keys, estimate `shard_count ≈ ceil(peak_write_qps / 500)`. - e.g., 4 for up to ~2,000-4,000 writes/sec, 16 for up to ~10,000+ writes/sec. - Setting an excessively high shard count produces diminishing write returns while needlessly increasing read latency and seek costs. If <= 1, the index is unsharded (1 physical shard).",
          "type": "integer"
        },
        "density": {
          "type": "string",
          "enum": [
            "DENSITY_UNSPECIFIED",
            "SPARSE_ALL",
            "SPARSE_ANY",
            "DENSE"
          ],
          "description": "Immutable. The density configuration of the index."
        },
        "multikey": {
          "description": "Optional. Whether the index is multikey. By default, the index is not multikey. For non-multikey indexes, none of the paths in the index definition reach or traverse an array, except via an explicit array index. For multikey indexes, at most one of the paths in the index definition reach or traverse an array, except via an explicit array index. Violations will result in errors. Note this field only applies to index with MONGODB_COMPATIBLE_API ApiScope.",
          "type": "boolean"
        }
      },
      "description": "Cloud Firestore indexes enable simple and complex queries against documents in a database. In Standard edition databases, single-field indexes are managed using the google.firestore.admin.v1.Field resource, and composite indexes are managed using the google.firestore.admin.v1.Index resource. In Enterprise edition databases, both single-field and composite indexes are managed using the google.firestore.admin.v1.Index resource."
    },
    "GoogleFirestoreAdminV1IndexConfig": {
      "type": "object",
      "description": "The index configuration for this field.",
      "properties": {
        "reverting": {
          "description": "Output only When true, the `Field`'s index configuration is in the process of being reverted. Once complete, the index config will transition to the same state as the field specified by `ancestor_field`, at which point `uses_ancestor_config` will be `true` and `reverting` will be `false`.",
          "type": "boolean"
        },
        "ancestorField": {
          "type": "string",
          "description": "Output only. Specifies the resource name of the `Field` from which this field's index configuration is set (when `uses_ancestor_config` is true), or from which it *would* be set if this field had no index configuration (when `uses_ancestor_config` is false)."
        },
        "usesAncestorConfig": {
          "type": "boolean",
          "description": "Output only. When true, the `Field`'s index configuration is set from the configuration specified by the `ancestor_field`. When false, the `Field`'s index configuration is defined explicitly."
        },
        "indexes": {
          "description": "The indexes supported for this field.",
          "items": {
            "$ref": "#/$defs/GoogleFirestoreAdminV1Index"
          },
          "type": "array"
        }
      }
    },
    "GoogleFirestoreAdminV1IndexField": {
      "type": "object",
      "description": "A field in an index. The field_path describes which field is indexed, the value_mode describes how the field value is indexed.",
      "properties": {
        "arrayConfig": {
          "description": "Indicates that this field supports operations on `array_value`s.",
          "type": "string",
          "enum": [
            "ARRAY_CONFIG_UNSPECIFIED",
            "CONTAINS"
          ]
        },
        "fieldPath": {
          "type": "string",
          "description": "Can be __name__. For single field indexes, this must match the name of the field or may be omitted."
        },
        "order": {
          "type": "string",
          "enum": [
            "ORDER_UNSPECIFIED",
            "ASCENDING",
            "DESCENDING"
          ],
          "description": "Indicates that this field supports ordering by the specified order or comparing using =, !=, <, <=, >, >=."
        },
        "vectorConfig": {
          "$ref": "#/$defs/GoogleFirestoreAdminV1VectorConfig",
          "description": "Indicates that this field supports nearest neighbor and distance operations on vector."
        },
        "searchConfig": {
          "$ref": "#/$defs/GoogleFirestoreAdminV1SearchConfig",
          "description": "Indicates that this field supports search operations."
        }
      }
    },
    "GoogleFirestoreAdminV1SearchConfig": {
      "type": "object",
      "description": "The configuration for how to index a field for search.",
      "properties": {
        "textSpec": {
          "$ref": "#/$defs/GoogleFirestoreAdminV1SearchTextSpec",
          "description": "Optional. The specification for building a text search index for a field."
        },
        "geoSpec": {
          "$ref": "#/$defs/GoogleFirestoreAdminV1SearchGeoSpec",
          "description": "Optional. The specification for building a geo search index for a field."
        }
      }
    },
    "GoogleFirestoreAdminV1SearchGeoSpec": {
      "type": "object",
      "properties": {
        "geoJsonIndexingDisabled": {
          "description": "Optional. Disables geoJSON indexing for the field. By default, geoJSON points are indexed. Firestore GeoPoints are indexed regardless of the value of this field.",
          "type": "boolean"
        }
      },
      "description": "The specification for how to build a geo search index for a field."
    },
    "GoogleFirestoreAdminV1SearchIndexOptions": {
      "type": "object",
      "properties": {
        "textLanguage": {
          "type": "string",
          "description": "Optional. The language to use for text search indexes. Used as the default language if not overridden at the document level by specifying the `text_language_override_field`. The language is specified as a BCP 47 language code. For indexes with MONGODB_COMPATIBLE_API ApiScope: If unspecified, the default language is English. For indexes with `ANY_API` ApiScope: If unspecified, the default behavior is autodetect."
        },
        "textLanguageOverrideFieldPath": {
          "description": "Optional. The field in the document that specifies which language to use for that specific document. For indexes with MONGODB_COMPATIBLE_API ApiScope: if unspecified, the language is taken from the \"language\" field if it exists or from `text_language` if it does not.",
          "type": "string"
        }
      },
      "description": "Options for search indexes at the definition level."
    },
    "GoogleFirestoreAdminV1SearchTextIndexSpec": {
      "properties": {
        "indexType": {
          "type": "string",
          "enum": [
            "TEXT_INDEX_TYPE_UNSPECIFIED",
            "TOKENIZED"
          ],
          "description": "Required. How to index the text field value."
        },
        "matchType": {
          "type": "string",
          "enum": [
            "TEXT_MATCH_TYPE_UNSPECIFIED",
            "MATCH_GLOBALLY"
          ],
          "description": "Required. How to match the text field value."
        }
      },
      "description": "Specification of how the field should be indexed for search text indexes.",
      "type": "object"
    },
    "GoogleFirestoreAdminV1SearchTextSpec": {
      "description": "The specification for how to build a text search index for a field.",
      "properties": {
        "indexSpecs": {
          "items": {
            "$ref": "#/$defs/GoogleFirestoreAdminV1SearchTextIndexSpec"
          },
          "type": "array",
          "description": "Required. Specifications for how the field should be indexed. Repeated so that the field can be indexed in multiple ways."
        }
      },
      "type": "object"
    },
    "GoogleFirestoreAdminV1TtlConfig": {
      "properties": {
        "state": {
          "enum": [
            "STATE_UNSPECIFIED",
            "CREATING",
            "ACTIVE",
            "NEEDS_REPAIR"
          ],
          "description": "Output only. The state of the TTL configuration.",
          "type": "string",
          "readOnly": true
        },
        "expirationOffset": {
          "type": "string",
          "description": "Optional. The offset, relative to the timestamp value from the TTL-enabled field, used to determine the document's expiration time. `expiration_offset.seconds` must be between 0 and 2,147,483,647 inclusive. Values more precise than seconds are rejected. If unset, defaults to 0, in which case the expiration time is the same as the timestamp value from the TTL-enabled field.",
          "format": "google-duration"
        }
      },
      "type": "object",
      "description": "The TTL (time-to-live) configuration for documents that have this `Field` set. A timestamp stored in a TTL-enabled field will be used to determine the expiration time of the document. The expiration time is the sum of the timestamp value and the `expiration_offset`. For Enterprise edition databases, the timestamp value may alternatively be stored in an array value in the TTL-enabled field. An expiration time in the past indicates that the document is eligible for immediate expiration. Using any other data type or leaving the field absent will disable expiration for the individual document."
    },
    "GoogleFirestoreAdminV1VectorConfig": {
      "type": "object",
      "properties": {
        "dimension": {
          "description": "Required. The vector dimension this configuration applies to. The resulting index will only include vectors of this dimension, and can be used for vector search with the same dimension.",
          "type": "integer",
          "format": "int32"
        },
        "flat": {
          "$ref": "#/$defs/GoogleFirestoreAdminV1FlatIndex",
          "description": "Indicates the vector index is a flat index."
        }
      },
      "description": "The index configuration to support vector search operations"
    }
  }
}