feat: schema prefixItems support (#226)

Author: JMLX42

crates/oas3/src/spec/schema.rs

@@ -165,12 +165,26 @@ pub struct ObjectSchema {
     ///
     /// Omitting this keyword has the same assertion behavior as an empty schema.
     ///
+    /// This keyword can be either:
+    /// - A boolean value: `false` means no additional items allowed, `true` means any additional items allowed
+    /// - A schema object: validates all additional items against this schema
+    ///
     /// See <https://json-schema.org/draft/2020-12/json-schema-core#name-items>.
     #[serde(skip_serializing_if = "Option::is_none")]
-    pub items: Option<Box<ObjectOrReference<ObjectSchema>>>,
+    pub items: Option<Box<Schema>>,
+
+    /// Validation succeeds if each element of the instance validates against the
+    /// schema at the same position, if any.
+    ///
+    /// This keyword does not constrain the length of the array.
+    /// If the array is longer than this keyword's value,
+    /// this keyword validates only the prefix of matching length.
+    ///
+    /// See <https://json-schema.org/draft/2020-12/json-schema-core#name-prefixitems>.
+    #[serde(rename = "prefixItems", default, skip_serializing_if = "Vec::is_empty")]
+    pub prefix_items: Vec<ObjectOrReference<ObjectSchema>>,
 
     // TODO: missing fields
-    // - prefixItems
     // - contains
 
     // #########################################################################
@@ -657,4 +671,179 @@ mod tests {
         assert!(schema.discriminator.is_some());
         assert_eq!(2, schema.discriminator.unwrap().mapping.unwrap().len());
     }
+
+    #[test]
+    fn prefix_items_basic() {
+        let spec = indoc::indoc! {"
+          type: array
+          prefixItems:
+            - type: string
+            - $ref: '#/components/schemas/Age'
+            - type: integer
+        "};
+        let schema = serde_yaml::from_str::<ObjectSchema>(spec).unwrap();
+
+        assert_eq!(schema.prefix_items.len(), 3);
+
+        // Check first schema (inline)
+        if let ObjectOrReference::Object(first_schema) = &schema.prefix_items[0] {
+            assert_eq!(
+                first_schema.schema_type,
+                Some(TypeSet::Single(Type::String))
+            );
+        } else {
+            panic!("Expected inline schema for first prefixItems element");
+        }
+
+        // Check second schema (reference)
+        if let ObjectOrReference::Ref { ref_path } = &schema.prefix_items[1] {
+            assert_eq!(ref_path, "#/components/schemas/Age");
+        } else {
+            panic!("Expected reference for second prefixItems element");
+        }
+
+        // Check third schema (inline)
+        if let ObjectOrReference::Object(third_schema) = &schema.prefix_items[2] {
+            assert_eq!(
+                third_schema.schema_type,
+                Some(TypeSet::Single(Type::Integer))
+            );
+        } else {
+            panic!("Expected inline schema for third prefixItems element");
+        }
+    }
+
+    #[test]
+    fn prefix_items_with_items() {
+        let spec = indoc::indoc! {"
+          type: array
+          prefixItems:
+            - type: string
+          items:
+            type: number
+        "};
+        let schema = serde_yaml::from_str::<ObjectSchema>(spec).unwrap();
+
+        assert_eq!(schema.prefix_items.len(), 1);
+        assert!(schema.items.is_some());
+
+        // Check prefixItems
+        if let ObjectOrReference::Object(prefix_schema) = &schema.prefix_items[0] {
+            assert_eq!(
+                prefix_schema.schema_type,
+                Some(TypeSet::Single(Type::String))
+            );
+        } else {
+            panic!("Expected inline schema for prefixItems element");
+        }
+
+        // Check items
+        if let Some(items_box) = &schema.items {
+            if let Schema::Object(obj_ref) = items_box.as_ref() {
+                if let ObjectOrReference::Object(items_schema) = obj_ref.as_ref() {
+                    assert_eq!(
+                        items_schema.schema_type,
+                        Some(TypeSet::Single(Type::Number))
+                    );
+                } else {
+                    panic!("Expected inline schema for items");
+                }
+            } else {
+                panic!("Expected object schema for items");
+            }
+        } else {
+            panic!("Expected items to be present");
+        }
+    }
+
+    #[test]
+    fn prefix_items_empty() {
+        let spec = indoc::indoc! {"
+          type: array
+          prefixItems: []
+        "};
+        let schema = serde_yaml::from_str::<ObjectSchema>(spec).unwrap();
+
+        assert_eq!(schema.prefix_items.len(), 0);
+    }
+
+    #[test]
+    fn prefix_items_serialization_round_trip() {
+        let spec = indoc::indoc! {"
+          type: array
+          prefixItems:
+            - type: string
+              minLength: 5
+            - type: integer
+              minimum: 0
+          items:
+            type: boolean
+        "};
+
+        // Deserialize from YAML
+        let original = serde_yaml::from_str::<ObjectSchema>(spec).unwrap();
+
+        // Serialize to YAML
+        let serialized = serde_yaml::to_string(&original).unwrap();
+
+        // Deserialize back
+        let round_tripped = serde_yaml::from_str::<ObjectSchema>(&serialized).unwrap();
+
+        // Compare structures (not YAML strings)
+        assert_eq!(original, round_tripped);
+    }
+
+    #[test]
+    fn items_object_schema_still_works() {
+        let spec = indoc::indoc! {"
+          type: array
+          items:
+            type: string
+            minLength: 5
+        "};
+        let schema = serde_yaml::from_str::<ObjectSchema>(spec).unwrap();
+
+        assert!(schema.items.is_some());
+
+        if let Some(items) = &schema.items {
+            match items.as_ref() {
+                Schema::Object(obj_ref) => {
+                    if let ObjectOrReference::Object(items_schema) = obj_ref.as_ref() {
+                        assert_eq!(
+                            items_schema.schema_type,
+                            Some(TypeSet::Single(Type::String))
+                        );
+                        assert_eq!(items_schema.min_length, Some(5));
+                    } else {
+                        panic!("Expected inline schema");
+                    }
+                }
+                _ => panic!("Expected object schema for items"),
+            }
+        } else {
+            panic!("Expected items to be present");
+        }
+    }
+
+    #[test]
+    fn items_boolean_serialization_round_trip() {
+        let spec = indoc::indoc! {"
+          type: array
+          prefixItems:
+            - type: string
+          items: false
+        "};
+
+        // Deserialize from YAML
+        let original = serde_yaml::from_str::<ObjectSchema>(spec).unwrap();
+
+        // Serialize to YAML
+        let serialized = serde_yaml::to_string(&original).unwrap();
+
+        // Deserialize back
+        let round_tripped = serde_yaml::from_str::<ObjectSchema>(&serialized).unwrap();
+
+        // Compare structures (not YAML strings)
+        assert_eq!(original, round_tripped);
+    }
 }

crates/roast/src/validation/validator.rs

@@ -84,10 +84,22 @@ impl ValidationTree {
                 trace!("adding array validators");
 
                 if let Some(schema_ref) = schema.items.as_ref() {
-                    let sub_schema = schema_ref.resolve(spec).unwrap();
-                    let vls = ValidationTree::from_schema(&sub_schema, spec).unwrap();
-
-                    valtree.branch = ValidationBranch::Array(Box::new(vls))
+                    match schema_ref.as_ref() {
+                        oas3::spec::Schema::Boolean(oas3::spec::BooleanSchema(false)) => {
+                            // items: false means no additional items allowed
+                            // For now, we treat this as having no array validation
+                            // TODO: A more complete implementation would validate array length against prefixItems
+                        }
+                        oas3::spec::Schema::Boolean(oas3::spec::BooleanSchema(true)) => {
+                            // items: true means any additional items allowed
+                            // No additional validation needed
+                        }
+                        oas3::spec::Schema::Object(obj_ref) => {
+                            let sub_schema = obj_ref.resolve(spec).unwrap();
+                            let vls = ValidationTree::from_schema(&sub_schema, spec).unwrap();
+                            valtree.branch = ValidationBranch::Array(Box::new(vls))
+                        }
+                    }
                 }
             }
 

integration-tests/samples/pass/schema_prefix_items.yaml

@@ -0,0 +1,113 @@
+openapi: 3.1.0
+info:
+  title: prefixItems Test API
+  version: 1.0.0
+paths: {}
+components:
+  schemas:
+    PersonTuple:
+      type: array
+      description: A tuple representing [firstName, lastName, age]
+      prefixItems:
+        - type: string
+          description: First name
+          minLength: 1
+        - type: string
+          description: Last name
+          minLength: 1
+        - type: integer
+          description: Age
+          minimum: 0
+          maximum: 150
+      minItems: 3
+      maxItems: 3
+
+    ExtendableTuple:
+      type: array
+      description: A tuple with fixed prefix and flexible additional items
+      prefixItems:
+        - type: string
+          enum: ["header", "body", "footer"]
+        - type: integer
+      items:
+        type: string
+        description: Additional string items allowed after the prefix
+
+    ComplexTuple:
+      type: array
+      description: A tuple using component references
+      prefixItems:
+        - $ref: '#/components/schemas/Header'
+        - $ref: '#/components/schemas/Payload'
+        - type: object
+          properties:
+            checksum:
+              type: string
+              pattern: '^[a-f0-9]{64}$'
+          required: [checksum]
+      items: false
+
+    EmptyPrefixArray:
+      type: array
+      prefixItems: []
+      items:
+        type: number
+      description: Array with empty prefixItems - all items follow the items schema
+
+    ValidatedTuple:
+      type: array
+      prefixItems:
+        - type: string
+          pattern: '^[A-Z]{2}$'
+          description: Two-letter country code
+        - type: number
+          multipleOf: 0.01
+          description: Price with cents
+        - type: boolean
+          description: Is available
+      items:
+        type: object
+        additionalProperties: true
+        description: Additional metadata objects
+
+    Header:
+      type: object
+      properties:
+        version:
+          type: string
+          pattern: '^\d+\.\d+\.\d+$'
+        timestamp:
+          type: integer
+          description: Unix timestamp
+      required: [version, timestamp]
+
+    Payload:
+      type: object
+      properties:
+        data:
+          type: string
+        encoding:
+          type: string
+          enum: ["utf-8", "base64", "hex"]
+      required: [data, encoding]
+
+    # Test boolean items schemas
+    BooleanItemsFalse:
+      type: array
+      description: Array that allows no items (empty array only)
+      items: false
+      
+    BooleanItemsTrue:
+      type: array
+      description: Array that allows any items
+      items: true
+      
+    MixedBooleanItems:
+      type: array
+      description: Tuple with fixed prefix and no additional items
+      prefixItems:
+        - type: string
+          enum: ["v1", "v2", "v3"]
+        - type: number
+          minimum: 0
+      items: false

integration-tests/src/samples.rs

@@ -74,6 +74,12 @@ mod tests {
         validate_sample(input, Format::Yaml);
     }
 
+    #[test]
+    fn test_schema_prefix_items_yaml() {
+        let input = include_str!("../samples/pass/schema_prefix_items.yaml");
+        validate_sample(input, Format::Yaml);
+    }
+
     /// Describes the format of the text input.
     enum Format {
         Json,