> For the complete documentation index, see [llms.txt](/llms.txt). Every page on this site is also available as markdown at `<path>.md`.

# Schema and utilities

Small public helpers used by multiple authoring APIs.

`normalize_schema(...)` is the shared schema normalizer behind tools, plans,
and references. Use it when you need to inspect the JSON Schema that Flow AI
will send to the Rust runtime before creating a `ToolSpec`, `PlanSpec`, or
`ReferenceSpec`.

`normalize_data_environment(...)` validates the same data-environment mapping
accepted by `create_runtime(...)` and Studio workspace bindings, without
constructing a runtime. It returns the camelCase wire mapping consumed by the
Rust runtime, or `None` when the environment is empty.

<span id="flowai_harness._schema.normalize_schema"></span>

## `normalize_schema`

`normalize_schema(schema: 'Any') -> 'dict[str, Any]'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>schema</code></td>
<td><code>Any</code></td>
<td>required</td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>dict[str, Any]</code></p>

Normalize a Python schema input into JSON Schema.

Accepted inputs:
- JSON Schema dictionaries.
- Pydantic ``BaseModel`` classes.
- Simple type maps such as ``{"query": str, "limit": int}``.
- Other Python type hints that Pydantic's ``TypeAdapter`` can export.

<span id="flowai_harness.runtime.normalize_data_environment"></span>

## `normalize_data_environment`

`normalize_data_environment(data_environment: 'DataEnvironmentConfig | Mapping[str, Any] | None', target_database_url: 'str | None' = None, *, runtime_resource_id: 'str') -> 'dict[str, Any] | None'`

<table>
<thead>
<tr>
<th>Parameter</th>
<th>Type</th>
<th>Default</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>data_environment</code></td>
<td><code><a href="/docs/reference/runtime#flowai_harness.runtime.DataEnvironmentConfig">DataEnvironmentConfig</a> | Mapping[str, Any] | None</code></td>
<td>required</td>
</tr>
<tr>
<td><code>target_database_url</code></td>
<td><code>str | None</code></td>
<td><code>None</code></td>
</tr>
<tr>
<td><code>runtime_resource_id</code></td>
<td><code>str</code></td>
<td>required</td>
</tr>
</tbody>
</table>

<p><strong>Returns:</strong> <code>dict[str, Any] | None</code></p>

Validate and normalize a data environment without constructing a runtime.

Args:
    data_environment: ``DataEnvironmentConfig`` or mapping; snake_case
        and camelCase keys are both accepted. See
        <a href="#flowai_harness.runtime.DataEnvironmentConfig">DataEnvironmentConfig</a>.
    target_database_url: Shorthand for
        ``data_environment["target_database_url"]``.
    runtime_resource_id: The runtime tenant the environment must agree
        with; a data environment that pins a different ``tenant_id`` is
        rejected.

Returns:
    CamelCase mapping passed to the Rust runtime, or ``None`` when no
        environment data is supplied. When present, the mapping can contain
        ``tenantId``, ``workspaceId``, ``kv``, ``targetDatabase``,
        ``targetDatabaseUrl``, ``targetDatabaseSchema``, ``catalog``, and
        ``catalogSearch``. See the
        <a href="#flowai_harness.runtime.DataEnvironmentConfig">DataEnvironmentConfig</a>
        table for key meanings.

Raises:
    ValueError: If ``target_database_url`` conflicts with the data
        environment, ``tenant_id`` does not match
        ``runtime_resource_id``, or a storage descriptor has an
        unsupported ``kind``.
    TypeError: If a value has an invalid type.