Clarify how setExtension and getExtension work with Schema properties

[Azquelt]

Schema extends Extensible which suggests that extension properties should start with x-.

However, schemas actually permit properties with any name and has set and get methods to allow this.

We should clarify which arbitrary properties of a schema are considered extensions.

[Azquelt]

If we decide to allow getExtension and setExtension to manage any unknown properties, we should maybe redeclare those methods on Schema and/or extend the wording in Extensible to indicate that some model objects may have different rules for extension names.

[MikeEdgar]

Some thoughts -

• When a schema has no $schema or the value is https://spec.openapis.org/oas/3.1/dialect/base, any property not defined in 2020-12 JSON Schema or the additional fixed properties defined by OAS are considered extensions when reading annotations, loading from a static file, or when set on in the Schema model from user code. An exception would be if a property is set by user code using addExtension or setExtensions.
• $schema values of https://json-schema.org/draft/2020-12/schema is similar to above. I wonder if technically this dialect excludes the OAS fixed fields for schemas, discriminator, xml, externalDocs, and example.
• For any other value of $schema nothing is considered to be an extension unless explicitly set by user code using addExtension or setExtensions.

The above would require Schema implementations to have knowledge of the properties allowed for the supported dialects and may need to react to a modification of the $schema value that results in some properties either becoming extensions, or no longer being extensions. This part may be complex, but I'm raising it in case there is any value.

I think the above is sufficiently more complex than what is defined in the Extensible JavaDocs and would probably be better documented directly in Schema on overridden methods.

[Azquelt]

Discussed this yesterday and came up with a few other options:

1. Make Schema not extend Extensible. "Extensions" aren't really a thing for schemas since JSON schema allows arbitrary properties which we support via get() and set()
2. Specify that the extensions methods as dealing with any property which is not part of the default dialect. This might be the closest to the OpenAPI spec which says schemas can be extended and additional properties may omit the x- prefix.
   • getExtensions would return all fields which are not part of the standard dialect
   • setExtensions would replace all fields which are not part of the standard dialect
   • would need to decide how to handle setExtension or getExtension being called for a field which is part of the standard dialect
   • implies that users should not use Extensible methods when using a custom dialect. Even if the custom dialect merely extends the standard one, any additional keywords in the custom dialect would be considered extensions by these methods.

It's worth noting that we don't currently define how the methods on Schema work for a custom schema dialect. I think in smallrye they will always get or set the field from the default vocabulary, regardless of the schema dialect configured.

[Azquelt]

Discussed on the call today. We think we should broadly go with Option 2 above.

• any fields which are not part of the standard dialect are considered extensions
• calling setExtensions(emptyMap()) would remove all properties not part of the standard dialect
• leave the behaviour of calling setExtension and getExtension with a name which is part of the standard dialect undefined for now
• override the Extensible methods on Schema to document how they behave
• add a caveat to Extensible javadoc that some parts may be different for some subclasses
  • in particular, the x- requirement does not apply to Schema