additionalProperties controls whether an OpenAPI object schema accepts properties that are not explicitly declared. Setting it to false makes the response contract reject undocumented fields, while allowing such fields makes the contract more permissive. section 7.2.1 section 10.2.4
Use the keyword to make API behavior observable and reviewable:
- Set additionalProperties:false when every returned field should be documented and unexpected response data should fail validation. section 7.2.1 section 10.2.4
- Validate the deployed response with an OpenAPI-aware test or gateway check; failures identify fields outside the declared schema. section 7.2.1
- Balance strictness against evolution: false rejects newly added server fields until the API definition is updated, and its interaction with allOf or anyOf is limited. section 10.2.4
Detecting undocumented product fields
An end-to-end GET request validates a product response against product-catalog-v1-0.oas.yaml. The test fails because the API returns numberOfReviews and reviewRating while additionalProperties is false. Pointing the validator at product-catalog-v1-1.oas.yaml, which declares those fields, makes the test pass. section 7.2.1
Listing 7.1 End-to-end schema test
public class EndToEndSchemaTest {
private final OpenApiValidationFilter validationFilter = new
OpenApiValidationFilter(“../product-catalog-v1-0.oas.yaml");
@Test
public void testGetProductEndToEnd() {
given() #1
.header("X-API-Key", "my_secret_api_key") #2
.filter(validationFilter) #3
.when()
.get("http://localhost:8000/v1/catalog/products
/612b4280-b5c0-4ad5-bce7-ede7ab2b90fc") #4
.then()
.assertThat()
.statusCode(200); #5
}
}
Shows the Rest Assured workflow: supply an API key, attach OpenApiValidationFilter, call the product endpoint, and assert status 200. section 7.2.1
