Repository: eclipse/microprofile-open-api
Pull request #131 (2017-12-07 19:25:09)

Added testing for additional methods not covered by generalized tests.
Signed-off-by: Michael Glavassevich <mrglavas@ca.ibm.com>


Patch:
diff --git a/api/pom.xml b/api/pom.xml
index 505aa8a..39baf04 100644
--- a/api/pom.xml
+++ b/api/pom.xml
@@ -87,24 +87,4 @@
             </plugin>
         </plugins>
     </build>
-    <profiles>
-        <profile>
-            <id>eclipse-jarsigner</id>
-            <build>
-                <plugins>
-                    <plugin>
-                        <groupId>org.eclipse.cbi.maven.plugins</groupId>
-                        <artifactId>eclipse-jarsigner-plugin</artifactId>
-                        <executions>
-                            <execution>
-                                <goals>
-                                    <goal>sign</goal>
-                                </goals>
-                            </execution>
-                        </executions>
-                    </plugin>
-                </plugins>
-            </build>
-        </profile>
-    </profiles>
 </project>
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java
index 7fb4676..7cfbc7a 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/Operation.java
@@ -23,6 +23,13 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
+import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
+import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
+import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
+import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
+import org.eclipse.microprofile.openapi.annotations.servers.Server;
+
 /**
  * Describes a single API operation on a path.
  * 
@@ -33,6 +40,21 @@ import java.lang.annotation.Target;
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 public @interface Operation {
+    /**
+     * The HTTP method for this operation.
+     *
+     * @return the HTTP method of this operation
+     **/
+    String method() default "";
+
+    /**
+     * A list of tags for API documentation control.
+     * <p>
+     * Tags can be used for logical grouping of operations by resources or any other qualifier.
+     * </p>
+     * @return the list of tags associated with this operation
+     **/
+    String[] tags() default {};
 
     /**
      * Provides a brief description of what this operation does.
@@ -49,6 +71,13 @@ public @interface Operation {
      **/
     String description() default "";
 
+    /**
+     * Additional external documentation for this operation.
+     *
+     * @return external documentation associated with this operation instance
+     **/
+    ExternalDocumentation externalDocs() default @ExternalDocumentation();
+
     /**
      * Unique string used to identify the operation. 
      * The id MUST be unique among all operations described in the API.
@@ -60,6 +89,33 @@ public @interface Operation {
      **/
     String operationId() default "";
 
+    /**
+     * An array of parameters applicable for this operation, 
+     * which will be added to any automatically detected parameters in the method itself.
+     * <p>
+     * The list MUST NOT include duplicated parameters. 
+     * A unique parameter is defined by a combination of a name and location.
+     * </p>
+     * @return the list of parameters for this operation
+     **/
+    Parameter[] parameters() default {};
+
+    /**
+     * The request body applicable for this operation.
+     *
+     * @return the request body of this operation
+     **/
+    RequestBody requestBody() default @RequestBody();
+
+    /**
+     * This is a REQUIRED property of an operation instance.
+     * <p>
+     * The list of possible responses as they are returned from executing this operation.
+     * </p>
+     * @return the list of responses for this operation
+     **/
+    APIResponse[] responses() default {};
+
     /**
      * Allows an operation to be marked as deprecated. 
      * Alternatively use the @Deprecated annotation.
@@ -70,6 +126,34 @@ public @interface Operation {
      **/
     boolean deprecated() default false;
 
+    /**
+     * A declaration of which security mechanisms can be used for this operation.
+     * Only one of the security requirement objects need to be satisfied to authorize a request. 
+     * <p>
+     * This definition overrides any declared top-level security. 
+     * To remove a top-level security declaration, an empty array can be used.
+     * </p>
+     * @return the list of security mechanisms for this operation
+     */
+    SecurityRequirement[] security() default {};
+
+    /**
+     * An alternative server array to service this operation.
+     * <p>
+     * If an alternative server object is specified at the Path Item Object or Root level, 
+     * it will be overridden by this value.
+     * </p>
+     * @return the list of servers hosting this operation
+     **/
+    Server[] servers() default {};
+
+    /**
+     * The list of optional extensions.
+     *
+     * @return an optional array of extensions
+     */
+    Extension[] extensions() default {};
+
     /**
      * Allows this operation to be marked as hidden
      * 
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java
index 6f55698..2eddca7 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/Callback.java
@@ -24,6 +24,8 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.RetentionPolicy;
 import java.lang.annotation.Target;
 
+import org.eclipse.microprofile.openapi.annotations.Operation;
+
 /**
  * This object represents a callback URL that will be invoked.
  * 
@@ -60,7 +62,7 @@ public @interface Callback {
      * 
      * @return the callback operations
      **/
-    CallbackOperation[] operations() default {};
+    Operation[] operation() default {};
 
     /**
      * Reference value to a Callback object.
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java
deleted file mode 100644
index ce68e92..0000000
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/callbacks/CallbackOperation.java
+++ /dev/null
@@ -1,114 +0,0 @@
-/**
- * Copyright (c) 2017 Contributors to the Eclipse Foundation
- * Copyright 2017 SmartBear Software
- * <p>
- * Licensed under the Apache License, Version 2.0 (the "License");
- * you may not use this file except in compliance with the License.
- * You may obtain a copy of the License at
- * <p>
- * http://www.apache.org/licenses/LICENSE-2.0
- * <p>
- * Unless required by applicable law or agreed to in writing, software
- * distributed under the License is distributed on an "AS IS" BASIS,
- * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
- * See the License for the specific language governing permissions and
- * limitations under the License.
- */
-
-package org.eclipse.microprofile.openapi.annotations.callbacks;
-
-import java.lang.annotation.Inherited;
-import java.lang.annotation.Retention;
-import java.lang.annotation.RetentionPolicy;
-import java.lang.annotation.Target;
-
-import org.eclipse.microprofile.openapi.annotations.ExternalDocumentation;
-import org.eclipse.microprofile.openapi.annotations.extensions.Extension;
-import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
-import org.eclipse.microprofile.openapi.annotations.parameters.RequestBody;
-import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
-import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
-
-/**
- * Describes a single API callback operation.
- * 
- * @see <a href= "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#operationObject">OpenAPI Specification Operation
- *      Object</a>
- **/
-@Target({ })
-@Retention(RetentionPolicy.RUNTIME)
-@Inherited
-public @interface CallbackOperation {
-    /**
-     * The HTTP method for this callback operation.
-     *
-     * @return the HTTP method of this callback operation
-     **/
-    String method() default "";
-
-    /**
-     * Provides a brief description of what this callback operation does.
-     *
-     * @return a summary of this callback operation
-     **/
-    String summary() default "";
-
-    /**
-     * A verbose description of the callback operation behavior.
-     * CommonMark syntax MAY be used for rich text representation.
-     *
-     * @return a description of this callback operation
-     **/
-    String description() default "";
-
-    /**
-     * Additional external documentation for this callback operation.
-     *
-     * @return external documentation associated with this callback operation instance
-     **/
-    ExternalDocumentation externalDocs() default @ExternalDocumentation();
-
-    /**
-     * An array of parameters applicable for this callback operation, 
-     * which will be added to any automatically detected parameters in the method itself.
-     * <p>
-     * The list MUST NOT include duplicated parameters. 
-     * A unique parameter is defined by a combination of a name and location.
-     * </p>
-     * @return the list of parameters for this callback operation
-     **/
-    Parameter[] parameters() default {};
-
-    /**
-     * The request body applicable for this callback operation.
-     *
-     * @return the request body of this callback operation
-     **/
-    RequestBody requestBody() default @RequestBody();
-
-    /**
-     * This is a REQUIRED property of an callback operation instance.
-     * <p>
-     * The list of possible responses as they are returned from executing this callback operation.
-     * </p>
-     * @return the list of responses for this callback operation
-     **/
-    APIResponse[] responses() default {};
-
-    /**
-     * A declaration of which security mechanisms can be used for this callback operation.
-     * Only one of the security requirement objects need to be satisfied to authorize a request. 
-     * <p>
-     * This definition overrides any declared top-level security. 
-     * To remove a top-level security declaration, an empty array can be used.
-     * @return the list of security mechanisms for this callback operation
-     */
-    SecurityRequirement[] security() default {};
-
-    /**
-     * The list of optional extensions.
-     *
-     * @return an optional array of extensions
-     */
-    Extension[] extensions() default {};
-}
\ No newline at end of file
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java
index 35c7e24..ca4c27e 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/parameters/RequestBody.java
@@ -30,7 +30,7 @@ import org.eclipse.microprofile.openapi.annotations.media.Content;
  * 
  * @see <a href="https://github.com/OAI/OpenAPI-Specification/blob/3.0.0-rc2/versions/3.0.md#requestBodyObject">requestBody Object</a>
  **/
-@Target({ ElementType.PARAMETER, ElementType.METHOD })
+@Target({ ElementType.PARAMETER })
 @Retention(RetentionPolicy.RUNTIME)
 @Inherited
 public @interface RequestBody {
@@ -59,10 +59,9 @@ public @interface RequestBody {
     boolean required() default false;
 
     /**
-     * The unique name to identify this request body. Unless this annotation is used on the actual request body parameter,
-     * it is required to match the name of that parameter so the appropriate association can be made.  When the request body
-     * is defined within {@link org.eclipse.microprofile.openapi.annotations.Components}. The name will be used as the key to 
-     * add this request body to the 'requestBodies' map for reuse.
+     * The unique name to identify this request body. Only REQUIRED when the request body is defined
+     * within {@link org.eclipse.microprofile.openapi.annotations.Components}. The name will be 
+     * used as the key to add this request body to the 'requestBodies' map for reuse.
      * 
      * @return this request body's name
      **/
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java
index 5b33c10..068a43a 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tag.java
@@ -30,7 +30,7 @@ import org.eclipse.microprofile.openapi.annotations.ExternalDocumentation;
  * This object represents a tag. A tag is meta-information you can use to help
  * organize your API endpoints and it can appear in two contexts.
  * <p>
- * Define tag objects on a method that implements an operation or on a class that
+ * Define tag objects on a method that implements an operation or on a type that
  * contains operations. They will be gathered and stored in the root object of
  * the OpenAPI document.
  * <p>
@@ -38,16 +38,18 @@ import org.eclipse.microprofile.openapi.annotations.ExternalDocumentation;
  * operation then the tag name will be added to the OpenAPI document and also be
  * added to the operation tags (see @Operation).
  * <p>
- * Reference to a Tag can be created by setting the 'ref' attribute.
+ * If more than one tag is defined with the same name then only one tag with that name
+ * will appear in the OpenAPI document. 
  * <p>
- * This annotation is {@link java.lang.annotation.Repeatable Repeatable}.
+ * If more than one tag is defined with the same name and only one tag contains a 
+ * description that is a non-empty string then that description will be preserved in 
+ * the OpenAPI document. If more than one non-empty description is specified the results 
+ * are implementation dependent. 
  * <p>
- * If more than one tag is defined with the same name then only one tag with that name will appear 
- * in the OpenAPI document and the results are implementation dependent. 
- * <p>
- * <b>Note:</b> If both {@link org.eclipse.microprofile.openapi.annotations.tags.Tag Tag} and 
- * {@link org.eclipse.microprofile.openapi.annotations.tags.Tags Tags} annotations are specified on the same method or class,
- * then both tag definitions should be applied.
+ * If more than one tag is defined with the same name and only one tag contains an
+ * external documentation that is defined with at least one non-empty string then that 
+ * external documentation will be preserved in the OpenAPI document. If more than one 
+ * non-empty external documentation is specified the results are implementation dependent. 
  * <pre>
  * &#64;Tag(name = "luggage", description = "Operations related to luggage handling.")
  * &#64;GET
@@ -79,8 +81,7 @@ import org.eclipse.microprofile.openapi.annotations.ExternalDocumentation;
 public @interface Tag {
 
     /**
-     * The name of this tag. The name must be unique and is case sensitive. 
-     * It is a REQUIRED property unless this is only a reference to a tag instance.
+     * The name of this tag. It is a REQUIRED property unless this is only a reference to a tag instance.
      *
      * @return the name of this tag
      */
diff --git a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java
index 9703f1a..1e830ac 100644
--- a/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java
+++ b/api/src/main/java/org/eclipse/microprofile/openapi/annotations/tags/Tags.java
@@ -26,10 +26,7 @@ import java.lang.annotation.Target;
 /**
  * The Tags annotation is a container for @Tag annotations. When used on a method or a type
  * it is treated as if each tag annotation were applied individually.
- * <p>
- * <b>Note:</b> If both {@link org.eclipse.microprofile.openapi.annotations.tags.Tag Tag} and 
- * {@link org.eclipse.microprofile.openapi.annotations.tags.Tags Tags} annotations are specified on the same method/class,
- * then both tag definitions should be applied to method/class.
+ * 
  * @see <a href= "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#tagObject">OpenAPI Specification Tag Object</a>
  *
  */
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 ae3ba4e..7859930 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
@@ -35,7 +35,7 @@ import org.eclipse.microprofile.openapi.models.Reference;
  * definitions follow the JSON Schema.
  * <p>
  * 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.
+ * defining the same schema again.
  * 
  * @see <a href= "https://github.com/OAI/OpenAPI-Specification/blob/master/versions/3.0.0.md#schemaObject">OpenAPI Specification Schema Object</a>
  */
@@ -62,21 +62,21 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
    }
 
     /**
-     * Returns the discriminator property from this Schema instance.
+     * Returns the discriminator property from this schema instance.
      *
      * @return the discriminator that is used to differentiate between the schemas which may satisfy the payload description
      **/
     Discriminator getDiscriminator();
 
     /**
-     * Sets the discriminator property of this Schema instance to the given object.
+     * Sets the discriminator property of this schema instance to the given object.
      *
      * @param discriminator the object that is used to differentiate between the schemas which may satisfy the payload description
      */
     void setDiscriminator(Discriminator discriminator);
 
     /**
-     * Sets the discriminator property of this Schema instance to the given object.
+     * Sets the discriminator property of this schema instance to the given object.
      *
      * @param discriminator the object that is used to differentiate between the schemas which may satisfy the payload description
      * @return the current Schema instance
@@ -84,43 +84,43 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Schema discriminator(Discriminator discriminator);
 
     /**
-     * Returns the title property from this Schema instance.
+     * Returns the title property from this schema instance.
      *
-     * @return the title assigned to this Schema
+     * @return the title assigned to this schema
      **/
     String getTitle();
 
     /**
-     * Sets the title property of this Schema instance to the given string.
+     * Sets the title property of this schema instance to the given string.
      *
-     * @param title a title to assign to this Schema
+     * @param title a title to assign to this schema
      */
     void setTitle(String title);
 
     /**
-     * Sets the title property of this Schema instance to the given string.
+     * Sets the title property of this schema instance to the given string.
      *
-     * @param title a title to assign to this Schema
+     * @param title a title to assign to this schema
      * @return the current Schema instance
      */
     Schema title(String title);
 
     /**
-     * Returns the default value property from this Schema instance.
+     * Returns the default value property from this schema instance.
      *
      * @return the default value object
      **/
     Object getDefaultValue();
 
     /**
-     * Set the default value property of this Schema instance to the value given.
+     * Set the default value property of this schema instance to the value given.
      *
      * @param defaultValue a value to use as the default
      */
     void setDefaultValue(Object defaultValue);
 
     /**
-     * Set the default value property of this Schema instance to the value given.
+     * Set the default value property of this schema instance to the value given.
      *
      * @param defaultValue a value to use as the default
      * @return the current Schema instance
@@ -128,14 +128,14 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Schema defaultValue(Object defaultValue);
 
     /**
-     * Returns the enumerated list of values allowed for objects defined by this Schema.
+     * Returns the enumerated list of values allowed for objects defined by this schema.
      *
-     * @return the list of values allowed for objects defined by this Schema
+     * @return the list of values allowed for objects defined by this schema
      */
     List<Object> getEnumeration();
 
     /**
-     * Sets the enumerated list of values allowed for objects defined by this Schema.
+     * Sets the enumerated list of values allowed for objects defined by this schema.
      *
      * @param enumeration a list of values allowed
      */
@@ -147,12 +147,12 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
      * Adds an item of the appropriate type to the enumerated list of values allowed.
      *
      * @param enumeration an object to add to the enumerated values
-     * @return current Schema instance
+     * @return current schema instance
      */
     Schema addEnumeration(Object enumeration);
 
     /**
-     * Returns the multipleOf property from this Schema instance.
+     * Returns the multipleOf property from this schema instance.
      * <p>
      * minimum: 0
      *
@@ -161,110 +161,110 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     BigDecimal getMultipleOf();
 
     /**
-     * Sets the multipleOf property of this Schema instance to the value given.
+     * Sets the multipleOf property of this schema instance to the value given.
      *
-     * @param multipleOf a positive number that restricts the value of objects described by this Schema
+     * @param multipleOf a positive number that restricts the value of objects described by this schema
      */
     void setMultipleOf(BigDecimal multipleOf);
 
     /**
-     * Sets the multipleOf property of this Schema instance to the value given.
+     * Sets the multipleOf property of this schema instance to the value given.
      *
-     * @param multipleOf a positive number that restricts the value of objects described by this Schema
+     * @param multipleOf a positive number that restricts the value of objects described by this schema
      * @return the current Schema instance
      */
     Schema multipleOf(BigDecimal multipleOf);
 
     /**
-     * Returns the maximum property from this Schema instance.
+     * Returns the maximum property from this schema instance.
      *
      * @return the maximum value of a numeric object
      **/
     BigDecimal getMaximum();
 
     /**
-     * Sets the maximum property of this Schema instance to the value given.
+     * Sets the maximum property of this schema instance to the value given.
      *
-     * @param maximum specifies the maximum numeric value of objects defined by this Schema
+     * @param maximum specifies the maximum numeric value of objects defined by this schema
      */
     void setMaximum(BigDecimal maximum);
 
     /**
-     * Sets the maximum property of this Schema instance to the value given.
+     * Sets the maximum property of this schema instance to the value given.
      *
-     * @param maximum specifies the maximum numeric value of objects defined by this Schema
+     * @param maximum specifies the maximum numeric value of objects defined by this schema
      * @return the current Schema instance
      */
     Schema maximum(BigDecimal maximum);
 
     /**
-     * Returns the exclusiveMaximum property from this Schema instance.
+     * Returns the exclusiveMaximum property from this schema instance.
      *
      * @return whether the numeric value of objects must be less than the maximum property
      **/
     Boolean getExclusiveMaximum();
 
     /**
-     * Sets the exclusiveMaximum property of this Schema instance to the value given.
+     * Sets the exclusiveMaximum property of this schema instance to the value given.
      *
-     * @param exclusiveMaximum when true the numeric value of objects defined by this Schema must be less than indicated by the maximum property
+     * @param exclusiveMaximum when true the numeric value of objects defined by this schema must be less than indicated by the maximum property
      */
     void setExclusiveMaximum(Boolean exclusiveMaximum);
 
     /**
-     * Sets the exclusiveMaximum property of this Schema instance to the value given.
+     * Sets the exclusiveMaximum property of this schema instance to the value given.
      *
-     * @param exclusiveMaximum when true the numeric value of objects defined by this Schema must be less than indicated by the maximum property
+     * @param exclusiveMaximum when true the numeric value of objects defined by this schema must be less than indicated by the maximum property
      * @return the current Schema instance
      */
     Schema exclusiveMaximum(Boolean exclusiveMaximum);
 
     /**
-     * Returns the minimum property from this Schema instance.
+     * Returns the minimum property from this schema instance.
      *
      * @return the minimum value of a numeric object
      **/
     BigDecimal getMinimum();
 
     /**
-     * Sets the minimum property of this Schema instance to the value given.
+     * Sets the minimum property of this schema instance to the value given.
      *
-     * @param minimum specifies the minimum numeric value of objects defined by this Schema
+     * @param minimum specifies the minimum numeric value of objects defined by this schema
      */
     void setMinimum(BigDecimal minimum);
 
     /**
-     * Sets the minimum property of this Schema instance to the value given.
+     * Sets the minimum property of this schema instance to the value given.
      *
-     * @param minimum specifies the minimum numeric value of objects defined by this Schema
+     * @param minimum specifies the minimum numeric value of objects defined by this schema
      * @return the current Schema instance
      */
     Schema minimum(BigDecimal minimum);
 
     /**
-     * Returns the exclusiveMinimum property from this Schema instance.
+     * Returns the exclusiveMinimum property from this schema instance.
      *
      * @return whether the numeric value of objects must be greater than the minimum property
      **/
     Boolean getExclusiveMinimum();
 
     /**
-     * Sets the exclusiveMinimum property of this Schema instance to the value given.
+     * Sets the exclusiveMinimum property of this schema instance to the value given.
      *
-     * @param exclusiveMinimum when true the numeric value of objects defined by this Schema must be greater than indicated by the minimum property
+     * @param exclusiveMinimum when true the numeric value of objects defined by this schema must be greater than indicated by the minimum property
      */
     void setExclusiveMinimum(Boolean exclusiveMinimum);
 
     /**
-     * Sets the exclusiveMinimum property of this Schema instance to the value given.
+     * Sets the exclusiveMinimum property of this schema instance to the value given.
      *
-     * @param exclusiveMinimum when true the numeric value of objects defined by this Schema must be greater than indicated by the minimum property
+     * @param exclusiveMinimum when true the numeric value of objects defined by this schema must be greater than indicated by the minimum property
      * @return the current Schema instance
      */
     Schema exclusiveMinimum(Boolean exclusiveMinimum);
 
     /**
-     * Returns the maxLength property from this Schema instance.
+     * Returns the maxLength property from this schema instance.
      * <p>
      * minimum: 0
      *
@@ -273,22 +273,22 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Integer getMaxLength();
 
     /**
-     * Sets the maxLength property of this Schema instance to the value given.
+     * Sets the maxLength property of this schema instance to the value given.
      *
-     * @param maxLength the maximum length of objects defined by this Schema
+     * @param maxLength the maximum length of objects defined by this schema
      */
     void setMaxLength(Integer maxLength);
 
     /**
-     * Sets the maxLength property of this Schema instance to the value given.
+     * Sets the maxLength property of this schema instance to the value given.
      *
-     * @param maxLength the maximum length of objects defined by this Schema
+     * @param maxLength the maximum length of objects defined by this schema
      * @return the current Schema instance
      */
     Schema maxLength(Integer maxLength);
 
     /**
-     * Returns the minLength property from this Schema instance.
+     * Returns the minLength property from this schema instance.
      * <p>
      * minimum: 0
      *
@@ -297,44 +297,44 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Integer getMinLength();
 
     /**
-     * Sets the minLength property of this Schema instance to the value given.
+     * Sets the minLength property of this schema instance to the value given.
      *
-     * @param minLength the minimum length of objects defined by this Schema
+     * @param minLength the minimum length of objects defined by this schema
      */
     void setMinLength(Integer minLength);
 
     /**
-     * Sets the minLength property of this Schema instance to the value given.
+     * Sets the minLength property of this schema instance to the value given.
      *
-     * @param minLength the minimum length of objects defined by this Schema
+     * @param minLength the minimum length of objects defined by this schema
      * @return the current Schema instance
      */
     Schema minLength(Integer minLength);
 
     /**
-     * Returns the pattern property from this Schema instance.
+     * Returns the pattern property from this schema instance.
      *
      * @return the regular expression which restricts the value of an object e.g. a string
      **/
     String getPattern();
 
     /**
-     * Sets the pattern property of this Schema instance to the string given.
+     * Sets the pattern property of this schema instance to the string given.
      *
-     * @param pattern the regular expression which restricts objects defined by this Schema
+     * @param pattern the regular expression which restricts objects defined by this schema
      */
     void setPattern(String pattern);
 
     /**
-     * Sets the pattern property of this Schema instance to the string given.
+     * Sets the pattern property of this schema instance to the string given.
      *
-     * @param pattern the regular expression which restricts objects defined by this Schema
+     * @param pattern the regular expression which restricts objects defined by this schema
      * @return the current Schema instance
      */
     Schema pattern(String pattern);
 
     /**
-     * Returns the maxItems property from this Schema instance.
+     * Returns the maxItems property from this schema instance.
      * <p>
      * minimum: 0
      *
@@ -343,22 +343,22 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Integer getMaxItems();
 
     /**
-     * Sets the maxItems property of this Schema instance to the value given.
+     * Sets the maxItems property of this schema instance to the value given.
      *
-     * @param maxItems the maximum number of elements in objects defined by this Schema e.g. array elements
+     * @param maxItems the maximum number of elements in objects defined by this schema e.g. array elements
      */
     void setMaxItems(Integer maxItems);
 
     /**
-     * Sets the maxItems property of this Schema instance to the value given.
+     * Sets the maxItems property of this schema instance to the value given.
      *
-     * @param maxItems the maximum number of elements in objects defined by this Schema e.g. array elements
+     * @param maxItems the maximum number of elements in objects defined by this schema e.g. array elements
      * @return the current Schema instance
      */
     Schema maxItems(Integer maxItems);
 
     /**
-     * Returns the minItems property from this Schema instance.
+     * Returns the minItems property from this schema instance.
      * <p>
      * minimum: 0
      *
@@ -367,44 +367,44 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Integer getMinItems();
 
     /**
-     * Sets the minItems property of this Schema instance to the value given.
+     * Sets the minItems property of this schema instance to the value given.
      *
-     * @param minItems the minimum number of elements in objects defined by this Schema e.g. array elements
+     * @param minItems the minimum number of elements in objects defined by this schema e.g. array elements
      */
     void setMinItems(Integer minItems);
 
     /**
-     * Sets the minItems property of this Schema instance to the value given.
+     * Sets the minItems property of this schema instance to the value given.
      *
-     * @param minItems the minimum number of elements in objects defined by this Schema e.g. array elements
+     * @param minItems the minimum number of elements in objects defined by this schema e.g. array elements
      * @return the current Schema instance
      */
     Schema minItems(Integer minItems);
 
     /**
-     * Returns the uniqueItems property from this Schema instance.
+     * Returns the uniqueItems property from this schema instance.
      *
      * @return whether to ensure items are unique
      **/
     Boolean getUniqueItems();
 
     /**
-     * Sets the uniqueItems property of this Schema instance to the value given.
+     * Sets the uniqueItems property of this schema instance to the value given.
      *
-     * @param uniqueItems ensure the items (e.g. array elements) are unique in objects defined by this Schema
+     * @param uniqueItems ensure the items (e.g. array elements) are unique in objects defined by this schema
      */
     void setUniqueItems(Boolean uniqueItems);
 
     /**
-     * Sets the uniqueItems property of this Schema instance to the value given.
+     * Sets the uniqueItems property of this schema instance to the value given.
      *
-     * @param uniqueItems ensure the items (e.g. array elements) are unique in objects defined by this Schema
+     * @param uniqueItems ensure the items (e.g. array elements) are unique in objects defined by this schema
      * @return the current Schema instance
      */
     Schema uniqueItems(Boolean uniqueItems);
 
     /**
-     * Returns the maxProperties property from this Schema instance.
+     * Returns the maxProperties property from this schema instance.
      * <p>
      * minimum: 0
      *
@@ -413,22 +413,22 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Integer getMaxProperties();
 
     /**
-     * Sets the maxProperties property of this Schema instance to the value given.
+     * Sets the maxProperties property of this schema instance to the value given.
      *
-     * @param maxProperties limit the number of properties in objects defined by this Schema
+     * @param maxProperties limit the number of properties in objects defined by this schema
      */
     void setMaxProperties(Integer maxProperties);
 
     /**
-     * Sets the maxProperties property of this Schema instance to the value given.
+     * Sets the maxProperties property of this schema instance to the value given.
      *
-     * @param maxProperties limit the number of properties in objects defined by this Schema
+     * @param maxProperties limit the number of properties in objects defined by this schema
      * @return the current Schema instance
      */
     Schema maxProperties(Integer maxProperties);
 
     /**
-     * Returns the minProperties property from this Schema instance.
+     * Returns the minProperties property from this schema instance.
      * <p>
      * minimum: 0
      *
@@ -437,112 +437,112 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Integer getMinProperties();
 
     /**
-     * Sets the minProperties property of this Schema instance to the value given.
+     * Sets the minProperties property of this schema instance to the value given.
      *
-     * @param minProperties limit the number of properties in objects defined by this Schema
+     * @param minProperties limit the number of properties in objects defined by this schema
      */
     void setMinProperties(Integer minProperties);
 
     /**
-     * Sets the minProperties property of this Schema instance to the value given.
+     * Sets the minProperties property of this schema instance to the value given.
      *
-     * @param minProperties limit the number of properties in objects defined by this Schema
+     * @param minProperties limit the number of properties in objects defined by this schema
      * @return the current Schema instance
      */
     Schema minProperties(Integer minProperties);
 
     /**
-     * Returns the required property from this Schema instance.
+     * Returns the required property from this schema instance.
      *
-     * @return the list of fields required in objects defined by this Schema
+     * @return the list of fields required in objects defined by this schema
      **/
     List<String> getRequired();
 
     /**
-     * Sets the list of fields required in objects defined by this Schema.
+     * Sets the list of fields required in objects defined by this schema.
      *
-     * @param required the list of fields required in objects defined by this Schema
+     * @param required the list of fields required in objects defined by this schema
      */
     void setRequired(List<String> required);
 
     /**
-     * Sets the list of fields required in objects defined by this Schema.
+     * Sets the list of fields required in objects defined by this schema.
      *
-     * @param required the list of fields required in objects defined by this Schema
+     * @param required the list of fields required in objects defined by this schema
      * @return the current Schema instance
      */
     Schema required(List<String> required);
 
     /**
-     * Adds the name of an item to the list of fields required in objects defined by this Schema.
+     * Adds the name of an item to the list of fields required in objects defined by this schema.
      *
-     * @param required the name of an item required in objects defined by this Schema instance
+     * @param required the name of an item required in objects defined by this schema instance
      * @return the current Schema instance
      */
     Schema addRequired(String required);
 
     /**
-     * Returns the type property from this Schema.
+     * Returns the type property from this schema.
      *
-     * @return the type used in this Schema. Default value <b>must</b> be <code>null</code>
+     * @return the type used in this schema. Default value <b>must</b> be <code>null</code>
      **/
     SchemaType getType();
 
     /**
-     * Sets the type used by this Schema to the string given.
+     * Sets the type used by this schema to the string given.
      *
-     * @param type the type used by this Schema or <code>null</code> for
+     * @param type the type used by this schema or <code>null</code> for
      * reference schemas
      */
     void setType(SchemaType type);
 
     /**
-     * Sets the type used by this Schema to the string given.
+     * Sets the type used by this schema to the string given.
      *
-     * @param type the type used by this Schema or <code>null</code> for
+     * @param type the type used by this schema or <code>null</code> for
      * reference schemas
      * @return the current Schema instance
      */
     Schema type(SchemaType type);
 
     /**
-     * Returns a Schema which describes properties not allowed in objects defined by the current schema.
+     * Returns a schema which describes properties not allowed in objects defined by the current schema.
      *
      * @return the not property's schema
      **/
     Schema getNot();
 
     /**
-     * Sets the not property to a Schema which describes properties not allowed in objects defined by the current schema.
+     * Sets the not property to a schema which describes properties not allowed in objects defined by the current schema.
      *
-     * @param not the Schema which describes properties not allowed
+     * @param not the schema which describes properties not allowed
      */
     void setNot(Schema not);
 
     /**
-     * Sets the not property to a Schema which describes properties not allowed in objects defined by the current schema.
+     * Sets the not property to a schema which describes properties not allowed in objects defined by the current schema.
      *
-     * @param not the Schema which describes properties not allowed
+     * @param not the schema which describes properties not allowed
      * @return the current Schema instance
      */
     Schema not(Schema not);
 
     /**
-     * Returns the properties defined in this Schema.
+     * Returns the properties defined in this schema.
      *
      * @return a map which associates property names with the schemas that describe their contents
      **/
     Map<String, Schema> getProperties();
 
     /**
-     * Sets the properties of this Schema instance to the map provided.
+     * Sets the properties of this schema instance to the map provided.
      *
      * @param properties a map which associates property names with the schemas that describe their contents
      */
     void setProperties(Map<String, Schema> properties);
 
     /**
-     * Sets the properties of this Schema instance to the map provided.
+     * Sets the properties of this schema instance to the map provided.
      *
      * @param properties a map which associates property names with the schemas that describe their contents
      * @return the current Schema instance
@@ -550,10 +550,10 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Schema properties(Map<String, Schema> properties);
 
     /**
-     * Adds a Schema property of the provided name using the given schema.
+     * Adds a schema property of the provided name using the given schema.
      *
-     * @param key the name of a new Schema property
-     * @param propertySchema the Schema which describes the properties of the named property
+     * @param key the name of a new schema property
+     * @param propertySchema the schema which describes the properties of the named property
      * @return the current Schema instance
      */
     Schema addProperty(String key, Schema propertySchema);
@@ -573,16 +573,16 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
      *   should conform to the Schema.</li>
      * </ul>
      *
-     * @return this Schema's additionalProperties property
+     * @return this schema's additionalProperties property
      */
     Object getAdditionalProperties();
 
     /**
-     * Sets the Schema which defines additional properties not defined by "properties" or "patternProperties".
+     * Sets the schema which defines additional properties not defined by "properties" or "patternProperties".
      * See the javadoc for {@link Schema#getAdditionalProperties()} for more details on this setting.  Note 
      * that this version of the setter is mutually exclusive with the Boolean variants.
      *
-     * @param additionalProperties a Schema which defines additional properties
+     * @param additionalProperties a schema which defines additional properties
      */
     void setAdditionalProperties(Schema additionalProperties);
     
@@ -591,16 +591,16 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
      * {@link Schema#getAdditionalProperties()} for more details on this setting.  Note that
      * this version of the setter is mutually exclusive with the {@link Schema} variants.
      *
-     * @param additionalProperties a Schema which defines additional properties
+     * @param additionalProperties a schema which defines additional properties
      */
     void setAdditionalProperties(Boolean additionalProperties);
 
     /**
-     * Sets the Schema which defines additional properties not defined by "properties" or "patternProperties".
+     * Sets the schema which defines additional properties not defined by "properties" or "patternProperties".
      * See the javadoc for {@link Schema#getAdditionalProperties()} for more details on this setting.  Note 
      * that this version of the setter is mutually exclusive with the Boolean variants.
      *
-     * @param additionalProperties a Schema which defines additional properties
+     * @param additionalProperties a schema which defines additional properties
      * @return the current Schema instance
      */
     Schema additionalProperties(Schema additionalProperties);
@@ -610,42 +610,42 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
      * {@link Schema#getAdditionalProperties()} for more details on this setting.  Note that
      * this version of the setter is mutually exclusive with the {@link Schema} variants.
      *
-     * @param additionalProperties a Schema which defines additional properties
+     * @param additionalProperties a schema which defines additional properties
      * @return the current Schema instance
      */
     Schema additionalProperties(Boolean additionalProperties);
 
     /**
-     * Returns a description of the purpose of this Schema.
+     * Returns a description of the purpose of this schema.
      *
      * @return a string containing a description
      **/
     String getDescription();
 
     /**
-     * Sets the description property of this Schema to the given string.
+     * Sets the description property of this schema to the given string.
      *
-     * @param description a string containing a description of the purpose of this Schema
+     * @param description a string containing a description of the purpose of this schema
      */
     void setDescription(String description);
 
     /**
-     * Sets the description property of this Schema to the given string.
+     * Sets the description property of this schema to the given string.
      *
-     * @param description a string containing a description of the purpose of this Schema
+     * @param description a string containing a description of the purpose of this schema
      * @return the current Schema instance
      */
     Schema description(String description);
 
     /**
-     * Returns the format property from this Schema instance. This property clarifies the data type specified in the type property.
+     * Returns the format property from this schema instance. This property clarifies the data type specified in the type property.
      *
-     * @return a string describing the format of the data in this Schema
+     * @return a string describing the format of the data in this schema
      **/
     String getFormat();
 
     /**
-     * Sets the format property of this Schema instance to the given string. The value may be one of the formats described in the OAS or a user
+     * Sets the format property of this schema instance to the given string. The value may be one of the formats described in the OAS or a user
      * defined format.
      *
      * @param format the string specifying the data format
@@ -653,7 +653,7 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     void setFormat(String format);
 
     /**
-     * Sets the format property of this Schema instance to the given string. The value may be one of the formats described in the OAS or a user
+     * Sets the format property of this schema instance to the given string. The value may be one of the formats described in the OAS or a user
      * defined format.
      *
      * @param format the string specifying the data format
@@ -662,111 +662,111 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Schema format(String format);
 
     /**
-     * Returns the nullable property from this Schema instance which indicates whether null is a valid value.
+     * Returns the nullable property from this schema instance which indicates whether null is a valid value.
      *
      * @return the nullable property
      **/
     Boolean getNullable();
 
     /**
-     * Sets the nullable property of this Schema instance. Specify true if this Schema will allow null values.
+     * Sets the nullable property of this schema instance. Specify true if this schema will allow null values.
      *
-     * @param nullable a boolean value indicating this Schema allows a null value.
+     * @param nullable a boolean value indicating this schema allows a null value.
      */
     void setNullable(Boolean nullable);
 
     /**
-     * Sets the nullable property of this Schema instance. Specify true if this Schema will allow null values.
+     * Sets the nullable property of this schema instance. Specify true if this schema will allow null values.
      *
-     * @param nullable a boolean value indicating this Schema allows a null value.
+     * @param nullable a boolean value indicating this schema allows a null value.
      * @return the current Schema instance
      */
     Schema nullable(Boolean nullable);
 
     /**
-     * Returns the readOnly property from this Schema instance.
+     * Returns the readOnly property from this schema instance.
      *
-     * @return indication that the Schema is only valid in a response message
+     * @return indication that the schema is only valid in a response message
      **/
     Boolean getReadOnly();
 
     /**
-     * Sets the readOnly property of this Schema. Only valid when the Schema is the property in an object.
+     * Sets the readOnly property of this schema. Only valid when the schema is the property in an object.
      *
-     * @param readOnly true indicates the Schema should not be sent as part of a request message
+     * @param readOnly true indicates the schema should not be sent as part of a request message
      */
     void setReadOnly(Boolean readOnly);
 
     /**
-     * Sets the readOnly property of this Schema. Only valid when the Schema is the property in an object.
+     * Sets the readOnly property of this schema. Only valid when the schema is the property in an object.
      *
-     * @param readOnly true indicates the Schema should not be sent as part of a request message
+     * @param readOnly true indicates the schema should not be sent as part of a request message
      * @return the current Schema instance
      */
     Schema readOnly(Boolean readOnly);
 
     /**
-     * Returns the writeOnly property from this Schema instance.
+     * Returns the writeOnly property from this schema instance.
      *
-     * @return indication that the Schema is only valid in a request message
+     * @return indication that the schema is only valid in a request message
      **/
     Boolean getWriteOnly();
 
     /**
-     * Sets the writeOnly property of this Schema. Only valid when the Schema is the property in an object.
+     * Sets the writeOnly property of this schema. Only valid when the schema is the property in an object.
      *
-     * @param writeOnly true indicates the Schema should not be sent as part of a response message
+     * @param writeOnly true indicates the schema should not be sent as part of a response message
      */
     void setWriteOnly(Boolean writeOnly);
 
     /**
-     * Sets the writeOnly property of this Schema. Only valid when the Schema is the property in an object.
+     * Sets the writeOnly property of this schema. Only valid when the schema is the property in an object.
      *
-     * @param writeOnly true indicates the Schema should not be sent as part of a response message
+     * @param writeOnly true indicates the schema should not be sent as part of a response message
      * @return the current Schema instance
      */
     Schema writeOnly(Boolean writeOnly);
 
     /**
-     * Returns the example property from this Schema instance.
+     * Returns the example property from this schema instance.
      *
-     * @return an object which is an example of an instance of this Schema
+     * @return an object which is an example of an instance of this schema
      **/
     Object getExample();
 
     /**
-     * Sets the example property of this Schema instance. To represent examples that cannot be naturally represented in JSON or YAML, a string value
+     * Sets the example property of this schema instance. To represent examples that cannot be naturally represented in JSON or YAML, a string value
      * can be used to contain the example with escaping where necessary.
      *
-     * @param example an object which is an instance of this Schema
+     * @param example an object which is an instance of this schema
      */
     void setExample(Object example);
 
     /**
-     * Sets the example property of this Schema instance. To represent examples that cannot be naturally represented in JSON or YAML, a string value
+     * Sets the example property of this schema instance. To represent examples that cannot be naturally represented in JSON or YAML, a string value
      * can be used to contain the example with escaping where necessary.
      *
-     * @param example an object which is an instance of this Schema
+     * @param example an object which is an instance of this schema
      * @return the current Schema instance
      */
     Schema example(Object example);
 
     /**
-     * Returns the externalDocs property from this Schema instance.
+     * Returns the externalDocs property from this schema instance.
      *
-     * @return additional external documentation for this Schema
+     * @return additional external documentation for this schema
      **/
     ExternalDocumentation getExternalDocs();
 
     /**
-     * Sets the externalDocs property of this Schema to the indicated value.
+     * Sets the externalDocs property of this schema to the indicated value.
      *
      * @param externalDocs an additional external documentation object
      */
     void setExternalDocs(ExternalDocumentation externalDocs);
 
     /**
-     * Sets the externalDocs property of this Schema to the indicated value.
+     * Sets the externalDocs property of this schema to the indicated value.
      *
      * @param externalDocs an additional external documentation object
      * @return the current Schema instance
@@ -774,36 +774,36 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     Schema externalDocs(ExternalDocumentation externalDocs);
 
     /**
-     * Returns the deprecated property from this Schema instance.
+     * Returns the deprecated property from this schema instance.
      *
-     * @return indication that the Schema is deprecated and should be transitioned out of usage
+     * @return indication that the schema is deprecated and should be transitioned out of usage
      **/
     Boolean getDeprecated();
 
     /**
-     * Sets the deprecated property of this Schema. This specifies that the Schema is deprecated and should be transitioned out of usage
+     * Sets the deprecated property of this schema. This specifies that the schema is deprecated and should be transitioned out of usage
      *
-     * @param deprecated true to indicate this Schema is deprecated
+     * @param deprecated true to indicate this schema is deprecated
      */
     void setDeprecated(Boolean deprecated);
 
     /**
-     * Sets the deprecated property of this Schema. This specifies that the Schema is deprecated and should be transitioned out of usage
+     * Sets the deprecated property of this schema. This specifies that the schema is deprecated and should be transitioned out of usage
      *
-     * @param deprecated true to indicate this Schema is deprecated
+     * @param deprecated true to indicate this schema is deprecated
      * @return the current Schema instance
      */
     Schema deprecated(Boolean deprecated);
 
     /**
-     * Returns the xml property from this Schema instance.
+     * Returns the xml property from this schema instance.
      *
      * @return a metadata object that allows for more fine-tuned XML model definitions
      **/
     XML getXml();
 
     /**
-     * Sets the xml property of this Schema instance. It may only be set on properties schemas and adds additional metadata to describe the XML
+     * Sets the xml property of this schema instance. It may only be set on properties schemas and adds additional metadata to describe the XML
      * representation of this property.
      *
      * @param xml a metadata object to describe the XML representation of this property
@@ -811,7 +811,7 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     void setXml(XML xml);
 
     /**
-     * Sets the xml property of this Schema instance. It may only be set on properties schemas and adds additional metadata to describe the XML
+     * Sets the xml property of this schema instance. It may only be set on properties schemas and adds additional metadata to describe the XML
      * representation of this property.
      *
      * @param xml a metadata object to describe the XML representation of this property
@@ -821,114 +821,114 @@ public interface Schema extends Extensible, Constructible, Reference<Schema> {
     
     
     /**
-     * Returns the Schema used for all the elements of an array typed Schema.
+     * Returns the schema used for all the elements of an ArraySchema instance (array).
      *
-     * @return the Schema used for all the elements
+     * @return the schema used for all the elements
      **/
     Schema getItems();
 
     /**
-     * Set the Schema used for all the elements of an array typed Schema.
+     * Set the schema used for all the elements of an ArraySchema instance (array).
      *
-     * @param items the Schema used by this array
+     * @param items the schema used by this array
      */
     void setItems(Schema items);
 
     /**
-     * Set the Schema used for all the elements of an array typed Schema.
+     * Set the schema used for all the elements of an ArraySchema instance (array).
      *
-     * @param items the Schema used by this array
-     * @return the current Schema instance
+     * @param items the schema used by this array
+     * @return the current ArraySchema instance
      */
     Schema items(Schema items);
     
     /**
-     * Returns the schemas used by the allOf property.
+     * Returns the schemas used by the allOf property in a ComposedSchema instance.
      *
      * @return the list of schemas used by the allOf property
      **/
     List<Schema> getAllOf();
 
     /**
-     * Sets the schemas used by the allOf property of this Schema.
+     * Sets the schemas used by the allOf property of this schema.
      * 
      * @param allOf the list of schemas used by the allOf property
      */
     void setAllOf(List<Schema> allOf);
 
     /**
-     * Sets the schemas used by the allOf property of this Schema.
+     * Sets the schemas used by the allOf property of this schema.
      * 
      * @param allOf the list of schemas used by the allOf property
-     * @return the current Schema instance
+     * @return the current ComposedSchema instance
      */
     Schema allOf(List<Schema> allOf);
 
     /**
-     * Adds the given Schema to the list of schemas used by the allOf property.
+     * Adds the given schema to this ComposedSchema's list of schemas used by the allOf property.
      * 
-     * @param allOf a Schema to use with the allOf property
-     * @return the current Schema instance
+     * @param allOf a schema to use with the allOf property
+     * @return the current ComposedSchema instance
      */
     Schema addAllOf(Schema allOf);
 
     /**
-     * Returns the schemas used by the anyOf property.
+     * Returns the schemas used by the anyOf property in a ComposedSchema instance.
      *
      * @return the list of schemas used by the anyOf property
      **/
     List<Schema> getAnyOf();
 
     /**
-     * Sets the schemas used by the anyOf property of this Schema.
+     * Sets the schemas used by the anyOf property of this schema.
      * 
      * @param anyOf the list of schemas used by the anyOf property
      */
     void setAnyOf(List<Schema> anyOf);
 
     /**
-     * Sets the schemas used by the anyOf property of this Schema.
+     * Sets the schemas used by the anyOf property of this schema.
      * 
      * @param anyOf the list of schemas used by the anyOf property
-     * @return the current Schema instance
+     * @return the current ComposedSchema instance
      */
     Schema anyOf(List<Schema> anyOf);
 
     /**
-     * Adds the given Schema to the list of schemas used by the anyOf property.
+     * Adds the given schema to this ComposedSchema's list of schemas used by the anyOf property.
      * 
-     * @param anyOf a Schema to use with the anyOf property
-     * @return the current Schema instance
+     * @param anyOf a schema to use with the anyOf property
+     * @return the current ComposedSchema instance
      */
     Schema addAnyOf(Schema anyOf);
 
     /**
-     * Returns the schemas used by the oneOf property.
+     * Returns the schemas used by the oneOf property in a ComposedSchema instance.
      *
      * @return the list of schemas used by the oneOf property
      **/
     List<Schema> getOneOf();
 
     /**
-     * Sets the schemas used by the oneOf property of this Schema.
+     * Sets the schemas used by the oneOf property of this schema.
      * 
      * @param oneOf the list of schemas used by the oneOf property
      */
     void setOneOf(List<Schema> oneOf);
 
     /**
-     * Sets the schemas used by the oneOf property of this Schema.
+     * Sets the schemas used by the oneOf property of this schema.
      * 
      * @param oneOf the list of schemas used by the oneOf property
-     * @return the current Schema instance
+     * @return the current ComposedSchema instance
      */
     Schema oneOf(List<Schema> oneOf);
 
     /**
-     * Adds the given Schema to the list of schemas used by the oneOf property.
+     * Adds the given schema to this ComposedSchema's list of schemas used by the oneOf property.
      * 
-     * @param oneOf a Schema to use with the oneOf property
-     * @return the current Schema instance
+     * @param oneOf a schema to use with the oneOf property
+     * @return the current ComposedSchema instance
      */
     Schema addOneOf(Schema oneOf);
 
diff --git a/pom.xml b/pom.xml
index fbe1418..82098a6 100644
--- a/pom.xml
+++ b/pom.xml
@@ -21,7 +21,7 @@
     <version>1.0-SNAPSHOT</version>
     <packaging>pom</packaging>
     <name>MicroProfile OpenAPI</name>
-    <description>Eclipse MicroProfile OpenAPI</description>
+    <description>Eclipse MicroProfile OpenAPI Feature :: Parent POM</description>
 
     <url>http://microprofile.io</url>
 
@@ -55,15 +55,15 @@
     </developers>
 
     <scm>
-        <url>https://github.com/eclipse/microprofile-open-api</url>
-        <connection>scm:git:https://github.com/eclipse/microprofile-open-api.git</connection>
-        <developerConnection>scm:git:git@github.com:eclipse/microprofile-open-api.git</developerConnection>
+        <url>https://github.com/eclipse/microprofile-openapi</url>
+        <connection>scm:git:https://github.com/eclipse/microprofile-openapi.git</connection>
+        <developerConnection>scm:git:git@github.com:eclipse/microprofile-openapi.git</developerConnection>
         <tag>HEAD</tag>
     </scm>
 
     <issueManagement>
         <system>GitHub</system>
-        <url>https://github.com/eclipse/microprofile-open-api/issues</url>
+        <url>https://github.com/eclipse/microprofile-openapi/issues</url>
     </issueManagement>
 
     <distributionManagement>
@@ -83,7 +83,9 @@
     <modules>
         <module>api</module>
         <module>tck</module>
+<!--
         <module>spec</module>
+-->
     </modules>
 
     <dependencyManagement>
@@ -105,49 +107,43 @@
 
     <build>
         <pluginManagement>
-            <plugins>
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-release-plugin</artifactId>
-                    <version>2.5.3</version>
-                    <configuration>
-                        <autoVersionSubmodules>true</autoVersionSubmodules>
-                        <localCheckout>true</localCheckout>
-                        <useReleaseProfile>false</useReleaseProfile>
-                        <arguments>${arguments} -Prelease -Drevremark=${revremark}</arguments>
-                    </configuration>
-                </plugin>
-                <plugin>
-                    <groupId>org.eclipse.cbi.maven.plugins</groupId>
-                    <artifactId>eclipse-jarsigner-plugin</artifactId>
-                    <version>1.1.4</version>
-                </plugin>
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-checkstyle-plugin</artifactId>
-                    <version>${checkstyle.version}</version>
-                </plugin>
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-jar-plugin</artifactId>
-                    <version>3.0.2</version>
-                </plugin>
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-source-plugin</artifactId>
-                    <version>3.0.1</version>
-                </plugin>
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-javadoc-plugin</artifactId>
-                    <version>2.10.4</version>
-                </plugin>
-                <plugin>
-                    <groupId>org.apache.maven.plugins</groupId>
-                    <artifactId>maven-gpg-plugin</artifactId>
-                    <version>1.6</version>
-                </plugin>
-            </plugins>
+        <plugins>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-release-plugin</artifactId>
+                <version>2.5.3</version>
+                <configuration>
+                    <autoVersionSubmodules>true</autoVersionSubmodules>
+                    <useReleaseProfile>false</useReleaseProfile>
+                    <localCheckout>true</localCheckout>
+                </configuration>
+            </plugin>
+            <plugin>
+                <groupId>org.eclipse.cbi.maven.plugins</groupId>
+                <artifactId>eclipse-jarsigner-plugin</artifactId>
+                <version>1.1.4</version>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-checkstyle-plugin</artifactId>
+                <version>${checkstyle.version}</version>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-jar-plugin</artifactId>
+                <version>3.0.2</version>
+            </plugin>
+            <plugin>
+                <groupId>org.apache.maven.plugins</groupId>
+                <artifactId>maven-source-plugin</artifactId>
+                <version>3.0.1</version>
+            </plugin>
+            <plugin>
+                 <groupId>org.apache.maven.plugins</groupId>
+                 <artifactId>maven-javadoc-plugin</artifactId>
+                 <version>2.10.4</version>
+            </plugin>
+        </plugins>
         </pluginManagement>
         <plugins>
             <plugin>
@@ -280,32 +276,20 @@
             <build>
                 <plugins>
                     <plugin>
-                        <groupId>org.apache.maven.plugins</groupId>
-                        <artifactId>maven-source-plugin</artifactId>
-                        <executions>
-                            <execution>
-                                <id>attach-sources</id>
-                                <goals>
-                                    <goal>jar-no-fork</goal>
-                                </goals>
-                            </execution>
-                        </executions>
-                    </plugin>
-                    <plugin>
-                        <groupId>org.apache.maven.plugins</groupId>
-                        <artifactId>maven-javadoc-plugin</artifactId>
-                        <executions>
-                            <execution>
-                                <id>attach-javadocs</id>
-                                <goals>
-                                    <goal>jar</goal>
-                                </goals>
-                            </execution>
-                        </executions>
+                        <groupId>org.sonatype.plugins</groupId>
+                        <artifactId>nexus-staging-maven-plugin</artifactId>
+                        <version>1.6.3</version>
+                        <extensions>true</extensions>
+                        <configuration>
+                            <nexusUrl>https://oss.sonatype.org/</nexusUrl>
+                            <serverId>ossrh</serverId>
+                            <autoReleaseAfterClose>${autorelease}</autoReleaseAfterClose>
+                        </configuration>
                     </plugin>
                     <plugin>
                         <groupId>org.apache.maven.plugins</groupId>
                         <artifactId>maven-gpg-plugin</artifactId>
+                        <version>1.6</version>
                         <executions>
                             <execution>
                                 <id>sign-artifacts</id>
diff --git a/spec/pom.xml b/spec/pom.xml
deleted file mode 100644
index 010d0f9..0000000
--- a/spec/pom.xml
+++ /dev/null
@@ -1,92 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!--
-  ~ Copyright (c) 2017 Contributors to the Eclipse Foundation
-  ~
-  ~ Licensed under the Apache License, Version 2.0 (the "License");
-  ~ you may not use this file except in compliance with the License.
-  ~ You may obtain a copy of the License at
-  ~
-  ~    http://www.apache.org/licenses/LICENSE-2.0
-  ~
-  ~ Unless required by applicable law or agreed to in writing, software
-  ~ distributed under the License is distributed on an "AS IS" BASIS,
-  ~ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-  ~ See the License for the specific language governing permissions and
-  ~ limitations under the License.
-  -->
-<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
-    <modelVersion>4.0.0</modelVersion>
-    <parent>
-        <!-- This is just for now and will not work if the API has a separate release cycle than the rest. -->
-        <groupId>org.eclipse.microprofile.openapi</groupId>
-        <artifactId>microprofile-openapi-parent</artifactId>
-        <version>1.0-SNAPSHOT</version>
-    </parent>
-
-    <artifactId>microprofile-openapi-spec</artifactId>
-    <packaging>pom</packaging>
-    <name>MicroProfile OpenAPI Specification</name>
-    <description>MicroProfile OpenAPI :: Specification</description>
-    <properties>
-        <asciidoctor-maven.version>1.5.5</asciidoctor-maven.version>
-        <asciidoctorj-pdf.version>1.5.0-alpha.15</asciidoctorj-pdf.version>
-        <license>Apache License v 2.0</license>
-        <maven.build.timestamp.format>MMMM dd, yyyy</maven.build.timestamp.format>
-        <revisiondate>${maven.build.timestamp}</revisiondate>
-        <revremark>Draft</revremark>
-    </properties>
-
-    <build>
-        <defaultGoal>clean package</defaultGoal>
-        <plugins>
-            <plugin>
-                <groupId>org.asciidoctor</groupId>
-                <artifactId>asciidoctor-maven-plugin</artifactId>
-                <version>${asciidoctor-maven.version}</version>
-                <dependencies>
-                    <dependency>
-                        <groupId>org.asciidoctor</groupId>
-                        <artifactId>asciidoctorj-pdf</artifactId>
-                        <version>${asciidoctorj-pdf.version}</version>
-                    </dependency>
-                </dependencies>
-                <executions>
-                    <execution>
-                        <id>generate-pdf-doc</id>
-                        <phase>generate-resources</phase>
-                        <goals>
-                            <goal>process-asciidoc</goal>
-                        </goals>
-                        <configuration>
-                            <backend>pdf</backend>
-                            <attributes>
-                                <revnumber>${project.version}</revnumber>
-                                <revremark>${revremark}</revremark>
-                                <revdate>${revisiondate}</revdate>
-                            </attributes>
-                        </configuration>
-                    </execution>
-                    <execution>
-                        <id>output-html</id>
-                        <phase>generate-resources</phase>
-                        <goals>
-                            <goal>process-asciidoc</goal>
-                        </goals>
-                        <configuration>
-                            <backend>html5</backend>
-                        </configuration>
-                    </execution>
-                </executions>
-                <configuration>
-                    <sourceDocumentName>microprofile-openapi-spec.adoc</sourceDocumentName>
-                    <sourceHighlighter>coderay</sourceHighlighter>
-                    <attributes>
-                        <license>Apache License v2.0</license>
-                    </attributes>
-                </configuration>
-            </plugin>
-        </plugins>
-    </build>
-
-
-</project>
diff --git a/spec/src/main/asciidoc/microprofile-openapi-spec.adoc b/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
index 6c204cb..3f321e3 100644
--- a/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
+++ b/spec/src/main/asciidoc/microprofile-openapi-spec.adoc
@@ -450,63 +450,35 @@ paths:
 
 ===== Schema
 
-.Sample 1 - Schema POJO
+TODO: Detailed usage description of annotation (issue #10)
+
+.Sample 1
 [source,Java]
 ----
-@Schema(name="MyBooking", description="POJO that represents a booking.")
-public class Booking {
-    @Schema(required = true, example = "32126319")
-    private String airMiles;
 
-    @Schema(required = true, example = "window")
-    private String seatPreference;
-}
 ----
 
 .Output for Sample 1
 [source, yaml]
 ----
-components:
-  schemas:
-    MyBooking:
-      description: POJO that represents a booking.
-      required:
-      - airMiles
-      - seatPreference
-      type: object
-      properties:
-        airMiles:
-          type: string
-          example: "32126319"
-        seatPreference:
-          type: string
-          example: window
+
 ----
 
+===== Tags
+
+TODO: Detailed usage description of annotation (issue #10)
 
-.Sample 2 - Schema POJO reference
+.Sample 1
 [source,Java]
 ----
-@POST
-public Response createBooking(
-     @RequestBody(description = "Create a new booking.",
-                  content = @Content(mediaType = "application/json",
-                                     schema = @Schema(implementation = Booking.class))) Booking booking) {
+
 ----
 
-.Output for Sample 2
+.Output for Sample 1
 [source, yaml]
 ----
-post:
-  operationId: createBooking
-  requestBody:
-    description: Create a new booking with the provided information.
-    content:
-      application/json:
-        schema:
-          $ref: '#/components/schemas/MyBooking'
-----
 
+----
 
 For more samples please see the https://github.com/eclipse/microprofile-open-api/wiki[MicroProfile Wiki].
 
diff --git a/spec/src/main/resources/META-INF/LICENSE b/spec/src/main/resources/META-INF/LICENSE
deleted file mode 100644
index 8dada3e..0000000
--- a/spec/src/main/resources/META-INF/LICENSE
+++ /dev/null
@@ -1,201 +0,0 @@
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "{}"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright {yyyy} {name of copyright owner}
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.
diff --git a/spec/src/main/resources/META-INF/NOTICE b/spec/src/main/resources/META-INF/NOTICE
deleted file mode 100644
index 0408fc0..0000000
--- a/spec/src/main/resources/META-INF/NOTICE
+++ /dev/null
@@ -1,13 +0,0 @@
-=========================================================================
-==  NOTICE file corresponding to section 4(d) of the Apache License,   ==
-==  Version 2.0, in this case for Microprofile Config                  ==
-=========================================================================
-
-SPDXVersion: SPDX-2.1
-PackageName: Eclipse Microprofile
-PackageHomePage: http://www.eclipse.org/microprofile
-PackageLicenseDeclared: Apache-2.0
-
-PackageCopyrightText: <text>
-Arthur De Magalhaes ademagalhaes@gmail.com
-</text>
diff --git a/tck/pom.xml b/tck/pom.xml
index 76fa985..8d07305 100644
--- a/tck/pom.xml
+++ b/tck/pom.xml
@@ -127,13 +127,6 @@
              <scope>compile</scope>
          </dependency>
 
-         <dependency>
-             <groupId>org.hamcrest</groupId>
-             <artifactId>java-hamcrest</artifactId>
-             <version>2.0.0.0</version>
-             <scope>compile</scope>
-         </dependency>
-
          <dependency>
              <groupId>javax.servlet</groupId>
              <artifactId>javax.servlet-api</artifactId>
@@ -160,24 +153,4 @@
              <version>2.9.2</version>
          </dependency>
     </dependencies>
-    <profiles>
-        <profile>
-            <id>eclipse-jarsigner</id>
-            <build>
-                <plugins>
-                    <plugin>
-                        <groupId>org.eclipse.cbi.maven.plugins</groupId>
-                        <artifactId>eclipse-jarsigner-plugin</artifactId>
-                        <executions>
-                            <execution>
-                                <goals>
-                                    <goal>sign</goal>
-                                </goals>
-                            </execution>
-                        </executions>
-                    </plugin>
-                </plugins>
-            </build>
-        </profile>
-    </profiles>
 </project>
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java
index 3c929dd..290c4b0 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/JAXRSApp.java
@@ -56,6 +56,7 @@ import org.eclipse.microprofile.openapi.apps.airlines.resources.ReviewResource;
 @ApplicationPath("/")
 @OpenAPIDefinition(
     tags = {
+            @Tag(name = "Airlines", description = "airlines app"),
             @Tag(name="user", description="Operations about user"),
             @Tag(name="create", description="Operations about create")
     },
@@ -68,7 +69,7 @@ import org.eclipse.microprofile.openapi.apps.airlines.resources.ReviewResource;
         termsOfService = "http://airlinesratingapp.com/terms", 
         contact = @Contact(
             name = "AirlinesRatingApp API Support",
-            url = "http://exampleurl.com/contact",
+            url = "https://github.com/microservices-api/oas3-airlines",
             email = "techsupport@airlinesratingapp.com"),
         license = @License(
             name = "Apache 2.0",
@@ -76,13 +77,10 @@ import org.eclipse.microprofile.openapi.apps.airlines.resources.ReviewResource;
         security = @SecurityRequirement(name = "airlinesRatingApp_auth"),
         servers = {
                 @Server(url = "https://{username}.gigantic-server.com:{port}/{basePath}", description = "The production API server",
-                        variables = {
-                                @ServerVariable(name = "username", description = "Reviews of the app by users", defaultValue = "user1",
-                                        enumeration = { "user1", "user2" }),
-                                @ServerVariable(name = "port", description = "Booking data", defaultValue = "8443"),
+                        variables = { @ServerVariable(name = "username", description = "Reviews of the app by users", defaultValue = "reviews"),
+                                @ServerVariable(name = "port", description = "Booking data", enumeration = { "8443", "443" }, defaultValue = "8443"),
                                 @ServerVariable(name = "user", description = "User data", defaultValue = "user"),
-                                @ServerVariable(name = "basePath", defaultValue = "v2") }),
-                @Server(url = "https://test-server.com:80/basePath", description = "The test API server") },
+                                @ServerVariable(name = "basePath", defaultValue = "v2") }) },
         components = @Components(
                 schemas = { 
                         @Schema(name = "Bookings", type = SchemaType.ARRAY, implementation = Booking.class),
@@ -135,7 +133,7 @@ import org.eclipse.microprofile.openapi.apps.airlines.resources.ReviewResource;
     description = "APIs for booking and managing air flights",
     externalDocs = @ExternalDocumentation(
         description = "For more information, see the link.",
-        url = "http://exampleurl.com/schema")
+        url = "https://github.com/janamanoharan/airlinesratingapp")
     )
 public class JAXRSApp extends Application {
     @Override
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
index 31b17c9..53a481b 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AirlinesResource.java
@@ -78,19 +78,15 @@ public class AirlinesResource {
         airlines.put(3, new Airline("PanAm 5000", "1-855-1267-561"));
     }
     
+    @Tag(
+        name = "getAirlines",
+        description = "method to retrieve all airlines"
+    )
     public static Airline getRandomAirline(){
         return airlines.get(JAXRSApp.getRandomNumber(2,1));
     }
     
     @GET
-    @Tag(
-            name = "Get Airlines",
-            description = "method to get all airlines"
-        )
-    @Tag(
-            name = "Retrieve Airlines",
-            description = "method to retrieve all airlines"
-            )
     @Operation(
         method = "get",
         summary = "Retrieve all available airlines",
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AvailabilityResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AvailabilityResource.java
index 83c04cb..faba1fd 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AvailabilityResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/AvailabilityResource.java
@@ -27,6 +27,7 @@ import org.eclipse.microprofile.openapi.annotations.ExternalDocumentation;
 import org.eclipse.microprofile.openapi.annotations.media.Schema;
 import org.eclipse.microprofile.openapi.annotations.responses.APIResponse;
 import org.eclipse.microprofile.openapi.annotations.tags.Tag;
+import org.eclipse.microprofile.openapi.annotations.tags.Tags;
 import org.eclipse.microprofile.openapi.annotations.Operation;
 import org.eclipse.microprofile.openapi.annotations.parameters.Parameter;
 import org.eclipse.microprofile.openapi.apps.airlines.JAXRSApp;
@@ -34,23 +35,18 @@ import org.eclipse.microprofile.openapi.apps.airlines.model.Flight;
 import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
 
 @Path("/availability")
-@Tag(
+@Tags(
+    value = @Tag(
         name = "Availability", 
-        description = "All the availability methods")
+        description = "All the availibility methods"))
 public class AvailabilityResource {
 
     @GET
-    @Tag(
-            name = "Get Flights",
-            description = "method to retrieve all flights available",
-            externalDocs = @ExternalDocumentation(
-                description = "A list of all the flights offered by the app",
-                url = "http://airlinesratingapp.com/ourflights")
-        )
     @Operation(
         method = "get",
         summary = "Retrieve all available flights",
         operationId = "getFlights",
+        tags = {"availability"},
         responses = {
             @APIResponse(
                 responseCode = "200",
@@ -70,16 +66,26 @@ public class AvailabilityResource {
                     mediaType = "n/a")
             )
         })
+    @Tag(
+        name = "getFlights",
+        description = "method to retrieve all flights available",
+        externalDocs = @ExternalDocumentation(
+            description = "A list of all the flights offered by the app",
+            url = "http://airlinesratingapp.com/ourflights")
+    )
     @Produces("application/json")
     public Response getFlights(
         @Parameter(
-            ref = "#/components/parameters/departureDate"
+            name = "departureDate",
+            required = true,
+            description = "Customer departure date",
+            schema = @Schema(
+                implementation = String.class)
         )
         @QueryParam("departureDate") String departureDate,
         @Parameter(
             name = "airportFrom",
             required = true,
-            allowEmptyValue = true,
             description = "Airport the customer departs from",
             schema = @Schema(
                 implementation = String.class)
@@ -88,7 +94,6 @@ public class AvailabilityResource {
         @Parameter(
             name = "returningDate",
             required = true,
-            allowReserved = true,
             description = "Customer return date",
             schema = @Schema(
                 implementation = String.class)
@@ -114,7 +119,6 @@ public class AvailabilityResource {
         @Parameter(
             name = "numberOfChildren",
             required = true,
-            deprecated = true,
             description = "Number of children on the flight",
             schema = @Schema(
                 minimum = "0",
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/BookingResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/BookingResource.java
index 4e0d73f..29e9fcf 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/BookingResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/BookingResource.java
@@ -30,7 +30,6 @@ import org.eclipse.microprofile.openapi.annotations.enums.SecuritySchemeType;
 import org.eclipse.microprofile.openapi.annotations.enums.SchemaType;
 import org.eclipse.microprofile.openapi.annotations.security.SecurityRequirement;
 import org.eclipse.microprofile.openapi.annotations.security.SecurityScheme;
-import org.eclipse.microprofile.openapi.annotations.servers.Server;
 
 import java.util.Map;
 import java.util.concurrent.ConcurrentHashMap;
@@ -49,21 +48,16 @@ import javax.ws.rs.core.Response.Status;
 import org.eclipse.microprofile.openapi.apps.airlines.model.Booking;
 
 @Path("/bookings")
-@Tag(
-        name = "Bookings", 
-        description = "All the bookings methods")
 @Tags(
     value = @Tag(
-            name = "Reservations", 
-            description = "All the reservation methods"))
+        name = "Bookings", 
+        description = "All the bookings methods"))
 @SecurityScheme(
     securitySchemeName = "bookingSecurityScheme",
     type = SecuritySchemeType.OPENIDCONNECT,
     description = "Security Scheme for booking resource",
     openIdConnectUrl = "http://openidconnect.com/testurl"
 )
-@Server(description = "Secure server", url = "https://gigantic-server.com:443")
-@Server(description = "Unsecure server", url = "http://gigantic-server.com:80")
 public class BookingResource {
     private Map<Integer, Booking> bookings = new ConcurrentHashMap<Integer, Booking>();
     private volatile int currentId = 0;
@@ -116,6 +110,7 @@ public class BookingResource {
         summary="Create a booking",
         description = "Create a new booking record with the booking information provided.",
         operationId = "createBooking",
+        tags = {"booking"},
         security = @SecurityRequirement(
             name = "bookingSecurityScheme",
             scopes = {"write:bookings", "read:bookings"}
@@ -148,7 +143,14 @@ public class BookingResource {
     )
     @Consumes("application/json")
     @Produces("application/json")
-    public Response createBooking(Booking task) {
+    public Response createBooking(
+        @Parameter(
+            description = "booking to create",
+            required = true,
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(implementation = Booking.class)))
+        Booking task) {
             bookings.put(currentId, task);
             return Response.status(Status.CREATED).entity("{\"id\":" + currentId++ + "}").build();
         }
@@ -171,6 +173,7 @@ public class BookingResource {
         method = "get",
         summary="Get a booking with ID",
         operationId = "getBookingById",
+        tags = {"booking"},
         responses={
             @APIResponse(
                 responseCode="200",
@@ -201,6 +204,7 @@ public class BookingResource {
         method = "put",
         summary="Update a booking with ID",
         operationId = "updateBookingId",
+        tags = {"booking"},
         responses={
             @APIResponse(
                 responseCode="200",
@@ -228,6 +232,7 @@ public class BookingResource {
         method = "delete",
         summary="Delete a booking with ID",
         operationId = "deleteBookingById",
+        tags = {"booking"},
         responses={
             @APIResponse(
                 responseCode="200",
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
index c259df5..11149d9 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/ReviewResource.java
@@ -65,9 +65,9 @@ import org.eclipse.microprofile.openapi.apps.airlines.model.User;
 @Path("/reviews")
 @Servers({ @Server(description = "Secure server", url = "https://gigantic-server.com:443"),
         @Server(description = "Unsecure server", url = "http://gigantic-server.com:80") })
-@Server(url = "{protocol}://test-server.com",
+@Server(url = "https://gigantic-server.com:{port}",
         description = "The production API server",
-        variables = { @ServerVariable(name = "protocol", enumeration = { "http", "https" }, defaultValue = "https") })
+        variables = { @ServerVariable(name = "port", description = "Review data", enumeration = { "9080", "9443" }, defaultValue = "9080") })
 @SecurityScheme(
     securitySchemeName = "reviewoauth2",
     type = SecuritySchemeType.OAUTH2,
@@ -85,11 +85,10 @@ import org.eclipse.microprofile.openapi.apps.airlines.model.User;
             tokenUrl = "https://example.com/api/oauth/token"
         ),
         password = @OAuthFlow(
-            refreshUrl = "https://example.com/api/oauth/refresh",
-            tokenUrl = "https://example.com/api/oauth/token"
+            refreshUrl = "https://example.com/api/oauth/refresh"
         ),
         clientCredentials = @OAuthFlow(
-            tokenUrl = "https://example.com/api/oauth/token",
+            authorizationUrl = "https://example.com/api/oauth/clientcredentials",
             scopes = @OAuthScope(
                 name = "read:reviews",
                 description = "search for a review"
@@ -98,16 +97,10 @@ import org.eclipse.microprofile.openapi.apps.airlines.model.User;
     )
 )
 @Tags(
-    value = {
-            @Tag(
-                    name = "Reviews",
-                    description = "All the review methods"
-                    ),
-            @Tag(
-                    name = "Ratings",
-                    description = "All the ratings methods"
-                    )
-            }
+    value = @Tag(
+        name = "Reviews",
+        description = "All the review methods"
+    )
 )
 public class ReviewResource {
 
@@ -128,6 +121,7 @@ public class ReviewResource {
         operationId = "getAllReviews",
         summary = "get all the reviews",
         method = "get",
+        tags = {"review"},
         responses = @APIResponse(
             responseCode = "200",
             description = "successful operation",
@@ -152,6 +146,7 @@ public class ReviewResource {
         operationId = "getReviewById",
         summary="Get a review with ID",
         method= "get",
+        tags = {"review"},
         responses={
             @APIResponse(
                 responseCode="200",
@@ -190,6 +185,7 @@ public class ReviewResource {
         method = "get",
         operationId = "getReviewByUser",
         summary="Get all reviews by user",
+        tags = {"review"},
         responses={
             @APIResponse(
                 responseCode="200",
@@ -235,6 +231,7 @@ public class ReviewResource {
         method = "get",
         operationId = "getReviewByAirline",
         summary="Get all reviews by airlines",
+        tags = {"review"},
         parameters = {
             @Parameter(
                 name = "airline",
@@ -290,6 +287,7 @@ public class ReviewResource {
         method = "get",
         operationId = "getReviewByAirlineAndUser",
         summary="Get all reviews for an airline by User",
+        tags = {"review"},
         responses={
             @APIResponse(
                 responseCode="200",
@@ -369,12 +367,18 @@ public class ReviewResource {
         method = "post",
         summary="Create a Review",
         operationId = "createReview",
-        tags = {"Reviews"},
+        tags = {"review"},
         servers = {
-                @Server(url = "localhost:9080/{proxyPath}/reviews/id",
-                        description = "view of all the reviews",
-                        variables = { @ServerVariable(name = "proxyPath", description = "Base path of the proxy", defaultValue = "proxy") }),
-                @Server(url = "http://random.url/reviews", description = "random text") },
+            @Server(
+                url = "localhost:9080/oas3-airlines/reviews/{id}",
+                description = "view of all the reviews",
+                variables = {
+                    @ServerVariable(
+                        name = "id",
+                        description = "id of the review",
+                        defaultValue = "1")
+            })
+        },
         security = @SecurityRequirement(
                      name = "reviewoauth2",
                      scopes = "write:reviews"),
@@ -403,12 +407,30 @@ public class ReviewResource {
                             )
         },
         requestBody = @RequestBody(
-                ref = "#/components/requestBodies/review"
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(
+                    implementation = Review.class),
+                examples = @ExampleObject(
+                    name = "review",
+                    summary = "External review example",
+                    externalValue = "http://foo.bar/examples/review-example.json"
+                    )
+                ),
+            required = true,
+            description = "example review to add"
         )
     )
     @Consumes("application/json")
     @Produces("application/json")
-    public Response createReview(Review review) {
+    public Response createReview(
+        @Parameter(
+            description = "review to create",
+            required = true,
+            content = @Content(
+                mediaType = "application/json",
+                schema = @Schema(implementation = Review.class)))
+    Review review) {
         reviews.put(currentId, review);
         return Response.status(Status.CREATED).entity("{\"id\":" + currentId++ + "}").build();
     }
@@ -419,6 +441,7 @@ public class ReviewResource {
         method = "delete",
         summary="Delete a Review with ID",
         operationId = "deleteReview",
+        tags = {"review"},
         responses={
             @APIResponse(
                 responseCode="200",
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
index fcc1817..f51043f 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/airlines/resources/UserResource.java
@@ -216,7 +216,6 @@ public class UserResource {
     @POST
     @Path("/createWithArray")
     @Tag(ref="user")
-    @Tag(ref="create")
     @Operation(
         method = "post",
         summary = "Creates list of users with given input array", //Array of User objects
@@ -270,10 +269,8 @@ public class UserResource {
         }
 
     @POST
-    @Path("/createWithList")
-    @Tag(ref="user")
-    @Tags(refs="create")
-    @Operation(
+      @Path("/createWithList")
+      @Operation(
         method = "post",
         summary = "Creates list of users with given input list", //List of User objects
         operationId = "createUsersFromList",
@@ -429,7 +426,10 @@ public class UserResource {
                 })
     public Response getUserByName(
         @Parameter(
-            ref= "username"
+            name = "username",
+            description = "The name that needs to be fetched. Use Bob1 for testing.",
+            schema = @Schema(type = SchemaType.STRING),
+            required = true
             )
         @PathParam("username") String userName) throws ApiException {
             User user = userData.findUserByName(userName);
@@ -565,7 +565,7 @@ public class UserResource {
         method = "get",
         summary = "Logs out current logged in user session",
         operationId = "logOutUser",
-        /* tags = {"user"}, // intentionally removed to have a method with no tags */
+        tags = {"user"},
         externalDocs = @ExternalDocumentation(
             description = "Policy on user security.",
             url = "http://exampleurl.com/policy"
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java
index 0cf0496..e2a6d63 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/apps/petstore/resource/PetResource.java
@@ -136,7 +136,6 @@ public class PetResource {
             name = "petId",
             description = "ID of pet that needs to be fetched",
             required = true,
-            example = "1",
             schema = @Schema(
                 implementation = Long.class,
                 maximum = "101",


Test patch:
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/EndpointTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/EndpointTest.java
index c411caa..2858613 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/EndpointTest.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/EndpointTest.java
@@ -17,27 +17,15 @@
 package org.eclipse.microprofile.openapi.tck;
 
 import static io.restassured.RestAssured.given;
-import static org.hamcrest.Matchers.both;
-import static org.hamcrest.Matchers.contains;
-import static org.hamcrest.Matchers.containsInAnyOrder;
 import static org.hamcrest.Matchers.containsString;
-import static org.hamcrest.Matchers.either;
-import static org.hamcrest.Matchers.empty;
 import static org.hamcrest.Matchers.equalTo;
-import static org.hamcrest.Matchers.hasItems;
-import static org.hamcrest.Matchers.hasKey;
-import static org.hamcrest.Matchers.hasSize;
-import static org.hamcrest.Matchers.not;
-import static org.hamcrest.Matchers.notNullValue;
-import static org.hamcrest.collection.IsMapWithSize.aMapWithSize;
 
 import java.io.File;
 import java.net.MalformedURLException;
 import java.net.URL;
-import java.util.ArrayList;
-import java.util.List;
 
 import org.eclipse.microprofile.openapi.tck.utils.YamlToJsonConverterServlet;
+import org.hamcrest.Matchers;
 import org.jboss.arquillian.container.test.api.Deployment;
 import org.jboss.arquillian.container.test.api.RunAsClient;
 import org.jboss.arquillian.junit.Arquillian;
@@ -88,12 +76,11 @@ public class EndpointTest {
             RestAssured.authentication = RestAssured.basic(userName, password);
             RestAssured.useRelaxedHTTPSValidation();
         }
-        RestAssured.defaultParser = Parser.JSON;
     }
-
+    
     @Before
     public void setUpTest() {
-        vr = given().when().get("/proxy").then().statusCode(200);
+        vr = given().when().get("/proxy").then().parser("", Parser.JSON).statusCode(200);
     }
 
     @Deployment(name = "proxy")
@@ -107,15 +94,14 @@ public class EndpointTest {
                 .addAsLibraries(new File("./lib/jackson-databind-2.9.2.jar"))
                 .addAsLibraries(new File("./lib/jackson-annotations-2.9.1.jar"))
                 .addAsLibraries(new File("./lib/snakeyaml-1.18.jar"))
-                .addAsLibraries(new File("./lib/commons-logging-1.2.jar"))
-                .addAsLibraries(new File("./lib/commons-lang3-3.4.jar"));
+                .addAsLibraries(new File("./lib/commons-logging-1.2.jar"));
     }
 
     @Deployment(name = "airlines")
     public static WebArchive createDeployment() {
         return ShrinkWrap.create(WebArchive.class, "airlines.war")
                 .addPackages(true, "org.eclipse.microprofile.openapi.apps.airlines")
-                .addAsManifestResource("openapi.yaml", "openapi/openapi.yaml");
+                .addAsManifestResource("openapi.yaml", "openapi.yaml");
     }
 
     @Test
@@ -136,7 +122,7 @@ public class EndpointTest {
     @RunAsClient
     public void testContact() {
         vr.body("info.contact.name", equalTo("AirlinesRatingApp API Support"));
-        vr.body("info.contact.url", equalTo("http://exampleurl.com/contact"));
+        vr.body("info.contact.url", equalTo("https://github.com/microservices-api/oas3-airlines"));
         vr.body("info.contact.email", equalTo("techsupport@airlinesratingapp.com"));
     }
 
@@ -157,324 +143,6 @@ public class EndpointTest {
     @Test
     @RunAsClient
     public void testServer() {
-        vr.body("servers", hasSize(2));
-        vr.body("servers.url", hasSize(2));
-
-        String url = "https://{username}.gigantic-server.com:{port}/{basePath}";
-        String serverPath = "servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("The production API server"));
-        vr.body(serverPath + ".variables", aMapWithSize(4));
-        vr.body(serverPath + ".variables.username.description", equalTo("Reviews of the app by users"));
-        vr.body(serverPath + ".variables.username.default", equalTo("user1"));
-        vr.body(serverPath + ".variables.username.enum", containsInAnyOrder("user1", "user2"));
-        vr.body(serverPath + ".variables.port.description", equalTo("Booking data"));
-        vr.body(serverPath + ".variables.port.default", equalTo("8443"));
-        vr.body(serverPath + ".variables.user.description", equalTo("User data"));
-        vr.body(serverPath + ".variables.user.default", equalTo("user"));
-        vr.body(serverPath + ".variables.basePath.default", equalTo("v2"));
-
-        url = "https://test-server.com:80/basePath";
-        serverPath = "servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("The test API server"));
-
-        // Testing @Servers and @Server defined on top of a class with @Server
-        // defined in an operation
-        // org.eclipse.microprofile.openapi.apps.airlines.resources.ReviewResource
-        vr.body("paths.'/reviews/{id}'.delete.servers", hasSize(3));
-        vr.body("paths.'/reviews/{id}'.delete.servers.url", hasSize(3));
-
-        url = "https://gigantic-server.com:443";
-        serverPath = "paths.'/reviews/{id}'.delete.servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("Secure server"));
-
-        url = "http://gigantic-server.com:80";
-        serverPath = "paths.'/reviews/{id}'.delete.servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("Unsecure server"));
-        vr.body(serverPath + ".variables", either(not(empty())).or(notNullValue()));
-
-        url = "{protocol}://test-server.com";
-        serverPath = "paths.'/reviews/{id}'.delete.servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("The production API server"));
-        vr.body(serverPath + ".variables", aMapWithSize(1));
-        vr.body(serverPath + ".variables.proxyPath.description", equalTo("Base path of the proxy"));
-        vr.body(serverPath + ".variables.proxyPath.default", equalTo("http"));
-        vr.body(serverPath + ".variables.proxyPath.enum", containsInAnyOrder("http", "https"));
-
-        // Testing two @Server defined in an @operation annotation on a method
-        // org.eclipse.microprofile.openapi.apps.airlines.resources.ReviewResource.createReview(Review)
-        vr.body("paths.'/reviews'.post.servers", hasSize(2));
-        vr.body("paths.'/reviews'.post.servers.url", hasSize(2));
-        url = "localhost:9080/{proxyPath}/reviews/id";
-        serverPath = "paths.'/reviews'.post.servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("view of all the reviews"));
-        vr.body(serverPath + ".variables", aMapWithSize(1));
-        vr.body(serverPath + ".variables.proxyPath.description", equalTo("Base path of the proxy"));
-        vr.body(serverPath + ".variables.proxyPath.default", equalTo("proxy"));
-        url = "http://random.url/reviews";
-        serverPath = "paths.'/reviews'.post.servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("random text"));
-
-        // Testing two @Server defined on top of a class
-        // org.eclipse.microprofile.openapi.apps.airlines.resources.BookingResource
-        vr.body("paths.'/bookings'.get.servers", hasSize(2));
-        vr.body("paths.'/bookings'.get.servers.url", hasSize(2));
-
-        url = "https://gigantic-server.com:80";
-        serverPath = "paths.'/bookings'.get.servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("Secure server"));
-        vr.body(serverPath + ".variables", either(not(empty())).or(notNullValue()));
-
-        url = "https://gigantic-server.com:443";
-        serverPath = "paths.'/bookings'.get.servers.find { it.url == '" + url + "' }";
-        vr.body(serverPath + ".description", equalTo("Unsecure server"));
-        vr.body(serverPath + ".variables", either(not(empty())).or(notNullValue()));
-    }
-
-    @Test
-    @RunAsClient
-    public void testOperationAirlinesResource() {
-        vr.body("paths.'/'.get.summary", equalTo("Retrieve all available airlines"));
-        vr.body("paths.'/'.get.operationId", equalTo("getAirlines"));
-    }
-
-    @Test
-    @RunAsClient
-    public void testOperationAvailabilityResource() {
-        vr.body("paths.'/availability'.get.summary", equalTo("Retrieve all available flights"));
-        vr.body("paths.'/availability'.get.operationId", equalTo("getFlights"));
-    }
-
-    @Test
-    @RunAsClient
-    public void testOperationBookingResource() {
-        vr.body("paths.'/bookings'.get.summary", equalTo("Retrieve all bookings for current user"));
-        vr.body("paths.'/bookings'.get.operationId", equalTo("getAllBookings"));
-
-        vr.body("paths.'/bookings'.post.summary", equalTo("Create a booking"));
-        vr.body("paths.'/bookings'.post.description", equalTo("Create a new booking record with the booking information provided."));
-        vr.body("paths.'/bookings'.post.operationId", equalTo("createBooking"));
-
-        vr.body("paths.'/bookings/{id}'.get.summary", equalTo("Get a booking with ID"));
-        vr.body("paths.'/bookings/{id}'.get.operationId", equalTo("getBookingById"));
-
-        vr.body("paths.'/bookings/{id}'.put.summary", equalTo("Update a booking with ID"));
-        vr.body("paths.'/bookings/{id}'.put.operationId", equalTo("updateBookingId"));
-
-        vr.body("paths.'/bookings/{id}'.delete.summary", equalTo("Delete a booking with ID"));
-        vr.body("paths.'/bookings/{id}'.delete.operationId", equalTo("deleteBookingById"));
-    }
-
-    @Test
-    @RunAsClient
-    public void testOperationReviewResource() {
-        vr.body("paths.'/reviews'.get.summary", equalTo("get all the reviews"));
-        vr.body("paths.'/reviews'.get.operationId", equalTo("getAllReviews"));
-
-        vr.body("paths.'/reviews'.post.summary", equalTo("Create a Review"));
-        vr.body("paths.'/reviews'.post.operationId", equalTo("createReview"));
-
-        vr.body("paths.'/reviews/{id}'.get.summary", equalTo("Get a review with ID"));
-        vr.body("paths.'/reviews/{id}'.get.operationId", equalTo("getReviewById"));
-
-        vr.body("paths.'/reviews/{id}'.delete.summary", equalTo("Delete a Review with ID"));
-        vr.body("paths.'/reviews/{id}'.delete.operationId", equalTo("deleteReview"));
-
-        vr.body("paths.'/reviews/{user}'.get.summary", equalTo("Get all reviews by user"));
-        vr.body("paths.'/reviews/{user}'.get.operationId", equalTo("getReviewByUser"));
-
-        vr.body("paths.'/reviews/{airline}'.get.summary", equalTo("Get all reviews by airlines"));
-        vr.body("paths.'/reviews/{airline}'.get.operationId", equalTo("getReviewByAirline"));
-
-        vr.body("paths.'/reviews/{user}/{airlines}'.get.summary", equalTo("Get all reviews for an airline by User"));
-        vr.body("paths.'/reviews/{user}/{airlines}'.get.operationId", equalTo("getReviewByAirlineAndUser"));
-    }
-
-    @Test
-    @RunAsClient
-    public void testOperationUserResource() {
-        vr.body("paths.'/user'.post.summary", equalTo("Create user"));
-        vr.body("paths.'/user'.post.description", equalTo("This can only be done by the logged in user."));
-        vr.body("paths.'/user'.post.operationId", equalTo("createUser"));
-
-        vr.body("paths.'/user/createWithArray'.post.summary", equalTo("Creates list of users with given input array"));
-        vr.body("paths.'/user/createWithArray'.post.operationId", equalTo("createUsersFromArray"));
-
-        vr.body("paths.'/user/createWithList'.post.summary", equalTo("Creates list of users with given input list"));
-        vr.body("paths.'/user/createWithList'.post.operationId", equalTo("createUsersFromList"));
-
-        vr.body("paths.'/user/{username}'.put.summary", equalTo("Update user"));
-        vr.body("paths.'/user/{username}'.put.description", equalTo("This can only be done by the logged in user."));
-        vr.body("paths.'/user/{username}'.put.operationId", equalTo("updateUser"));
-
-        vr.body("paths.'/user/{username}'.delete.summary", equalTo("Delete user"));
-        vr.body("paths.'/user/{username}'.delete.description", equalTo("This can only be done by the logged in user."));
-        vr.body("paths.'/user/{username}'.delete.operationId", equalTo("deleteUser"));
-
-        vr.body("paths.'/user/{username}'.get.summary", equalTo("Get user by user name"));
-        vr.body("paths.'/user/{username}'.get.operationId", equalTo("getUserByUserName"));
-
-        vr.body("paths.'/user/{id}'.get.summary", equalTo("Get user by id"));
-        vr.body("paths.'/user/{id}'.get.operationId", equalTo("getUserById"));
-
-        vr.body("paths.'/user/login'.get.summary", equalTo("Logs user into the system"));
-        vr.body("paths.'/user/login'.get.operationId", equalTo("logInUser"));
-
-        vr.body("paths.'/user/logout'.get.summary", equalTo("Logs out current logged in user session"));
-        vr.body("paths.'/user/logout'.get.operationId", equalTo("logOutUser"));
-    }
-
-    @Test
-    @RunAsClient
-    public void testParameter() throws InterruptedException {
-        testAvailabilityGetParamater(vr);
-        testBookingIdMethods(vr);
-        testReviewIdMethods(vr);
-        testUserLoginMethods(vr);
-    }
-
-    private void testUserLoginMethods(ValidatableResponse vr2) {
-        String reviewParameters = "paths.'/user/login'.get.parameters";
-        vr.body(reviewParameters, hasSize(2));
-        vr.body(reviewParameters + ".findAll { it }.name", hasItems("username", "password"));
-        List<String[]> list = new ArrayList<String[]>();
-        list.add(new String[] { "username", "The user name for login" });
-        list.add(new String[] { "password", "The password for login in clear text" });
-
-        for (int i = 0; i < list.size(); i++) {
-            String currentParam = list.get(i)[0];
-            String query = reviewParameters + ".findAll { it.name == '" + currentParam + "' }";
-
-            vr.body(query + ".in", both(hasSize(1)).and(contains("query")));
-            vr.body(query + ".description", both(hasSize(1)).and(contains(list.get(i)[1])));
-            vr.body(query + ".required", both(hasSize(1)).and(contains(true)));
-            vr.body(query + ".schema.type", both(hasSize(1)).and(contains("string")));
-        }
-    }
-
-    private void testReviewIdMethods(ValidatableResponse vr2) {
-        String reviewParameters = "paths.'/reviews/{id}'.get.parameters";
-        vr.body(reviewParameters, hasSize(1));
-        vr.body(reviewParameters + ".findAll { it }.name", contains("id"));
-        vr.body(reviewParameters + ".findAll { it.name == 'id' }.in", both(hasSize(1)).and(contains("path")));
-        // vr.body(reviewParameters + ".findAll { it.name == 'id' }.description", both(hasSize(1)).and(contains("ID of the booking")));
-        vr.body(reviewParameters + ".findAll { it.name == 'id' }.required", both(hasSize(1)).and(contains(true)));
-        vr.body(reviewParameters + ".findAll { it.name == 'id' }.content.'*/*'.schema.type", both(hasSize(1)).and(contains("integer")));
-    }
-
-    private void testBookingIdMethods(ValidatableResponse vr) {
-        String bookingParameters = "paths.'/bookings/{id}'.%s.parameters";
-
-        for (String method : new String[] { "get", "put", "delete" }) {
-            bookingParameters = String.format(bookingParameters, method);
-
-            vr.body(bookingParameters, hasSize(1));
-            vr.body(bookingParameters + ".findAll { it }.name", contains("id"));
-
-            vr.body(bookingParameters + ".findAll { it.name == 'id' }.in", both(hasSize(1)).and(contains("path")));
-            // TODO
-            vr.body(bookingParameters + ".findAll { it.name == 'id' }.description", both(hasSize(1)).and(contains("ID of the booking")));
-            vr.body(bookingParameters + ".findAll { it.name == 'id' }.required", both(hasSize(1)).and(contains(true)));
-            vr.body(bookingParameters + ".findAll { it.name == 'id' }.schema.type", both(hasSize(1)).and(contains("integer")));
-        }
-    }
-
-    private void testAvailabilityGetParamater(ValidatableResponse vr) {
-        String availabilityParameters = "paths.'/availability'.get.parameters";
-
-        vr.body(availabilityParameters, hasSize(6));
-        vr.body(availabilityParameters + ".findAll { it }.name",
-                hasItems("departureDate", "airportFrom", "returningDate", "airportTo", "numberOfAdults", "numberOfChildren"));
-
-        List<String[]> list = new ArrayList<String[]>();
-        list.add(new String[] { "departureDate", "Customer departure date" });
-        list.add(new String[] { "airportFrom", "Airport the customer departs from" });
-        list.add(new String[] { "returningDate", "Customer return date" });
-        list.add(new String[] { "airportTo", "Airport the customer returns to" });
-        list.add(new String[] { "numberOfAdults", "Number of adults on the flight" });
-        list.add(new String[] { "numberOfChildren", "Number of children on the flight" });
-
-        for (int i = 0; i < list.size(); i++) {
-            String currentParam = list.get(i)[0];
-            String query = availabilityParameters + ".findAll { it.name == '" + currentParam + "' }";
-
-            vr.body(query + ".in", both(hasSize(1)).and(contains("query")));
-            vr.body(query + ".description", both(hasSize(1)).and(contains(list.get(i)[1])));
-            vr.body(query + ".required", both(hasSize(1)).and(contains(true)));
-            vr.body(query + ".schema.type", both(hasSize(1)).and(contains("string")));
-        }
-
-        vr.body(availabilityParameters + ".findAll { it.name == 'numberOfAdults' }.schema.minimum", both(hasSize(1)).and(contains(0)));
-        vr.body(availabilityParameters + ".findAll { it.name == 'numberOfChildren' }.schema.minimum", both(hasSize(1)).and(contains(0)));
-    }
-
-    @Test
-    @RunAsClient
-    public void testExplode() throws InterruptedException {
-        String explode = "paths.'/user/{username}'.put.responses.'200'.content.'application/xml'.encoding.password.explode";
-        vr.body(explode, equalTo(true));
-        explode = "paths.'/user/{username}'.put.responses.'200'.content.'application/xml'.encoding.password.explode";
-        vr.body(explode, equalTo(true));
-    }
-
-    @Test
-    @RunAsClient
-    public void testSecurityRequirement() throws InterruptedException {
-        vr.body("security.airlinesRatingApp_auth[0][0]", equalTo(null));
-
-        vr.body("paths.'/reviews'.post.security.reviewoauth2[0][0]", equalTo("write:reviews"));
-        vr.body("paths.'/reviews'.post.security.reviewoauth2", hasSize(1));
-
-        vr.body("paths.'/user'.post.security.httpTestScheme[0][0]", equalTo("write:users"));
-        vr.body("paths.'/user'.post.security.httpTestScheme", hasSize(1));
-
-        vr.body("paths.'/user/createWithArray'.post.security.httpTestScheme[0][0]", equalTo("write:users"));
-        vr.body("paths.'/user/createWithArray'.post.security.httpTestScheme", hasSize(1));
-
-        vr.body("paths.'/user/createWithList'.post.security.httpTestScheme[0][0]", equalTo("write:users"));
-        vr.body("paths.'/user/createWithList'.post.security.httpTestScheme", hasSize(1));
-
-        vr.body("paths.'/user/{username}'.get.security.httpTestScheme[0][0]", equalTo("write:users"));
-        vr.body("paths.'/user/{username}'.get.security.httpTestScheme", hasSize(1));
-
-        vr.body("paths.'/user/{username}'.put.security.httpTestScheme[0][0]", equalTo("write:users"));
-        vr.body("paths.'/user/{username}'.put.security.httpTestScheme", hasSize(1));
-
-        vr.body("paths.'/user/{username}'.delete.security.httpTestScheme[0][0]", equalTo("write:users"));
-        vr.body("paths.'/user/{username}'.delete.security.httpTestScheme", hasSize(1));
-
-        vr.body("paths.'/user/{id}'.get.security.httpTestScheme[0][0]", equalTo("write:users"));
-        vr.body("paths.'/user/{id}'.get.security.httpTestScheme", hasSize(1));
-
-        vr.body("paths.'/user/{login}'.get.security.httpTestScheme[0][0]", equalTo(null));
-        vr.body("paths.'/user/{logout}'.get.security.httpTestScheme[0][0]", equalTo(null));
-    }
-
-    @Test
-    @RunAsClient
-    public void testSecuritySchemesInComponents() throws InterruptedException {
-        String s = "components.securitySchemes";
-        vr.body(s, hasKey("httpTestScheme"));
-        vr.body(s, hasKey("airlinesRatingApp_auth"));
-        vr.body(s, hasKey("reviewoauth2"));
-
-        vr.body(s + ".httpTestScheme.type", equalTo("http"));
-        vr.body(s + ".httpTestScheme.description", equalTo("user security scheme"));
-        vr.body(s + ".httpTestScheme.name", equalTo("httpTestScheme"));
-        vr.body(s + ".httpTestScheme.scheme", equalTo("testScheme"));
-
-        vr.body(s + ".airlinesRatingApp_auth.type", equalTo("apiKey"));
-        vr.body(s + ".airlinesRatingApp_auth.description", equalTo("authentication needed to access Airlines app"));
-        vr.body(s + ".airlinesRatingApp_auth.name", equalTo("airlinesRatingApp_auth"));
-        vr.body(s + ".airlinesRatingApp_auth.in", equalTo("header"));
-
-        vr.body(s + ".reviewoauth2.type", equalTo("oauth2"));
-        vr.body(s + ".reviewoauth2.description", equalTo("authentication needed to create and delete reviews"));
-        vr.body(s + ".reviewoauth2.name", equalTo("reviewoauth2"));
-
-        String t = "components.securitySchemes.reviewoauth2.flows";
-        vr.body(t + ".implicit.authorizationUrl", equalTo("https://example.com/api/oauth/dialog"));
-        vr.body(t + ".implicit.scopes.'write:reviews'", equalTo("create a review"));
-        vr.body(t + ".authorizationCode.authorizationUrl", equalTo("https://example.com/api/oauth/dialog"));
-        vr.body(t + ".authorizationCode.tokenUrl", equalTo("https://example.com/api/oauth/token"));
+        vr.body("servers[*]", Matchers.hasSize(8));
     }
 }
diff --git a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
index b696131..cd941bf 100644
--- a/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
+++ b/tck/src/main/java/org/eclipse/microprofile/openapi/tck/ModelConstructionTest.java
@@ -162,7 +162,52 @@ public class ModelConstructionTest {
     
     @Test
     public void componentsTest() {
-        processConstructible(Components.class);
+        final Components c = processConstructible(Components.class);
+        
+        final String callbackKey = "myCallback";
+        final Callback callbackValue = createConstructibleInstance(Callback.class);
+        checkSameObject(c, c.addCallback(callbackKey, callbackValue));
+        checkMapEntry(c.getCallbacks(), callbackKey, callbackValue);
+        
+        final String exampleKey = "myExample";
+        final Example exampleValue = createConstructibleInstance(Example.class);
+        checkSameObject(c, c.addExample(exampleKey, exampleValue));
+        checkMapEntry(c.getExamples(), exampleKey, exampleValue);
+        
+        final String headerKey = "myHeader";
+        final Header headerValue = createConstructibleInstance(Header.class);
+        checkSameObject(c, c.addHeader(headerKey, headerValue));
+        checkMapEntry(c.getHeaders(), headerKey, headerValue);
+        
+        final String linkKey = "myLink";
+        final Link linkValue = createConstructibleInstance(Link.class);
+        checkSameObject(c, c.addLink(linkKey, linkValue));
+        checkMapEntry(c.getLinks(), linkKey, linkValue);
+        
+        final String parameterKey = "myParameter";
+        final Parameter<?> parameterValue = createConstructibleInstance(CookieParameter.class);
+        checkSameObject(c, c.addParameter(parameterKey, parameterValue));
+        checkMapEntry(c.getParameters(), parameterKey, parameterValue);
+        
+        final String requestBodyKey = "myRequestBody";
+        final RequestBody requestBodyValue = createConstructibleInstance(RequestBody.class);
+        checkSameObject(c, c.addRequestBody(requestBodyKey, requestBodyValue));
+        checkMapEntry(c.getRequestBodies(), requestBodyKey, requestBodyValue);
+        
+        final String responseKey = "myResponse";
+        final APIResponse responseValue = createConstructibleInstance(APIResponse.class);
+        checkSameObject(c, c.addResponse(responseKey, responseValue));
+        checkMapEntry(c.getResponses(), responseKey, responseValue);
+        
+        final String schemaKey = "mySchema";
+        final Schema schemaValue = createConstructibleInstance(Schema.class);
+        checkSameObject(c, c.addSchema(schemaKey, schemaValue));
+        checkMapEntry(c.getSchemas(), schemaKey, schemaValue);
+        
+        final String securitySchemeKey = "mySecurityScheme";
+        final SecurityScheme securitySchemeValue = createConstructibleInstance(SecurityScheme.class);
+        checkSameObject(c, c.addSecurityScheme(securitySchemeKey, securitySchemeValue));
+        checkMapEntry(c.getSecuritySchemes(), securitySchemeKey, securitySchemeValue);
     }
     
     @Test
@@ -172,27 +217,87 @@ public class ModelConstructionTest {
     
     @Test
     public void openAPITest() {
-        processConstructible(OpenAPI.class);
+        final OpenAPI o = processConstructible(OpenAPI.class);
+        
+        final SecurityRequirement sr = createConstructibleInstance(SecurityRequirement.class);
+        checkSameObject(o, o.addSecurityRequirement(sr));
+        checkListEntry(o.getSecurity(), sr);
+        
+        final Server s = createConstructibleInstance(Server.class);
+        checkSameObject(o, o.addServer(s));
+        checkListEntry(o.getServers(), s);
+        
+        final Tag t = createConstructibleInstance(Tag.class);
+        checkSameObject(o, o.addTag(t));
+        checkListEntry(o.getTags(), t);
     }
     
     @Test
     public void operationTest() {
-        processConstructible(Operation.class);
+        final Operation o = processConstructible(Operation.class);
+        
+        final Parameter<?> p = createConstructibleInstance(CookieParameter.class);
+        checkSameObject(o, o.addParameter(p));
+        checkListEntry(o.getParameters(), p);
+        
+        final SecurityRequirement sr = createConstructibleInstance(SecurityRequirement.class);
+        checkSameObject(o, o.addSecurityRequirement(sr));
+        checkListEntry(o.getSecurity(), sr);
+        
+        final Server s = createConstructibleInstance(Server.class);
+        checkSameObject(o, o.addServer(s));
+        checkListEntry(o.getServers(), s);
+        
+        final String tag = new String("myTag");
+        checkSameObject(o, o.addTag(tag));
+        checkListEntry(o.getTags(), tag);
     }
     
     @Test
     public void pathItemTest() {
-        processConstructible(PathItem.class);
+        final PathItem pi = processConstructible(PathItem.class);
+        
+        final Parameter<?> p = createConstructibleInstance(CookieParameter.class);
+        checkSameObject(pi, pi.addParameter(p));
+        checkListEntry(pi.getParameters(), p);
+        
+        final Server s = createConstructibleInstance(Server.class);
+        checkSameObject(pi, pi.addServer(s));
+        checkListEntry(pi.getServers(), s);
     }
     
     @Test
     public void pathsTest() {
-        processConstructible(Paths.class);
+        final Paths p = processConstructible(Paths.class);
+        
+        final String pathItemKey = "myPathItem";
+        final PathItem pathItemValue = createConstructibleInstance(PathItem.class);
+        checkSameObject(p, p.addPathItem(pathItemKey, pathItemValue));
+        checkMapEntry(p, pathItemKey, pathItemValue);
+        
+        final String pathItemKey2 = "myPathItem2";
+        final PathItem pathItemValue2 = createConstructibleInstance(PathItem.class);
+        Assert.assertNull("No previous mapping expected.", p.put(pathItemKey2, pathItemValue2));
+        checkMapEntry(p, pathItemKey2, pathItemValue2);
+        
+        Assert.assertEquals("The map is expected to contain two entries.", 2, p.size());
     }
     
     @Test
     public void callbackTest() {
-        processConstructible(Callback.class);
+        final Callback c = processConstructible(Callback.class);
+        
+        final String pathItemKey = "myPathItem";
+        final PathItem pathItemValue = createConstructibleInstance(PathItem.class);
+        checkSameObject(c, c.addPathItem(pathItemKey, pathItemValue));
+        checkMapEntry(c, pathItemKey, pathItemValue);
+        
+        final String pathItemKey2 = "myPathItem2";
+        final PathItem pathItemValue2 = createConstructibleInstance(PathItem.class);
+        Assert.assertNull("No previous mapping expected.", c.put(pathItemKey2, pathItemValue2));
+        checkMapEntry(c, pathItemKey2, pathItemValue2);
+        
+        Assert.assertEquals("The map is expected to contain two entries.", 2, c.size());
     }
     
     @Test
@@ -202,7 +307,12 @@ public class ModelConstructionTest {
     
     @Test
     public void headerTest() {
-        processConstructible(Header.class);
+        final Header h = processConstructible(Header.class);
+        
+        final String exampleKey = "myExample";
+        final Example exampleValue = createConstructibleInstance(Example.class);
+        checkSameObject(h, h.addExample(exampleKey, exampleValue));
+        checkMapEntry(h.getExamples(), exampleKey, exampleValue);
     }
     
     @Test
@@ -222,17 +332,39 @@ public class ModelConstructionTest {
     
     @Test
     public void linkTest() {
-        processConstructible(Link.class);
+        final Link l = processConstructible(Link.class);
+        
+        final String parameterKey = "myParameter";
+        final Parameter<?> parameterValue = createConstructibleInstance(CookieParameter.class);
+        checkSameObject(l, l.addParameter(parameterKey, parameterValue));
+        checkMapEntry(l.getParameters(), parameterKey, parameterValue);
     }
     
     @Test
     public void contentTest() {
-        processConstructible(Content.class);
+        final Content c = processConstructible(Content.class);
+        
+        final String mediaTypeKey = "myPathItem";
+        final MediaType mediaTypeValue = createConstructibleInstance(MediaType.class);
+        checkSameObject(c, c.addMediaType(mediaTypeKey, mediaTypeValue));
+        checkMapEntry(c, mediaTypeKey, mediaTypeValue);
+        
+        final String mediaTypeKey2 = "myPathItem2";
+        final MediaType mediaTypeValue2 = createConstructibleInstance(MediaType.class);
+        Assert.assertNull("No previous mapping expected.", c.put(mediaTypeKey2, mediaTypeValue2));
+        checkMapEntry(c, mediaTypeKey2, mediaTypeValue2);
+        
+        Assert.assertEquals("The map is expected to contain two entries.", 2, c.size());
     }
     
     @Test
     public void discriminatorTest() {
-        processConstructible(Discriminator.class);
+        final Discriminator d = processConstructible(Discriminator.class);
+        
+        final String key = "myKey";
+        final String value = new String("myValue");
+        checkSameObject(d, d.addMapping(key, value));
+        checkMapEntry(d.getMapping(), key, value);
     }
     
     @Test
@@ -242,12 +374,47 @@ public class ModelConstructionTest {
     
     @Test
     public void mediaTypeTest() {
-        processConstructible(MediaType.class);
+        final MediaType mt = processConstructible(MediaType.class);
+        
+        final String encodingKey = "myEncoding";
+        final Encoding encodingValue = createConstructibleInstance(Encoding.class);
+        checkSameObject(mt, mt.addEncoding(encodingKey, encodingValue));
+        checkMapEntry(mt.getEncoding(), encodingKey, encodingValue);
+        
+        final String exampleKey = "myExample";
+        final Example exampleValue = createConstructibleInstance(Example.class);
+        checkSameObject(mt, mt.addExample(exampleKey, exampleValue));
+        checkMapEntry(mt.getExamples(), exampleKey, exampleValue);
     }
     
     @Test
     public void schemaTest() {
-        processConstructible(Schema.class);
+        final Schema s = processConstructible(Schema.class);
+        
+        final Schema allOf = createConstructibleInstance(Schema.class);
+        checkSameObject(s, s.addAllOf(allOf));
+        checkListEntry(s.getAllOf(), allOf);
+        
+        final Schema anyOf = createConstructibleInstance(Schema.class);
+        checkSameObject(s, s.addAnyOf(anyOf));
+        checkListEntry(s.getAnyOf(), anyOf);
+        
+        final String enumeration = new String("enumValue");
+        checkSameObject(s, s.addEnumeration(enumeration));
+        checkListEntry(s.getEnumeration(), enumeration);
+        
+        final Schema oneOf = createConstructibleInstance(Schema.class);
+        checkSameObject(s, s.addOneOf(oneOf));
+        checkListEntry(s.getOneOf(), oneOf);
+        
+        final String propertySchemaKey = "myPropertySchemaKey";
+        final Schema propertySchemaValue = createConstructibleInstance(Schema.class);
+        checkSameObject(s, s.addProperty(propertySchemaKey, propertySchemaValue));
+        checkMapEntry(s.getProperties(), propertySchemaKey, propertySchemaValue);
+        
+        final String required = new String("required");
+        checkSameObject(s, s.addRequired(required));
+        checkListEntry(s.getRequired(), required);
     }
     
     @Test
@@ -258,33 +425,25 @@ public class ModelConstructionTest {
     @Test
     public void cookieParameterTest() {
         final CookieParameter cp = processConstructible(CookieParameter.class);
-        // Check value of read-only 'in' property.
-        Assert.assertEquals("The value of the 'in' property is expected to be 'cookie'.",
-                Parameter.In.COOKIE, cp.getIn());
+        checkParameterCommon(cp, Parameter.In.COOKIE, "cookie");
     }
-    
+
     @Test
     public void headerParameterTest() {
         final HeaderParameter hp = processConstructible(HeaderParameter.class);
-        // Check value of read-only 'in' property.
-        Assert.assertEquals("The value of the 'in' property is expected to be 'header'.",
-                Parameter.In.HEADER, hp.getIn());
+        checkParameterCommon(hp, Parameter.In.HEADER, "header");
     }
     
     @Test
     public void pathParameterTest() {
         final PathParameter pp = processConstructible(PathParameter.class);
-        // Check value of read-only 'in' property.
-        Assert.assertEquals("The value of the 'in' property is expected to be 'path'.",
-                Parameter.In.PATH, pp.getIn());
+        checkParameterCommon(pp, Parameter.In.PATH, "path");
     }
     
     @Test
     public void queryParameterTest() {
         final QueryParameter qp = processConstructible(QueryParameter.class);
-        // Check value of read-only 'in' property.
-        Assert.assertEquals("The value of the 'in' property is expected to be 'query'.",
-                Parameter.In.QUERY, qp.getIn());
+        checkParameterCommon(qp, Parameter.In.QUERY, "query");
     }
     
     @Test
@@ -294,12 +453,34 @@ public class ModelConstructionTest {
     
     @Test
     public void apiResponseTest() {
-        processConstructible(APIResponse.class);
+        final APIResponse response = processConstructible(APIResponse.class);
+        
+        final String headerKey = "myHeaderKey";
+        final Header headerValue = createConstructibleInstance(Header.class);
+        checkSameObject(response, response.addHeader(headerKey, headerValue));
+        checkMapEntry(response.getHeaders(), headerKey, headerValue);
+        
+        final String linkKey = "myLinkKey";
+        final Link linkValue = createConstructibleInstance(Link.class);
+        checkSameObject(response, response.addLink(linkKey, linkValue));
+        checkMapEntry(response.getLinks(), linkKey, linkValue);
     }
     
     @Test
     public void apiResponsesTest() {
-        processConstructible(APIResponses.class);
+        final APIResponses responses = processConstructible(APIResponses.class);
+        
+        final String responseKey = "myResponse";
+        final APIResponse responseValue = createConstructibleInstance(APIResponse.class);
+        checkSameObject(responses, responses.addApiResponse(responseKey, responseValue));
+        checkMapEntry(responses, responseKey, responseValue);
+        
+        final String responseKey2 = "myResponse2";
+        final APIResponse responseValue2 = createConstructibleInstance(APIResponse.class);
+        Assert.assertNull("No previous mapping expected.", responses.put(responseKey2, responseValue2));
+        checkMapEntry(responses, responseKey2, responseValue2);
+        
+        Assert.assertEquals("The map is expected to contain two entries.", 2, responses.size());
     }
     
     @Test
@@ -314,12 +495,36 @@ public class ModelConstructionTest {
     
     @Test
     public void scopesTest() {
-        processConstructible(Scopes.class);
+        final Scopes s = processConstructible(Scopes.class);
+        
+        final String scopeKey = "myScope";
+        final String scopeValue = new String("myDescription");
+        checkSameObject(s, s.addScope(scopeKey, scopeValue));
+        checkMapEntry(s, scopeKey, scopeValue);
+        
+        final String scopeKey2 = "myScope2";
+        final String scopeValue2 = new String("myDescription2");
+        Assert.assertNull("No previous mapping expected.", s.put(scopeKey2, scopeValue2));
+        checkMapEntry(s, scopeKey2, scopeValue2);
+        
+        Assert.assertEquals("The map is expected to contain two entries.", 2, s.size());
     }
     
     @Test
     public void securityRequirementTest() {
-        processConstructible(SecurityRequirement.class);
+        final SecurityRequirement sr = processConstructible(SecurityRequirement.class);
+        
+        final String schemeKey = "myResponse";
+        final List<String> schemeValue = new ArrayList<String>();
+        checkSameObject(sr, sr.addScheme(schemeKey, schemeValue));
+        checkMapEntry(sr, schemeKey, schemeValue);
+        
+        final String schemeKey2 = "myResponse2";
+        final List<String> schemeValue2 = new ArrayList<String>();
+        Assert.assertNull("No previous mapping expected.", sr.put(schemeKey2, schemeValue2));
+        checkMapEntry(sr, schemeKey2, schemeValue2);
+        
+        Assert.assertEquals("The map is expected to contain two entries.", 2, sr.size());
     }
     
     @Test
@@ -334,12 +539,28 @@ public class ModelConstructionTest {
     
     @Test
     public void serverVariableTest() {
-        processConstructible(ServerVariable.class);
+        final ServerVariable sv = processConstructible(ServerVariable.class);
+        
+        final String enumeration = new String("enumValue");
+        checkSameObject(sv, sv.addEnumeration(enumeration));
+        checkListEntry(sv.getEnumeration(), enumeration);
     }
     
     @Test
     public void serverVariablesTest() {
-        processConstructible(ServerVariables.class);
+        final ServerVariables svs = processConstructible(ServerVariables.class);
+        
+        final String varKey = "myServerVariable";
+        final ServerVariable varValue = createConstructibleInstance(ServerVariable.class);
+        checkSameObject(svs, svs.addServerVariable(varKey, varValue));
+        checkMapEntry(svs, varKey, varValue);
+        
+        final String varKey2 = "myServerVariable2";
+        final ServerVariable varValue2 = createConstructibleInstance(ServerVariable.class);
+        Assert.assertNull("No previous mapping expected.", svs.put(varKey2, varValue2));
+        checkMapEntry(svs, varKey2, varValue2);
+        
+        Assert.assertEquals("The map is expected to contain two entries.", 2, svs.size());
     }
     
     @Test
@@ -403,11 +624,26 @@ public class ModelConstructionTest {
         final String myRef1 = createReference(r, "myRef1");
         r.setRef(myRef1);
         Assert.assertEquals("The return value of getRef() is expected to be equal to the value that was set.", myRef1, r.getRef());
+        // Check that the short name ref value can be set using the setter method and that the getter method returns the expanded value.
+        if (!(r instanceof PathItem)) {
+            final String shortName = "myRef2";
+            final String myRef2 = createReference(r, shortName);
+            r.setRef(shortName);
+            Assert.assertEquals("The return value of getRef() is expected to be a fully expanded name.", myRef2, r.getRef());
+        }
         // Check that the ref value can be set using the builder method and that the getter method returns the same value.
-        final String myRef2 = createReference(r, "myRef2");
-        final Reference<?> self = r.ref(myRef2);
+        final String myRef3 = createReference(r, "myRef3");
+        final Reference<?> self = r.ref(myRef3);
         Assert.assertSame("The return value of ref() is expected to return the current instance.", r, self);
-        Assert.assertEquals("The return value of getRef() is expected to be equal to the value that was set.", myRef2, r.getRef());
+        Assert.assertEquals("The return value of getRef() is expected to be equal to the value that was set.", myRef3, r.getRef());
+        // Check that the short name ref value can be set using the builder method and that the getter method returns the expanded value.
+        if (!(r instanceof PathItem)) {
+            final String shortName = "myRef4";
+            final String myRef4 = createReference(r, shortName);
+            final Reference<?> self2 = r.ref(shortName);
+            Assert.assertSame("The return value of ref() is expected to return the current instance.", r, self2);
+            Assert.assertEquals("The return value of getRef() is expected to be a fully expanded name.", myRef4, r.getRef());
+        }
     }
     
     private void processConstructibleProperty(Constructible o, Property p, Class<?> enclosingInterface) {
@@ -607,4 +843,31 @@ public class ModelConstructionTest {
         });
         return properties;
     }
+    
+    private <T extends Parameter<T>> void checkParameterCommon(Parameter<T> p, Parameter.In expectedIn, String name) {
+        final String exampleKey = "myExample";
+        final Example exampleValue = createConstructibleInstance(Example.class);
+        checkSameObject(p, p.addExample(exampleKey, exampleValue));
+        checkMapEntry(p.getExamples(), exampleKey, exampleValue);
+        
+        // Check value of read-only 'in' property.
+        Assert.assertEquals("The value of the 'in' property is expected to be '" + name + "'.",
+                expectedIn, p.getIn());
+    }
+    
+    private <T> void checkMapEntry(Map<String,T> map, String key, T value) {
+        Assert.assertNotNull("The map must not be null.", map);
+        Assert.assertTrue("The map is expected to contain the key: " + key, map.containsKey(key));
+        Assert.assertSame("The value associated with the key: " + key + " is expected to be the same one that was added.",
+                value, map.get(key));
+    }
+    
+    private <T> void checkListEntry(List<T> list, T value) {
+        Assert.assertNotNull("The list must not be null.", list);
+        Assert.assertTrue("The list is expected to contain the value: " + value, list.stream().anyMatch((v) -> v == value));
+    }
+    
+    private <T> void checkSameObject(T expected, T actual) {
+        Assert.assertSame("Expecting same object.", expected, actual);
+    }
 }