Skip to content

Switchyard lets LLM applications route traffic across models and providers while preserving native OpenAI and Anthropic API compatibility - enabling flexible model selection, benchmarking, and cost/performance optimization.

Rust

fix(translation): preserve structured-output enforcement (#892)

Graham Kingedfce4fa24ba
diff --git a/crates/libsy/src/algorithms/advisor_gate.rs b/crates/libsy/src/algorithms/advisor_gate.rs
index 9f0c35ef2..fde8dc6ad 100644
--- a/crates/libsy/src/algorithms/advisor_gate.rs
+++ b/crates/libsy/src/algorithms/advisor_gate.rs
@@ -529,7 +529,7 @@ impl AdvisorGate {
},
output: OutputParams {
max_output_tokens: Some(self.config.advisor_max_tokens),
- response_format: None,
+ ..OutputParams::default()
},
..LlmRequest::default()
},
diff --git a/crates/libsy/src/algorithms/util/llm_judge.rs b/crates/libsy/src/algorithms/util/llm_judge.rs
index d3fbe34e0..9da6589c4 100644
--- a/crates/libsy/src/algorithms/util/llm_judge.rs
+++ b/crates/libsy/src/algorithms/util/llm_judge.rs
@@ -169,6 +169,7 @@ where
output: OutputParams {
max_output_tokens: Some(self.runtime.max_output_tokens),
response_format: Some(self.contract.response_format().clone()),
+ ..OutputParams::default()
},
..LlmRequest::default()
},
diff --git a/crates/protocol/src/llm.rs b/crates/protocol/src/llm.rs
index 7968faa85..cef8d5980 100644
--- a/crates/protocol/src/llm.rs
+++ b/crates/protocol/src/llm.rs
@@ -263,6 +263,10 @@ pub struct OutputParams {
pub max_output_tokens: Option<u64>,
/// Provider-neutral or provider-specific structured-output configuration.
pub response_format: Option<Value>,
+ /// Whether the provider must enforce the response schema, overriding native
+ /// flags when set and retaining native behavior when `None`.
+ #[serde(default, skip_serializing_if = "Option::is_none")]
+ pub is_schema_enforced: Option<bool>,
}
/// Provider reasoning controls preserved by translation.
diff --git a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs b/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
index 231d97b84..bbcd31cf2 100644
--- a/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
+++ b/crates/switchyard-translation/src/codecs/anthropic/buffered.rs
@@ -10,6 +10,7 @@ use crate::codecs::common::{
text_from_blocks,
};
use crate::codecs::openai_chat::{decode_file_source, decode_image_source};
+use crate::codecs::structured_output::decode_openai_schema_enforcement;
use crate::codecs::{
DecodedRequest, DecodedResponse, EncodedRequest, EncodedResponse, FormatCodec,
};
@@ -64,6 +65,7 @@ impl FormatCodec for AnthropicMessagesCodec {
.map(ToOwned::to_owned),
output: OutputParams {
max_output_tokens,
+ is_schema_enforced: response_format.as_ref().map(|_| true),
response_format,
},
sampling: SamplingParams {
@@ -304,8 +306,12 @@ impl FormatCodec for AnthropicMessagesCodec {
body.insert("output_config".to_string(), json!({"effort": effort}));
}
if let Some(response_format) = &request.output.response_format
- && let Some(format) =
- encode_anthropic_output_format(response_format, &mut diagnostics, policy)?
+ && let Some(format) = encode_anthropic_output_format(
+ response_format,
+ request.output.is_schema_enforced,
+ &mut diagnostics,
+ policy,
+ )?
{
let output_config = body
.entry("output_config".to_string())
@@ -317,6 +323,14 @@ impl FormatCodec for AnthropicMessagesCodec {
});
};
output_config.insert("format".to_string(), format);
+ } else if request.output.response_format.is_none()
+ && request.output.is_schema_enforced == Some(true)
+ {
+ push_lossy(
+ &mut diagnostics,
+ policy,
+ "Structured-output schema enforcement requires a response format with a schema",
+ )?;
}
let body = embed_preservation(Value::Object(body), &request.preservation, policy);
@@ -491,6 +505,7 @@ fn decode_anthropic_output_format(
/// Maps the neutral OpenAI-shaped JSON schema to Anthropic's output format.
fn encode_anthropic_output_format(
response_format: &Value,
+ enforcement: Option<bool>,
diagnostics: &mut Vec<TranslationDiagnostic>,
policy: &TranslationPolicy,
) -> Result<Option<Value>> {
@@ -516,6 +531,15 @@ fn encode_anthropic_output_format(
return Ok(None);
};
+ if enforcement.or_else(|| decode_openai_schema_enforcement(Some(response_format)))
+ == Some(false)
+ {
+ push_lossy(
+ diagnostics,
+ policy,
+ "Anthropic structured output enforces the schema; advisory schema enforcement was strengthened",
+ )?;
+ }
let mut schema = schema.clone();
if strip_anthropic_unsupported_constraints(&mut schema) {
push_lossy(
diff --git a/crates/switchyard-translation/src/codecs/mod.rs b/crates/switchyard-translation/src/codecs/mod.rs
index 16b1bda80..3b36a0bb8 100644
--- a/crates/switchyard-translation/src/codecs/mod.rs
+++ b/crates/switchyard-translation/src/codecs/mod.rs
@@ -9,6 +9,7 @@ pub mod openai_chat;
mod openai_media;
pub mod responses;
pub mod stream;
+mod structured_output;
use serde_json::Value;
diff --git a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
index d90423518..fff2ec46c 100644
--- a/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
+++ b/crates/switchyard-translation/src/codecs/openai_chat/buffered.rs
@@ -12,6 +12,7 @@ use crate::codecs::common::{
use crate::codecs::openai_media::{
ImagePayload, file_payload, file_source_text, image_payload, image_source_text,
};
+use crate::codecs::structured_output::{decode_openai_schema_enforcement, encode_openai_format};
use crate::codecs::{
DecodedRequest, DecodedResponse, EncodedRequest, EncodedResponse, FormatCodec,
};
@@ -59,6 +60,7 @@ impl FormatCodec for OpenAiChatCodec {
.or_else(|| body.get("max_tokens"))
.and_then(Value::as_u64),
response_format: body.get("response_format").cloned(),
+ is_schema_enforced: decode_openai_schema_enforcement(body.get("response_format")),
},
reasoning: ReasoningParams {
effort: body
@@ -254,8 +256,8 @@ impl FormatCodec for OpenAiChatCodec {
Value::String(effort.clone()),
);
}
- if let Some(format) = &request.output.response_format {
- body.insert("response_format".to_string(), format.clone());
+ if let Some(format) = encode_openai_format(&request.output, &mut diagnostics, policy)? {
+ body.insert("response_format".to_string(), format);
}
copy_openai_chat_request_extensions(&mut body, &request.extensions.fields);
diff --git a/crates/switchyard-translation/src/codecs/responses/buffered.rs b/crates/switchyard-translation/src/codecs/responses/buffered.rs
index c9bb8828f..fb970f2d9 100644
--- a/crates/switchyard-translation/src/codecs/responses/buffered.rs
+++ b/crates/switchyard-translation/src/codecs/responses/buffered.rs
@@ -16,6 +16,7 @@ use crate::codecs::openai_chat::{decode_file_source, decode_image_source};
use crate::codecs::openai_media::{
ImagePayload, file_payload, file_source_text, image_payload, image_source_text,
};
+use crate::codecs::structured_output::{decode_openai_schema_enforcement, encode_openai_format};
use crate::codecs::{
DecodedRequest, DecodedResponse, EncodedRequest, EncodedResponse, FormatCodec,
};
@@ -50,6 +51,7 @@ impl FormatCodec for OpenAiResponsesCodec {
let sanitized = strip_codex_compaction_markers(body);
let body = sanitized.as_ref().unwrap_or(body);
let mut diagnostics = Vec::new();
+ let response_format = decode_responses_text_format(body.get("text"));
let mut request = LlmRequest {
model: body
.get("model")
@@ -58,7 +60,8 @@ impl FormatCodec for OpenAiResponsesCodec {
.map(ToOwned::to_owned),
output: OutputParams {
max_output_tokens: body.get("max_output_tokens").and_then(Value::as_u64),
- response_format: decode_responses_text_format(body.get("text")),
+ is_schema_enforced: decode_openai_schema_enforcement(response_format.as_ref()),
+ response_format,
},
reasoning: ReasoningParams {
effort: body
@@ -170,10 +173,10 @@ impl FormatCodec for OpenAiResponsesCodec {
fn encode_request(
&self,
request: &LlmRequest,
- _policy: &TranslationPolicy,
+ policy: &TranslationPolicy,
) -> Result<EncodedRequest> {
if let Some(body) =
- exact_preserved_request(&request.preservation, WireFormat::OpenAiResponses, _policy)
+ exact_preserved_request(&request.preservation, WireFormat::OpenAiResponses, policy)
{
return Ok(EncodedRequest {
body,
@@ -181,7 +184,7 @@ impl FormatCodec for OpenAiResponsesCodec {
});
}
let mut diagnostics = Vec::new();
- validate_request_capabilities(request, &mut diagnostics, _policy)?;
+ validate_request_capabilities(request, &mut diagnostics, policy)?;
let mut body = Map::new();
if let Some(model) = &request.model {
body.insert("model".to_string(), Value::String(model.clone()));
@@ -204,7 +207,7 @@ impl FormatCodec for OpenAiResponsesCodec {
encode_responses_input(
&request.messages,
&mut diagnostics,
- _policy,
+ policy,
crate::codex_namespaces::tool_namespaces(&request.extensions),
&crate::codex_custom_tools::custom_tool_names(&request.extensions),
crate::codex_custom_tools::custom_call_outputs(&request.extensions),
@@ -251,10 +254,12 @@ impl FormatCodec for OpenAiResponsesCodec {
if let Some(max_output_tokens) = request.output.max_output_tokens {
body.insert("max_output_tokens".to_string(), json!(max_output_tokens));
}
- if let Some(response_format) = &request.output.response_format {
+ if let Some(response_format) =
+ encode_openai_format(&request.output, &mut diagnostics, policy)?
+ {
body.insert(
"text".to_string(),
- json!({"format": encode_responses_text_format(response_format)}),
+ json!({"format": encode_responses_text_format(&response_format)}),
);
}
// An Anthropic request's raw reasoning is its `thinking` object, which Responses
@@ -298,7 +303,7 @@ impl FormatCodec for OpenAiResponsesCodec {
}
copy_responses_request_extensions(&mut body, &request.extensions.fields);
- let body = embed_preservation(Value::Object(body), &request.preservation, _policy);
+ let body = embed_preservation(Value::Object(body), &request.preservation, policy);
Ok(EncodedRequest { body, diagnostics })
}
diff --git a/crates/switchyard-translation/src/codecs/structured_output.rs b/crates/switchyard-translation/src/codecs/structured_output.rs
new file mode 100644
index 000000000..5299bac6c
--- /dev/null
+++ b/crates/switchyard-translation/src/codecs/structured_output.rs
@@ -0,0 +1,171 @@
+// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+//! Structured-output enforcement across provider formats.
+
+use serde_json::Value;
+
+use crate::diagnostic::TranslationDiagnostic;
+use crate::error::Result;
+use crate::llm::OutputParams;
+use crate::policy::TranslationPolicy;
+use crate::util::push_lossy;
+
+pub(super) fn decode_openai_schema_enforcement(format: Option<&Value>) -> Option<bool> {
+ let format = format.filter(|format| format["type"] == "json_schema")?;
+ Some(format["json_schema"]["strict"].as_bool().unwrap_or(false))
+}
+
+pub(super) fn encode_openai_format(
+ output: &OutputParams,
+ diagnostics: &mut Vec<TranslationDiagnostic>,
+ policy: &TranslationPolicy,
+) -> Result<Option<Value>> {
+ let mut format = output.response_format.clone();
+ let Some(is_enforced) = output.is_schema_enforced else {
+ return Ok(format);
+ };
+ let schema = format
+ .as_mut()
+ .filter(|format| format["type"] == "json_schema")
+ .and_then(|format| format.get_mut("json_schema"))
+ .and_then(Value::as_object_mut);
+ let Some(schema) = schema.filter(|schema| schema.get("schema").is_some_and(Value::is_object))
+ else {
+ if is_enforced {
+ push_lossy(
+ diagnostics,
+ policy,
+ "Structured-output schema enforcement requires a json_schema object with a schema",
+ )?;
+ }
+ return Ok(format);
+ };
+ // Preserve native strict schemas, including constructs outside our checked subset.
+ if is_enforced
+ && schema.get("strict").and_then(Value::as_bool) != Some(true)
+ && !schema
+ .get("schema")
+ .is_some_and(is_openai_strict_compatible)
+ {
+ push_lossy(
+ diagnostics,
+ policy,
+ "Structured-output schema was left non-strict: compatibility with OpenAI strict mode could not be established",
+ )?;
+ } else {
+ schema.insert("strict".into(), Value::Bool(is_enforced));
+ }
+ Ok(format)
+}
+
+// A conservative subset shared by OpenAI base and fine-tuned models. Fine-tuning
+// excludes format, pattern, minLength/maxLength, minimum/maximum, multipleOf,
+// and minItems/maxItems. These and unchecked constructs such as references retain
+// their schema with a lossiness diagnostic.
+fn is_openai_strict_compatible(schema: &Value) -> bool {
+ #[derive(Default)]
+ struct Size {
+ properties: usize,
+ enum_values: usize,
+ chars: usize,
+ }
+
+ fn visit(schema: &Value, depth: usize, size: &mut Size) -> bool {
+ let Some(object) = schema.as_object() else {
+ return false;
+ };
+ if object.keys().any(|key| {
+ !matches!(
+ key.as_str(),
+ "type"
+ | "title"
+ | "description"
+ | "properties"
+ | "required"
+ | "additionalProperties"
+ | "items"
+ | "enum"
+ | "const"
+ | "anyOf"
+ )
+ }) {
+ return false;
+ }
+ if let Some(values) = object.get("enum") {
+ let Some(values) = values.as_array().filter(|values| !values.is_empty()) else {
+ return false;
+ };
+ if values
+ .iter()
+ .any(|value| value.is_object() || value.is_array())
+ {
+ return false;
+ }
+ let chars = values
+ .iter()
+ .filter_map(Value::as_str)
+ .map(|value| value.chars().count())
+ .sum::<usize>();
+ if values.len() > 250 && chars > 15_000 {
+ return false;
+ }
+ size.enum_values += values.len();
+ size.chars += chars;
+ }
+ if let Some(value) = object.get("const") {
+ if value.is_object() || value.is_array() {
+ return false;
+ }
+ size.chars += value.as_str().map_or(0, |value| value.chars().count());
+ }
+ if let Some(choices) = object.get("anyOf") {
+ // Limit siblings to annotations so every constraint is checked in a branch.
+ return object
+ .keys()
+ .all(|key| matches!(key.as_str(), "anyOf" | "title" | "description"))
+ && choices.as_array().is_some_and(|choices| {
+ !choices.is_empty() && choices.iter().all(|choice| visit(choice, depth, size))
+ });
+ }
+ let schema_type = match &schema["type"] {
+ Value::String(kind) => Some(kind.as_str()),
+ Value::Array(kinds)
+ if kinds.len() == 2 && kinds.iter().any(|kind| kind.as_str() == Some("null")) =>
+ {
+ kinds
+ .iter()
+ .filter_map(Value::as_str)
+ .find(|kind| *kind != "null")
+ }
+ _ => None,
+ };
+ match schema_type {
+ Some("object") if depth < 10 => {
+ let (Some(fields), Some(required)) = (
+ schema["properties"].as_object(),
+ schema["required"].as_array(),
+ ) else {
+ return false;
+ };
+ size.properties += fields.len();
+ size.chars += fields.keys().map(|key| key.chars().count()).sum::<usize>();
+ schema["additionalProperties"] == false
+ && required.len() == fields.len()
+ && fields.iter().all(|(name, value)| {
+ required.iter().any(|value| value.as_str() == Some(name))
+ && visit(value, depth + 1, size)
+ })
+ }
+ Some("array") if depth < 10 => visit(&schema["items"], depth + 1, size),
+ Some("string" | "number" | "integer" | "boolean" | "null") => true,
+ _ => false,
+ }
+ }
+ let mut size = Size::default();
+ schema["type"] == "object"
+ && visit(schema, 0, &mut size)
+ && size.properties <= 5000
+ && size.enum_values <= 1000
+ && size.chars <= 120_000
+}
diff --git a/crates/switchyard-translation/src/engine.rs b/crates/switchyard-translation/src/engine.rs
index 9e739c503..3399c769e 100644
--- a/crates/switchyard-translation/src/engine.rs
+++ b/crates/switchyard-translation/src/engine.rs
@@ -127,6 +127,10 @@ impl TranslationEngine {
}
/// Encodes a neutral request IR into a target wire format.
+ ///
+ /// Preserved target bodies take precedence over normalized fields, including
+ /// `output.is_schema_enforced`. Clear the target's preservation entry or use
+ /// [`crate::policy::PreservationPolicy::Disabled`] to encode IR edits.
pub fn encode_request(
&self,
target: impl Into<FormatId>,
diff --git a/crates/switchyard-translation/tests/request_translation.rs b/crates/switchyard-translation/tests/request_translation.rs
index eceb54693..35e5a7a11 100644
--- a/crates/switchyard-translation/tests/request_translation.rs
+++ b/crates/switchyard-translation/tests/request_translation.rs
@@ -2776,6 +2776,170 @@ fn anthropic_structured_output_request(output: Value) -> Value {
body
}
+#[test]
+fn structured_output_enforcement_survives_translation_or_is_diagnosed() -> TestResult {
+ let engine = TranslationEngine::default();
+ let mut optional = city_schema();
+ optional["required"] = json!([]);
+ let mut choices = city_schema();
+ choices["properties"]["city"] = json!({"anyOf": [
+ {"type": "string", "enum": ["Paris", "London"]},
+ {"type": "null", "const": null},
+ {"type": "array", "items": {"type": ["string", "null"]}}
+ ]});
+ let mut sibling_constraints = city_schema();
+ sibling_constraints["properties"]["city"] = json!({
+ "anyOf": [city_schema()],
+ "properties": {"optional": {"type": "string"}}
+ });
+ let mut nested = city_schema();
+ for _ in 1..10 {
+ nested = json!({"type": "object", "properties": {"child": nested},
+ "required": ["child"], "additionalProperties": false});
+ }
+ let too_deep = json!({"type": "object", "properties": {"child": nested},
+ "required": ["child"], "additionalProperties": false});
+ let mut all_of = city_schema();
+ all_of["allOf"] = json!([city_schema()]);
+ for (schema, is_compatible) in [
+ (city_schema(), true),
+ (choices, true),
+ (sibling_constraints, false),
+ (nested, true),
+ (optional, false),
+ (all_of, false),
+ (too_deep, false),
+ ] {
+ let body = anthropic_structured_output_request(json!({
+ "output_config": {"format": {"type": "json_schema", "schema": schema}}
+ }));
+ let mut decoded =
+ engine.decode_request(WireFormat::AnthropicMessages, &body, &normalized_policy())?;
+ assert_eq!(decoded.request.output.is_schema_enforced, Some(true));
+ for target in [WireFormat::OpenAiChat, WireFormat::OpenAiResponses] {
+ let translated =
+ engine.encode_request(target, &decoded.request, &normalized_policy())?;
+ let format = if target == WireFormat::OpenAiChat {
+ &translated.body["response_format"]["json_schema"]
+ } else {
+ &translated.body["text"]["format"]
+ };
+ assert_eq!(format["schema"], schema);
+ assert_eq!(format["strict"].as_bool(), is_compatible.then_some(true));
+ assert_eq!(translated.diagnostics.is_empty(), is_compatible);
+ let policy = TranslationPolicy {
+ lossy_conversion_policy: LossyConversionPolicy::Reject,
+ ..normalized_policy()
+ };
+ assert_eq!(
+ engine
+ .translate_request(WireFormat::AnthropicMessages, target, &body, &policy)
+ .err()
+ .map(|error| error.kind()),
+ (!is_compatible).then_some("LossyConversion")
+ );
+ }
+ decoded.request.output.is_schema_enforced = Some(false);
+ let encoded = engine.encode_request(
+ WireFormat::OpenAiChat,
+ &decoded.request,
+ &normalized_policy(),
+ )?;
+ assert_eq!(
+ encoded.body["response_format"]["json_schema"]["strict"],
+ false
+ );
+ }
+ let mut request = switchyard_translation::LlmRequest::default();
+ request.output.is_schema_enforced = Some(true);
+ for format in [
+ None,
+ Some(json!({"type": "json_schema"})),
+ Some(json!({"type": "json_object"})),
+ ] {
+ request.output.response_format = format;
+ for target in [
+ WireFormat::OpenAiChat,
+ WireFormat::OpenAiResponses,
+ WireFormat::AnthropicMessages,
+ ] {
+ let encoded = engine.encode_request(target, &request, &normalized_policy())?;
+ assert_eq!(encoded.diagnostics.len(), 1);
+ let policy = TranslationPolicy {
+ lossy_conversion_policy: LossyConversionPolicy::Reject,
+ ..normalized_policy()
+ };
+ assert_eq!(
+ engine
+ .encode_request(target, &request, &policy)
+ .err()
+ .map(|error| error.kind()),
+ Some("LossyConversion")
+ );
+ }
+ }
+ for strict in [None, Some(false), Some(true)] {
+ let mut body = json!({
+ "model": "model", "messages": [{"role": "user", "content": "ping"}],
+ "response_format": {"type": "json_schema", "json_schema": {
+ "name": "response", "schema": city_schema()
+ }}
+ });
+ if let Some(strict) = strict {
+ body["response_format"]["json_schema"]["strict"] = json!(strict);
+ }
+ let responses = engine.translate_request(
+ WireFormat::OpenAiChat,
+ WireFormat::OpenAiResponses,
+ &body,
+ &normalized_policy(),
+ )?;
+ for (source, body) in [
+ (WireFormat::OpenAiChat, &body),
+ (WireFormat::OpenAiResponses, &responses.body),
+ ] {
+ let mut decoded = engine.decode_request(source, body, &normalized_policy())?;
+ assert_eq!(
+ decoded.request.output.is_schema_enforced,
+ Some(strict == Some(true))
+ );
+ let translated = engine.encode_request(
+ WireFormat::AnthropicMessages,
+ &decoded.request,
+ &normalized_policy(),
+ )?;
+ assert_eq!(
+ translated.body["output_config"]["format"]["schema"],
+ city_schema()
+ );
+ assert_eq!(translated.diagnostics.is_empty(), strict == Some(true));
+ let policy = TranslationPolicy {
+ lossy_conversion_policy: LossyConversionPolicy::Reject,
+ ..normalized_policy()
+ };
+ assert_eq!(
+ engine
+ .encode_request(WireFormat::AnthropicMessages, &decoded.request, &policy)
+ .err()
+ .map(|error| error.kind()),
+ (strict != Some(true)).then_some("LossyConversion")
+ );
+ // The explicit IR setting overrides an existing provider flag.
+ decoded.request.output.is_schema_enforced = Some(strict != Some(true));
+ let encoded = engine.encode_request(
+ WireFormat::OpenAiChat,
+ &decoded.request,
+ &normalized_policy(),
+ )?;
+ assert_eq!(
+ encoded.body["response_format"]["json_schema"]["strict"],
+ strict != Some(true)
+ );
+ }
+ }
+ Ok(())
+}
+
fn city_schema() -> Value {
json!({
"type": "object",