How to use $ref within a schema in OpenAPI 3.0?

Question

I want to represent the following JSON as a schema in an OpenAPI 3.0 API definition:

{
get-question: {
  question-id:string
  }
}

So far, I have written:

components:
  schemas:
  #schema of a question-id
    QuestionID:   #{question-id: string}
      properties:
        question-id:
          type: string
      required:
        - question-id

  #schema of a get-question request which contains a question id      
    GetQuestion: #{get-question: {question-id:string}}
      properties:
        get-questions:
          type: $ref:'#/components/schemas/QuestionID'
      required:
        - get-questions

but I am getting these errors in the Swagger Editor:

Schema error at components.schemas['GetQuestion']
should have required property '$ref'
missingProperty: $ref
Jump to line 79
Schema error at components.schemas['GetQuestion']
should match exactly one schema in oneOf
Jump to line 79
Schema error at components.schemas['GetQuestion'].properties['get-questions']
should have required property '$ref'
missingProperty: $ref
Jump to line 81
Schema error at components.schemas['GetQuestion'].properties['get-questions']
should match exactly one schema in oneOf
Jump to line 81
Schema error at components.schemas['GetQuestion'].properties['get-questions'].type
should be equal to one of the allowed values
allowedValues: array, boolean, integer, number, object, string
Jump to line 82

What is the correct syntax for $ref?

Answer 1

$ref is used instead of type, not as the value of type. Also note the space after : to separate the key and value in YAML.

        get-questions:
          $ref: '#/components/schemas/QuestionID'

You also need to add type: object to your QuestionID and GetQuestion schemas to indicate that they are objects; the properties keyword alone is not enough.

There also seems to be a typo in one of the property names - it's get-questions (plural) in the GetQuestion schema but get-question (singular) in your JSON example. I guess it should be get-question.

Complete example:

components:
  schemas:
    # schema of a question-id
    QuestionID:      # {question-id: string}
      type: object   # <-----
      properties:
        question-id:
          type: string
      required:
        - question-id

    #schema of a get-question request which contains a question id      
    GetQuestion:     # {get-question: {question-id:string}}
      type: object   # <-----
      properties:
        get-question:
          $ref: '#/components/schemas/QuestionID'   # <-----
      required:
        - get-questions