title: When should I use $ref versus the object id in Open API
body: <p>I'm working on a schema in OpenAPI with Swagger, and I'm not sure if I'm misusing the <code>$ref</code> element. I have a <code>User</code> model and a <code>Project</code> model, similar to something like</p>
  
  <pre><code>User:
        type: object
        properties:
          id:
            type: string
            format: uuid
          name:
            type: string
          ...
  Project:
        type: object
        properties:
          id:
            type: string
          user_id:
            $ref: "#/components/schemas/User"
          ...
  </code></pre>
  
  <p>I don't see much in the Open API Spec documentation as to what the <code>$ref</code> element is specifically, but in the JSON Schema documentation—of which Open API extends the <code>$ref</code> element—I've found the following description of the item:</p>
  
  <blockquote>
    <p>The easiest way to describe $ref is that it gets logically replaced with the thing that it points to.</p>
  </blockquote>
  
  <p>In the case above, I just want to refer to the user who posted a project. It seems unnecessary to essentially include all of the information about the User in the Project model if that is what it's doing. Would it be better practice to just have a <code>string</code> element of the uuid of the <code>user_id</code>? Or is it correct as is? Is it more common to name the field <code>user</code> rather than <code>user_id</code> if that is the case?</p>
  
  <p><strong>Edit</strong>:
  I realize the heart of what was bothering me is if there were to be recursive references. If a User has an array of <code>$ref</code> to Projects, but also a Project has an array of <code>$ref</code> to Users, the replacement (if that's what it's doing) would infinitely embed each model in the other. I assume this wouldn't happen in practice, assuming that a <code>$ref</code> is just a pointer to the Model?</p>