Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

fix(openai): harden strict schema normalization

AkitaOnRails1e7f10d0f881
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8e8584fa..4bbc7374 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -9,6 +9,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
### Fixed
- Filesystem watcher now reindexes a project when backends report only a
parent-directory event, improving external editor capture on macOS/FSEvents.
+- OpenAI strict structured-output schema normalization now strips generated
+ `$ref` annotation siblings and rewrites generated enum `oneOf` schemas to
+ `anyOf`, unblocking `memory_consolidate multi_page=true` on OpenAI models.
## [0.2.0] - 2026-05-26
### Added
diff --git a/crates/ai-memory-llm/src/openai.rs b/crates/ai-memory-llm/src/openai.rs
index 0b180ce5..8b4048a6 100644
--- a/crates/ai-memory-llm/src/openai.rs
+++ b/crates/ai-memory-llm/src/openai.rs
@@ -346,29 +346,24 @@ impl OpenAiProvider {
fn enforce_strict_object_schemas(value: &mut serde_json::Value) {
match value {
serde_json::Value::Object(map) => {
- // OpenAI's structured-output validator rejects any sibling
- // keyword next to `$ref` with a 400 (per JSON Schema 2020-12
- // §8.2.3.1, $ref siblings are ignored during validation —
- // OpenAI hardens that into a hard error). schemars 1.x emits
- // a field-level `description` next to `$ref` for every
- // doc-commented field typed as an external enum (e.g.
- // `tier: Tier` on `ConsolidatedPageUpdate`); without this
- // strip, `memory_consolidate multi_page=true` 400s on every
- // call. Dropping the siblings is semantically a no-op —
- // only the documentation-only annotation is lost; the
- // type's own description on the referenced `$defs` entry
- // is what reaches the model.
+ // OpenAI's structured-output subset rejects any sibling
+ // keyword next to `$ref` with a 400. schemars 1.x emits a
+ // field-level `description` next to `$ref` for doc-commented
+ // fields typed as external enums (e.g. `tier: Tier` on
+ // `ConsolidatedPageUpdate`); without this strip,
+ // `memory_consolidate multi_page=true` fails before the model
+ // runs. In our generated schemas those siblings are
+ // annotations, not validation constraints, so the referenced
+ // definition remains the source of truth.
if map.contains_key("$ref") {
map.retain(|k, _| k == "$ref");
return;
}
// OpenAI strict mode rejects `oneOf` outright but accepts
- // `anyOf`. schemars 1.x emits `oneOf` for every Rust enum
- // with tagged variants (closed sets where exactly one
- // branch matches), e.g. `Tier` and `PageKind` under `$defs`
- // in `ConsolidatedBatch`. For non-overlapping branches the
- // rewrite is semantically lossless and unblocks every
- // structured-output call that touches an enum.
+ // `anyOf`. schemars 1.x emits `oneOf` for closed Rust enums
+ // such as `Tier` and `PageKind` under `$defs` in
+ // `ConsolidatedBatch`; their const branches are disjoint, so
+ // the rewrite preserves the generated schema's accepted set.
if let Some(one_of) = map.remove("oneOf") {
map.insert("anyOf".to_string(), one_of);
}
@@ -466,7 +461,9 @@ mod tests {
model_requires_max_completion_tokens, normalize_openai_base,
};
use crate::types::{ChatMessage, ChatRequest, Role};
+ use schemars::JsonSchema;
use secrecy::SecretString;
+ use serde::{Deserialize, Serialize};
use serde_json::json;
fn provider_for(model: &str) -> OpenAiProvider {
@@ -574,11 +571,8 @@ mod tests {
// doc-commented field is typed as an external enum (e.g.
// `tier: Tier` in `ConsolidatedPageUpdate`). Without this
// strip, `memory_consolidate multi_page=true` 400s on every
- // call against gpt-4o-mini. JSON Schema 2020-12 §8.2.3.1 says
- // siblings of `$ref` are ignored during validation, so
- // dropping them is semantically a no-op — only the
- // documentation-only field-level description is lost (the
- // type's own description on the referenced definition stays).
+ // call against gpt-4o-mini. In our generated schemas those
+ // siblings are annotations, not validation constraints.
let mut schema = json!({
"type": "object",
"properties": {
@@ -634,11 +628,37 @@ mod tests {
assert_eq!(any_of.as_array().unwrap().len(), 2);
}
+ #[test]
+ fn enforce_strict_normalizes_schemars_enum_refs() {
+ #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+ struct Fixture {
+ /// Doc-commented enum field, matching the schemars shape that
+ /// triggered OpenAI's `$ref` sibling rejection.
+ tier: FixtureTier,
+ /// Array of the same enum, covering `$ref` under `items`.
+ tiers: Vec<FixtureTier>,
+ }
+
+ #[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
+ #[serde(rename_all = "snake_case")]
+ enum FixtureTier {
+ Working,
+ Episodic,
+ }
+
+ let mut schema = serde_json::to_value(schemars::schema_for!(Fixture)).unwrap();
+ enforce_strict_object_schemas(&mut schema);
+
+ assert_no_one_of(&schema);
+ assert_no_ref_siblings(&schema);
+ assert_eq!(schema["additionalProperties"], json!(false));
+ }
+
#[test]
fn enforce_strict_strips_ref_siblings_inside_array_items() {
- // The same JSON-Schema-2020-12 rule applies anywhere $ref
- // appears, not just on direct object properties — schemars
- // emits it inside `items` for `Vec<EnumType>` too.
+ // OpenAI applies the same `$ref` sibling restriction anywhere a
+ // ref appears, not just on direct object properties. schemars
+ // emits this shape inside `items` for `Vec<EnumType>` too.
let mut schema = json!({
"type": "array",
"items": {
@@ -652,6 +672,42 @@ mod tests {
assert!(items.get("description").is_none());
}
+ fn assert_no_one_of(value: &serde_json::Value) {
+ match value {
+ serde_json::Value::Object(map) => {
+ assert!(map.get("oneOf").is_none(), "oneOf remains in {value}");
+ for child in map.values() {
+ assert_no_one_of(child);
+ }
+ }
+ serde_json::Value::Array(items) => {
+ for child in items {
+ assert_no_one_of(child);
+ }
+ }
+ _ => {}
+ }
+ }
+
+ fn assert_no_ref_siblings(value: &serde_json::Value) {
+ match value {
+ serde_json::Value::Object(map) => {
+ if map.contains_key("$ref") {
+ assert_eq!(map.len(), 1, "$ref has siblings in {value}");
+ }
+ for child in map.values() {
+ assert_no_ref_siblings(child);
+ }
+ }
+ serde_json::Value::Array(items) => {
+ for child in items {
+ assert_no_ref_siblings(child);
+ }
+ }
+ _ => {}
+ }
+ }
+
#[test]
fn enforce_strict_overwrites_caller_additional_properties_true() {
// OpenAI strict mode requires `additionalProperties: false` on
diff --git a/docs/deploy.md b/docs/deploy.md
index 3fd8cda7..12b5b708 100644
--- a/docs/deploy.md
+++ b/docs/deploy.md
@@ -152,9 +152,11 @@ alternatives:
> reasoning off.
ai-memory's consolidator uses OpenAI's `json_schema` strict mode for
-structured output. Most modern models honour this, but if you switch
-to a niche local model, run a quick `ai-memory llm-test` (with a
-structured prompt) before trusting it.
+structured output. The OpenAI provider normalizes schemars output into
+OpenAI's supported subset (`additionalProperties: false`, complete
+`required`, generated enum `anyOf`, and plain `$ref` nodes). Most modern
+models honour this, but if you switch to a niche local model, run a quick
+`ai-memory llm-test` (with a structured prompt) before trusting it.
## Backups