fastapi-streams 0.1.0__tar.gz → 0.2.0__tar.gz

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/CHANGELOG.md

@@ -3,6 +3,54 @@
 All notable changes and consumer upgrade steps are recorded here. Entries marked
 unreleased describe prepared source versions that have not been published.
 
+## 0.2.0 - 2026-10-18
+
+- Source preparation passed workspace CI, independent wheel matrices and the
+  package release dry run. See the [release preparation evidence](../../docs/releases.md#verified-follow-up-preparation-2026-10-18).
+
+### Added
+
+- Preserve supported string patterns/lengths and numeric bounds/multiples in the
+  codegen IR and generated Python Pydantic annotations, including nested and
+  referenced scalars. Diagnose unsupported constraints and regex expressions.
+- Add `RequestOptions(unknown_events="ignore")` to generated Python SDKs. It
+  skips unknown string tags in a top-level discriminated event union; the default
+  remains an error. Malformed known events, missing tags and invalid JSON fail.
+  Both HTTPX backends retain their validation and transport behavior.
+- Add tested contract-first native proxy and private OpenAPI 3.1 REST-codegen
+  recipes. The authoritative OpenAPI 3.2 artifact remains unchanged.
+
+### Breaking generated-code changes
+
+- Regenerated Python models enforce scalar rules that 0.1.0 silently dropped.
+  Fix invalid payloads before adopting the new SDK. Unsupported constraints emit
+  `UnsupportedConstraintWarning`; constraints alongside enum/const/composition
+  and unsupported Python regex patterns fail explicitly. Move supported scalar
+  constraints onto scalar branches where possible. This is not full JSON Schema
+  validation. TypeScript remains static-only.
+- Regenerate committed SDKs and run consumer validation tests. Pass HTTPX2
+  generation/check options consistently if used. No wire names change.
+
+### Upgrade from 0.1.0
+
+1. Update `fastapi-streams[codegen]` to 0.2.0 and regenerate both SDKs from the
+   authoritative OpenAPI document. Keep the selected Python HTTP backend on
+   generation and check commands.
+2. Fix data violating preserved scalar constraints and review all unsupported-rule
+   diagnostics. Re-run consuming client validation and stream tests.
+3. Keep the default unknown-event error policy, or opt in per request only where
+   the upstream intentionally emits additional top-level discriminator values.
+
+### Release verification
+
+- Extend installed-wheel HTTPX/HTTPX2 smoke consumers to verify scalar constraints,
+  default unknown-event rejection, opt-in skipping and malformed known events.
+
+### Documentation
+
+- Fix PyPI installation instructions and supported-scope wording. Replace the
+  predecessor release guide with the workspace release process.
+
 ## 0.1.0 - 2026-10-17
 
 ### Added

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: fastapi-streams
-Version: 0.1.0
+Version: 0.2.0
 Summary: Typed FastAPI streams with generated TypeScript and Python clients.
 Project-URL: Documentation, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams/docs
 Project-URL: Source, https://github.com/mathisarends/canon/tree/main/packages/fastapi-streams
@@ -45,10 +45,10 @@ A CI check catches drift between the Python app, the contract, and generated cod
 
 ## 1. Decorate your FastAPI endpoint
 
-Install from GitHub with the optional codegen extra:
+Install from PyPI with the optional codegen extra:
 
 ```sh
-uv add 'fastapi-streams[codegen] @ git+https://github.com/mathisarends/fastapi-streams.git'
+uv add 'fastapi-streams[codegen]'
 ```
 
 Save this as `app.py`:
@@ -236,7 +236,8 @@ and regenerating committed clients.
 | [Development](docs/development.md) | Tests, supported scope, and roadmap. |
 | [Releasing](docs/releasing.md) | Tag-based releases and credential-free PyPI publishing. |
 
-v0.0.1 supports GET/POST JSON SSE streams. Ordinary REST endpoints stay in the
-contract for your existing REST SDK. See the [supported scope](docs/development.md#supported-scope-and-roadmap).
+The current release supports GET/POST JSON SSE streams. Ordinary REST endpoints
+stay in the contract for your existing REST SDK. See the
+[supported scope](docs/development.md#supported-scope-and-roadmap).
 
 Python 3.12+ · FastAPI 0.143.3+ · Pydantic v2 · [MIT](LICENSE)

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/README.md

@@ -27,10 +27,10 @@ A CI check catches drift between the Python app, the contract, and generated cod
 
 ## 1. Decorate your FastAPI endpoint
 
-Install from GitHub with the optional codegen extra:
+Install from PyPI with the optional codegen extra:
 
 ```sh
-uv add 'fastapi-streams[codegen] @ git+https://github.com/mathisarends/fastapi-streams.git'
+uv add 'fastapi-streams[codegen]'
 ```
 
 Save this as `app.py`:
@@ -218,7 +218,8 @@ and regenerating committed clients.
 | [Development](docs/development.md) | Tests, supported scope, and roadmap. |
 | [Releasing](docs/releasing.md) | Tag-based releases and credential-free PyPI publishing. |
 
-v0.0.1 supports GET/POST JSON SSE streams. Ordinary REST endpoints stay in the
-contract for your existing REST SDK. See the [supported scope](docs/development.md#supported-scope-and-roadmap).
+The current release supports GET/POST JSON SSE streams. Ordinary REST endpoints
+stay in the contract for your existing REST SDK. See the
+[supported scope](docs/development.md#supported-scope-and-roadmap).
 
 Python 3.12+ · FastAPI 0.143.3+ · Pydantic v2 · [MIT](LICENSE)

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/docs/README.md

@@ -7,9 +7,10 @@ TypeScript Fetch and Python HTTPX clients from the same definitions.
 | --- | --- |
 | [Quickstart](quickstart.md) | Run the complete example and define your first stream. |
 | [Contracts and codegen](codegen.md) | Export OpenAPI, generate both clients, and detect drift in CI. |
+| [Native transports](native-transports.md) | Existing SSE proxies, contract-first generation and private REST codegen views. |
 | [Client usage](clients.md) | Named event values, typed iteration, authentication, cancellation, and errors. |
 | [Development](development.md) | Local checks, test coverage, supported features, and roadmap. |
-| [Releasing](releasing.md) | Tag-based releases, PyPI Trusted Publishing setup, and recovery. |
+| [Releasing](releasing.md) | Workspace release preparation, PyPI publishing, and recovery. |
 | [Architecture](architecture.md) | Server integration, shared IR, generation, and transport boundaries. |
 
 Start with the [quickstart](quickstart.md), then use the

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/docs/codegen.md

@@ -116,3 +116,41 @@ Generation is deterministic. A manifest tracks owned files and cleans up stale
 generated files without deleting neighboring handwritten files. Use a dedicated
 output directory for each language. Unsafe paths and generated-name collisions
 fail explicitly.
+
+## Runtime validation and unknown variants
+
+Python validates generated event models and request bodies with Pydantic. Supported
+scalar constraints are `pattern`, `minLength`, `maxLength`, `minimum`, `maximum`,
+`exclusiveMinimum`, `exclusiveMaximum`, and `multipleOf`. They survive nested
+models, arrays, nullable types and referenced scalar aliases. Patterns use
+Pydantic's Rust regex engine; unsupported expressions fail generation. Numeric
+multiples follow Pydantic's floating-point tolerance. This is not a complete JSON
+Schema validator. Formats, collection/object limits and other unsupported rules
+emit `UnsupportedConstraintWarning`; promote it to an error in CI when required.
+Constraints alongside enum/const or composition fail explicitly; constraints on
+scalar branches are supported. TypeScript provides static shapes and does not
+validate incoming JSON or enforce scalar constraints at runtime.
+
+Python event unions are closed by default: unknown variants raise
+`StreamParseError`. For an upstream that emits more variants than your declared
+subset, explicitly choose a per-request policy:
+
+```python
+from generated import RequestOptions
+
+options = RequestOptions(unknown_events="ignore")
+async for event in client.runs.run_events(run_id="run_abc", options=options):
+    ...
+```
+
+Ignoring requires a top-level discriminated union with known string tags. Only
+valid JSON objects with an unknown string discriminator are skipped. Invalid
+JSON, missing/non-string discriminators and malformed known variants still fail;
+unknown nested variants inside a known event fail too. The option adds no retry,
+reconnect or replay. TypeScript continues to forward JSON-decoded values without
+runtime union validation. Regenerate existing Python SDKs to obtain the option.
+
+## Existing native streams and mixed REST generation
+
+See the [native transport and mixed-codegen recipe](native-transports.md) when
+an existing generator, native server or byte-preserving proxy owns the stream.

fastapi_streams-0.2.0/docs/native-transports.md

@@ -0,0 +1,49 @@
+# Native SSE transports and mixed client generation
+
+An authoritative OpenAPI 3.2 contract can describe an existing SSE endpoint.
+`fastapi-streams generate --schema` does not require `StreamRouter`, a running
+server or replacement of the application's stream implementation.
+
+The executable [native proxy example](../examples/native_proxy.py) declares an
+explicit event union through `itemSchema.properties.data.contentSchema` and
+registers its referenced models. Its `StreamingResponse` forwards upstream raw
+bytes, status and selected response headers. Keepalives and unknown event frames
+are not decoded or reserialized. The response closes the upstream connection;
+the FastAPI lifespan owns the HTTP client. Application authentication, allowed
+headers, run identity, recovery and replay remain application responsibilities.
+The declared 200 contract must match the reviewed upstream; other upstream status
+codes are preserved and generated SDKs apply their usual HTTP error handling.
+
+From this package directory:
+
+```console
+uv run fastapi-streams schema --app examples.native_proxy:app --output openapi.json
+uv run fastapi-streams generate --schema openapi.json --language python --python-http-client httpx2 --output generated/sse
+uv run fastapi-streams check --schema openapi.json --language python --python-http-client httpx2 --output generated/sse
+```
+
+Keep `openapi.json` as the single authoritative artifact for REST and SSE. If an
+existing REST generator accepts only OpenAPI 3.1, derive a private codegen view:
+
+```console
+uv run python -m examples.rest_codegen openapi.json build/rest.openapi.json
+uv run python -m examples.rest_codegen openapi.json build/rest.openapi.json --check
+```
+
+The [adaptation example](../examples/rest_codegen.py) deep-copies the contract,
+sets the private view to 3.1 and replaces each inline JSON SSE `itemSchema` with
+a media `schema` referencing decoded event data. This keeps event models reachable
+for REST generators that use reachability or schema-tag filtering. That schema
+is a private model-discovery aid, not the SSE wire body. Filter SSE operations out
+of ordinary HTTP method generation and configure your generator's model/tag
+selection explicitly. All components and REST operations remain available.
+
+This recipe handles ordinary REST operations and inline JSON SSE envelopes. It is
+not a general OpenAPI 3.2 downgrade: review additional 3.2 features against the
+chosen REST generator. Unsupported SSE envelope shapes fail explicitly. Never
+publish the private view as the service contract or edit it by hand. Generate it
+from the authoritative artifact before REST generation/drift checks; generate
+and check the SSE SDK directly from the authoritative artifact. Keep HTTP and
+SSE outputs in separate directories. Run both clients' consumer tests.
+
+[Back to code generation](codegen.md)

fastapi_streams-0.2.0/docs/releasing.md

@@ -0,0 +1,13 @@
+# Releasing fastapi-streams
+
+Use the [workspace release process](../../../docs/releases.md). Only root
+workflows execute in this repository; nested workflows and the predecessor
+package-local release script are historical configuration.
+
+Releases use independent `fastapi-streams-vX.Y.Z` tags and the root lockfile.
+Prepare a new version, update the changelog and generated clients, pass the
+workspace and installed-artifact checks, and wait for CI on the exact commit.
+Run the root release workflow with `dry_run=true` before publication. A real
+publication requires explicit authorization.
+
+[Back to documentation](README.md)

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/examples/agent_runs/generated_python/agent_runs/api.py

@@ -35,7 +35,9 @@ class AgentRunsApi:
 
         Use contextlib.aclosing for deterministic cleanup when exiting iteration early. Task cancellation closes the response and propagates normally.
 
-        Events are validated with Pydantic.
+        Events are validated with Pydantic against generated shapes, variants and supported scalar constraints (string pattern/length, numeric bounds/multiples). Unsupported source constraints are diagnosed during generation; this is not full JSON Schema validation.
+
+        Unknown event variants fail by default. For a top-level discriminated union, RequestOptions(unknown_events='ignore') skips unknown string tags. Malformed known events, missing tags and invalid JSON still fail.
         """
         query: list[tuple[str, str]] = []
         headers: dict[str, str] = {}
@@ -55,7 +57,7 @@ class AgentRunsApi:
         self,
         *,
         run_id: str,
-        delay: float | None = None,
+        delay: Models.StreamRunEventsDelay | None = None,
         options: RequestOptions | None = None,
     ) -> AsyncGenerator[Models.RunEvent, None]:
         """
@@ -73,7 +75,9 @@ class AgentRunsApi:
 
         Use contextlib.aclosing for deterministic cleanup when exiting iteration early. Task cancellation closes the response and propagates normally.
 
-        Events are validated with Pydantic.
+        Events are validated with Pydantic against generated shapes, variants and supported scalar constraints (string pattern/length, numeric bounds/multiples). Unsupported source constraints are diagnosed during generation; this is not full JSON Schema validation.
+
+        Unknown event variants fail by default. For a top-level discriminated union, RequestOptions(unknown_events='ignore') skips unknown string tags. Malformed known events, missing tags and invalid JSON still fail.
         """
         query: list[tuple[str, str]] = []
         headers: dict[str, str] = {}

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/examples/agent_runs/generated_python/models.py

@@ -38,7 +38,7 @@ class RunFailed(BaseModel):
 
 class RunRequest(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
-    prompt: str
+    prompt: Annotated[str, Field(max_length=500, min_length=1)]
 
 class RunStarted(BaseModel):
     model_config = ConfigDict(populate_by_name=True)
@@ -49,6 +49,8 @@ type StreamPromptError = HTTPValidationError
 
 type StreamPromptErrorBody = StreamPromptError
 
+type StreamRunEventsDelay = Annotated[float, Field(le=1, ge=0)]
+
 type StreamRunEventsError = HTTPValidationError
 
 type StreamRunEventsErrorBody = StreamRunEventsError

{fastapi_streams-0.1.0/fastapi_streams/codegen/templates/python → fastapi_streams-0.2.0/examples/agent_runs/generated_python}/runtime.py

@@ -5,6 +5,7 @@ import codecs
 from collections.abc import AsyncGenerator, Mapping, Sequence
 from dataclasses import dataclass
 from enum import Enum
+from typing import Literal
 
 import httpx
 from pydantic import JsonValue, TypeAdapter, ValidationError
@@ -36,6 +37,7 @@ class _Default(Enum):
 class RequestOptions:
     headers: Mapping[str, str] | None = None
     timeout: float | None | _Default = _Default.TIMEOUT
+    unknown_events: Literal["error", "ignore"] = "error"
 
 
 type ParameterValue = str | int | float | bool | None
@@ -158,6 +160,20 @@ class Transport:
         body: bytes | None = None,
         options: RequestOptions | None = None,
     ) -> AsyncGenerator[T, None]:
+        discriminator: str | None = None
+        known_tags: set[str] = set()
+        if options and options.unknown_events not in {"error", "ignore"}:
+            raise ValueError("unknown_events must be 'error' or 'ignore'")
+        if options and options.unknown_events == "ignore":
+            schema = adapter.json_schema()
+            policy = schema.get("discriminator", {})
+            discriminator = policy.get("propertyName")
+            known_tags = set(policy.get("mapping", {}))
+            if not isinstance(discriminator, str) or not known_tags:
+                raise ValueError(
+                    "unknown_events='ignore' requires a top-level "
+                    "discriminated event union"
+                )
         request_headers = self.headers.copy()
         request_headers.update(headers)
         if options and options.headers:
@@ -210,6 +226,17 @@ class Transport:
                     try:
                         yield adapter.validate_json(payload)
                     except ValidationError as exc:
+                        if discriminator is not None:
+                            try:
+                                value = TypeAdapter[JsonValue](JsonValue).validate_json(
+                                    payload
+                                )
+                            except ValidationError:
+                                raise StreamParseError(payload) from exc
+                            if isinstance(value, dict):
+                                tag = value.get(discriminator)
+                                if isinstance(tag, str) and tag not in known_tags:
+                                    continue
                         raise StreamParseError(payload) from exc
         except httpx.HTTPError as exc:
             raise TransportError("SSE HTTP transport failed") from exc

fastapi_streams-0.2.0/examples/native_proxy.py

@@ -0,0 +1,99 @@
+from collections.abc import AsyncGenerator
+from contextlib import asynccontextmanager
+from typing import Annotated, Any, Literal
+
+import httpx
+from fastapi import FastAPI, Request
+from pydantic import BaseModel, Field, TypeAdapter
+from starlette.background import BackgroundTask
+from starlette.responses import StreamingResponse
+
+
+class Started(BaseModel):
+    type: Literal["started"]
+    run_id: str = Field(pattern="^run_[A-Za-z0-9_-]+$")
+
+
+class Done(BaseModel):
+    type: Literal["done"]
+    run_id: str = Field(pattern="^run_[A-Za-z0-9_-]+$")
+
+
+type Event = Annotated[Started | Done, Field(discriminator="type")]
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
+    async with httpx.AsyncClient(
+        base_url="https://upstream.example.test", timeout=None
+    ) as client:
+        app.state.upstream = client
+        yield
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(lifespan=lifespan)
+    payload = TypeAdapter(Event).json_schema(
+        ref_template="#/components/schemas/{model}"
+    )
+    definitions = payload.pop("$defs", {})
+
+    @app.get(
+        "/runs/{run_id}/events",
+        operation_id="run_events",
+        tags=["runs"],
+        response_class=StreamingResponse,
+        openapi_extra={
+            "responses": {
+                "200": {
+                    "content": {
+                        "text/event-stream": {
+                            "itemSchema": {
+                                "type": "object",
+                                "properties": {
+                                    "data": {
+                                        "type": "string",
+                                        "contentMediaType": "application/json",
+                                        "contentSchema": payload,
+                                    }
+                                },
+                                "required": ["data"],
+                            },
+                        }
+                    }
+                }
+            }
+        },
+    )
+    async def events(run_id: str, request: Request) -> StreamingResponse:
+        upstream = request.app.state.upstream
+        # The application's boundary owns authentication and allowed upstream headers.
+        response = await upstream.send(
+            upstream.build_request("GET", f"/runs/{run_id}/events"), stream=True
+        )
+        headers = {
+            name: value
+            for name, value in response.headers.items()
+            if name.lower() in {"content-type", "content-encoding", "cache-control"}
+        }
+        return StreamingResponse(
+            response.aiter_raw(),
+            status_code=response.status_code,
+            headers=headers,
+            background=BackgroundTask(response.aclose),
+        )
+
+    original_openapi = app.openapi
+
+    def openapi() -> dict[str, Any]:
+        document = original_openapi()
+        document.setdefault("components", {}).setdefault("schemas", {}).update(
+            definitions
+        )
+        return document
+
+    app.openapi = openapi
+    return app
+
+
+app = create_app()

fastapi_streams-0.2.0/examples/rest_codegen.py

@@ -0,0 +1,76 @@
+import argparse
+import json
+from copy import deepcopy
+from pathlib import Path
+
+from fastapi_streams.codegen.openapi import ContractError, Document, validate_contract
+
+
+def rest_codegen_document(document: Document) -> Document:
+    """Derive a private 3.1 codegen view of ordinary REST plus JSON SSE contracts.
+
+    This example covers itemSchema/data/contentSchema, not arbitrary OAS 3.2.
+    The SSE schema denotes decoded event data only in this private view.
+    """
+    validate_contract(document)
+    result = deepcopy(document)
+    result["openapi"] = "3.1.0"
+    result.pop("jsonSchemaDialect", None)
+    for path in result.get("paths", {}).values():
+        for method, operation in path.items():
+            if method not in {
+                "get",
+                "post",
+                "put",
+                "patch",
+                "delete",
+                "head",
+                "options",
+                "trace",
+            }:
+                continue
+            for response in operation.get("responses", {}).values():
+                for media_type, media in response.get("content", {}).items():
+                    if "itemSchema" not in media:
+                        continue
+                    if media_type != "text/event-stream":
+                        raise ContractError(
+                            "This recipe only adapts JSON SSE itemSchema"
+                        )
+                    envelope = media.pop("itemSchema")
+                    try:
+                        data = envelope["properties"]["data"]
+                        if data["contentMediaType"] != "application/json":
+                            raise KeyError("contentMediaType")
+                        media["schema"] = data["contentSchema"]
+                    except (KeyError, TypeError) as exc:
+                        raise ContractError(
+                            "Expected inline JSON SSE envelope"
+                        ) from exc
+    return result
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description="Derive a private REST codegen view")
+    parser.add_argument("source", type=Path)
+    parser.add_argument("output", type=Path)
+    parser.add_argument("--check", action="store_true")
+    args = parser.parse_args()
+    content = (
+        json.dumps(
+            rest_codegen_document(json.loads(args.source.read_text("utf-8"))),
+            indent=2,
+            sort_keys=True,
+        )
+        + "\n"
+    )
+    if args.check:
+        if not args.output.is_file() or args.output.read_text("utf-8") != content:
+            raise SystemExit("Private REST codegen view is out of date")
+    else:
+        args.output.parent.mkdir(parents=True, exist_ok=True)
+        args.output.write_text(content, encoding="utf-8", newline="\n")
+
+
+if __name__ == "__main__":
+    main()

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/fastapi_streams/__init__.py

@@ -1,4 +1,4 @@
 from fastapi_streams.router import StreamRouter
 
 __all__ = ["StreamRouter"]
-__version__ = "0.1.0"
+__version__ = "0.2.0"

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/fastapi_streams/codegen/diagnostics.py

@@ -15,6 +15,10 @@ class OptionalDiscriminatorWarning(UserWarning):
     """An event union may be missing the field used to select its variant."""
 
 
+class UnsupportedConstraintWarning(UserWarning):
+    """A source validation keyword cannot be enforced by generated clients."""
+
+
 def warn_optional_discriminators(contract: Contract) -> None:
     """Diagnose event discriminators without changing the declared requiredness."""
     declarations = {item.name: item.type for item in contract.declarations}

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/fastapi_streams/codegen/documentation.py

@@ -45,7 +45,14 @@ def operation_doc(
                 "Use contextlib.aclosing for deterministic cleanup when exiting "
                 "iteration early. Task cancellation closes the response and "
                 "propagates normally.",
-                "Events are validated with Pydantic.",
+                "Events are validated with Pydantic against generated shapes, "
+                "variants and supported scalar constraints (string pattern/length, "
+                "numeric bounds/multiples). Unsupported source constraints are "
+                "diagnosed during generation; this is not full JSON Schema validation.",
+                "Unknown event variants fail by default. For a top-level discriminated "
+                "union, RequestOptions(unknown_events='ignore') skips unknown string "
+                "tags. Malformed known events, missing tags and invalid JSON "
+                "still fail.",
             ]
         )
     if operation.deprecated:

{fastapi_streams-0.1.0 → fastapi_streams-0.2.0}/fastapi_streams/codegen/ir.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import re
+import warnings
 from dataclasses import dataclass
 from typing import Any, Literal, cast
 
@@ -33,6 +34,7 @@ class Scalar:
     name: Literal[
         "string", "integer", "number", "boolean", "null", "never", "JsonValue"
     ]
+    constraints: tuple[tuple[str, str | int | float], ...] = ()
 
 
 @dataclass(frozen=True)
@@ -402,6 +404,56 @@ class _Types:
             self.names[name] = ref
             self.pending[name] = target
             return Reference(name)
+        unsupported = sorted(
+            set(node)
+            & {
+                "format",
+                "minItems",
+                "maxItems",
+                "uniqueItems",
+                "contains",
+                "minContains",
+                "maxContains",
+                "minProperties",
+                "maxProperties",
+                "patternProperties",
+                "propertyNames",
+                "dependentRequired",
+                "dependentSchemas",
+                "unevaluatedProperties",
+                "unevaluatedItems",
+                "not",
+                "if",
+                "then",
+                "else",
+            }
+        )
+        if unsupported:
+            from fastapi_streams.codegen.diagnostics import UnsupportedConstraintWarning
+
+            warnings.warn(
+                f"Schema {node.get('title', '<inline>')!r}: constraints "
+                f"{', '.join(unsupported)} are not enforced by generated clients",
+                UnsupportedConstraintWarning,
+                stacklevel=2,
+            )
+        constraints = {
+            "minLength": "min_length",
+            "maxLength": "max_length",
+            "pattern": "pattern",
+            "minimum": "ge",
+            "maximum": "le",
+            "exclusiveMinimum": "gt",
+            "exclusiveMaximum": "lt",
+            "multipleOf": "multiple_of",
+        }
+        if set(node) & constraints.keys() and any(
+            key in node for key in ("const", "enum", "oneOf", "anyOf", "allOf")
+        ):
+            raise ContractError(
+                "Scalar constraints alongside enum/const or composition are not "
+                "supported; put constraints on scalar branches instead"
+            )
         if "const" in node:
             return self.literal(node["const"])
         if "enum" in node:
@@ -436,10 +488,27 @@ class _Types:
                     self.parse({**node, "type": part}) for part in cast(list[str], kind)
                 )
             )
-        if kind in ("string", "boolean", "null"):
-            return Scalar(kind)
-        if kind in ("number", "integer"):
-            return Scalar(kind)
+        if kind in ("string", "boolean", "null", "number", "integer"):
+            applicable: set[str] = (
+                {"minLength", "maxLength", "pattern"}
+                if kind == "string"
+                else {
+                    "minimum",
+                    "maximum",
+                    "exclusiveMinimum",
+                    "exclusiveMaximum",
+                    "multipleOf",
+                }
+                if kind in ("number", "integer")
+                else set()
+            )
+            return Scalar(
+                kind,
+                tuple(
+                    (constraints[key], node[key])
+                    for key in sorted(applicable & node.keys())
+                ),
+            )
         if kind == "array":
             if "prefixItems" in node:
                 raise ContractError("Tuple schemas (prefixItems) are not supported")