> This page is for version v0.25.0.
> For other versions, use one of these documentation indexes:
> - Latest (default): https://docs.nvidia.com/nemo/guardrails/latest/llms.txt
> - v0.25.0: https://docs.nvidia.com/nemo/guardrails/v0.25.0/llms.txt
> - v0.24.1: https://docs.nvidia.com/nemo/guardrails/v0.24.1/llms.txt
> - v0.24.0: https://docs.nvidia.com/nemo/guardrails/v0.24.0/llms.txt
> - v0.23.0: https://docs.nvidia.com/nemo/guardrails/v0.23.0/llms.txt
> - v0.22.0: https://docs.nvidia.com/nemo/guardrails/v0.22.0/llms.txt

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.nvidia.com/nemo/guardrails/llms.txt.

# nemoguardrails.server.experimental.provider.projection_policy

Field and object policies for provider payload projections.

Model declarations provide field coverage, guarded text locations, and
exported contract schemas.

## Module Contents

### Classes

| Name                                                                                          | Description                                                   |
| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`ArrayVariant`](#nemoguardrails-server-experimental-provider-projection_policy-ArrayVariant) | Identify one reviewed object branch in a heterogeneous array. |
| [`ObjectPolicy`](#nemoguardrails-server-experimental-provider-projection_policy-ObjectPolicy) | Describe the reviewed boundary of one JSON object.            |
| [`PolicyModel`](#nemoguardrails-server-experimental-provider-projection_policy-PolicyModel)   | Require declared fields to carry guard policy metadata.       |

### Functions

| Name                                                                                                            | Description                                                                        |
| --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [`_check_reason`](#nemoguardrails-server-experimental-provider-projection_policy-_check_reason)                 | Require a structured reason such as core_capability.tool_content.                  |
| [`_field`](#nemoguardrails-server-experimental-provider-projection_policy-_field)                               | Build Annotated field metadata while keeping defaults in assignments.              |
| [`constrained`](#nemoguardrails-server-experimental-provider-projection_policy-constrained)                     | Mark a field restricted by its type and optional Pydantic constraints.             |
| [`disabled`](#nemoguardrails-server-experimental-provider-projection_policy-disabled)                           | Declare an unsupported feature as an omittable, null-only field.                   |
| [`export_payload_schema`](#nemoguardrails-server-experimental-provider-projection_policy-export_payload_schema) | Export a fresh, inline schema with object and field guard annotations.             |
| [`field_coverage`](#nemoguardrails-server-experimental-provider-projection_policy-field_coverage)               | Derive disjoint runtime field inventories from one object's declarations.          |
| [`field_policy`](#nemoguardrails-server-experimental-provider-projection_policy-field_policy)                   | Read a field's guard metadata, returning an empty mapping if absent.               |
| [`guarded`](#nemoguardrails-server-experimental-provider-projection_policy-guarded)                             | Mark guarded content or a container leading to guarded content.                    |
| [`guarded_array_variant`](#nemoguardrails-server-experimental-provider-projection_policy-guarded_array_variant) | Resolve the one text-bearing branch of a reviewed object union.                    |
| [`model_graph`](#nemoguardrails-server-experimental-provider-projection_policy-model_graph)                     | Collect the root and nested policy models in traversal order.                      |
| [`opaque`](#nemoguardrails-server-experimental-provider-projection_policy-opaque)                               | Mark a declared field as provider-owned data outside guarded content.              |
| [`payload_contract`](#nemoguardrails-server-experimental-provider-projection_policy-payload_contract)           | Build runtime coverage metadata for a request or response projection.              |
| [`policy_json_schema`](#nemoguardrails-server-experimental-provider-projection_policy-policy_json_schema)       | Describe default object validation without the contract's union restrictions.      |
| [`replacement_blocker`](#nemoguardrails-server-experimental-provider-projection_policy-replacement_blocker)     | Return a subject's replacement blocker after checking it names a reviewed sibling. |
| [`text_location`](#nemoguardrails-server-experimental-provider-projection_policy-text_location)                 | Derive one buffered text target directly from typed field declarations.            |

### Data

[`CONTRACT_VERSION`](#nemoguardrails-server-experimental-provider-projection_policy-CONTRACT_VERSION)

[`EXTENSION`](#nemoguardrails-server-experimental-provider-projection_policy-EXTENSION)

[`_FIELD_CONSTRAINTS`](#nemoguardrails-server-experimental-provider-projection_policy-_FIELD_CONSTRAINTS)

[`_REASON`](#nemoguardrails-server-experimental-provider-projection_policy-_REASON)

[`_SOURCE_COMPONENT`](#nemoguardrails-server-experimental-provider-projection_policy-_SOURCE_COMPONENT)

### API

```python
class nemoguardrails.server.experimental.provider.projection_policy.ArrayVariant(
    match: tuple[tuple[str, str | int | bool], ...],
    cardinality: typing.Literal['any', 'at_most_one', 'exactly_one']
)
```

Dataclass

Identify one reviewed object branch in a heterogeneous array.

Match keys must be required singleton Literal fields of the owning model.
Cardinality applies when a text binding selects this branch from an array,
not when the object is validated in isolation. Non-text branches use 'any'.
The same declaration describes selection in exported guard contracts.

**`cardinality`** `Literal['any', 'at_most_one', 'exactly_one']`

---

**`match`** `tuple[tuple[str, str | int | bool], ...]`

---

```python
nemoguardrails.server.experimental.provider.projection_policy.ArrayVariant.__post_init__() -> None
```

Reject ambiguous or unrepresentable selector declarations.

```python
class nemoguardrails.server.experimental.provider.projection_policy.ObjectPolicy(
    source: str | None = None,
    opaque: tuple[str, ...] = (),
    unknown_fields: typing.Literal['forbid', 'configurable'] = 'forbid',
    variant: nemoguardrails.server.experimental.provider.projection_policy.ArrayVariant | None = None
)
```

Dataclass

Describe the reviewed boundary of one JSON object.

This metadata does not select guardrails, a deployment configuration, or a
capability profile. Field-specific policy belongs on the field annotations.

**`opaque`** `tuple[str, ...] = ()`

Reviewed passthrough fields not declared as Pydantic fields.
Names must be unique and must not overlap declared fields.

---

**`source`** `str | None = None`

Provider component schema name, without a JSON Pointer prefix.
This is provenance metadata, not a schema lookup or validation step.

---

**`unknown_fields`** `Literal['forbid', 'configurable'] = 'forbid'`

How unreviewed members are handled. "forbid" always
rejects them. "configurable" rejects them unless validation
explicitly allows unknown content fields, which is reserved for
trusted configuration. Members listed in opaque are reviewed.

---

**`variant`** `ArrayVariant | None = None`

Optional discriminator and selection cardinality when this
model is a branch of a guarded heterogeneous array.

---

```python
nemoguardrails.server.experimental.provider.projection_policy.ObjectPolicy.__post_init__() -> None
```

Reject values the exported contract format cannot represent.

```python
class nemoguardrails.server.experimental.provider.projection_policy.PolicyModel()
```

**Bases:** `BaseModel`

Require declared fields to carry guard policy metadata.

Combine this base with the appropriate runtime projection base. At subclass
creation it checks field classifications, opaque inventory overlap, disabled
field defaults, and unsupported aliases. At validation it enforces the
object's unknown-field policy. It does not prove upstream field coverage or
serialize arbitrary custom validators into the exported schema.

**`model_config`** `= ConfigDict(extra='allow')`

---

**`policy`** `ObjectPolicy = ObjectPolicy()`

---

```python
nemoguardrails.server.experimental.provider.projection_policy.PolicyModel.__get_pydantic_json_schema__(
    core_schema: pydantic_core.CoreSchema,
    handler: pydantic.GetJsonSchemaHandler
) -> pydantic.json_schema.JsonSchemaValue
```

classmethod

Attach policy using model identity, independent of schema display titles.

Keep Pydantic's references and validation assertions. Object closure
describes default validation; trusted overrides and case-alias checks
remain explicit guard annotations.

```python
nemoguardrails.server.experimental.provider.projection_policy.PolicyModel.__pydantic_init_subclass__(
    kwargs: typing.Any = {}
) -> None
```

classmethod

Check local policy consistency after Pydantic has assembled fields.

```python
nemoguardrails.server.experimental.provider.projection_policy.PolicyModel.reject_coerced_variant_discriminators(
    value: typing.Any
) -> typing.Any
```

classmethod

Keep parsed variant selection consistent with the original payload.

```python
nemoguardrails.server.experimental.provider.projection_policy.PolicyModel.reject_unreviewed_fields(
    info: pydantic.ValidationInfo
) -> typing_extensions.Self
```

Reject members outside the reviewed fields unless policy allows them.

A case variant of a reviewed name, such as `Tools`, is always
rejected: some providers match member names case-insensitively, so it
could reach a field this policy disables or inspects.

```python
nemoguardrails.server.experimental.provider.projection_policy._check_reason(
    reason: str
) -> None
```

Require a structured reason such as core_capability.tool_content.

```python
nemoguardrails.server.experimental.provider.projection_policy._field(
    metadata: dict[str, typing.Any],
    constraints: dict[str, typing.Any]
) -> typing.Any
```

Build Annotated field metadata while keeping defaults in assignments.

```python
nemoguardrails.server.experimental.provider.projection_policy.constrained(
    reason: str | None = None,
    constraints: typing.Any = {}
) -> typing.Any
```

Mark a field restricted by its type and optional Pydantic constraints.

The optional reason explains the restriction in the exported contract.
This helper adds no restriction by itself; the annotation and constraints
must express it. Defaults belong on the field assignment.

```python
nemoguardrails.server.experimental.provider.projection_policy.disabled(
    reason: str,
    extension: bool = False
) -> typing.Any
```

Declare an unsupported feature as an omittable, null-only field.

Use field: Annotated\[None, disabled(reason)] = None. Non-null values are
rejected by the field type, and PolicyModel checks this declaration.
A nonblank structured reason explains the restriction. Set extension for a
locally recognized field outside the pinned provider schema.

```python
nemoguardrails.server.experimental.provider.projection_policy.export_payload_schema(
    model: type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel],
    projection_id: str
) -> dict[str, typing.Any]
```

Export a fresh, inline schema with object and field guard annotations.

This function does not validate the complete contract format, inspect an
upstream provider schema, or capture arbitrary Python validator behavior.
The operation exporter is responsible for format validation.

**Parameters:**

**`model`** `type[PolicyModel]`

`type[` [`PolicyModel`](#nemoguardrails-server-experimental-provider-projection_policy-PolicyModel) `]` — Trusted policy-annotated model to describe.

---

**`projection_id`** `str`

Exported root title; the class name remains model metadata.

---

**Returns:** `dict[str, Any]`

A payload schema, not a complete operation contract.

**Raises:**

* `ValueError`: Nested models are not policy-annotated, names collide,
  references recurse, or an anyOf union cannot be safely converted.

```python
nemoguardrails.server.experimental.provider.projection_policy.field_coverage(
    model: type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel]
) -> nemoguardrails.server.experimental.provider.payload.ProjectionFieldCoverage
```

Derive disjoint runtime field inventories from one object's declarations.

Local extensions occupy a separate inventory even when their annotation
is constrained. The opaque inventory includes declared opaque attributes
and ObjectPolicy.opaque names. This does not check an upstream schema.

```python
nemoguardrails.server.experimental.provider.projection_policy.field_policy(
    field: pydantic.fields.FieldInfo
) -> dict[str, typing.Any]
```

Read a field's guard metadata, returning an empty mapping if absent.

The returned mapping may belong to the field; callers must not mutate it.

```python
nemoguardrails.server.experimental.provider.projection_policy.guarded(
    role: typing.Literal['user', 'assistant'] | None = None,
    replaceable: bool | None = None,
    blocked_by: str | None = None,
    replacement_reason: str | None = None,
    constraints: typing.Any = {}
) -> typing.Any
```

Mark guarded content or a container leading to guarded content.

Use inside Annotated and put defaults on the field assignment. Declaring
replacement eligibility does not enable runtime replacement support.

**Parameters:**

**`role`** `Literal['user', 'assistant'] | None` — default: None

Text subject role. Omit for structural container fields.

---

**`replaceable`** `bool | None` — default: None

Whether the subject permits replacement. The buffered
binding defaults to read-only when this is not declared.

---

**`blocked_by`** `str | None` — default: None

Sibling field whose non-empty value prevents replacement.

---

**`replacement_reason`** `str | None` — default: None

Structured reason for the replacement restriction.

---

**`**constraints`** `Any` — default: \{}

min_length, max_length, pattern, ge, le, or strict.
Format support is checked separately when exporting a complete
guard contract; strictness has no JSON Schema keyword.

---

```python
nemoguardrails.server.experimental.provider.projection_policy.guarded_array_variant(
    annotation: typing.Any
) -> tuple[type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel], nemoguardrails.server.experimental.provider.projection_policy.ArrayVariant] | None
```

Resolve the one text-bearing branch of a reviewed object union.

Every branch must declare a mutually exclusive discriminator. The selected
branch has bounded cardinality; other branches must not hide guarded text.
Return None for a non-union item, whose ordinary array bounds apply instead.
No JSON Schema generation or provider lookup participates in binding.

```python
nemoguardrails.server.experimental.provider.projection_policy.model_graph(
    root: type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel]
) -> dict[str, type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel]]
```

Collect the root and nested policy models in traversal order.

Models are keyed by class name. Reject nested models without policy and
distinct models sharing a name. Repeated references are visited once;
recursive schema export is rejected separately.

```python
nemoguardrails.server.experimental.provider.projection_policy.opaque() -> typing.Any
```

Mark a declared field as provider-owned data outside guarded content.

Use field: Annotated\[Any, opaque()] = None for an unconstrained optional
value. ObjectPolicy.opaque is the alternative for reviewed fields that do
not need a model attribute. Do not declare the same field in both places.

```python
nemoguardrails.server.experimental.provider.projection_policy.payload_contract(
    model: type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel],
    projection_id: str,
    direction: typing.Literal['request', 'response'],
    profile: nemoguardrails.server.experimental.provider.payload.PayloadCapabilityProfile = PayloadCapabilityProfile.SI...
) -> nemoguardrails.server.experimental.provider.payload.PayloadProjectionContract
```

Build runtime coverage metadata for a request or response projection.

**Parameters:**

**`model`** `type[PolicyModel]`

`type[` [`PolicyModel`](#nemoguardrails-server-experimental-provider-projection_policy-PolicyModel) `]` — Policy-annotated root, with policy-annotated nested models.

---

**`projection_id`** `str`

Stable identifier for this payload projection.

---

**`direction`** `Literal['request', 'response']`

Whether the projection describes a request or response.

---

**`profile`** `PayloadCapabilityProfile` — default: PayloadCapabilityProfile.SINGLE_TEXT_V1

[`PayloadCapabilityProfile`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/server/experimental/provider/payload#nemoguardrails-server-experimental-provider-payload-PayloadCapabilityProfile) — Framework-defined capability implemented by the runtime.

---

**Returns:** [`PayloadProjectionContract`](/nemo/guardrails/v0.25.0/guardrails-python-sdk/nemoguardrails/server/experimental/provider/payload#nemoguardrails-server-experimental-provider-payload-PayloadProjectionContract)

Root and nested-model coverage, ready to attach in a binding module.

```python
nemoguardrails.server.experimental.provider.projection_policy.policy_json_schema(
    model: type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel]
) -> dict[str, typing.Any]
```

Describe default object validation without the contract's union restrictions.

Add reviewed opaque properties, default closure, and explicit object policy
to the root and nested model definitions. Inline references so the schema can
be embedded in an OpenAPI document without dangling definition paths; retain
union semantics. Recursive models cannot be inlined and are rejected.
The result is fresh; arbitrary Python validators are not serialized.

```python
nemoguardrails.server.experimental.provider.projection_policy.replacement_blocker(
    model: type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel],
    subject: dict[str, typing.Any]
) -> str | None
```

Return a subject's replacement blocker after checking it names a reviewed sibling.

A misspelled blocker would never match a provider member and would silently
allow replacement, so buffered and stream subjects both validate it.

**Raises:**

* `ValueError`: The blocker is not a declared or reviewed opaque field of the model.

```python
nemoguardrails.server.experimental.provider.projection_policy.text_location(
    model: type[nemoguardrails.server.experimental.provider.projection_policy.PolicyModel]
) -> nemoguardrails.server.experimental.provider.payload.GuardedTextLocation
```

Derive one buffered text target directly from typed field declarations.

Follow guarded models and exactly-one-item lists without schema generation
or contract-format conversion. Heterogeneous arrays use ObjectPolicy.variant
to select exactly one text-bearing member. A nullable subject, or one without
a minimum length, may hold no text.

**Raises:**

* `ValueError`: A subject is missing or ambiguous, a guarded container is
  unsupported, or a replacement blocker is not a reviewed sibling.

```python
nemoguardrails.server.experimental.provider.projection_policy.CONTRACT_VERSION = '1.0.0-alpha.1'
```

```python
nemoguardrails.server.experimental.provider.projection_policy.EXTENSION = 'x-nemo-guardrails'
```

```python
nemoguardrails.server.experimental.provider.projection_policy._FIELD_CONSTRAINTS = frozenset({'min_length', 'max_length', 'pattern', 'ge', 'le', 'strict'})
```

```python
nemoguardrails.server.experimental.provider.projection_policy._REASON = re.compile('(core_capability|provider_integrity|projection_policy)\\.[a-z][a-z0-...
```

```python
nemoguardrails.server.experimental.provider.projection_policy._SOURCE_COMPONENT = re.compile('[A-Za-z_][A-Za-z0-9._-]*')
```