Meta-Defining JSON Schema inside of an openAPI spec (Version 3.0.2)

[GeraldIr]

The following definition of a json_schema is found in an openAPI specification I'm currently working with:

        "json_schema": {
          "type": "object",
          "title": "JSON Schema",
          "description": "A JSON Schema compliant to [JSON Schema draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or later.\n\nJSON Schemas SHOULD always be dereferenced (i.e. all `$refs` should be resolved).\nThis allows clients to consume the schemas much better.\nClients are not expected to support dereferencing `$refs`.\n\nNote: The specified schema in the OpenAPI document is only a common subset of JSON Schema.\nAdditional keywords from the JSON Schema specification MAY be used.",
          "properties": {
            "$schema": {
              "description": "The JSON Schema version. If not given in the context of openEO,\ndefaults to `draft-07`.\n\nYou may need to add the default value for `$schema` property explicitly to the JSON Schema\nobject before passing it to a JSON Schema validator.",
              "type": "string",
              "format": "uri",
              "default": "http://json-schema.org/draft-07/schema#"
            },
            "$id": {
              "description": "ID of your JSON Schema.",
              "type": "string",
              "format": "uri"
            },
            "type": {
              "description": "The allowed basic data type(s) for a value.\n\nIf this property is not present, all data types are allowed.",
              "oneOf": [
                {
                  "$ref": "#/components/schemas/json_schema_type"
                },
                {
                  "type": "array",
                  "minItems": 1,
                  "uniqueItems": true,
                  "items": {
                    "$ref": "#/components/schemas/json_schema_type"
                  }
                }
              ]
            },
            "pattern": {
              "type": "string",
              "format": "regex",
              "description": "The regular expression a string value must match against."
            },
            "enum": {
              "type": "array",
              "items": {},
              "description": "An exclusive list of allowed values."
            },
            "minimum": {
              "type": "number",
              "description": "The minimum value (inclusive) allowed for a numerical value."
            },
            "maximum": {
              "type": "number",
              "description": "The maximum value (inclusive) allowed for a numerical value."
            },
            "minItems": {
              "type": "number",
              "minimum": 0,
              "default": 0,
              "description": "The minimum number of items required in an array."
            },
            "maxItems": {
              "type": "number",
              "minimum": 0,
              "description": "The maximum number of items required in an array."
            },
            "items": {
              "description": "Specifies schemas for the items in an array.",
              "anyOf": [
                {
                  "type": "array",
                  "minItems": 1,
                  "items": {
                    "$ref": "#/components/schemas/json_schema"
                  }
                },
                {
                  "$ref": "#/components/schemas/json_schema"
                }
              ]
            }
          },
          "additionalProperties": {
            "description": "You can add any other property supported by the JSON Schema version that is given through the property `$schema`, so either [draft-07](https://json-schema.org/draft-07/json-schema-validation.html) or any later version."
          }
        },

This is then being referenced to be used in multiple parts of the document to describe the JSON responses of the API. (Here's a link to the entire document https://api.openeo.org/)

To my understanding this was done in an attempt to mimic JSON Schema dialects introduced in 3.1.0.

I believe this to not only be superfluous, as all the functionality that is needed is already covered by the inherent existence of the openAPI version of the JSON Schema (https://spec.openapis.org/oas/v3.0.2#schema-object), but also strictly unsupported because of the use of $id and $schema, which are covered by JSON Schema (https://json-schema.org/), hence their inclusion in this meta-implementation of it, but not supported in the context of a openAPI document (openapi-core library fails at validating this spec because of the inclusion of the $id property).

I was discussing this with the person who made this specific specification and he told me that I was wrong in thinking this and I should ask the openAPI community itself. (Open-EO/openeo-api#499)

[jdesrosiers]

To my understanding this was done in an attempt to mimic JSON Schema dialects introduced in 3.1.0.

That's not what it looks like to me. The response to some of the requests are JSON Schemas. For example, if you request GET /collections/{collection_id}/queryables, you will get a JSON Schema in response. That JSON Schema doesn't have anything to do with OpenAPI and isn't constrained by it. It's a response. It's part of the API, not the description of the API. As far as OpenAPI is concerned, the standard JSON Schema in responses are not schemas, they are values just like any other response.

However, OpenAPI needs to be able to describe that response. It needs an OpenAPI dialect schema that describes the standard JSON Schema schema in the response. That's all #/components/schemas/json_schema is for.

The only time a standard JSON Schema appears in the OpenAPI document, is under the OpenAPI example keyword. The schema isn't part of OpenAPI in this case. It's just a value like any other response. It needs to validate against the #/components/schemas/json_schema because that's what the response defines, but it doesn't have to be an OpenAPI dialect schema. It's just a value.

[GeraldIr]

I'm sorry I'm still a bit confused:

• Firstly, is the json_schema object not a schema object and therefore has to follow the guidelines outlined here https://spec.openapis.org/oas/v3.0.2#schema-object disallowing certain properties (such as $id)? And if it isn't when is the strict non-support for keywords such as $id relevant? Even if it is ultimately used as a response, does the structure of the response itself not have to be described by the openAPI spec and thus have to follow the rules of how such documents are structured.

• Secondly, the "/collections/{collection_id}/queryables" is the only endpoint with application/schema+json mimetype, but the json_schema is referenced in way more endpoints than that one.

• Lastly, why then is the spec-validation failing due to the existence of $id fields if they would be fine to have in a openAPI document in the places that they are in. (specifically openapi-core python library)

[jdesrosiers]

Firstly, is the json_schema object not a schema object and therefore has to follow the guidelines outlined here https://spec.openapis.org/oas/v3.0.2#schema-object disallowing certain properties (such as $id)?

That schema doesn't use $id or $schema as a keyword. Those are property names.

{
  "$id": "..." // <= This is a keyword and would not be allowed
  "properties": {
    "$id": { // <= This is just a property name. It just happens to be spelled the same as the keyword.
    } 
  }
}

Secondly, the "/collections/{collection_id}/queryables" is the only endpoint with application/schema+json mimetype, but the json_schema is referenced in way more endpoints than that one.

Yes, other resources seem to include schemas embedded in their responses. That's similar to how OpenAPI has schemas embedded in them. The schemas being part of a response is no different than a schema being the whole response.

Lastly, why then is the spec-validation failing due to the existence of $id fields if they would be fine to have in a openAPI document in the places that they are in. (specifically openapi-core python library)

Sounds like a bug in that library. I'd suggest opening an issue with them.

[Saud96525]

{
"$id": "..." // <= This is a keyword and would not be allowed
"properties": {
"$id": { // <= This is just a property name. It just happens to be spelled the same as the keyword.
}
}
}

[handrews]

This was answered, closing.