Schema issues in documentation examples about openapi-specification

[handrews]

The whole "JSON Schema v5" thing was a bit of a misunderstanding- that draft is mostly just draft-04 tidied up. the uriref/uri-ref format was something that slipped in but was never implemented because there's no way to detect "draft-05" as distinct from draft-04. In draft-06 (we gave up and skipped 5 because of the confusion) we added it properly as uri-reference.

On the plus side (sort-of), unrecognized format values are ignored so it's mostly harmless. But it should match the spec.

---

I'd advise against "additionalProperties": false

[zx80]

But it should match the spec.

I know that v5 was a kind-of a misunderstanding, but anyway spec examples should really match the spec that they were created to illustrate…

I'd advise against "additionalProperties": false

This one is just a suggestion. However, why not? ISTM that most of the time people should use that instead of the default, so it would not be that bad if a few examples in the documentation do that.

[handrews]

However, why not?

Mostly, because it's something of a footgun and makes your schemas difficult if not impossible to re-use. Which, particularly when using a pet example (implicitly referencing the inheritance in the petstore example) is best avoided.

The re-use problems were mostly solved in OAS 3.1 / draft 2020-12 with unevaluatedProperties, and I really don't want to generate an endless stream of complaints about additionalProperties here from people who copy the example and then try to extend it.

ISTM that most of the time people should use that instead of the default

This impression is common among users of strictly typed languages and uncommon among users of dynamically typed languages.

[zx80]

The re-use problems were mostly solved in OAS 3.1 / draft 2020-12 with unevaluatedProperties, and I really don't want to generate an endless stream of complaints about additionalProperties here from people who copy the example and then try to extend it.

Then would it be possible to add unevaluatedProperty in some example, if it does (more or less) solve the re-use (inheritance) issue?

ISTM that most of the time people should use that instead of the default

This impression is common among users of strictly typed languages and uncommon among users of dynamically typed languages.

I do not buy this usual argument in full: if a dynamic person actually bothers to declare a schema, i.e. a type, I do not understand why they would stop midstream: they get all of the pain with only part of the benefit.