diff --git a/api/pom.xml b/api/pom.xml
index 763f5643..96fb2132 100644
--- a/api/pom.xml
+++ b/api/pom.xml
@@ -33,6 +33,12 @@
osgi.annotationprovided
+
+ biz.aQute.bnd
+ biz.aQute.bnd.annotation
+ 7.0.0
+ provided
+
diff --git a/api/src/main/java/module-info.java b/api/src/main/java/module-info.java
index cf6617b9..3ce0a2c6 100644
--- a/api/src/main/java/module-info.java
+++ b/api/src/main/java/module-info.java
@@ -52,5 +52,5 @@
// Required for compilation, not used at runtime
requires static osgi.annotation;
-
+ requires static biz.aQute.bnd.annotation;
}
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java
index 90da485d..88589af0 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/Extensible.java
@@ -23,19 +23,24 @@
* The base interface for OpenAPI model objects that can contain extensions. Extensions contain data not required by the
* specification and may or may not be supported by the tools you use.
*
- * The extensions property names are always prefixed by "x-".
+ * The extension's property names are always prefixed by "x-" unless otherwise specified by sub-interfaces or Extensible
+ * methods overridden therein. Sub-interfaces may also include additional detail regarding the handling of extension
+ * properties and how they relate to other well-known properties of the interface.
+ *
+ * For example, {@link org.eclipse.microprofile.openapi.models.media.Schema Schema} defines such handling and relaxes
+ * the requirement that extension properties are prefixed by "x-".
*/
public interface Extensible> {
/**
- * Returns the extensions property from an Extensible instance.
+ * Returns the map of all extension properties from an Extensible instance.
*
* @return a map containing keys which start with "x-" and values which provide additional information
**/
Map getExtensions();
/**
- * Sets this Extensible's extensions property to the given map of extensions.
+ * Sets this Extensible's extension properties to the given map of extensions.
*
* @param extensions
* map containing keys which start with "x-" and values which provide additional information
@@ -49,7 +54,7 @@ default T extensions(Map extensions) {
}
/**
- * Adds the given object to this Extensible's map of extensions, with the given name as its key.
+ * Adds the given extension property to this Extensible, with the given name as its key.
*
* @param name
* the key used to access the extension object. Always prefixed by "x-".
@@ -61,7 +66,7 @@ default T extensions(Map extensions) {
T addExtension(String name, Object value);
/**
- * Removes the given object to this Extensible's map of extensions, with the given name as its key.
+ * Removes an extension with the given property name from this Extensible.
*
* @param name
* the key used to access the extension object. Always prefixed by "x-".
@@ -69,7 +74,7 @@ default T extensions(Map extensions) {
void removeExtension(String name);
/**
- * Sets this Extensible's extensions property to the given map of extensions.
+ * Sets this Extensible's extension properties to the given map of extensions.
*
* @param extensions
* map containing keys which start with "x-" and values which provide additional information
@@ -77,7 +82,7 @@ default T extensions(Map extensions) {
void setExtensions(Map extensions);
/**
- * Checks whether an extension with the given name is present in this Extensible's map of extensions.
+ * Checks whether an extension with the given name is present in this Extensible.
*
* @param name
* the key used to access the extension object. Always prefixed by "x-".
@@ -93,7 +98,7 @@ default boolean hasExtension(String name) {
}
/**
- * Returns the extension object with the given name from this Extensible's map of extensions.
+ * Returns the object with the given name from this Extensible's extensions.
*
* @param name
* the key used to access the extension object. Always prefixed by "x-".
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java
index ed8daad1..1a6f6a06 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/models/media/Schema.java
@@ -39,6 +39,13 @@
* Any time a Schema Object can be used, a Reference Object can be used in its place. This allows referencing an
* existing definition instead of defining the same Schema again.
*
+ *
Extensions
Although Schema is {@link Extensible}, the behavior of extensions is only
+ * defined for the OAS schema dialect identified by URI {@code https://spec.openapis.org/oas/3.1/dialect/base} (the
+ * default if not specified). For this dialect, Schema instances will consider all unknown properties to be extensions.
+ *
+ * The behavior is undefined when adding an extension via one of the methods of the {@link Extensible} interface when
+ * the name of the extension matches the name of a standard OAS schema property.
+ *
* @see OpenAPI Specification Schema Object
*/
public interface Schema extends Extensible, Constructible, Reference {
@@ -2060,6 +2067,9 @@ default Schema examples(List