use schemars::generate::SchemaSettings;
use schemars::JsonSchema;
use serde::{Deserialize, Serialize};
use serde_json::{Map, Value};
use crate::error::{summarize, AiError, Result};
#[derive(Serialize, Deserialize, JsonSchema)]
#[serde(deny_unknown_fields)]
pub(crate) struct OutputEnvelope<T> {
pub result: T,
}
pub(crate) struct OutputContract {
pub schema: Value,
pub example: Value,
validator: jsonschema::Validator,
}
impl OutputContract {
pub(crate) fn build<T: JsonSchema>() -> Result<Self> {
let settings = SchemaSettings::draft2020_12();
let generator = settings.into_generator();
let schema = generator.into_root_schema_for::<OutputEnvelope<T>>();
let schema = serde_json::to_value(&schema)
.map_err(|err| AiError::UnsupportedSchema(err.to_string()))?;
let schema = normalize(schema);
let example = normalize(generate_example(&schema)?);
let validator = jsonschema::options()
.with_draft(jsonschema::Draft::Draft202012)
.build(&schema)
.map_err(|err| {
AiError::UnsupportedSchema(format!("schema compilation failed: {err}"))
})?;
if let Err(err) = validator.validate(&example) {
return Err(AiError::UnsupportedSchema(format!(
"generated example failed self-validation: {}",
summarize(&err.to_string(), 200)
)));
}
Ok(OutputContract {
schema,
example,
validator,
})
}
pub(crate) fn validate(&self, instance: &Value) -> std::result::Result<(), String> {
validator_validate(&self.validator, instance)
}
}
fn validator_validate(
validator: &jsonschema::Validator,
instance: &Value,
) -> std::result::Result<(), String> {
match validator.validate(instance) {
Ok(()) => Ok(()),
Err(err) => Err(format!(
"model output does not conform to the output schema at `{}`",
err.instance_path()
)),
}
}
pub(crate) fn normalize(value: Value) -> Value {
match value {
Value::Object(map) => {
let mut entries: Vec<(String, Value)> = map.into_iter().collect();
entries.sort_by(|a, b| a.0.cmp(&b.0));
let mut out = Map::with_capacity(entries.len());
for (key, value) in entries {
out.insert(key, normalize(value));
}
Value::Object(out)
}
Value::Array(items) => Value::Array(items.into_iter().map(normalize).collect()),
other => other,
}
}
pub(crate) fn canonical_string(value: &Value) -> String {
serde_json::to_string(value).unwrap_or_default()
}
fn unsupported(reason: impl Into<String>) -> AiError {
AiError::UnsupportedSchema(reason.into())
}
pub(crate) fn generate_example(root: &Value) -> Result<Value> {
generate(root, root, &mut Vec::new())
}
fn generate(schema: &Value, root: &Value, visiting: &mut Vec<String>) -> Result<Value> {
let obj = schema
.as_object()
.ok_or_else(|| unsupported("schema node is not an object"))?;
if let Some(value) = obj.get("const") {
return Ok(value.clone());
}
if let Some(value) = obj.get("default") {
return Ok(value.clone());
}
if let Some(variants) = obj.get("enum").and_then(Value::as_array) {
return variants
.first()
.cloned()
.ok_or_else(|| unsupported("`enum` has no variants to pick from"));
}
if let Some(reference) = obj.get("$ref").and_then(Value::as_str) {
return generate_ref(reference, root, visiting);
}
for keyword in ["oneOf", "anyOf"] {
if let Some(branches) = obj.get(keyword).and_then(Value::as_array) {
let mut last_error = None;
for branch in branches {
let mut branch_visiting = visiting.clone();
match generate(branch, root, &mut branch_visiting) {
Ok(value) => return Ok(value),
Err(err) => last_error = Some(err),
}
}
return Err(last_error.unwrap_or_else(|| {
unsupported(format!("`{keyword}` has no branches to pick from"))
}));
}
}
if let Some(branches) = obj.get("allOf").and_then(Value::as_array) {
let mut merged = Map::new();
for branch in branches {
let mut branch_visiting = visiting.clone();
let value = generate(branch, root, &mut branch_visiting)?;
let Value::Object(part) = value else {
return Err(unsupported("`allOf` branch did not produce an object"));
};
merged.extend(part);
}
return Ok(Value::Object(merged));
}
match obj.get("type") {
Some(Value::String(kind)) => generate_typed(kind, obj, root, visiting),
Some(Value::Array(kinds)) => {
let mut last_error = None;
for kind in kinds {
let Some(kind) = kind.as_str() else { continue };
let mut narrowed = obj.clone();
narrowed.insert("type".to_string(), Value::String(kind.to_string()));
let mut branch_visiting = visiting.clone();
match generate_typed(kind, &narrowed, root, &mut branch_visiting) {
Ok(value) => return Ok(value),
Err(err) => last_error = Some(err),
}
}
Err(last_error.unwrap_or_else(|| unsupported("union `type` has no usable variant")))
}
Some(_) => Err(unsupported(
"`type` must be a string or an array of strings",
)),
None => {
if obj.contains_key("properties") || obj.contains_key("required") {
generate_object(obj, root, visiting)
} else if obj.contains_key("items") || obj.contains_key("prefixItems") {
generate_array(obj, root, visiting)
} else {
Err(unsupported(
"schema node has no `type`, `enum`, `const`, `$ref` or composition keywords",
))
}
}
}
}
fn generate_ref(reference: &str, root: &Value, visiting: &mut Vec<String>) -> Result<Value> {
if !reference.starts_with("#/") && reference != "#" {
return Err(unsupported(format!(
"external `$ref` `{reference}` is not allowed; only local `$defs` references"
)));
}
if visiting.iter().any(|seen| seen == reference) {
return Err(unsupported(format!(
"circular required `$ref` chain at `{reference}`"
)));
}
let pointer = &reference[1..]; let target = root
.pointer(pointer)
.ok_or_else(|| unsupported(format!("unresolvable local `$ref` `{reference}`")))?;
visiting.push(reference.to_string());
let value = generate(target, root, visiting);
visiting.pop();
value
}
fn generate_typed(
kind: &str,
obj: &Map<String, Value>,
root: &Value,
visiting: &mut Vec<String>,
) -> Result<Value> {
match kind {
"object" => generate_object(obj, root, visiting),
"array" => generate_array(obj, root, visiting),
"string" => generate_string(obj),
"integer" => generate_integer(obj),
"number" => generate_number(obj),
"boolean" => Ok(Value::Bool(false)),
"null" => Ok(Value::Null),
other => Err(unsupported(format!("unknown schema type `{other}`"))),
}
}
fn generate_object(
obj: &Map<String, Value>,
root: &Value,
visiting: &mut Vec<String>,
) -> Result<Value> {
let mut out = Map::new();
if let Some(required) = obj.get("required").and_then(Value::as_array) {
let properties = obj.get("properties").and_then(Value::as_object);
for key in required {
let Some(key) = key.as_str() else { continue };
let property = properties
.and_then(|props| props.get(key))
.ok_or_else(|| unsupported(format!("required property `{key}` has no schema")))?;
out.insert(key.to_string(), generate(property, root, visiting)?);
}
}
Ok(Value::Object(out))
}
fn generate_array(
obj: &Map<String, Value>,
root: &Value,
visiting: &mut Vec<String>,
) -> Result<Value> {
let min_items = obj.get("minItems").and_then(Value::as_u64).unwrap_or(0) as usize;
if min_items == 0 {
return Ok(Value::Array(Vec::new()));
}
let items = obj
.get("items")
.ok_or_else(|| unsupported("`minItems` requires an `items` schema"))?;
let element = generate(items, root, visiting)?;
Ok(Value::Array(vec![element; min_items]))
}
fn generate_string(obj: &Map<String, Value>) -> Result<Value> {
if obj.contains_key("pattern") {
return Err(unsupported(
"`pattern` constraints cannot be synthesized into an example",
));
}
let mut value = match obj.get("format").and_then(Value::as_str) {
None => String::new(),
Some(format) => known_format_value(format)
.ok_or_else(|| unsupported(format!("unknown string format `{format}`")))?,
};
let min_length = obj.get("minLength").and_then(Value::as_u64).unwrap_or(0) as usize;
while value.chars().count() < min_length {
value.push('a');
}
Ok(Value::String(value))
}
fn known_format_value(format: &str) -> Option<String> {
let value = match format {
"date-time" => "2000-01-01T00:00:00Z",
"date" => "2000-01-01",
"time" => "00:00:00",
"duration" => "PT0S",
"email" | "idn-email" => "user@example.com",
"hostname" | "idn-hostname" => "example.com",
"ipv4" => "127.0.0.1",
"ipv6" => "::1",
"uri" | "iri" | "uri-reference" | "iri-reference" => "https://example.com/",
"uri-template" => "https://example.com/{id}",
"uuid" => "00000000-0000-0000-0000-000000000000",
"json-pointer" => "/",
"relative-json-pointer" => "0",
"regex" => ".*",
_ => return None,
};
Some(value.to_string())
}
fn lower_bound(obj: &Map<String, Value>) -> Option<f64> {
let mut bound: Option<f64> = None;
let mut raise = |value: f64| bound = Some(bound.map_or(value, |b: f64| b.max(value)));
if let Some(min) = obj.get("minimum").and_then(Value::as_f64) {
raise(min);
}
if let Some(min) = obj.get("exclusiveMinimum").and_then(Value::as_f64) {
raise(min);
}
bound
}
fn generate_integer(obj: &Map<String, Value>) -> Result<Value> {
let exclusive = obj.get("exclusiveMinimum").and_then(Value::as_f64);
let mut candidate = match lower_bound(obj) {
Some(bound) => {
let mut value = bound.ceil() as i64;
if Some(bound) == exclusive && value as f64 == bound {
value += 1; }
value
}
None => 0,
};
if let Some(multiple) = obj.get("multipleOf").and_then(Value::as_i64) {
if multiple > 0 {
candidate = candidate.div_euclid(multiple) * multiple;
if candidate < lower_bound(obj).unwrap_or(f64::MIN) as i64 {
candidate += multiple;
}
}
}
Ok(Value::Number(candidate.into()))
}
fn generate_number(obj: &Map<String, Value>) -> Result<Value> {
let mut candidate = lower_bound(obj).unwrap_or(0.0);
if obj.get("exclusiveMinimum").and_then(Value::as_f64) == Some(candidate) {
candidate += 1.0; }
if let Some(multiple) = obj.get("multipleOf").and_then(Value::as_f64) {
if multiple > 0.0 {
candidate = (candidate / multiple).ceil() * multiple;
}
}
serde_json::Number::from_f64(candidate)
.map(Value::Number)
.ok_or_else(|| unsupported("numeric bounds do not yield a finite example"))
}
#[cfg(test)]
mod tests {
use serde_json::json;
use super::*;
fn example(schema: Value) -> Result<Value> {
let schema = normalize(schema);
let value = generate_example(&schema)?;
let validator = jsonschema::options()
.with_draft(jsonschema::Draft::Draft202012)
.build(&schema)
.expect("schema compiles");
assert!(
validator.is_valid(&value),
"example {value} must validate against {schema}"
);
Ok(value)
}
#[test]
fn enum_and_const_and_default_precedence() {
assert_eq!(example(json!({"enum": ["a", "b"]})).unwrap(), json!("a"));
assert_eq!(example(json!({"const": 7})).unwrap(), json!(7));
assert_eq!(
example(json!({"type": "string", "default": "hi"})).unwrap(),
json!("hi")
);
}
#[test]
fn scalars_respect_bounds() {
assert_eq!(
example(json!({"type": "integer", "minimum": 5})).unwrap(),
json!(5)
);
assert_eq!(
example(json!({"type": "integer", "exclusiveMinimum": 5})).unwrap(),
json!(6)
);
assert_eq!(
example(json!({"type": "integer", "minimum": 1, "multipleOf": 4})).unwrap(),
json!(4)
);
assert_eq!(
example(json!({"type": "number", "exclusiveMinimum": 2.5})).unwrap(),
json!(3.5)
);
assert_eq!(example(json!({"type": "boolean"})).unwrap(), json!(false));
assert_eq!(example(json!({"type": "null"})).unwrap(), Value::Null);
}
#[test]
fn strings_min_length_and_formats() {
assert_eq!(
example(json!({"type": "string", "minLength": 3})).unwrap(),
json!("aaa")
);
assert_eq!(
example(json!({"type": "string", "format": "date-time"})).unwrap(),
json!("2000-01-01T00:00:00Z")
);
assert!(example(json!({"type": "string", "format": "made-up"})).is_err());
assert!(example(json!({"type": "string", "pattern": "^a+$"})).is_err());
}
#[test]
fn objects_generate_required_only() {
let schema = json!({
"type": "object",
"properties": {
"req": {"type": "string"},
"opt": {"type": "integer"}
},
"required": ["req"]
});
assert_eq!(example(schema).unwrap(), json!({"req": ""}));
}
#[test]
fn arrays_follow_min_items() {
assert_eq!(
example(json!({"type": "array", "items": {"type": "string"}})).unwrap(),
json!([])
);
assert_eq!(
example(json!({
"type": "array",
"items": {"type": "integer"},
"minItems": 2
}))
.unwrap(),
json!([0, 0])
);
}
#[test]
fn unions_pick_first_constructible_branch() {
assert_eq!(
example(json!({"anyOf": [{"type": "string"}, {"type": "integer"}]})).unwrap(),
json!("")
);
assert_eq!(
example(json!({
"oneOf": [
{"type": "string", "pattern": "^a+$"},
{"type": "integer"}
]
}))
.unwrap(),
json!(0)
);
assert_eq!(
example(json!({"type": ["string", "null"]})).unwrap(),
json!("")
);
}
#[test]
fn all_of_merges_object_branches() {
let schema = json!({
"allOf": [
{"type": "object", "properties": {"a": {"type": "string"}}, "required": ["a"]},
{"type": "object", "properties": {"b": {"type": "integer"}}, "required": ["b"]}
]
});
assert_eq!(example(schema).unwrap(), json!({"a": "", "b": 0}));
}
#[test]
fn local_refs_resolve_and_cycles_are_rejected() {
let schema = json!({
"$defs": {"name": {"type": "string", "minLength": 1}},
"$ref": "#/$defs/name"
});
assert_eq!(example(schema).unwrap(), json!("a"));
let cyclic = json!({
"$defs": {
"node": {
"type": "object",
"properties": {"next": {"$ref": "#/$defs/node"}},
"required": ["next"]
}
},
"$ref": "#/$defs/node"
});
let err = example(cyclic).expect_err("cycle must fail");
assert!(matches!(err, AiError::UnsupportedSchema(_)));
}
#[test]
fn external_refs_are_rejected() {
let err = example(json!({"$ref": "https://example.com/schema.json"}))
.expect_err("external ref must fail");
assert!(matches!(err, AiError::UnsupportedSchema(_)));
let err = example(json!({"$ref": "other.json#/defs/x"})).expect_err("file ref must fail");
assert!(matches!(err, AiError::UnsupportedSchema(_)));
}
#[test]
fn deterministic_example_for_nested_struct() {
#[derive(JsonSchema)]
#[allow(dead_code)]
struct Nested {
name: String,
tags: Vec<String>,
}
let contract_a = OutputContract::build::<OutputEnvelope<Nested>>().unwrap();
let contract_b = OutputContract::build::<OutputEnvelope<Nested>>().unwrap();
assert_eq!(contract_a.schema, contract_b.schema);
assert_eq!(contract_a.example, contract_b.example);
assert_eq!(
canonical_string(&contract_a.example),
canonical_string(&contract_b.example)
);
}
}