Skip to content

hsml.deployment_schema #

DeploymentSchema #

The request and response contract of a deployment.

Serving keys, passed features, and request parameters are required in every request; extra logging features are optional. columns gives the positional order for list rows. Types are feature store offline types (bigint, string, array<double>, ...); see to_json_schema() for the JSON encoding each one accepts.

Example 
# a custom predictor script with an explicit contract
schema = DeploymentSchema(
    serving_keys=[{"name": "cc_num", "type": "bigint", "nullable": False}],
    passed_features=[{"name": "amount", "type": "double"}],
)
deployment = model.deploy(script_file="predictor.py", schema=schema)

deployment.schema.validate_instances([{"cc_num": 1, "amount": "x"}])  # -> errors
print(deployment.schema.to_openapi()["paths"])

columns property #

columns: list[SchemaField]

All fields in positional order: serving keys, passed features, request parameters, extra logging features.

extra_logging_features property #

extra_logging_features: list[SchemaField]

Client-supplied values that are only logged; optional.

feature_view property #

feature_view: dict[str, Any] | None

{"name", "version"} of the feature view the schema was inferred from.

inferred property #

inferred: bool

Whether the schema was inferred from the feature view rather than given.

max_batch_rows property #

max_batch_rows: int

Largest batch a request may carry; part of the published contract, so changing it changes the schema id.

names property #

names: list[str]

Names of all fields in positional order.

output property #

output: dict[str, Any]

Response contract: {"kind": "predictions" | "feature_vectors", "columns": [...] | None}.

passed_features property #

passed_features: list[SchemaField]

Feature view features whose values the client provides; required.

request_parameters property #

request_parameters: list[SchemaField]

Parameters of on-demand transformations; required.

required_names property #

required_names: list[str]

Names a request row must contain.

schema_id property #

schema_id: str

Content hash of the schema; equal schemas have equal ids.

serving_keys property #

serving_keys: list[SchemaField]

Fields identifying the entity to look up; required and non-null.

training_dataset_version property #

training_dataset_version: int | None

Training dataset version whose statistics the deployment uses.

unresolved property #

unresolved: list[str]

Names whose type is unknown and therefore not validated.

describe #

describe() -> None

Print the schema as JSON.

rows #

rows(instances: list[Any]) -> list[dict[str, Any]]

Convert validated rows to dicts keyed by field name.

PARAMETER DESCRIPTION
instances

Rows that passed validate_instances, as objects or arrays.

TYPE: list[Any]

RETURNS DESCRIPTION
list[dict[str, Any]]

One dict per row with every field of the schema.

split_row #

split_row(row: dict[str, Any]) -> dict[str, dict[str, Any]]

Split one row dict into its groups.

PARAMETER DESCRIPTION
row

A row as returned by rows.

TYPE: dict[str, Any]

RETURNS DESCRIPTION
dict[str, dict[str, Any]]

{"serving_keys": {...}, "passed_features": {...}, "request_parameters": {...}, "extra_logging_features": {...}}.

to_json_schema #

to_json_schema(
    max_rows: int | None = None,
) -> dict[str, Any]

Render the request and response contracts as JSON Schema (draft 2020-12).

PARAMETER DESCRIPTION
max_rows

Largest accepted batch; defaults to max_batch_rows.

TYPE: int | None DEFAULT: None

RETURNS DESCRIPTION
dict[str, Any]

{"request": <JSON Schema>, "response": <JSON Schema>}.

to_openapi #

to_openapi(
    name: str,
    url: str | None = None,
    max_rows: int | None = None,
) -> dict[str, Any]

Render an OpenAPI 3.1 document for the deployment's :predict endpoint.

PARAMETER DESCRIPTION
name

Deployment name.

TYPE: str

url

Full inference URL when known; otherwise the path is rendered relative to the server the client already uses.

TYPE: str | None DEFAULT: None

max_rows

Largest accepted batch; defaults to max_batch_rows.

TYPE: int | None DEFAULT: None

RETURNS DESCRIPTION
dict[str, Any]

The OpenAPI document as a dict.

validate_instance #

validate_instance(
    instance: Any, row: int = 0
) -> list[dict[str, Any]]

Validate one request row.

PARAMETER DESCRIPTION
instance

A row as an object keyed by field name or an array in columns order.

TYPE: Any

row

Index of the row in its batch, reported in the errors.

TYPE: int DEFAULT: 0

RETURNS DESCRIPTION
list[dict[str, Any]]

The errors found, each {"row", "field", "reason"}; empty when the row is valid.

validate_instances #

validate_instances(
    instances: Any, max_rows: int | None = None
) -> list[dict[str, Any]]

Validate a batch of rows.

Rows must all be objects or all be arrays.

PARAMETER DESCRIPTION
instances

The rows of a request.

TYPE: Any

max_rows

Largest accepted batch; defaults to max_batch_rows.

TYPE: int | None DEFAULT: None

RETURNS DESCRIPTION
list[dict[str, Any]]

All errors found across the batch; empty when the batch is valid.

DeploymentSchemaError #

Bases: ModelServingException

A request does not match a deployment schema. errors lists {"row", "field", "reason"}.

SchemaField #

One field of a deployment schema: a name, an optional feature store type, and nullability.

A None type means the type could not be resolved (request parameters of on-demand transformations); such fields are not type-checked.