fix: Align schema compatibility with JSON Schema semantics

- compare const, enum, and numeric constraints by accepted values
- handle exact mixed numeric equality and signed-zero bounds
- apply the validator's default dialect to unevaluated properties

Author: aviator5

Cargo.lock

@@ -183,6 +183,8 @@ chrono = "0.4"
 
 # JSON Schema validation
 jsonschema = { version = "0.40", default-features = false }
+# Exact comparison between differently typed numbers, as used by `jsonschema`.
+num-cmp = "0.1"
 
 # JSON Schema generation
 schemars = { version = "1.2", features = ["uuid1"] }

Cargo.toml

@@ -1587,6 +1587,15 @@ pub fn struct_to_gts_schema(attr: TokenStream, item: TokenStream) -> TokenStream
     //   `properties` declared in the same schema object, so closing a branch
     //   would reject the properties its sibling branches declare. Schemars
     //   already closes the branches of an externally tagged enum itself.
+    // * a `definitions` entry a combinator branch resolves to, because such an
+    //   entry *is* the branch and closing it would reject the sibling branches'
+    //   properties just the same. Reachability is computed first, over both the
+    //   property subschemas and `definitions` itself, and is followed through
+    //   chains of aliasing definitions (a top-level `$ref`). The granularity is
+    //   the whole entry, so a definition used both as a combinator branch and as
+    //   an ordinary property schema stays open everywhere: keeping the
+    //   composition satisfiable wins over closing the ordinary use, which merely
+    //   forfeits in-place evolution for that one level.
     // * the generic extension field, which this macro replaces with a bare
     //   `{"type": "object"}` before this pass runs and which sec 4.4.1 requires
     //   to stay open so derived types can extend it.
@@ -1616,6 +1625,82 @@ pub fn struct_to_gts_schema(attr: TokenStream, item: TokenStream) -> TokenStream
             ];
             const SCHEMA_LIST: &[&str] = &["allOf", "anyOf", "oneOf", "prefixItems"];
 
+            fn local_definition_name(reference: &str) -> Option<String> {
+                reference
+                    .strip_prefix("#/definitions/")
+                    .or_else(|| reference.strip_prefix("#/$defs/"))
+                    .and_then(|name| name.split('/').next())
+                    .map(|name| name.replace("~1", "/").replace("~0", "~"))
+            }
+
+            fn collect_combinator_definition_refs(
+                value: &serde_json::Value,
+                is_combinator_branch: bool,
+                referenced: &mut ::std::collections::HashSet<String>,
+            ) {
+                let Some(object) = value.as_object() else {
+                    return;
+                };
+
+                if is_combinator_branch
+                    && let Some(name) = object
+                        .get("$ref")
+                        .and_then(serde_json::Value::as_str)
+                        .and_then(local_definition_name)
+                {
+                    referenced.insert(name);
+                }
+
+                for (keyword, nested) in object {
+                    let branch = COMBINATORS.contains(&keyword.as_str());
+                    if SINGLE_SCHEMA.contains(&keyword.as_str()) {
+                        collect_combinator_definition_refs(nested, branch, referenced);
+                    } else if SCHEMA_MAP.contains(&keyword.as_str()) {
+                        collect_combinator_definition_refs_map(nested, branch, referenced);
+                    } else if SCHEMA_LIST.contains(&keyword.as_str()) {
+                        collect_combinator_definition_refs_list(nested, branch, referenced);
+                    } else if keyword == "items" {
+                        if nested.is_array() {
+                            collect_combinator_definition_refs_list(nested, branch, referenced);
+                        } else {
+                            collect_combinator_definition_refs(nested, branch, referenced);
+                        }
+                    }
+                }
+            }
+
+            fn collect_combinator_definition_refs_map(
+                value: &serde_json::Value,
+                is_combinator_branch: bool,
+                referenced: &mut ::std::collections::HashSet<String>,
+            ) {
+                if let Some(object) = value.as_object() {
+                    for nested in object.values() {
+                        collect_combinator_definition_refs(
+                            nested,
+                            is_combinator_branch,
+                            referenced,
+                        );
+                    }
+                }
+            }
+
+            fn collect_combinator_definition_refs_list(
+                value: &serde_json::Value,
+                is_combinator_branch: bool,
+                referenced: &mut ::std::collections::HashSet<String>,
+            ) {
+                if let Some(values) = value.as_array() {
+                    for nested in values {
+                        collect_combinator_definition_refs(
+                            nested,
+                            is_combinator_branch,
+                            referenced,
+                        );
+                    }
+                }
+            }
+
             fn close_schema(value: &mut serde_json::Value, is_combinator_branch: bool) {
                 let Some(object) = value.as_object_mut() else {
                     return;
@@ -1674,9 +1759,51 @@ pub fn struct_to_gts_schema(attr: TokenStream, item: TokenStream) -> TokenStream
                 }
             }
 
+            let mut combinator_definitions = ::std::collections::HashSet::new();
+            collect_combinator_definition_refs_map(
+                &properties,
+                false,
+                &mut combinator_definitions,
+            );
+            if let Some(definitions) = definitions.as_ref() {
+                collect_combinator_definition_refs_map(
+                    definitions,
+                    false,
+                    &mut combinator_definitions,
+                );
+            }
+
+            // A definition whose top level is a bare `$ref` only aliases another
+            // one - Schemars emits that for a newtype struct carrying no doc
+            // comment - so the alias target is what actually contributes the
+            // branch's content model and has to stay open as well. Chase the
+            // alias chain to a fixed point; a name is enqueued only when it was
+            // newly inserted, so the walk terminates even on a `$ref` cycle.
+            let mut alias_queue: Vec<String> =
+                combinator_definitions.iter().cloned().collect();
+            while let Some(name) = alias_queue.pop() {
+                let alias = definitions
+                    .as_ref()
+                    .and_then(serde_json::Value::as_object)
+                    .and_then(|object| object.get(&name))
+                    .and_then(|definition| definition.get("$ref"))
+                    .and_then(serde_json::Value::as_str)
+                    .and_then(local_definition_name);
+                if let Some(alias) = alias
+                    && combinator_definitions.insert(alias.clone())
+                {
+                    alias_queue.push(alias);
+                }
+            }
+
             close_schema_map(&mut properties, false);
-            if let Some(definitions) = definitions.as_mut() {
-                close_schema_map(definitions, false);
+            if let Some(definitions_object) = definitions
+                .as_mut()
+                .and_then(serde_json::Value::as_object_mut)
+            {
+                for (name, definition) in definitions_object {
+                    close_schema(definition, combinator_definitions.contains(name));
+                }
             }
         }
     };

gts-dylint/Cargo.lock

@@ -97,6 +97,95 @@ pub struct SchemaWithNestedContactV1 {
     pub contact: NestedContact,
 }
 
+fn composed_contact_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
+    let contact = generator.subschema_for::<NestedContact>();
+    serde_json::from_value(serde_json::json!({
+        "allOf": [
+            contact,
+            {
+                "type": "object",
+                "properties": {
+                    "label": {"type": "string"}
+                },
+                "required": ["label"]
+            }
+        ]
+    }))
+    .expect("test schema")
+}
+
+#[struct_to_gts_schema(
+    dir_path = "schemas",
+    base = true,
+    type_id = gts_id!("x.test.nested.composed_definition.v1~"),
+    description = "Schema composing a definition with sibling properties",
+    properties = "schema_type,composed"
+)]
+#[derive(Debug)]
+pub struct SchemaWithComposedDefinitionV1 {
+    #[serde(rename = "type")]
+    pub schema_type: GtsTypeId,
+    #[schemars(schema_with = "composed_contact_schema")]
+    pub composed: serde_json::Value,
+}
+
+// Newtype structs without a doc comment: Schemars emits each definition as a
+// bare `{"$ref": ...}` alias, so the combinator branch only reaches
+// `NestedContact` through two hops of aliasing.
+#[derive(Debug, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
+pub struct ContactAlias(pub NestedContact);
+
+#[derive(Debug, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
+pub struct ContactAliasAlias(pub ContactAlias);
+
+fn composed_alias_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
+    let alias = generator.subschema_for::<ContactAliasAlias>();
+    serde_json::from_value(serde_json::json!({
+        "allOf": [
+            alias,
+            {
+                "type": "object",
+                "properties": {
+                    "label": {"type": "string"}
+                },
+                "required": ["label"]
+            }
+        ]
+    }))
+    .expect("test schema")
+}
+
+#[struct_to_gts_schema(
+    dir_path = "schemas",
+    base = true,
+    type_id = gts_id!("x.test.nested.aliased_definition.v1~"),
+    description = "Schema composing an aliased definition with sibling properties",
+    properties = "schema_type,composed"
+)]
+#[derive(Debug)]
+pub struct SchemaWithAliasedDefinitionV1 {
+    #[serde(rename = "type")]
+    pub schema_type: GtsTypeId,
+    #[schemars(schema_with = "composed_alias_schema")]
+    pub composed: serde_json::Value,
+}
+
+#[struct_to_gts_schema(
+    dir_path = "schemas",
+    base = true,
+    type_id = gts_id!("x.test.nested.shared_definition.v1~"),
+    description = "Schema using one definition as a combinator branch and as a property",
+    properties = "schema_type,composed,plain"
+)]
+#[derive(Debug)]
+pub struct SchemaWithSharedDefinitionV1 {
+    #[serde(rename = "type")]
+    pub schema_type: GtsTypeId,
+    #[schemars(schema_with = "composed_contact_schema")]
+    pub composed: serde_json::Value,
+    pub plain: NestedContact,
+}
+
 #[derive(Debug, serde::Serialize, serde::Deserialize, schemars::JsonSchema)]
 #[schemars(extend("additionalProperties" = true))]
 pub struct OpenExtensionPoint {
@@ -466,6 +555,107 @@ mod tests {
         jsonschema::validator_for(&schema).expect("emitted Draft-07 schema must compile");
     }
 
+    #[test]
+    fn test_definition_referenced_by_combinator_branch_stays_open() {
+        let schema = SchemaWithComposedDefinitionV1::gts_schema_with_refs();
+        assert_eq!(
+            schema.pointer("/properties/composed/allOf/0/$ref"),
+            Some(&serde_json::json!("#/definitions/NestedContact"))
+        );
+        assert!(
+            schema
+                .pointer("/definitions/NestedContact/additionalProperties")
+                .is_none(),
+            "a definition composed with sibling properties must stay open:\n{}",
+            serde_json::to_string_pretty(&schema).unwrap()
+        );
+
+        let validator =
+            jsonschema::validator_for(&schema).expect("emitted Draft-07 schema must compile");
+        let instance = serde_json::json!({
+            "type": "gts.x.test.nested.composed_definition.v1~",
+            "composed": {
+                "email": "dev@example.com",
+                "label": "primary"
+            }
+        });
+        assert!(
+            validator.is_valid(&instance),
+            "combinator siblings should not be rejected by a closed definition"
+        );
+    }
+
+    /// The branch may reach its definition through a chain of aliasing
+    /// definitions, which Schemars emits for newtype structs.
+    #[test]
+    fn test_definition_aliased_by_combinator_branch_stays_open() {
+        let schema = SchemaWithAliasedDefinitionV1::gts_schema_with_refs();
+        assert_eq!(
+            schema.pointer("/definitions/ContactAlias/$ref"),
+            Some(&serde_json::json!("#/definitions/NestedContact")),
+            "test relies on Schemars emitting a bare $ref alias:\n{}",
+            serde_json::to_string_pretty(&schema).unwrap()
+        );
+        assert!(
+            schema
+                .pointer("/definitions/NestedContact/additionalProperties")
+                .is_none(),
+            "a definition an alias chain composes with sibling properties must stay open:\n{}",
+            serde_json::to_string_pretty(&schema).unwrap()
+        );
+
+        let validator =
+            jsonschema::validator_for(&schema).expect("emitted Draft-07 schema must compile");
+        let instance = serde_json::json!({
+            "type": "gts.x.test.nested.aliased_definition.v1~",
+            "composed": {
+                "email": "dev@example.com",
+                "label": "primary"
+            }
+        });
+        assert!(
+            validator.is_valid(&instance),
+            "combinator siblings should not be rejected through an alias chain"
+        );
+    }
+
+    /// Reachability is tracked per `definitions` entry, not per use site, so one
+    /// composed use keeps the entry open for its ordinary uses too. That trades
+    /// the in-place evolvability of the ordinary level for a satisfiable
+    /// composition - see the pass documentation in `gts-macros/src/lib.rs`.
+    #[test]
+    fn test_shared_definition_stays_open_for_its_ordinary_use() {
+        let schema = SchemaWithSharedDefinitionV1::gts_schema_with_refs();
+        assert_eq!(
+            schema.pointer("/properties/plain/$ref"),
+            Some(&serde_json::json!("#/definitions/NestedContact"))
+        );
+        assert!(
+            schema
+                .pointer("/definitions/NestedContact/additionalProperties")
+                .is_none(),
+            "a definition shared with a combinator branch must stay open:\n{}",
+            serde_json::to_string_pretty(&schema).unwrap()
+        );
+
+        let validator =
+            jsonschema::validator_for(&schema).expect("emitted Draft-07 schema must compile");
+        let instance = serde_json::json!({
+            "type": "gts.x.test.nested.shared_definition.v1~",
+            "composed": {
+                "email": "dev@example.com",
+                "label": "primary"
+            },
+            "plain": {
+                "email": "ops@example.com"
+            }
+        });
+        assert!(
+            validator.is_valid(&instance),
+            "both uses of the shared definition must still accept valid instances"
+        );
+    }
+
     /// Nested object levels are closed so that a later definition of the type
     /// can add an optional property backward compatibly (gts-spec sec 4.4-4.5),
     /// while the levels where closing would be wrong are left alone.

gts-macros/src/lib.rs

@@ -21,6 +21,7 @@ serde.workspace = true
 serde_json.workspace = true
 thiserror.workspace = true
 jsonschema.workspace = true
+num-cmp.workspace = true
 schemars.workspace = true
 walkdir.workspace = true
 tracing.workspace = true