When using "$ref" inside the "items" and if using other references inside item schema it is resulting in "undefined entity" inside the documentation generated by postman

[gregorybliault (Grégory Bliault)]

Hello,

I might not understand something properly but I found something weird when generating my documentation. When using “$ref” inside an “items” and if using other references inside the item schema it is resulting in “undefined entity” inside the documentation generated by postman with the message “Entity definition not found”. I am using postman 10.12.13.

Is this a bug or am I not understanding something?

Here is a schema I created to outline the issue (I am using Open API 3.0.0) :

{
    "$id": "someid",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Schema to filter image based on DICOM parameters.",
    "type": "object",
    "definitions": {
        "numericalCriterionEqual": {
            "title": "Numerical criterion equal",
            "properties": {
                "value": {
                    "type": "number"
                },
                "operator": {
                    "properties": {
                        "label": {
                            "enum": [
                                "="
                            ]
                        },
                        "value": {
                            "enum": [
                                "equals"
                            ]
                        },
                        "type": {
                            "type": "string",
                            "enum": [
                                "NUMERICAL_OPERATOR"
                            ]
                        },
                        "variant": {
                            "type": "string",
                            "enum": [
                                "SINGLE_VALUE",
                                "ALL_ELEMENT",
                                "ANY_ELEMENT"
                            ]
                        }
                    }
                }
            }
        },
        "criterion": {
                "description": "Criterion",
                "type": "object",
                "properties": {
                    "operator": {
                        "description": "The selected operator",
                        "type": "object",
                        "required": [
                            "type",
                            "value",
                            "label"
                        ],
                        "additionalProperties": false,
                        "properties": {
                            "type": {
                                "type": "string",
                                "enum": [
                                    "NUMERICAL_OPERATOR",
                                    "TEXTUAL_OPERATOR"
                                ]
                            },
                            "variant": {
                                "type": "string",
                                "enum": [
                                    "SINGLE_VALUE",
                                    "ALL_ELEMENT",
                                    "ANY_ELEMENT"
                                ]
                            },
                            "value": {
                                "type": "string"
                            },
                            "label": {
                                "type": "string"
                            }
                        }
                    },
                    "value": {
                        "description": "Value for the criterion."
                    }
                },
                "required": [
                    "operator",
                    "value"
                ],
                "additionalProperties": false,
                "oneOf": [
                    {
                        "$ref": "#/definitions/numericalCriterionEqual"
                    }
                ]
        },
        "criteriaAPI2": {
            "description": "List of criteria in the expression",
            "type": "array",
            "items": {
                "$ref": "#/definitions/criterion"
            }
        },
        "criteriaAPI": {
            "description": "List of criteria in the expression",
            "type": "array",
            "items": {
                "description": "Criterion",
                "type": "object",
                "properties": {
                    "operator": {
                        "description": "The selected operator",
                        "type": "object",
                        "required": [
                            "type",
                            "value",
                            "label"
                        ],
                        "additionalProperties": false,
                        "properties": {
                            "type": {
                                "type": "string",
                                "enum": [
                                    "NUMERICAL_OPERATOR",
                                    "TEXTUAL_OPERATOR"
                                ]
                            },
                            "variant": {
                                "type": "string",
                                "enum": [
                                    "SINGLE_VALUE",
                                    "ALL_ELEMENT",
                                    "ANY_ELEMENT"
                                ]
                            },
                            "value": {
                                "type": "string"
                            },
                            "label": {
                                "type": "string"
                            }
                        }
                    },
                    "value": {
                        "description": "Value for the criterion."
                    }
                },
                "required": [
                    "operator",
                    "value"
                ],
                "additionalProperties": false,
                "oneOf": [
                    {
                        "$ref": "#/definitions/numericalCriterionEqual"
                    }
                ]
            }
        },
        "expressionAPI": {
            "description": "An expression",
            "type": "object",
            "properties": {
                "criteria": {
                    "$ref": "#/definitions/criteriaAPI"
                }
            },
            "required": [
                "logicalOperator",
                "criteria",
                "expressions"
            ]
        },
        
        "expressionAPI2": {
            "description": "An expression",
            "type": "object",
            "properties": {
                "criteria": {
                    "$ref": "#/definitions/criteriaAPI2"
                }
            },
            "required": [
                "logicalOperator",
                "criteria",
                "expressions"
            ]
        },
        "test": {
            "type": "object",
            "properties": {
                "filter": {
                    "description": "The filter (an expression)",
                    "$ref": "#/definitions/expressionAPI"
                },
                "filter2": {
                    "description": "The filter (an expression)",
                    "$ref": "#/definitions/expressionAPI2"
                }
            },
            "additionalProperties": false,
            "required": [
                "filter",
                "name"
            ]
        }
    }
}

And there is the documentation generated by postman (you can see the behavior described in the filter2 property) :

[gregorybliault (Grégory Bliault)]

I kind of found a way of fixing this “Entity definition not found” by making a small modification. I am still using the same json file from my first message (let’s call it test.schema.json) but I changed my index.json from :

{
    "openapi": "3.0.0",
    "info": {
        "version": "0.0.7",
        "title": "SPINE API",
        "description": "SPINE API"
    },
    "servers": [
        {
            "url": "{{SPINEUrl}}/api"
        }
    ],
    "paths": {
        "/test": {
            "get": {
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "tags": [
                    "test"
                ],
                "summary": "Just testing the schemas",
                "responses": {
                    "200": {
                        "description": "200",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "./test.schema.json#/definitions/test"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected error"
                    }
                }
            }
        }
    },
    "components": {
        "examples": {},
        "schemas": {},
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT"
            }
        }
    },
    "tags": [
        {
            "name": "workflow execution matrix",
            "description": "Workflow Execution Matrix"
        }
    ]
}

to

{
    "openapi": "3.0.0",
    "info": {
        "version": "0.0.7",
        "title": "SPINE API",
        "description": "SPINE API"
    },
    "servers": [
        {
            "url": "{{SPINEUrl}}/api"
        }
    ],
    "paths": {
        "/test": {
            "get": {
                "security": [
                    {
                        "bearerAuth": []
                    }
                ],
                "tags": [
                    "test"
                ],
                "summary": "Just testing the schemas",
                "responses": {
                    "200": {
                        "description": "200",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/test"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Unexpected error"
                    }
                }
            }
        }
    },
    "components": {
        "examples": {},
        "schemas": {
            "test": {
                "type": "object",
                "properties": {
                    "filter": {
                        "description": "The filter (an expression)",
                        "$ref": "./test.schema.json#/definitions/expressionAPI"
                    },
                    "filter2": {
                        "description": "The filter (an expression)",
                        "$ref": "./test.schema.json#/definitions/expressionAPI2"
                    }
                },
                "additionalProperties": false,
                "required": [
                    "filter",
                    "name"
                ]
            }
        },
        "securitySchemes": {
            "bearerAuth": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT"
            }
        }
    },
    "tags": [
        {
            "name": "workflow execution matrix",
            "description": "Workflow Execution Matrix"
        }
    ]
}

Basically I just moved the main response schema from the test.json.schema to the index.json and I get the following documentation, as I expected to have for the object “filter2” :