use crate::{Map, Value};
use std::fmt;
use std::io;
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
#[non_exhaustive]
pub enum SchemaDefectKind {
UndescribedObject,
UndescribedArray,
}
impl fmt::Display for SchemaDefectKind {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
Self::UndescribedObject => concat!(
r#"declares "type": "object" without describing what it accepts; add "#,
r#""properties", give "additionalProperties" a schema, or declare it "#,
r#"free-form with a "description" and "additionalProperties": true"#,
),
Self::UndescribedArray => r#"declares "type": "array" without "items""#,
})
}
}
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct SchemaDefect {
pub tool: Option<String>,
pub path: String,
pub kind: SchemaDefectKind,
}
impl fmt::Display for SchemaDefect {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
if let Some(tool) = &self.tool {
write!(formatter, "tool \"{tool}\": ")?;
}
if self.path.is_empty() {
formatter.write_str("the input schema root ")?;
} else {
write!(formatter, "{} ", self.path)?;
}
write!(formatter, "{}", self.kind)
}
}
impl std::error::Error for SchemaDefect {}
pub fn validate_tool_schema(schema: &Value) -> Result<(), Vec<SchemaDefect>> {
let defects = defects_in(None, schema);
if defects.is_empty() {
Ok(())
} else {
Err(defects)
}
}
pub(crate) fn defects_in(tool: Option<&str>, schema: &Value) -> Vec<SchemaDefect> {
let mut defects = Vec::new();
inspect(tool, schema, &mut String::new(), &mut defects);
defects
}
pub(crate) fn reject_defects(defects: &[SchemaDefect]) -> io::Result<()> {
if defects.is_empty() {
return Ok(());
}
let mut message = String::from("strict schemas rejected the tool catalog:");
for defect in defects {
message.push_str("\n ");
message.push_str(&defect.to_string());
}
Err(io::Error::new(io::ErrorKind::InvalidInput, message))
}
pub(crate) fn reject_messages(messages: &[String]) -> io::Result<()> {
if messages.is_empty() {
return Ok(());
}
Err(io::Error::new(
io::ErrorKind::InvalidInput,
messages.join("; "),
))
}
fn inspect(tool: Option<&str>, node: &Value, path: &mut String, defects: &mut Vec<SchemaDefect>) {
let Some(node) = node.as_object() else {
return;
};
if declares_type(node, "object") && !describes_members(node) {
defects.push(defect(tool, path, SchemaDefectKind::UndescribedObject));
}
if declares_type(node, "array") && !node.contains_key("items") {
defects.push(defect(tool, path, SchemaDefectKind::UndescribedArray));
}
if let Some(properties) = node.get("properties").and_then(Value::as_object) {
for (name, property) in properties {
descend(tool, property, path, &["properties", name], defects);
}
}
match node.get("items") {
Some(Value::Array(items)) => {
for (position, item) in items.iter().enumerate() {
descend(tool, item, path, &["items", &position.to_string()], defects);
}
}
Some(items) => descend(tool, items, path, &["items"], defects),
None => {}
}
if let Some(additional) = node.get("additionalProperties") {
descend(tool, additional, path, &["additionalProperties"], defects);
}
}
fn descend(
tool: Option<&str>,
node: &Value,
path: &mut String,
segments: &[&str],
defects: &mut Vec<SchemaDefect>,
) {
let parent = path.len();
for segment in segments {
push_segment(path, segment);
}
inspect(tool, node, path, defects);
path.truncate(parent);
}
fn describes_members(node: &Map<String, Value>) -> bool {
if node.contains_key("properties") {
return true;
}
match node.get("additionalProperties") {
Some(Value::Object(_)) => true,
Some(Value::Bool(true)) => node
.get("description")
.and_then(Value::as_str)
.is_some_and(|description| !description.trim().is_empty()),
_ => false,
}
}
fn declares_type(node: &Map<String, Value>, name: &str) -> bool {
match node.get("type") {
Some(Value::String(declared)) => declared == name,
Some(Value::Array(declared)) => declared.iter().any(|entry| entry.as_str() == Some(name)),
_ => false,
}
}
fn defect(tool: Option<&str>, path: &str, kind: SchemaDefectKind) -> SchemaDefect {
SchemaDefect {
tool: tool.map(str::to_owned),
path: path.to_owned(),
kind,
}
}
fn push_segment(path: &mut String, segment: &str) {
path.push('/');
for character in segment.chars() {
match character {
'~' => path.push_str("~0"),
'/' => path.push_str("~1"),
_ => path.push(character),
}
}
}
#[cfg(test)]
mod tests {
use super::{reject_defects, validate_tool_schema, SchemaDefectKind};
use crate::json;
fn defect_paths(schema: &crate::Value) -> Vec<(String, SchemaDefectKind)> {
validate_tool_schema(schema)
.expect_err("schema must be rejected")
.into_iter()
.map(|defect| (defect.path, defect.kind))
.collect()
}
#[test]
fn a_bare_object_property_is_rejected() {
let schema = json!({
"type": "object",
"properties": {
"budget": {"type": "object"}
},
"required": ["budget"]
});
assert_eq!(
defect_paths(&schema),
vec![(
"/properties/budget".to_owned(),
SchemaDefectKind::UndescribedObject
)]
);
}
#[test]
fn a_bare_array_property_is_rejected() {
let schema = json!({
"type": "object",
"properties": {
"tags": {"type": "array"}
}
});
assert_eq!(
defect_paths(&schema),
vec![(
"/properties/tags".to_owned(),
SchemaDefectKind::UndescribedArray
)]
);
}
#[test]
fn an_explicitly_declared_free_form_object_is_accepted() {
let schema = json!({
"type": "object",
"properties": {
"passthrough": {
"type": "object",
"description": "Opaque options forwarded to the upstream planner.",
"additionalProperties": true
},
"labels": {
"type": "object",
"additionalProperties": {"type": "string"}
}
}
});
assert_eq!(validate_tool_schema(&schema), Ok(()));
}
#[test]
fn a_free_form_object_without_a_description_is_rejected() {
let schema = json!({
"type": "object",
"properties": {
"passthrough": {"type": "object", "additionalProperties": true}
}
});
assert_eq!(
defect_paths(&schema),
vec![(
"/properties/passthrough".to_owned(),
SchemaDefectKind::UndescribedObject
)]
);
}
#[test]
fn a_nested_object_inside_properties_is_rejected() {
let schema = json!({
"type": "object",
"properties": {
"availability": {
"type": "object",
"properties": {
"window": {"type": "object"},
"slots": {"type": "array", "items": {"type": "object"}}
}
}
}
});
assert_eq!(
defect_paths(&schema),
vec![
(
"/properties/availability/properties/slots/items".to_owned(),
SchemaDefectKind::UndescribedObject
),
(
"/properties/availability/properties/window".to_owned(),
SchemaDefectKind::UndescribedObject
),
]
);
}
#[test]
fn a_fully_described_schema_is_accepted() {
let schema = json!({
"type": "object",
"properties": {
"budget": {
"type": "object",
"properties": {
"ceiling_cents": {"type": "integer"},
"weavatrix": {"type": "string"}
},
"required": ["ceiling_cents", "weavatrix"]
},
"windows": {
"type": "array",
"items": {
"type": "object",
"properties": {"start": {"type": "string"}}
}
},
"note": {"type": "string"}
},
"required": ["budget"]
});
assert_eq!(validate_tool_schema(&schema), Ok(()));
}
#[test]
fn a_no_argument_tool_declares_an_empty_property_set() {
assert_eq!(
validate_tool_schema(&json!({"type": "object", "properties": {}})),
Ok(())
);
assert_eq!(
defect_paths(&json!({"type": "object"})),
vec![(String::new(), SchemaDefectKind::UndescribedObject)]
);
}
#[test]
fn nullable_unions_and_untyped_nodes_follow_the_same_rule() {
assert_eq!(
defect_paths(&json!({
"type": "object",
"properties": {
"maybe": {"type": ["object", "null"]},
"either": {"oneOf": [{"type": "string"}]}
}
})),
vec![(
"/properties/maybe".to_owned(),
SchemaDefectKind::UndescribedObject
)]
);
}
#[test]
fn pointers_escape_reserved_characters_in_property_names() {
assert_eq!(
defect_paths(&json!({
"type": "object",
"properties": {"a/b~c": {"type": "array"}}
})),
vec![(
"/properties/a~1b~0c".to_owned(),
SchemaDefectKind::UndescribedArray
)]
);
}
#[test]
fn rejection_reports_every_defect_in_one_message() {
let defects = validate_tool_schema(&json!({
"type": "object",
"properties": {
"budget": {"type": "object"},
"tags": {"type": "array"}
}
}))
.expect_err("schema must be rejected");
let error = reject_defects(&defects).expect_err("defects must be refused");
let message = error.to_string();
assert_eq!(error.kind(), std::io::ErrorKind::InvalidInput);
assert!(message.contains("/properties/budget"), "{message}");
assert!(message.contains("/properties/tags"), "{message}");
assert!(reject_defects(&[]).is_ok());
}
}