nested schema definitions on openapi spec

[jeusdi]

Currently, I'm using maven plugin to generate json schema from my response classes. After having generated json schema, I use them into my openapi spec 3.x in order to create response schemas.

I'm getting an issue with this generated schema:

{
  "definitions" : {
    "NestedGroupResponse" : {
      "type" : "object",
      "properties" : {
        "groups" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/NestedGroupResponse"
          }
        },
        "label" : {
          "type" : "string"
        },
        "references" : {
          "type" : "array",
          "items" : {
            "type" : "string"
          }
        }
      }
    }
  },
  "type" : "object",
  "properties" : {
    "documentId" : {
      "type" : "string"
    },
    "group" : {
      "type" : "object",
      "properties" : {
        "groups" : {
          "type" : "array",
          "items" : {
            "$ref" : "#/definitions/NestedGroupResponse"
          }
        },
        "references" : {
          "type" : "array",
          "items" : {
            "type" : "string"
          }
        }
      }
    },
    "id" : {
      "type" : "string"
    },
    "transactionId" : {
      "type" : "string"
    }
  }
}

The above schema class is:

@Data
@Builder
@Jacksonized
public class GetReferenceByUniqueIdentifierResponse {

  private static final String ID = "id";
  private static final String TRANSACTION_ID = "transactionId";
  private static final String DOCUMENT_ID = "documentId";
  private static final String GROUP = "group";

  @JsonProperty(ID)
  private String id;

  @JsonProperty(TRANSACTION_ID)
  private String transactionId;

  @JsonProperty(DOCUMENT_ID)
  private String documentId;

  @JsonProperty(GROUP)
  @JsonInclude(JsonInclude.Include.NON_NULL)
  private ReferenceGroupResponse referenceGroup;

}

@Data
@Builder
@Jacksonized
public class ReferenceGroupResponse {

  private static final String GROUPS = "groups";
  private static final String REFERENCES = "references";

  @JsonProperty(GROUPS)
  private List<NestedGroupResponse> groups;

  @JsonProperty(REFERENCES)
  private List<String> references;

}

@Data
@Builder
@Jacksonized
public class NestedGroupResponse {

  private static final String LABEL = "label";
  private static final String GROUPS = "groups";
  private static final String REFERENCES = "references";

  @JsonProperty(LABEL)
  private String label;

  @JsonProperty(GROUPS)
  private List<NestedGroupResponse> groups;

  @JsonProperty(REFERENCES)
  private List<String> references;

}

maven plugin generates this schema correctly. Nevertheless, openapi swagger editor is telling me:

Property "definitions" is not allowed here.

I guess that nested schemas doesn't quite fit well on openapi spec.

Any ideas about how to handle this issue?

[CarstenWickner]

Hi @jeusdi,

It sounds like the issue is not in the schema generation – although I'm missing the schema for ReferenceGroupResponse – but in the way you inject this into your OpenAPI definition.
I suspect you put this into the inline response schema part and not in the consolidated list of components.

Please provide a full executable example including the JSON Schema Generator configuration and the logic around this being injected into the OpenAPI definition.

[jeusdi]

Thanks @CarstenWickner.

I'm aware it's not an issue of schema generator. I mean, schema generator gets me a valid json schema of my GetReferenceByUniqueIdentifierResponse.

Here my related schema generator maven plugin configuration:

      <plugin>
        <groupId>com.github.victools</groupId>
        <artifactId>jsonschema-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>generate</goal>
              </goals>
            </execution>
          </executions>
          <configuration>
            <classNames>
              <className>net.gencat.transversal.espaidoc.presentation.frontoffice.apigateway.document.push.response.PushDocumentResultResponse</className>
              <className>net.gencat.transversal.espaidoc.presentation.frontoffice.apigateway.reference.create.response.CreateReferenceResultResponse</className>
              <className>net.gencat.transversal.espaidoc.presentation.frontoffice.apigateway.reference.getbyuniqueidentifier.response.GetReferenceByUniqueIdentifierResponse</className>
            </classNames>
            <schemaFilePath>./openapi/components/schemas</schemaFilePath>
            <schemaFileName>{0}.json</schemaFileName>
            <modules>
              <module>
                  <name>Jackson</name>
                  <options>
                      <option>FLATTENED_ENUMS_FROM_JSONVALUE</option>
                  </options>
              </module>
            </modules>
            <options>
              <enabled>
                <option>EXTRA_OPEN_API_FORMAT_VALUES</option>
              </enabled>
              <disabled>SCHEMA_VERSION_INDICATOR</disabled>
            </options>
          </configuration>
        </plugin>

As you can guess, my goal is using schema generator in order to generate json schemas and use them into my openapi spec.

Generated json schemas are generated on <schemaFilePath>./openapi/components/schemas</schemaFilePath>. So, they are picked up from my openapi paths:

"get": {
  "summary": "Find reference by ID",
  "description": "Returns a single reference",
  "operationId": "getReferenceById",
  "parameters": [
    {
      "name": "referenceId",
      "in": "path",
      "description": "ID of reference to fetch",
      "required": true,
      "schema": {
        "type": "string"
      }
    }
  ],
  "tags": ["references"],
  "responses": {
    "200": {
      "description": "Reference found",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "../components/schemas/GetReferenceByUniqueIdentifierResponse.json"
          }
        }
      }
    },
    "400": {
      "$ref": "../components/responses/BadRequest.json"
    },
    "401": {
      "$ref": "../components/responses/Unauthorized.json"
    },
    "403": {
      "$ref": "../components/responses/Forbidden.json"
    },
    "404": {
      "$ref": "../components/responses/NotFound.json"
    },
    "500": {
      "$ref": "../components/responses/InternalError.json"
    }
  }
}

Probably I don't quite figure out how schemas should be generated according to its destination.

Should I generate schemas taking in mind something according to those schemas have to be embedded on an openapi spec?

[CarstenWickner]

Interesting. Generally speaking, this should be fine.

Have you tried including the following parameter in your Maven plugin configuration? That is the expected JSON Schema Version starting with OpenAPI 3.1.0 and would result in the keyword $defs being used instead of the offending definitions.

<schemaVersion>DRAFT_2020_12</schemaVersion>

If that doesn't solve your issue, we have to face the challenge of your circular reference – which prevents simply adding Option.INLINE_ALL_SCHEMAS.
If such a nested OpenAPI schema definition is not allowed to include definitions/$defs, then you may have to generate a dedicated schema file for the NestedGroupResponse (which could then do "$ref": "#" for the circular reference without including the offending definitions/$defs`).

[jeusdi]

Thanks @CarstenWickner, it worked changing schemaVersion to DRAFT_2020_12. Where can I read something to get some help about openapi spec "compatible" json schema versions?

[CarstenWickner]

@jeusdi I checked this here: https://swagger.io/specification/ under the "Data types" section it mentions:

Data types in the OAS are based on the types supported by the JSON Schema Specification Draft 2020-12, which suggests that at least parts of OpenAPI are a superset of this particular JSON Schema draft version.