Example to write a schema in OAS

oas-schema-example.yaml

components:                                             # define schemas under this section
  schemas:
    Category:                                           # create a category schema
      description: Category of pets
      type: object                                      # this can correspond to a JSON object
      properties:                                       # define the properties in the object
        id:
          type: integer                                 # define the type of object
          example: 1                                    # give an example for better documentation
        categoryName:
          type: string
          enum: [dog,cat,hamster,parrot,rabbit]         # enum is used to define a specific set of values
          example: dog
    
    # similarly, define for breed and location       
    Breed:
      description: Breed of a pet within a category
      ....
    Location:
      description: Location of a pet
      ....
    
    # create a pet schema     
    Pet:
      description: Pet details
      type: object
      properties:
        petId:
          type: integer
          example: 1
        petName:
          type: string
          example: Tabby
        petImageUrl:
          type: string
          example: www.link/to/image.jpg
        age:
          type: number
          example: 0.5
        petDescription:
          type: string
          example: Fun loving and active
        category:
          $ref: '#/components/schemas/Category'             # reference other schemas using $ref
        breed:
          $ref: '#/components/schemas/Breed'
        location:
          $ref: '#/components/schemas/Location'