Need $ref as a variable in open-api-spec.yml file

[Prasanna_Ailuri]

Hi Team,

I am using Open-API-SPEC 3.0 and have a requirement to build the below mentioned object 

        {

            "value": "a12345",

            "$ref": "https://example.com/v3/Resources/a12345",

            "display": "Resource-a12345"

        }

And when I specify the same in open-api-spec.yaml as below:

MyObject:
  required:
    - value
  type: object
  properties:
    value:
      type: string
    display:
      type: string
    $ref:
      type: string

 I am receiving a wrong structure with 2 values in place of $ref, Could anyone suggest or guide me on how to solve my specific requirement?

Thanks in Advance,

Prasanna Ailuri

[frankkilcommins]

Hi @Prasanna_Ailuri 

Could you share your OpenAPI 3.0 definition? I'm not sure based on above what you are trying to achieve.

Thanks,

Frank

[Prasanna_Ailuri]

Hi @frankkilcommins ,

We have an endpoint which returns objects as an array of below mentioned JSON:

        {

            "value": "a12345",

            "$ref": "https://example.com/v3/Resources/a12345",

            "display": "Resource-a12345"

        }

Thanks,

Prasanna

[Prasanna_Ailuri]

paths:
/users:
get:
summary: Returns a list of users.
description: Optional extended description in CommonMark or HTML.
responses:
'200': # status code
description: A JSON array of user names
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Response'
components:
schemas:
Response:
type: object
properties:
id:
type: string
meta:
type: array
items:
$ref: '#/components/schemas/Metadata'
Metadata:
required:
- value
type: object
properties:
value:
type: string
display:
type: string
$ref:
type: string

[frankkilcommins]

Hi @Prasanna_Ailuri 

Thanks for the info. I'm still not 100% clear on what you are trying to achieve.

I've defined a version of an API with the path and schemas you have descripted at https://app.swaggerhub.com/apis/frank-kilcommins/UsersReference/1.0.0#/default/get_users

A sample response for the API would be as follows:

[
  {
    "id": "string",
    "meta": [
      {
        "value": "string",
        "display": "string",
        "$ref": "string"
      }
    ]
  }
]

Note that $ref in a JSON payload response has no semantic meaning. I think you might be misinterpreting how to use references in your API definition. The way you have defined it means that it's just a string property with a name of "$ref". Using a JSON Schema keyword in this way may cause you issues in other tooling.

To be strictly compliant with OpenAPI 3.x, a JSON Reference can only be used where explicitly noted in the OpenAPI specification. For example, it can be used for Paths, Parameters, Schema Objects and more. Basically, if you can define a schema object inline then you can also put in a reference object.

You have defined your 'MetaData Object' as follows:

Metadata:
 required:
 - value
 type: object
 properties:
  value:
   type: string
  display:
   type: string
  $ref:
   type: string

The above usage is not using the $ref keyword as expected. To use references appropriately, the value of the $ref keyword must be a string representing an URI, URI reference, URI template or a JSON pointer.

For more information on how to use object references, see https://swagger.io/docs/specification/using-ref/

[Prasanna_Ailuri]

Hi @frankkilcommins 

Thanks for the detailing ,https://app.swaggerhub.com/apis/frank-kilcommins/UsersReference/1.0.0#/default/get_users is my exact requirement.

But when you build that object and return the response of it via any endpoint in Java

The below is happening:

[{
    "id": "string",    
          "meta": [{
        "value": "string",       
        "display": "string",
                   "$Ref": "string",        
                 "$ref": "string"
      }]
  }]

 An Extra Ref is getting added runtime

Thanks,

Prasanna 

[frankkilcommins]

Hi @Prasanna_Ailuri 

Are you using Swagger-Codegen to generate your server implementation?

I've just generated a Java SpringBoot server stub from the OpenAPI definition shared above and the response from the GET '/users' is as follows (which looks correct):

[
    {
        "meta": [
            {
                "display": "display",
                "value": "value",
                "$ref": "$ref"
            },
            {
                "display": "display",
                "value": "value",
                "$ref": "$ref"
            }
        ],
        "id": "id"
    },
    {
        "meta": [
            {
                "display": "display",
                "value": "value",
                "$ref": "$ref"
            },
            {
                "display": "display",
                "value": "value",
                "$ref": "$ref"
            }
        ],
        "id": "id"
    }
]

I suspect your issue is related to the usage of the keyword $ref. I would recommend that you change the name of that property so that it does not clash with a JSON Schema keyword.

Thanks,

Frank