What is the practical different between the usage

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.}}