Merge pull request #43 from p1c2u/feature/exitend-readme-about-openapi-31-schema-support

Extend readme for OpenAPI 3.1 support

Author: p1c2u

README.rst

@@ -42,7 +42,9 @@ Alternatively you can download the code and install from the repository:
 Usage
 #####
 
-Simple usage
+By default, the latest OpenAPI schema syntax is expected.
+
+To validate an OpenAPI v3.1 schema:
 
 .. code-block:: python
 
@@ -59,28 +61,77 @@ Simple usage
                "type": "string"
            },
            "age": {
-               "type": "integer",
+               "type": ["integer", "null"],
                "format": "int32",
                "minimum": 0,
-               "nullable": True,
            },
            "birth-date": {
                "type": "string",
                "format": "date",
-           }
+           },
+           "address": {
+                "type": 'array',
+                "prefixItems": [
+                    { "type": "number" },
+                    { "type": "string" },
+                    { "enum": ["Street", "Avenue", "Boulevard"] },
+                    { "enum": ["NW", "NE", "SW", "SE"] }
+                ],
+                "items": False,
+            }
        },
        "additionalProperties": False,
    }
 
    # If no exception is raised by validate(), the instance is valid.
-   validate({"name": "John", "age": 23}, schema)
+   validate({"name": "John", "age": 23, "address": [1600, "Pennsylvania", "Avenue"]}, schema)
 
    validate({"name": "John", "city": "London"}, schema)
 
    Traceback (most recent call last):
        ...
    ValidationError: Additional properties are not allowed ('city' was unexpected)
 
+if you want to disambiguate the expected schema version, import and use ``OAS31Validator``:
+
+.. code-block:: python
+
+   from openapi_schema_validator import OAS31Validator
+
+   validate({"name": "John", "age": 23}, schema, cls=OAS31Validator)
+
+In order to validate OpenAPI 3.0 schema, import and use ``OAS30Validator`` instead of ``OAS31Validator``.
+
+.. code-block:: python
+
+   from openapi_schema_validator import OAS30Validator
+
+   # A sample schema
+   schema = {
+       "type": "object",
+       "required": [
+          "name"
+       ],
+       "properties": {
+           "name": {
+               "type": "string"
+           },
+           "age": {
+               "type": "integer",
+               "format": "int32",
+               "minimum": 0,
+               "nullable": True,
+           },
+           "birth-date": {
+               "type": "string",
+               "format": "date",
+           }
+       },
+       "additionalProperties": False,
+   }
+
+   validate({"name": "John", "age": 23}, schema, cls=OAS30Validator)
+
 Format check
 ************
 

tests/integration/test_validators.py

@@ -582,3 +582,52 @@ def test_schema_ref(self):
 
         error = "'id' is a required property"
         assert error in str(excinfo.value)
+
+    @pytest.mark.parametrize('value', [
+        [1600, "Pennsylvania", "Avenue", "NW"],
+        [1600, "Pennsylvania", "Avenue"],
+    ])
+    def test_array_prefixitems(self, value):
+        schema = {
+            "type": 'array',
+            "prefixItems": [
+                { "type": "number" },
+                { "type": "string" },
+                { "enum": ["Street", "Avenue", "Boulevard"] },
+                { "enum": ["NW", "NE", "SW", "SE"] }
+            ],
+            "items": False,
+        }
+        validator = OAS31Validator(
+            schema,
+            format_checker=oas31_format_checker,
+        )
+
+        result = validator.validate(value)
+
+        assert result is None
+
+    @pytest.mark.parametrize('value', [
+        [1600, "Pennsylvania", "Avenue", "NW", "Washington"],
+    ])
+    def test_array_prefixitems_invalid(self, value):
+        schema = {
+            "type": 'array',
+            "prefixItems": [
+                { "type": "number" },
+                { "type": "string" },
+                { "enum": ["Street", "Avenue", "Boulevard"] },
+                { "enum": ["NW", "NE", "SW", "SE"] }
+            ],
+            "items": False,
+        }
+        validator = OAS31Validator(
+            schema,
+            format_checker=oas31_format_checker,
+        )
+
+        with pytest.raises(ValidationError) as excinfo:
+            validator.validate(value)
+
+        error = "Expected at most 4 items, but found 5"
+        assert error in str(excinfo.value)