alkhttp/docs/architecture/decisions/066-from-jsonschema-as-http-adapter.md

# ADR-066: `from_jsonschema` as an HTTP-Backed Single-Endpoint Adapter in alkhttp

*Ported from alknet ADR-066 (`from_jsonschema` as an HTTP-Backed Single-Endpoint Adapter in alknet-http); re-targeted to alkhttp.*

## Status

Accepted (supersedes the `from_jsonschema` clause of ADR-017 §5 and the
`FromJsonSchema` provenance row of ADR-022 — both described a schema-only,
no-handler adapter in the call crate)

## Context

`from_jsonschema` was originally specified (alknet ADR-017 §5) as a
schema-only
adapter living in the call crate (`alknet-call`, now alkcall): it produced
`HandlerRegistration` bundles
with a `NOT_FOUND`-returning placeholder handler and `FromJsonSchema`
provenance. The stated use case was validation, discovery, and
composition-graph construction without a runtime — type-checking a
composition plan without executing it, building a UI of available
operations without standing up the transports.

This is broken. An operation in the `OperationRegistry` needs a real
handler. A placeholder that returns `NOT_FOUND` does not work with how
the registry is supposed to function: an `Internal` op registered with
a dead handler is a trap, not a feature. The "schema-only, no handler"
concept conflated two things — schema *validation* (a compile-time /
planning activity that doesn't need a registry entry at all) and
operation *registration* (which always needs a handler). Validation
against a JSON Schema does not require a `HandlerRegistration`; it
requires the schema and a validator. Registering an operation requires
a handler. The old `from_jsonschema` tried to do the former by abusing
the latter, and produced something that works for neither.

The misplacement was compounded by a location error: the adapter lived
in the call crate (which is supposed to stay lean — no HTTP client), but
a `from_jsonschema` that is actually useful for calling non-standard
endpoints needs reqwest, exactly like `from_openapi` and `from_mcp`.
The adapter location map in ADR-017 / the call crate's
`client-and-adapters.md` already
establishes that HTTP-backed adapters live in the HTTP crate; the old
`from_jsonschema` violated its own stated principle by living in
the call crate. The move was recorded as alknet ADR-066 (moved from
`alknet-call` to `alknet-http`); with the extraction, that makes it this
crate — alkhttp. The `FromJsonSchema` provenance variant itself stays in
the call crate (alkcall ADR-027 records the provenance-side decision:
`FromJsonSchema` is a handler-bearing leaf in alkcall's
`OperationProvenance` enum).

A concrete use case now forces the decision: composing a non-standard,
non-OpenAPI, basic REST endpoint that does not have a full OpenAPI
document. The endpoint has a method, a URL, an input/output JSON Schema,
and an auth scheme — but no `paths` object, no `operationId`, no
`components`. `from_openapi` requires an OpenAPI document; this endpoint
doesn't have one. The gap is: register a single HTTP endpoint as a
call-protocol operation, one at a time, with the caller supplying the
schema directly.

## Decision

`from_jsonschema` becomes an HTTP-backed single-endpoint adapter in
alkhttp, functionally similar to `from_openapi` but registering
one endpoint at a time instead of parsing a full OpenAPI document:

1. **The adapter implementation lives in alkhttp**
   (`src/adapters/from_jsonschema.rs`). The
   forwarding handler uses the same reqwest-backed `SharedHttpClient`
   and the same no-env-vars credential injection as `from_openapi`. The
   adapter implements `OperationAdapter` (the trait from alkcall,
   ADR-017 §5 — unchanged).

2. **Give it a real forwarding handler.** A `from_jsonschema`-imported
   operation is a leaf with a reqwest forwarding handler, identical in
   shape to a `from_openapi`-imported operation — it builds an HTTP
   request from the input (path/query/body split per a path template),
   injects credentials from `context.capabilities`, sends via the shared
   HTTP client, and parses the response (JSON, text, or binary — same
   content-type branching as `from_openapi`). For a `Sub`
   op type with `text/event-stream` response, it registers a
   `StreamingHandler` (ADR-049), same as `from_openapi`.

3. **Single-endpoint registration.** The caller supplies:
   - An `OperationSpec` (name, op type, input/output JSON Schema,
     `error_schemas`, `access_control`, `visibility`).
   - An `HttpServiceConfig` (base URL, auth scheme, default headers —
     the same config type `from_openapi` uses).
   - A path template + HTTP method (the one endpoint).

   The adapter builds one `HandlerRegistration` with `FromJsonSchema`
   provenance and a real forwarding handler. The caller registers it in
   the `OperationRegistry`. This is the "one endpoint at a time" shape:
   no `paths` object to iterate, no `operationId` to normalize.

4. **`FromJsonSchema` provenance stays in alkcall** (in the
   `OperationProvenance` enum, `registration.rs`). The provenance type
   lives where the registry types live; only the adapter implementation
   moved. `FromJsonSchema` is now a leaf provenance — it has a handler
   (a reqwest forwarding handler), same trust model as `FromOpenAPI`
   (HTTP endpoint trusted; handler is a forwarding stub).

5. **Remove the "schema-only, no handler" concept.** The placeholder
   handler and the "schema-only ops are `Internal`, so dispatch should
   never reach them" rationale are removed. An op registered with
   `FromJsonSchema` provenance is a real, callable, HTTP-forwarding
   operation — `Internal` by default (adapter-registered ops are
   composition material, ADR-015), but it actually forwards if invoked.

   The schema-validation-without-a-handler use case (type-checking a
   composition plan, building a UI) does not require a
   `HandlerRegistration` at all. That use case is served by consuming
   the `OperationSpec` directly (the spec already carries the input/
   output JSON Schemas); no adapter, no registry entry, no handler is
   needed. If a future use case requires registering a schema-only op
   for discovery purposes, that is a separate feature and would warrant
   its own ADR — it is not what `from_jsonschema` is.

### Relationship to `from_openapi`

| | `from_openapi` | `from_jsonschema` |
|---|---|---|
| Input | A full OpenAPI 3.x document (JSON or YAML) | A single endpoint: `OperationSpec` + `HttpServiceConfig` + path template + method |
| Granularity | One `HandlerRegistration` per `(path, method)` in the doc | One `HandlerRegistration` per call |
| Schema source | Parsed from the OpenAPI doc (parameters, request body, responses) | Supplied directly by the caller |
| Handler | reqwest forwarding handler (shared HTTP client) | Same reqwest forwarding handler |
| Provenance | `FromOpenAPI` | `FromJsonSchema` |
| Location | alkhttp | alkhttp |
| Use case | Standard OpenAPI APIs (GitHub, OpenAI, Anthropic) | Non-standard, non-OpenAPI, or basic REST endpoints without a full spec |

The two adapters share the forwarding-handler implementation, the
credential injection path, the error-fidelity rule (`HTTP_<status>`
prefix, [ADR-023](023-operation-error-schemas.md)), and the no-env-vars
invariant ([ADR-014](014-secret-material-flow-and-capability-injection.md)).
The
difference is purely the input shape: a full document vs. a single
endpoint.

### Response-key wildcards (review 002 OAI-13)

`from_openapi` projects OpenAPI response keys onto `HTTP_<status>` error
codes, which require a concrete status. Class wildcards map to the first
legal concrete status in their implied range: `4XX` → `HTTP_400`, `5XX`
→ `HTTP_500`. The declared payload schema of the wildcard response is
carried by the projected entry. `default` has no implied status range,
so it is not projected (it would advertise an `HTTP_0` code that can
never match a callback status) — unmapped upstream statuses surface as
the synthesized `HTTP_<actual>` at call time regardless. A concrete
status key always outranks a wildcard covering the same range, in both
error projection and the success sweep (SSE detection +
output-schema selection), where the precedence order is: concrete 2XX
statuses, then `2XX`, then `default`.

### Forwarding contract decisions (review 002 FWD-17/18/19)

The shared forwarding core (`src/adapters/forward.rs`) used by both
`from_openapi` and `from_jsonschema` pins three contracts. Each is a
decision the code half-implied; the module doc carries the full normative
text, this section records the reasoning at the assembly-trust boundary
that ADR-066 establishes: an assembly's spec/template/base-URL inputs
are trusted configuration, while peer call-time input never is.

**FWD-17 — SSE payload contract (decided: carry raw payload + event
name for non-JSON frames).** A subscription frame's `data:` payload
that is itself valid JSON surfaces as the decoded value (`123` stays a
number, `"123"` stays a string). Any other payload surfaces as the
`{"data": <raw>, "event": <name|null>}` wrapper: a legitimately
non-JSON stream stays field-addressable and an upstream's named-event
conventions (`event: error`) are visible instead of indistinguishable
from data. The `event` value is the frame's `event:` field under
WHATWG last-wins semantics — `null` when absent, never the implicit
`message` default, so "named" and "default" stay distinguishable. JSON
frames surface as themselves even under a named event; consequence:
the event name is only visible on non-JSON frames. Chosen over the
alternative (document the old JSON-or-string contract) because the old
behavior silently erased payload shape and made an upstream's error
convention unobservable — a fidelity loss on the same axis ADR-023
already rejects for status mapping.

**FWD-18 — placeholder routing rule (decided: fix + structural-value
error).** A key matching a path-template placeholder is consumed by the
path and never also emits as a query parameter, whatever its value's
shape (the renderer's placeholder check precedes query routing — fixed
behavior, pinned by test). A placeholder renders exactly one literal
path segment, so a structural value (object/array) under a placeholder
key fails with `INVALID_INPUT` rather than splicing minified JSON into
the path. Scalar values (string/number/boolean/null) render
percent-encoded as before.

**FWD-19 — literal `%` in template text (decided: documented
trade-off, not rejection).** A `%` inside a *value* is always encoded
(`%` → `%25`), so a value can never inject or fake percent escapes. A
`%` in *template or base text* survives verbatim: an assembly writing
`%2F` into a template is presumed to intend a pre-encoded segment for
upstreams that route `%2F` differently from `/`. Inputs are
assembly-supplied (this ADR's trust boundary), so the strict shape
(call-time rejection of raw `%` in template text) is rejected — it
would break legitimate pre-encoded templates without adding safety:
the surviving `%2F` still renders as a single literal segment, cannot
change the origin, and cannot be forged from peer input. The trade-off
(upstream-dependent routing of bare percent escapes) is the
assembly's choice, not this crate's.

## Consequences

**Positive**:
- `from_jsonschema` actually works — it has a real handler, not a
  placeholder. A concrete use case (non-standard REST endpoints) is
  served.
- The adapter location is consistent: all HTTP-backed adapters
  (`from_openapi`, `from_mcp`, `from_jsonschema`) live in the HTTP crate
  (alkhttp),
  where reqwest is. The call crate (alkcall) stays lean.
- The "schema-only, no handler" trap is removed. An op in the registry
  is always callable.
- `FromJsonSchema` provenance becomes a real leaf, consistent with
  `FromOpenAPI`/`FromMCP`/`FromCall`.

**Negative**:
- The schema-validation-without-a-handler use case (the original stated
  purpose) is no longer served by `from_jsonschema`. That use case is
  served by consuming `OperationSpec` directly, but any code that relied
  on the placeholder handler returning `NOT_FOUND` breaks. The only
  existing consumer was the call crate's own tests; no downstream consumer
  depended on this — the placeholder was a trap, not a contract.
- The call crate loses a public export (`from_jsonschema`, `FromJsonSchema`
  the adapter struct). The `FromJsonSchema` provenance variant stays;
  the adapter struct moves. Downstream consumers that referenced the
  adapter (none currently) would need to use alkhttp's re-export.

**Neutral**:
- `FromJsonSchema` provenance is now a leaf (handler-bearing), not a
  "no handler" provenance. The ADR-022 table row updates: it can compose?
  No. Has composition authority? No. Default visibility? Internal. Trust
  model? HTTP endpoint trusted; handler is a forwarding stub. This
  aligns with the other leaves. ADR-017 §5 and ADR-022's provenance
  table/enum-doc are amended (2026-07-09) to point here — the
  supersession is recorded in the superseded ADRs, not only in this one.

## References

- Supersedes the `from_jsonschema` clause of
  [ADR-017](017-call-protocol-client-and-adapter-contract.md) §5
  ("`FromJsonSchema` — imports from a JSON Schema definition (schema-only,
  no handler)") and the operational spec in the call crate's
  `client-and-adapters.md` §"from_jsonschema" (alknet mono-repo:
  `docs/architecture/crates/call/client-and-adapters.md`).
- Supersedes the `FromJsonSchema` row of
  [ADR-022](022-handler-registration-provenance-and-composition-authority.md)
  (the "no handler — schema only" framing).
- Aligns with the adapter location principle in
  [ADR-017](017-call-protocol-client-and-adapter-contract.md) §5 and the
  call crate's `client-and-adapters.md` §"Adapter Location Map": HTTP-backed
  adapters live in the HTTP crate (alkhttp).
- Reuses the forwarding handler, credential injection, error fidelity
  (`HTTP_<status>` prefix, [ADR-023](023-operation-error-schemas.md)),
  streaming shape ([ADR-049](049-streaming-handler-for-subscriptions.md)),
  and no-env-vars invariant ([ADR-014](014-secret-material-flow-and-capability-injection.md))
  established by `from_openapi`.
- Reuses `HttpServiceConfig` and `SharedHttpClient` from
  `from_openapi` (in alkhttp).
- alkcall ADR-027 — the decision record in the call crate (`from_jsonschema`
  as an HTTP-backed adapter; `FromJsonSchema` provenance is a
  handler-bearing leaf in alkcall's `OperationProvenance`).