Add documentation guide on specifying attribute domains.

Add a dedicated guide (`specifying_domains.md`) covering why attribute domains must be specified before inspecting private data, the supported attribute types and out-of-domain handling in `dpsynth.domain`, specifying domains in Python and YAML, and deriving domains automatically from Pydantic models, Protocol Buffers, and Pandas dtypes via `dpsynth.adapters`.

PiperOrigin-RevId: 997186307

Author: Ryan McKenna

docs/index.md

@@ -104,6 +104,9 @@ contributor expanding the library, explore the documentation below:
 
 *   **[Documentation Sitemap](sitemap.md)**: Complete table of contents and
     layout of the DPSynth documentation.
+*   **[Specifying Attribute Domains](specifying_domains.md)**: Upfront domain
+    requirements, supported attribute types, the DPSynth domain language, and
+    inferring domains from Pydantic, Protobuf, and Pandas schemas.
 *   **[Data Model & Terminology](data_and_terminology.md)**: Attributes
     (categorical vs. numerical), schema deduction, and `domain.yaml`
     specifications.
@@ -151,6 +154,7 @@ APIs:
 :caption: Getting Started
 :hidden:
 
+specifying_domains
 data_and_terminology
 in_memory_api
 scalable_pipeline_api

docs/sitemap.md

@@ -21,6 +21,23 @@
 
 --------------------------------------------------------------------------------
 
+<details>
+<summary>📁 <a href="specifying_domains.md">Specifying Attribute Domains</a></summary>
+
+*   [Why Domains Must Be Specified Up Front](specifying_domains.md#why-domains-must-be-specified-up-front)
+*   [Supported Attribute Types](specifying_domains.md#supported-attribute-types)
+    *   [Out-of-Domain Handling](specifying_domains.md#out-of-domain-handling)
+*   [Specifying Domains in the DPSynth Language](specifying_domains.md#specifying-domains-in-the-dpsynth-language)
+*   [Deriving Domains from Structured Containers](specifying_domains.md#deriving-domains-from-structured-containers)
+    *   [1. From Pydantic Models (`dpsynth.adapters.pydantic`)](specifying_domains.md#1-from-pydantic-models-dpsynthadapterspydantic)
+    *   [2. From Protocol Buffers (`dpsynth.adapters.protobuf`)](specifying_domains.md#2-from-protocol-buffers-dpsynthadaptersprotobuf)
+    *   [3. From Pandas Dtypes (`dpsynth.adapters.pandas`)](specifying_domains.md#3-from-pandas-dtypes-dpsynthadapterspandas)
+    *   [Customizing Inferred Domains](specifying_domains.md#customizing-inferred-domains)
+
+</details>
+
+--------------------------------------------------------------------------------
+
 <details>
 <summary>📁 <a href="data_and_terminology.md">Data Model and Terminology</a></summary>
 

docs/specifying_domains.md

@@ -0,0 +1,268 @@
+<!-- Copyright 2026 Google LLC
+
+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. -->
+
+# Specifying Attribute Domains
+
+<!-- disableFinding(LINK_RELATIVE_G3DOC) -->
+
+Every synthesis mechanism in DPSynth requires an explicit **domain
+specification** describing the attributes (columns) of your dataset and the set
+of valid values each attribute can take. This guide explains why domains must be
+defined before touching private data, how to express domains directly in the
+DPSynth domain language, and how to derive them automatically from structured
+schema definitions like Pydantic models, Protocol Buffers, and Pandas dtypes.
+
+## Why Domains Must Be Specified Up Front
+
+In differential privacy, the domain of an attribute defines the sample space of
+noisy measurements and bounds the sensitivity of each record's contribution.
+Crucially, **the domain must be specified before inspecting the sensitive
+dataset**:
+
+*   **Data-dependent bounds leak privacy**: Computing `df["income"].min()` and
+    `df["income"].max()` or extracting `df["category"].unique()` directly from
+    private data is not differentially private. Adding or removing a single
+    outlier record can change the observed range or reveal the presence of a
+    rare category.
+*   **Calibration precedes execution**: In DPSynth's [three-step mechanism
+    lifecycle](mechanism_api.md#three-step-pipeline), you pass the domain schema
+    to `config.calibrate(schema, epsilon=..., delta=...)` to allocate privacy
+    budgets and construct per-column initializers *before* the calibrated
+    mechanism ever sees private data.
+*   **Handling unknown domains privately**: When the valid categories of a
+    string column are not known from public metadata, use
+    {class}`~dpsynth.domain.OpenSetCategoricalAttribute` rather than scanning
+    the raw data. DPSynth will automatically spend a fraction of the privacy
+    budget on differentially private partition selection to discover common
+    categories.
+
+## Supported Attribute Types
+
+DPSynth provides four attribute classes in {mod}`dpsynth.domain` to model
+tabular columns:
+
+| Attribute Type | When to Use | Required Public Metadata | DP Initialization |
+| :--- | :--- | :--- | :--- |
+| {class}`~dpsynth.domain.CategoricalAttribute` | Finite set of known values (`bool`, `int`, `float`, or `str`), such as booleans, enum values, US states, or status codes. | `possible_values`: sequence of valid categories. | None (domain is already discrete and fixed). |
+| {class}`~dpsynth.domain.NumericalAttribute` | Ordered integer or continuous floating-point numbers, such as age, balance, or duration. | `min_value` and `max_value` (inclusive bounds), plus `dtype` (`"int"` or `"float"`). | Discretizes into bins via DP quantiles (or uses fixed `bin_edges` if provided). |
+| {class}`~dpsynth.domain.OpenSetCategoricalAttribute` | Categorical strings whose valid values are unknown in advance, such as free-entered city names or job titles. | None (`default_value` defaults to `"<OOD>"`; optional `public_possible_values`). | Discovers frequent categories via DP Gaussian thresholding (requires $\delta > 0$). |
+| {class}`~dpsynth.domain.FreeFormTextAttribute` | Unstructured text fields synthesized by a language model. | `max_tokens` (defaults to `256`). | Handled by text-generation mechanisms. |
+
+### Out-of-Domain Handling
+
+Real-world datasets frequently contain missing values (`None`, `NaN`) or records
+that fall outside expected bounds. Because raising a runtime error on unexpected
+records would leak information about the private data, DPSynth handles
+out-of-domain values deterministically during encoding:
+
+*   **Categorical attributes**: Any value not present in `possible_values` is
+    mapped to `possible_values[out_of_domain_index]` (default `0`). If missing
+    or unexpected values may occur, place a typed sentinel (such as `"Unknown"`
+    for strings or `-1` for integers) at index `0` of `possible_values`. If all
+    records are guaranteed to be in-domain, omit the sentinel so the synthesizer
+    never generates it.
+*   **Numerical attributes**: Controlled by `clip_to_range`:
+    *   `clip_to_range=True` (default): Values outside `[min_value, max_value]`
+        are clipped to the nearest bound, and `NaN` or non-numeric entries map
+        to `min_value`.
+    *   `clip_to_range=False`: Values outside `[min_value, max_value]` and `NaN`
+        entries are routed to a dedicated out-of-domain bin during
+        discretization and decoded back to `sentinel` (`np.nan` by default, or a
+        custom numeric/string sentinel).
+
+## Specifying Domains in the DPSynth Language
+
+You can define a domain directly in Python as a dictionary mapping column names
+to attribute instances, or wrap it in a {class}`~dpsynth.domain.Schema` when
+pairing the domain with cross-attribute constraints:
+
+```python
+import dpsynth
+from dpsynth import domain
+
+domains = {
+    "age": domain.NumericalAttribute(min_value=18, max_value=100, dtype="int"),
+    "balance": domain.NumericalAttribute(
+        min_value=0.0,
+        max_value=50_000.0,
+        dtype="float",
+        clip_to_range=False,
+    ),
+    "tier": domain.CategoricalAttribute(
+        possible_values=["UNKNOWN", "FREE", "PRO", "ENTERPRISE"],
+        out_of_domain_index=0,
+    ),
+    "is_active": domain.CategoricalAttribute(possible_values=[False, True]),
+    "city": domain.OpenSetCategoricalAttribute(),
+}
+
+# Optional: bundle with cross-attribute constraints in a Schema
+schema = domain.Schema(domains)
+```
+
+Domain specifications and `Schema` objects can also be saved to and loaded from
+YAML via `dpsynth.to_yaml` and `dpsynth.from_yaml`:
+
+```python
+yaml_str = dpsynth.to_yaml(schema)
+restored_schema = dpsynth.from_yaml(yaml_str)
+```
+
+## Deriving Domains from Structured Containers
+
+In many applications, your dataset schema is already captured in a structured
+container such as a **Pydantic model**, a **Protocol Buffer descriptor**, or
+**Pandas column dtypes** (for example, from a Parquet schema). Manually
+rewriting tens or hundreds of fields in the DPSynth domain language creates
+unnecessary boilerplate and risks schema drift.
+
+DPSynth provides `infer_domain` helpers under `dpsynth.adapters` that
+automatically translate these schema definitions into `dict[str,
+domain.AttributeType]`. Because the output is a standard Python dictionary, you
+can inspect or override individual attributes before calibrating your mechanism.
+
+### 1. From Pydantic Models (`dpsynth.adapters.pydantic`)
+
+Pydantic models can encode both categorical types (`bool`, `enum.Enum`,
+`typing.Literal`) and numerical bounds (`pydantic.Field(ge=..., le=...)`)
+directly on the class definition. Optional fields (`T | None`) automatically
+include `"None"` in `CategoricalAttribute` or set `clip_to_range=False` on
+`NumericalAttribute`:
+
+```python
+import enum
+from typing import Literal
+from dpsynth.adapters import pydantic as pydantic_adapter
+import pydantic
+
+
+class Tier(enum.Enum):
+  FREE = "FREE"
+  PRO = "PRO"
+
+
+class UserRecord(pydantic.BaseModel):
+  age: int = pydantic.Field(ge=18, le=100)
+  balance: float | None = pydantic.Field(ge=0.0, le=50_000.0)
+  tier: Tier
+  status: Literal["active", "suspended"]
+  city: str
+
+
+domains = pydantic_adapter.infer_domain(UserRecord)
+```
+
+If numeric fields on the Pydantic model do not carry `Field(ge=..., le=...)`
+annotations, you can supply their bounds via the `numerical_bounds` argument:
+
+```python
+domains = pydantic_adapter.infer_domain(
+    UserRecord,
+    numerical_bounds={"age": (18, 100), "balance": (0.0, 50_000.0)},
+)
+```
+
+Non-optional nested `BaseModel` fields are recursively flattened into
+dot-separated attribute names (such as `"metrics.balance"`).
+
+### 2. From Protocol Buffers (`dpsynth.adapters.protobuf`)
+
+Protocol Buffer descriptors define field types (`int32`, `float`, `bool`,
+`string`), enum values, and nested message structures, but do not store numeric
+min/max ranges. Pass your Protobuf message class or `Descriptor` along with
+`numerical_bounds` to `protobuf.infer_domain`:
+
+```python
+from dpsynth.adapters import protobuf
+
+domains = protobuf.infer_domain(
+    UserProfileProto,
+    numerical_bounds={
+        "age": (18.0, 100.0),
+        "account.balance": (0.0, 50_000.0),
+    },
+    ignore_unsupported_fields=True,
+)
+```
+
+Key behaviors of `protobuf.infer_domain`:
+
+*   **Enums and booleans**: Mapped to `CategoricalAttribute` using enum names by
+    default (`enum_format="name"`) or wire numbers (`enum_format="number"`).
+*   **Integers and floats**: Mapped to `NumericalAttribute` with `dtype="int"`
+    or `dtype="float"` using the bounds provided in `numerical_bounds`.
+*   **Strings**: Mapped to `OpenSetCategoricalAttribute`.
+*   **Nested messages**: Non-repeated submessages are recursively flattened into
+    dot-separated keys (such as `"account.balance"`).
+*   **Unsupported or unbounded fields**: Setting
+    `ignore_unsupported_fields=True` skips repeated fields, unsupported wire
+    types (such as `bytes`), and numeric fields omitted from `numerical_bounds`.
+
+### 3. From Pandas Dtypes (`dpsynth.adapters.pandas`)
+
+When working with typed tabular formats such as Parquet or Arrow, or when a
+public schema is already represented as Pandas dtypes (`pd.CategoricalDtype`,
+`bool`, `int64`, `float64`, `string`), use `pandas.infer_domain` on a
+`df.dtypes` `pd.Series` or a `{column: dtype}` mapping:
+
+```python
+from dpsynth.adapters import pandas as pandas_adapter
+import pandas as pd
+
+schema_dtypes = {
+    "age": "int64",
+    "balance": "float64",
+    "tier": pd.CategoricalDtype(["UNKNOWN", "FREE", "PRO", "ENTERPRISE"]),
+    "is_active": "bool",
+    "city": "string",
+}
+
+domains = pandas_adapter.infer_domain(
+    schema_dtypes,
+    numerical_bounds={"age": (18.0, 100.0), "balance": (0.0, 50_000.0)},
+    ignore_unsupported_fields=True,
+)
+```
+
+```{warning}
+When inferring a `CategoricalAttribute` from a `pd.CategoricalDtype`, the list
+of categories in `dtype.categories` **must** come from a public schema. Never
+call `df[col].astype("category")` on sensitive data and pass the resulting
+dtypes to `infer_domain`, as doing so extracts the exact active support of the
+private dataset without differential privacy. For string columns with unknown
+categories, leave the dtype as `"string"` (or `object`) so it maps to
+`OpenSetCategoricalAttribute`.
+```
+
+### Customizing Inferred Domains
+
+Because `infer_domain` returns a plain `dict[str, domain.AttributeType]`, you
+can easily customize specific columns after inference when a schema container
+does not capture a nuance of your domain (for example, replacing an inferred
+`OpenSetCategoricalAttribute` on a string column with a known closed-set
+`CategoricalAttribute`, or specifying custom `bin_edges` on a numerical column):
+
+```python
+domains = protobuf.infer_domain(
+    UserProfileProto,
+    numerical_bounds={"age": (18.0, 100.0)},
+    ignore_unsupported_fields=True,
+)
+
+# Override a string field whose valid country codes are publicly known:
+domains["country_code"] = domain.CategoricalAttribute(
+    possible_values=["OTHER", "US", "CA", "GB", "DE", "FR", "JP", "IN", "BR"],
+    out_of_domain_index=0,
+)
+```