> For the complete documentation index, see [llms.txt](https://guardian.hedera.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://guardian.hedera.com/docs/develop/guardian/workspace/schemas/schema-fields-reference/geo-fields.md). # Geo Fields Geo fields are three built-in string field types — **Country**, **Continent**, and **State/Province** — that let a schema author collect standardized geographic data backed by an ISO 3166 dataset. Each type exposes a searchable dropdown populated at runtime from the shared dataset; no enum list needs to be maintained in the schema itself. Fields may be used independently or linked together into a cascading group. A linked group shares state: selecting a value in one field filters the options in related fields and auto-populates unambiguous ancestors in the same group. ### The problem it solves Free-text or untyped enum fields for location data produce inconsistent values across documents — `"USA"`, `"US"`, `"United States"` all mean the same country but will not match in queries or validation. Maintaining an enum list in each schema duplicates data and drifts from the authoritative standard. Geo fields give every schema the same consistent dataset without copying it into the schema. Stored values are ISO codes (`US`, `NA`, `US-CA`), so they match regardless of how the label is displayed. ### How it works **Three separate types** correspond to three geographic levels. Country stores an ISO 3166-1 alpha-2 code. Continent stores a continent code (`AF`, `AN`, `AS`, `EU`, `NA`, `OC`, `SA`). State/Province stores an ISO 3166-2 subdivision code, or the subdivision name when no short code is defined. **A dependency link** connects a child field to a compatible parent. The link is declared on the child field with a "Depends on" selector in the schema editor. Country may depend on Continent; State/Province may depend on Country or Continent. The link is stored in the field's `$comment` as `{ "dependency": { "on": "", "kind": "geo" } }`. **Cascading runs in both directions.** Selecting a value filters descendants to only the options compatible with that value. Selecting a more specific value auto-populates its unambiguous ancestors. A user can start from any field in the group. All fields stay enabled and editable at all times. **Backend validation is independent of the form.** When a document is submitted, the server checks that every geo field value exists in the dataset and that all linked fields are consistent with each other. A country and a continent that belong to different regions are rejected with a field-level error even if the document was constructed outside the form. **Excel import and export** treat geo fields like any other field type. The `Field Type` cell uses the type name (`Country`, `Continent`, `State/Province`). The `Test Value`, `Default Value`, and `Suggest Value` cells accept and return human-readable display names for Country (`United States`) and Continent (`North America`). State/Province keeps its code in both directions (for example, `CA-ON` for Ontario), since subdivision names are not consistently standardized across locales the way country and continent names are. Excel's display names are a convenience layer for readability — the value stored in the document is always the underlying ISO code, regardless of which format Excel shows. If a child field has a parent declared in the editor, the parent field's key is written to the `Parameter` cell on export and read back on import. On import, rows with unrecognized field types, values not found in the dataset, or invalid `Parameter` pairings produce row-level errors identifying the sheet and row. ### Key distinctions * **Values are ISO codes, not labels.** The stored value is always a code (`US`), not a display name (`United States`). This keeps values stable when display names change across locales or dataset updates. * **Cascading is bidirectional.** Choosing a parent filters children; choosing a child auto-populates a parent. No field is locked until another is filled. * **Unlinked geo fields are independent.** A Country field with no "Depends on" works as a standalone lookup. Linking is always optional. * **Validation requires a declared dependency group.** Backend consistency checks (country matches continent, state matches country) apply only to fields connected by an explicit dependency link. Unlinked geo fields in the same schema are validated individually against the dataset but not cross-checked against each other. ### Related * Task: [Configure Geo Fields](/docs/develop/guardian/workspace/schemas/schema-fields-reference/geo-fields/configure-geo-fields.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://guardian.hedera.com/docs/develop/guardian/workspace/schemas/schema-fields-reference/geo-fields.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.