Errors on api-with-examples.yaml example

[tfesenko]

KaiZen shows errors on the api-with-examples.yaml OpenAPI v3 example.

Other examples from this PR are OK.

Probably it's related to the example definition in the JSON Schema which prohibits additional properties. Allowing them fixes three of four validation errors:

--- a/com.reprezen.swagedit.openapi3/src/com/reprezen/swagedit/openapi3/schema/schema_v3.json
+++ b/com.reprezen.swagedit.openapi3/src/com/reprezen/swagedit/openapi3/schema/schema_v3.json
@@ -619,7 +619,7 @@
     "example": {
       "type": "object",
       "description": "Allows sharing examples for operation requests and responses. This object can either be a freeform object, array or primitive value.  To represent examples of media types that cannot naturally represented in the OpenAPI definition, a string value can be used to contain the example with escaping where necessary.",
-      "additionalProperties": false
+      "additionalProperties": true
     },
     "links": {
       "type": "object",

---

Problem markers:

Description	Resource	Path	Location	Type
Failed to match exactly one schema:
 - /definitions/responseOrReference/oneOf/0:
	Failed to match exactly one schema:
	 - /definitions/exampleOrReference/oneOf/0:
		 - object has properties "version" which are not allowed
	 - /definitions/exampleOrReference/oneOf/1:
		 - object has properties "version" which are not allowed
		 - object has missing required properties "$ref"
 - /definitions/responseOrReference/oneOf/1:
	 - object has missing required properties "$ref"
	 - object has properties "content", "description" which are not allowed
	api-with-examples.yaml	/Foo	line 126	Problem
Failed to match exactly one schema:
 - /definitions/responseOrReference/oneOf/0:
	Failed to match exactly one schema:
	 - /definitions/exampleOrReference/oneOf/0:
		 - object has properties "version" which are not allowed
	 - /definitions/exampleOrReference/oneOf/1:
		 - object has properties "version" which are not allowed
		 - object has missing required properties "$ref"
 - /definitions/responseOrReference/oneOf/1:
	 - object has properties "content", "description" which are not allowed
	 - object has missing required properties "$ref"
	api-with-examples.yaml	/Foo	line 82	Problem
Failed to match exactly one schema:
 - /definitions/responseOrReference/oneOf/0:
	Failed to match exactly one schema:
	 - /definitions/exampleOrReference/oneOf/0:
		 - object has properties "versions" which are not allowed
	 - /definitions/exampleOrReference/oneOf/1:
		 - object has properties "versions" which are not allowed
		 - object has missing required properties "$ref"
 - /definitions/responseOrReference/oneOf/1:
	 - object has missing required properties "$ref"
	 - object has properties "content", "description" which are not allowed
	api-with-examples.yaml	/Foo	line 12	Problem
Failed to match exactly one schema:
 - /definitions/responseOrReference/oneOf/0:
	Failed to match exactly one schema:
	 - /definitions/exampleOrReference/oneOf/0:
		 - value of type string is not allowed, value should be of type object
	 - /definitions/exampleOrReference/oneOf/1:
		 - value of type string is not allowed, value should be of type object
 - /definitions/responseOrReference/oneOf/1:
	 - object has missing required properties "$ref"
	 - object has properties "content", "description" which are not allowed
	api-with-examples.yaml	/Foo	line 44	Problem

[tedepstein]

@tfesenko , about this:

Probably it's related to the example definition in the JSON Schema which prohibits additional properties. Allowing them fixes three of four validation errors:

Have we raised this issue on the OpenAPI spec project? We should get a clear answer as to whether the examples are wrong, or the OpenAPI 3 spec needs to be updated.

[tfesenko]

Related to #292 "JSON Schema for OpenAPI v3"

[tfesenko]

The schema seems to be right, and the spec example from the PR should be corrected. additionalProperties should be left prohibited for the examples, just like for all other elements.

So, what's wrong with api-with-examples.yaml?

• Map vs List
  Examples for a response should be a Map[ string, Example Object | Reference Object], but in api-with-examples.yaml, they are a list of example values.
• value/externalValue vs inlining directly
  The example value should be stored in the value property for inline examples, and in the externalValue property for externally defined examples. api-with-examples.yaml defines the values directly under the examples element, instead of using value or externalValue.

Based on this comment, they are aware of this problem:

examples need to be updated to the new construct.

So, we should wait for updated v3 example and should not worry about validation errors in api-with-examples.yaml for now.

[tfesenko]

Fixed in OAI/OpenAPI-Specification#1286
Our api-with-examples.yaml was updated accordingly, an automated test verifies that this spec can be loaded without validation errors.