[weiqingy]

Linked issue: #280

Purpose of change

Passing an output_schema to the watsonx.ai connection now constrains the reply through the provider instead of raising. Both languages rejected a schema outright before, so every caller fell back to prompt engineering, even though the chat endpoint accepts a response_format carrying a JSON Schema and enforces it during decoding.

Runtime flow

The connection derives a JSON Schema from the caller's type, wraps it as {"type": "json_schema", "json_schema": {"name", "schema", "strict": true}}, and sets it at the request root. The branch runs only for a Java POJO class or a pydantic model, and only when the capability predicate answers true. It sits before both parameter-merge steps, so a caller's own value is read before anything is written. Java generates the schema directly, having no vendor SDK here; Python renders it from pydantic through render_output_schema.

Key decisions

No model allowlist. OpenAI and Azure gate this on a list of model names; this connection reports it for every model. IBM publishes no per-model structured-output table and no capability flag on the model specification, and no client I could find gates by model. IBM does state Chat API support requires the vLLM runtime, so reaching this endpoint implies the runtime that applies the constraint. An allowlist would encode a gate nobody documents and answer "unsupported" for models that work. Ollama reports unconditionally for a comparable reason. This diverges from the base contract, which asks an unrecognized model to report false; the override records that.

Plain schema rendering. OpenAI and Azure rewrite the required list to name every property, which OpenAI's strict mode demands and watsonx does not; reusing that renderer would report every optional field as mandatory. Relatedly, additionalProperties is not forbidden, since emitting it on one side only would make the two languages send different documents for the same type.

Behavioral Semantics

Interaction decisions

Output schema kind against a caller-supplied response_format:

Schema	No caller value	Caller value	Caller value of null
None	nothing added	forwarded unchanged	Java drops it; Python forwards it
POJO / pydantic model	derived envelope sent	raises	derived envelope sent
RowTypeInfo	nothing added, prompt fallback	forwarded unchanged	forwarded unchanged

The middle-right cell is the only new refusal. A null is excluded because the derived envelope overwrites it before the request is built. The bottom row is deliberate: the conflict fires only where a schema was applied.

Behavioral contracts

1. The predicate answers true for every model, including an unknown or absent one.
2. A POJO or pydantic schema produces a root response_format, strict true, named for the type.
3. No schema produces no response_format key.
4. An untranslatable schema produces none either, and the call proceeds.
5. A schema plus a caller response_format carrying a value raises.
6. A caller response_format alone reaches the service unchanged.
7. The derived schema names properties as the deserializer does: renames honored, ignored fields excluded.
8. Both languages state the same contract for a given type: same property names, types, required set.

Failure behavior

An untranslatable schema degrades to the prompt fallback silently, matching existing behavior. A schema plus a caller response_format value raises before the request is built. A pydantic model with no JSON Schema raises TypeError naming the model rather than a translation failure. Provider and transport errors, including retries, are unchanged.

Two cases do not fail loudly. A self-referential type generates a self-referencing document and is sent as-is; no generator setting here prevents it. An empty completion is not distinguished from a normal one, which is existing behavior for every reply.

Tests

Contract	Java	Python
1	supportsNativeStructuredOutputIsUnconditional	test_supports_native_structured_output_is_unconditional
2	buildPayloadWritesResponseFormatForPojoSchema, serializedRequestBodyCarriesResponseFormatAtRoot	test_params_carry_response_format_for_basemodel_schema
3	buildPayloadOmitsResponseFormatWithoutSchema	test_params_omit_response_format_without_schema
4	buildPayloadOmitsResponseFormatForRowTypeInfo	test_row_type_info_schema_returns_and_sends_no_response_format
5	chatWithSchemaAndCallerResponseFormatRaises	test_schema_and_caller_response_format_raises
6	callerResponseFormatSurvivesWhenNoSchemaIsSent	test_caller_response_format_survives_when_no_schema_is_sent
7	derivedSchemaHonorsJacksonAnnotations	pydantic's own rendering
8	n/a	test_derived_schema_matches_java_semantically

Coverage by risk. The highest risk is sending a document the provider rejects or ignores, so the Java suite asserts the full serialized request body through a local stub server rather than the builder's output. Next is a schema constraining the model to a document the deserializer then refuses, covered by contract 7. Conflict handling is covered on both parameter channels in both languages.

Not verified. No live call was made against watsonx, because I hold no credentials. An environment-gated live test ships for each language and neither has run, here or in CI. Nothing here establishes that IBM accepts the document, that an incapable model is rejected rather than ignoring the schema, or how a self-referential schema behaves at the provider. Python's stubbing sits above the SDK's payload assembly, so it pins the parameters handed to the SDK, not the bytes sent.

Implementation invariants and supporting evidence

Not user-observable, so recorded here rather than as contracts.

The Java payload seam widened from a static three-argument method to a four-argument instance method, because the capability predicate it now consults is an instance method.

The generated Java schema omits additionalProperties and keeps the document root inline rather than behind a $ref. Neither is required by the endpoint; both keep the two languages emitting the same shape. The generator marks every field required except an Optional one, which matches pydantic treating a field without a default as required.

The two languages emit different schema metadata: the Java document carries $schema, the pydantic document carries title. Contract 8 is therefore asserted semantically rather than as document equality.

A caller response_format valued null with no schema at all reaches the Python request body, where the Java write loops drop it. Those lines are untouched by this change and the divergence predates it.

Suite results: Java 44 run with 2 skipped, both skipped being the live tests. Python 27 passed with 2 deselected. The cross-connection guard asserting that a connection which cannot translate a schema rejects one still passes; contract 4's test is what keeps that covered once the predicate is overridden.

API

No new public classes, and nothing changes for an existing caller. No production code path passes an output schema in either language today, so this adds a capability rather than altering behavior, and a caller supplying response_format directly is unaffected.

What becomes possible is passing an output_schema without it raising. The only new refusal is supplying both an output schema and a response_format value in one call.

Documentation

• doc-needed
• doc-not-needed
• doc-included

The capability is not reachable by a user until the policy layer is wired up, so the user-facing documentation belongs with that change.

Was this patch authored or co-authored using generative AI tooling?

• Yes
• No

Generated-by: Claude Code 2.1.260 (Claude Opus 5)

[weiqingy]

The one failing check is unrelated to this PR.

• cross-language [ubuntu-latest] [python-3.12] [java-21]: pull access denied for minio/minio. The job dies in the Start Milvus step, before any test runs, and the Maven build in that same job reports BUILD SUCCESS immediately before it. Evidence: failing job.

This is a repo-wide break rather than something in this branch. minio/minio is no longer pullable from Docker Hub, so any run started after that change fails the same way, and #1098 is failing identically. PRs whose runs predate it are still green, which is why the break looks selective.

Re-running does not clear it. I re-triggered the job once and it failed with the same error, so this needs the image reference fixed rather than another attempt.

#1116 changes that image reference to quay.io/minio/minio.