What is the practical different between the usage of JSON and YAML in Swagger?

Question

It appears that JSON includes the path information and http request verb, whereas YAML seems to just definition a tree structure alone.

What is the difference between them? Or am I mixing up different concepts/hierarchies here? newbie to swagger, just started learning.

If YAML is a superset of JSON what specifically is the superset adding here - is it URL paths and HTTP verbs ? Is adding an example also something that YAML adds to JSON for Swagger ?

Answer 1

According to the OpenAPI Specification,

An OpenAPI document that conforms to the OpenAPI Specification is itself a JSON object, which may be represented either in JSON or YAML format.

So feature-wise, there is no difference between using JSON or YAML. What YAML as a superset of JSON adds here is merely a different syntax. Using an example from the specification, these two documents are identical:

{
  "servers": [
    {
      "url": "https://development.gigantic-server.com/v1",
      "description": "Development server"
    },
    {
      "url": "https://staging.gigantic-server.com/v1",
      "description": "Staging server"
    },
    {
      "url": "https://api.gigantic-server.com/v1",
      "description": "Production server"
    }
  ]
}

and

servers:
- url: https://development.gigantic-server.com/v1
  description: Development server
- url: https://staging.gigantic-server.com/v1
  description: Staging server
- url: https://api.gigantic-server.com/v1
  description: Production server

The first document is valid JSON and valid YAML (since YAML is a superset of JSON). The second document is valid YAML and structurally identical to the first document.

So to answer the question about what the YAML superset adds here: It adds different syntax for specifying the same structures. Nothing more.

_{^{YAML does include some features that are not mappable to JSON, but they are irrelevant here because Swagger/OpenAPI doesn't use them.}}