bsodfather/crank
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: implement schema validation and sample normalization

Browse Source
This commit is contained in:
a.tolmachev
2026-03-25 12:52:54 +03:00
parent 08f354d469
commit 23a4601c30
6 changed files with 665 additions and 176 deletions
Download Patch File Download Diff File Expand all files Collapse all files
TASKS.md
+3 -13
View File
@@ -2,21 +2,9 @@
## Current
### `feat/domain-model`
Status: completed
DoD:
- core domain types from `docs/data-model.md` exist
- basic JSON and YAML serialization works
- domain unit tests pass
## Next
### `feat/schema-engine`
Status: pending
Status: in_progress
DoD:
@@ -24,6 +12,8 @@ DoD:
- schema validation works
- JSON sample normalization works
## Next
### `feat/mapping-engine`
Status: pending
crates/mcpaas-schema/src/error.rs
+55
View File
@@ -0,0 +1,55 @@
use thiserror::Error;
#[derive(Clone, Debug, PartialEq, Eq, Error)]
pub enum SchemaError {
#[error("missing required field at {path}")]
MissingField { path: String },
#[error("invalid value at {path}: expected {expected}, got {actual}")]
InvalidType {
path: String,
expected: &'static str,
actual: &'static str,
},
#[error("invalid enum value at {path}: expected one of {expected:?}, got {actual}")]
InvalidEnumValue {
path: String,
expected: Vec<String>,
actual: String,
},
#[error("no matching oneof variant at {path}")]
OneofMismatch { path: String },
}
impl SchemaError {
pub fn missing_field(path: impl Into<String>) -> Self {
Self::MissingField { path: path.into() }
}
pub fn invalid_type(
path: impl Into<String>,
expected: &'static str,
actual: &'static str,
) -> Self {
Self::InvalidType {
path: path.into(),
expected,
actual,
}
}
pub fn invalid_enum_value(
path: impl Into<String>,
expected: Vec<String>,
actual: impl Into<String>,
) -> Self {
Self::InvalidEnumValue {
path: path.into(),
expected,
actual: actual.into(),
}
}
pub fn oneof_mismatch(path: impl Into<String>) -> Self {
Self::OneofMismatch { path: path.into() }
}
}
crates/mcpaas-schema/src/lib.rs
+6 -163
View File
@@ -1,164 +1,7 @@
use std::collections::BTreeMap;
mod error;
mod model;
mod normalize;
mod validate;
use serde::{Deserialize, Serialize};
use serde_json::Value;
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SchemaKind {
Object,
Array,
String,
Integer,
Number,
Boolean,
Enum,
#[serde(rename = "null")]
Null,
Oneof,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Schema {
#[serde(rename = "type")]
pub kind: SchemaKind,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[serde(default)]
pub required: bool,
#[serde(default)]
pub nullable: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub default_value: Option<Value>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub fields: BTreeMap<String, Schema>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub items: Option<Box<Schema>>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub enum_values: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub variants: Vec<Schema>,
}
impl Schema {
pub fn is_object(&self) -> bool {
self.kind == SchemaKind::Object
}
pub fn field(&self, name: &str) -> Option<&Schema> {
self.fields.get(name)
}
pub fn has_required_fields(&self) -> bool {
self.fields.values().any(|field| field.required)
}
}
#[cfg(test)]
mod tests {
use std::collections::BTreeMap;
use super::{Schema, SchemaKind};
#[test]
fn object_schema_exposes_fields() {
let mut fields = BTreeMap::new();
fields.insert(
"email".to_owned(),
Schema {
kind: SchemaKind::String,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
},
);
let schema = Schema {
kind: SchemaKind::Object,
description: Some("User input".to_owned()),
required: true,
nullable: false,
default_value: None,
fields,
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
};
assert!(schema.is_object());
assert!(schema.has_required_fields());
assert_eq!(
schema.field("email").map(|field| field.required),
Some(true)
);
}
#[test]
fn schema_serializes_type_field() {
let schema = Schema {
kind: SchemaKind::Array,
description: None,
required: false,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: Some(Box::new(Schema {
kind: SchemaKind::String,
description: None,
required: false,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
})),
enum_values: Vec::new(),
variants: Vec::new(),
};
let value = serde_json::to_value(schema).unwrap();
assert_eq!(value["type"], "array");
assert_eq!(value["items"]["type"], "string");
}
#[test]
fn schema_roundtrips_through_yaml() {
let schema = Schema {
kind: SchemaKind::Object,
description: Some("Lead output".to_owned()),
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::from([(
"id".to_owned(),
Schema {
kind: SchemaKind::String,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
},
)]),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
};
let yaml = serde_yaml::to_string(&schema).unwrap();
let restored: Schema = serde_yaml::from_str(&yaml).unwrap();
assert!(yaml.contains("type: object"));
assert_eq!(restored, schema);
}
}
pub use error::SchemaError;
pub use model::{Schema, SchemaKind};
crates/mcpaas-schema/src/model.rs
+178
View File
@@ -0,0 +1,178 @@
use std::collections::BTreeMap;
use serde::{Deserialize, Serialize};
use serde_json::Value;
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SchemaKind {
Object,
Array,
String,
Integer,
Number,
Boolean,
Enum,
#[serde(rename = "null")]
Null,
Oneof,
}
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
pub struct Schema {
#[serde(rename = "type")]
pub kind: SchemaKind,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub description: Option<String>,
#[serde(default)]
pub required: bool,
#[serde(default)]
pub nullable: bool,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub default_value: Option<Value>,
#[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
pub fields: BTreeMap<String, Schema>,
#[serde(default, skip_serializing_if = "Option::is_none")]
pub items: Option<Box<Schema>>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub enum_values: Vec<String>,
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub variants: Vec<Schema>,
}
impl Schema {
pub fn is_object(&self) -> bool {
self.kind == SchemaKind::Object
}
pub fn field(&self, name: &str) -> Option<&Schema> {
self.fields.get(name)
}
pub fn has_required_fields(&self) -> bool {
self.fields.values().any(|field| field.required)
}
pub fn expected_type_name(&self) -> &'static str {
match self.kind {
SchemaKind::Object => "object",
SchemaKind::Array => "array",
SchemaKind::String => "string",
SchemaKind::Integer => "integer",
SchemaKind::Number => "number",
SchemaKind::Boolean => "boolean",
SchemaKind::Enum => "enum",
SchemaKind::Null => "null",
SchemaKind::Oneof => "oneof",
}
}
}
#[cfg(test)]
mod tests {
use std::collections::BTreeMap;
use super::{Schema, SchemaKind};
#[test]
fn object_schema_exposes_fields() {
let mut fields = BTreeMap::new();
fields.insert(
"email".to_owned(),
Schema {
kind: SchemaKind::String,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
},
);
let schema = Schema {
kind: SchemaKind::Object,
description: Some("User input".to_owned()),
required: true,
nullable: false,
default_value: None,
fields,
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
};
assert!(schema.is_object());
assert!(schema.has_required_fields());
assert_eq!(
schema.field("email").map(|field| field.required),
Some(true)
);
}
#[test]
fn schema_serializes_type_field() {
let schema = Schema {
kind: SchemaKind::Array,
description: None,
required: false,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: Some(Box::new(Schema {
kind: SchemaKind::String,
description: None,
required: false,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
})),
enum_values: Vec::new(),
variants: Vec::new(),
};
let value = serde_json::to_value(schema).unwrap();
assert_eq!(value["type"], "array");
assert_eq!(value["items"]["type"], "string");
}
#[test]
fn schema_roundtrips_through_yaml() {
let schema = Schema {
kind: SchemaKind::Object,
description: Some("Lead output".to_owned()),
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::from([(
"id".to_owned(),
Schema {
kind: SchemaKind::String,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
},
)]),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
};
let yaml = serde_yaml::to_string(&schema).unwrap();
let restored: Schema = serde_yaml::from_str(&yaml).unwrap();
assert!(yaml.contains("type: object"));
assert_eq!(restored, schema);
}
}
crates/mcpaas-schema/src/normalize.rs
+163
View File
@@ -0,0 +1,163 @@
use std::collections::BTreeMap;
use serde_json::{Map, Value};
use crate::{Schema, SchemaKind};
impl Schema {
pub fn from_json_sample(value: &Value) -> Self {
match value {
Value::Null => Self {
kind: SchemaKind::Null,
description: None,
required: true,
nullable: true,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
},
Value::Bool(_) => scalar_schema(SchemaKind::Boolean),
Value::String(_) => scalar_schema(SchemaKind::String),
Value::Number(number) if number.is_i64() || number.is_u64() => {
scalar_schema(SchemaKind::Integer)
}
Value::Number(_) => scalar_schema(SchemaKind::Number),
Value::Array(items) => array_schema(items),
Value::Object(fields) => object_schema(fields),
}
}
}
fn scalar_schema(kind: SchemaKind) -> Schema {
Schema {
kind,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
}
}
fn array_schema(items: &[Value]) -> Schema {
Schema {
kind: SchemaKind::Array,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: items
.first()
.map(|item| Box::new(Schema::from_json_sample(item))),
enum_values: Vec::new(),
variants: Vec::new(),
}
}
fn object_schema(fields: &Map<String, Value>) -> Schema {
Schema {
kind: SchemaKind::Object,
description: None,
required: true,
nullable: false,
default_value: None,
fields: fields
.iter()
.map(|(name, value)| (name.clone(), Schema::from_json_sample(value)))
.collect(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
}
}
#[cfg(test)]
mod tests {
use std::collections::BTreeMap;
use serde_json::json;
use crate::{Schema, SchemaKind};
#[test]
fn infers_object_schema_from_json_sample() {
let schema = Schema::from_json_sample(&json!({
"lead": {
"email": "user@example.com",
"active": true
},
"score": 42
}));
assert_eq!(schema.kind, SchemaKind::Object);
assert_eq!(
schema.field("lead").map(|field| field.kind.clone()),
Some(SchemaKind::Object)
);
assert_eq!(
schema
.field("lead")
.and_then(|field| field.field("email"))
.map(|field| field.kind.clone()),
Some(SchemaKind::String)
);
assert_eq!(
schema.field("score").map(|field| field.kind.clone()),
Some(SchemaKind::Integer)
);
}
#[test]
fn infers_array_item_schema_from_first_sample_item() {
let schema = Schema::from_json_sample(&json!([
{
"id": "lead_01",
"tags": ["warm", "priority"]
}
]));
assert_eq!(schema.kind, SchemaKind::Array);
assert_eq!(
schema
.items
.as_deref()
.and_then(|item| item.field("id"))
.map(|field| field.kind.clone()),
Some(SchemaKind::String)
);
assert_eq!(
schema
.items
.as_deref()
.and_then(|item| item.field("tags"))
.map(|field| field.kind.clone()),
Some(SchemaKind::Array)
);
}
#[test]
fn infers_null_schema_for_null_sample() {
let schema = Schema::from_json_sample(&serde_json::Value::Null);
assert_eq!(
schema,
Schema {
kind: SchemaKind::Null,
description: None,
required: true,
nullable: true,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
}
);
}
}
crates/mcpaas-schema/src/validate.rs
+260
View File
@@ -0,0 +1,260 @@
use serde_json::Value;
use crate::{Schema, SchemaError, SchemaKind};
impl Schema {
pub fn validate_shape(&self, value: &Value) -> Result<(), SchemaError> {
validate_value(self, value, "$")
}
}
fn validate_value(schema: &Schema, value: &Value, path: &str) -> Result<(), SchemaError> {
if value.is_null() {
if schema.nullable || schema.kind == SchemaKind::Null {
return Ok(());
}
return Err(SchemaError::invalid_type(
path,
schema.expected_type_name(),
"null",
));
}
match schema.kind {
SchemaKind::Object => validate_object(schema, value, path),
SchemaKind::Array => validate_array(schema, value, path),
SchemaKind::String => validate_scalar(schema, value, path, Value::is_string),
SchemaKind::Integer => validate_scalar(schema, value, path, Value::is_i64_or_u64),
SchemaKind::Number => validate_scalar(schema, value, path, Value::is_number),
SchemaKind::Boolean => validate_scalar(schema, value, path, Value::is_boolean),
SchemaKind::Enum => validate_enum(schema, value, path),
SchemaKind::Null => Err(SchemaError::invalid_type(
path,
"null",
actual_type_name(value),
)),
SchemaKind::Oneof => validate_oneof(schema, value, path),
}
}
fn validate_object(schema: &Schema, value: &Value, path: &str) -> Result<(), SchemaError> {
let Some(object) = value.as_object() else {
return Err(SchemaError::invalid_type(
path,
"object",
actual_type_name(value),
));
};
for (field_name, field_schema) in &schema.fields {
let field_path = format!("{path}.{field_name}");
match object.get(field_name) {
Some(field_value) => validate_value(field_schema, field_value, &field_path)?,
None if field_schema.required => return Err(SchemaError::missing_field(field_path)),
None => {}
}
}
Ok(())
}
fn validate_array(schema: &Schema, value: &Value, path: &str) -> Result<(), SchemaError> {
let Some(items) = value.as_array() else {
return Err(SchemaError::invalid_type(
path,
"array",
actual_type_name(value),
));
};
if let Some(item_schema) = schema.items.as_deref() {
for (index, item) in items.iter().enumerate() {
let item_path = format!("{path}[{index}]");
validate_value(item_schema, item, &item_path)?;
}
}
Ok(())
}
fn validate_scalar(
schema: &Schema,
value: &Value,
path: &str,
is_valid: impl Fn(&Value) -> bool,
) -> Result<(), SchemaError> {
if is_valid(value) {
return Ok(());
}
Err(SchemaError::invalid_type(
path,
schema.expected_type_name(),
actual_type_name(value),
))
}
fn validate_enum(schema: &Schema, value: &Value, path: &str) -> Result<(), SchemaError> {
let Some(actual) = value.as_str() else {
return Err(SchemaError::invalid_type(
path,
"enum",
actual_type_name(value),
));
};
if schema.enum_values.iter().any(|expected| expected == actual) {
return Ok(());
}
Err(SchemaError::invalid_enum_value(
path,
schema.enum_values.clone(),
actual,
))
}
fn validate_oneof(schema: &Schema, value: &Value, path: &str) -> Result<(), SchemaError> {
if schema
.variants
.iter()
.any(|variant| validate_value(variant, value, path).is_ok())
{
return Ok(());
}
Err(SchemaError::oneof_mismatch(path))
}
fn actual_type_name(value: &Value) -> &'static str {
match value {
Value::Null => "null",
Value::Bool(_) => "boolean",
Value::Number(number) if number.is_i64() || number.is_u64() => "integer",
Value::Number(_) => "number",
Value::String(_) => "string",
Value::Array(_) => "array",
Value::Object(_) => "object",
}
}
trait JsonValueExt {
fn is_i64_or_u64(&self) -> bool;
}
impl JsonValueExt for Value {
fn is_i64_or_u64(&self) -> bool {
self.as_i64().is_some() || self.as_u64().is_some()
}
}
#[cfg(test)]
mod tests {
use std::collections::BTreeMap;
use serde_json::json;
use crate::{Schema, SchemaError, SchemaKind};
#[test]
fn validates_nested_object_shape() {
let schema = Schema {
kind: SchemaKind::Object,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::from([(
"lead".to_owned(),
Schema {
kind: SchemaKind::Object,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::from([(
"email".to_owned(),
Schema {
kind: SchemaKind::String,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
},
)]),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
},
)]),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
};
let result = schema.validate_shape(&json!({
"lead": {
"email": "user@example.com"
}
}));
assert!(result.is_ok());
}
#[test]
fn rejects_missing_required_field() {
let schema = Schema {
kind: SchemaKind::Object,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::from([(
"email".to_owned(),
Schema {
kind: SchemaKind::String,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
},
)]),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
};
let error = schema.validate_shape(&json!({})).unwrap_err();
assert_eq!(error, SchemaError::missing_field("$.email"));
}
#[test]
fn rejects_invalid_scalar_type() {
let schema = Schema {
kind: SchemaKind::Boolean,
description: None,
required: true,
nullable: false,
default_value: None,
fields: BTreeMap::new(),
items: None,
enum_values: Vec::new(),
variants: Vec::new(),
};
let error = schema.validate_shape(&json!("true")).unwrap_err();
assert_eq!(error, SchemaError::invalid_type("$", "boolean", "string"));
}
}