Description on references


(Arie Gofer) #1

Hi,
Let’s say I have a model “Person” with all its properties. The model has its description for example: “Representing a human being in the system with all its properties”.
Let’s say I have a model “Car” which (among others) have “owner” and “principleDriver” properties. Both referencing to the Person entity.
When I document the car model, I want to be able to explain that “owner” is “The person who owns the car” (representing the ROLE of this person in regards to the car). What happens today is that the property description is ignored (actually deleted after I set it).
Any suggestions?
Thanks !


(Arie Gofer) #2

@taylor In addition to the above - is there any way to indicate such references in the READ perspective in a way the user can know that this is a model defined elsewhere (possibly with a link to it), rather than see it “embedded” within the referencing model? (I hope my question is clear :slight_smile:)


(Taylor Barnett) #3

The only suggestion I have for the first one is to add it to the description of the “Car” model. But I am not sure I know what you mean by that the description is ignored or deleted. Could you expand on that?

12%20AM


(Taylor Barnett) #4

On the second question, sadly there is not. We deference it so that it doesn’t appear as a link and there’s not really a way to stop that from happening right now.


(Arie Gofer) #5

The point is whether you can show an indication that this is not an “embedded” data type, but rather a common model defined elsewhere.

As for the original question - here is a visual example:
Let’s say we have a model called car:
image

And we have a model called person:


As you can see - I have two possible vehicle for a person - personal and work. I expect that description I set for the “workVehicle”, which explain the need for this reference, will appear and not the general explanation of what Car is.

So I expect it to look like this (poor photoshop work, I know):

I hope it is clearer now.


(Arie Gofer) #6

@taylor any insights on this one ? Thanks !


(Taylor Barnett) #7

Thank you for the images. It makes it really clear. It appears in the process of dereferencing the description gets replaced. I’ve spent some time reading the OpenAPI Specification on this to see what is suppose to be valid and it seems like you should be able to do it, based on: https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md#schema-object.

I’m in the process of opening up something internally on it.


(Taylor Barnett) #8

So it turns out this is really debatable whether it is allowed by the specification. We’re still talking about it internally, but it seems like it isn’t really allowed in OAS 3.

This is a long way to say, we are considering supporting it, but we may have just implemented something badly.

I wouldn’t heavily rely on this existing. Sorry for the not so great news.


(Arie Gofer) #9

@taylor
Thanks for the research. I separate it into two different parts:

  1. The ability to view the “context-based-description” (e.g. “the car used by the person for private needs”) in your documentation
  2. The issue of "where should this description be carried on the spec according to OpenAPI specs.

and if I understand correctly, the “$ref” object just does have this extra “description” option.

I have no idea how you are (Stoplight) involved in the OpenAPI initiative, but I believe this is a need which should be raised. In a sense, the problem stems in the fact the “$ref” is is being used where it should actually be an option for “type” attribute for a field. So if a field was of type “Car” (e.g. type="$ref:Car"), then you would have everything I am looking for. I hope it makes sense.
Thanks !