alkcall/docs/architecture/decisions/027-from-jsonschema-as-http-adapter.md

ADR-027: from_jsonschema as an HTTP-Backed Single-Endpoint Adapter in alknet-http

Status

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

Context

from_jsonschema was originally specified (ADR-022 §5) as a schema-only adapter living in alknet-call: 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 alknet-call (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-022 / client-and-adapters.md already establishes that HTTP-backed adapters live in alknet-http; the old from_jsonschema violated its own stated principle by living in alknet-call.

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 alknet-http, functionally similar to from_openapi but registering one endpoint at a time instead of parsing a full OpenAPI document:

1. Move the adapter implementation to alknet-http (crates/alknet-http/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 alknet-call, ADR-022 §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 Subscription op type with text/event-stream response, it registers a StreamingHandler (ADR-021), 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 alknet-call (in the OperationProvenance enum, registration.rs). The provenance type lives where the registry types live; only the adapter implementation moves. 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-017), 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	alknet-http	alknet-http
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-016), and the no-env-vars invariant (ADR-010). The difference is purely the input shape: a full document vs. a single endpoint.

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 alknet-http, where reqwest is. alknet-call 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 is the call crate's own tests; no downstream consumer depended on this — the placeholder was a trap, not a contract.
• alknet-call 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 alknet-http's re-export.

Neutral:

• FromJsonSchema provenance is now a leaf (handler-bearing), not a "no handler" provenance. The ADR-018 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-022 §5 and ADR-018'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-022 §5 ("FromJsonSchema — imports from a JSON Schema definition (schema-only, no handler)") and the operational spec in docs/architecture/crates/call/client-and-adapters.md §"from_jsonschema".
• Supersedes the FromJsonSchema row of ADR-018 (the "no handler — schema only" framing).
• Aligns with the adapter location principle in ADR-022 §5 and client-and-adapters.md §"Adapter Location Map": HTTP-backed adapters live in alknet-http.
• Reuses the forwarding handler, credential injection, error fidelity (HTTP_<status> prefix, ADR-016), streaming shape (ADR-021), and no-env-vars invariant (ADR-010) established by from_openapi.
• Reuses HttpServiceConfig and SharedHttpClient from from_openapi (in alknet-http).

Amendment 2026-10-13: name normalization (alknet-http → alkhttp)

This ADR's decision text was authored when the HTTP host crate was named alknet-http inside the alknet mono-repo. The HTTP host is now the standalone sibling crate alkhttp, which wraps alkcall (extraction context: ADR-031; the adapter-location rule is unchanged — the trait lives in alkcall, HTTP-backed adapters live in alkhttp). The title's "in alknet-http" and the body's crate-name references should be read as "in alkhttp"; the References below link to the source-repo originals (provenance). The FromJsonSchema provenance variant remains in alkcall.