OpenAPI/JsonSchema - use unevaluatedProperties instead of additionalProperties and support setting to false

[Christopher Radek (chrisradek)]

Related to #3549

This PR does a couple things:

Json Schema and Open API 3.1 use unevaluatedProperties instead of additionalProperties

unevaluatedProperties is similar to additionalProperties in that it can specify what extra properties are allowed on an object. One key difference from additionalProperties though is that it evaluates properties after any in-place applicators. Practically speaking, this means that it will take into account any properties defined in allOf subschemas when validating an object instance, whereas additionalProperties only takes into account properties defined in its containing schema.

This is particularly useful when trying to set additionalProperties to false on a schema that has sub-schemas.

Risks

Functionally, I don't believe this is a breaking change. Where this might cause problems though is if someone is doing their own processing of the Json Schema or Open API 3.1 output to add additionalProperties: false if that field isn't present, since those would now be called unevaluatedProperties.

Open API 3 - support Record<never> for additionalProperties: { not: {} }

This change brings the Open API 3 (3.0 and 3.1) emitter in line with the Json Schema emitter, which already supports treating Record<never> as additionalProperties: { not: {} }. { not: {} } is equivalent to the boolean false for schemas, so this is the same as supporting additionalProperties: false.

Note: For Open API 3.1 output, unevaluatedProperties is emitted instead of additionalProperties.

For Open API 3.0 output that still relies on additionalProperties, there's some additional handling of model extends so that any properties that exist on a base model, but not the derived model, are redeclared as propertyName: {} in the derived model. Without this, if the base model contains any properties that aren't in the derived model, and the derived model spreads Record<never>, that emitted schema will never pass validation on an input.

Example

model Widget {
  id: string;
  ...Record<never>;
}

{
  "type": "object",
  "required": [ "id" ],
  "properties": { "id": { "type": "string" } },
  "unevaluatedProperties": { "not": {} }
}

Followups

A separate PR will be created to add an emitter option to JsonSchema/OpenAPI emitters to automatically set additionalProperties: { not: {} } on at least leaf schemas.

[Azure SDK Bot (azure-sdk)]

All changed packages have been documented.

• ✅ @typespec/json-schema
• ✅ @typespec/openapi3

Show changes

@typespec/json-schema - feature ✏️

Updates JsonSchema and Open API 3.1 emitters to use unevaluatedProperties instead of additionalProperties, and updates Open API 3 emitters to match JsonSchema behavior of treating Record<never> as setting additionalProperties: { not: {} }

@typespec/openapi3 - feature ✏️

Updates JsonSchema and Open API 3.1 emitters to use unevaluatedProperties instead of additionalProperties, and updates Open API 3 emitters to match JsonSchema behavior of treating Record<never> as setting additionalProperties: { not: {} }

[Azure SDK Bot (azure-sdk)]

You can try these changes here

🛝 Playground	🌐 Website	📚 Next docs	🛝 VSCode Extension