Provide information about the source ADD format and version

[kylef]

I think it would make sense that we provide information in the parse result (or API Element) that contains some information about the source document such as the format itself (Swagger, OpenAPI, API Blueprint) and the version of that format.

Although the goal of API Elements is that the format is canonical and the original source shouldn't matter. When telling users about the errors/warnings or linking to the underlying specification it can be needed. I believe Apiary editor for example tells the user the format used in the error/warning messages so it has to detect this itself.

I think this should be in form of a link element in the parse result to the specific format/version, the link element can contain a title. I am not entirely sure what link relation we should use, I've used via in the example, we should ensure that is semantically correct.

5. The value "via" signifies that the IRI in the value of the href
   attribute identifies a resource that is the source of the
   information provided in the containing element.

For example:

• https://spec.openapis.org/oas/v2.0
• https://spec.openapis.org/oas/v3.0.0
• https://spec.openapis.org/oas/v3.0.1
• https://apiblueprint.org/ (we don't provide versioned specs but probably should in future if we intend to diverge major versions).

This could perhaps look something like:

{
  "element": "parseResult",
  "meta": {
    "links": [
      {
        "element": "link",
        "attributes": {
          "title": {
            "element": "string",
            "content": "OpenAPI"
          },
          "relation": {
            "element": "string",
            "content": "via"
          },
          "href": {
            "element": "string",
            "content": "https://spec.openapis.org/oas/v3.0.1"
          }
        }
      }
    ]
  }
}

[honzajavorek]

This could simplify Dredd as well. Currently its parse function returns two results, the media type and the API Elements object. As Dredd needs to know the media type in multiple occasions later on, it's a bit tedious to keep the information together in the rest of the flow. If it's in one package out of the box, that would be nice.

And yes, I know one of the occasions is a dirty "if/else media type" branching, which is something beating the purpose of API Elements, but it's there for backward compatibility. Although scheduled to be removed, it's gonna live with us for a while. Theoretical purity meets reality 🙂

[char0n]

Yes I think this has been discussed in the past. We need to embed the meta information from the original document inside the api elements it self. It creates a lot of problems and bypasses currently.

What the new doc renderer needs is:

• lineNumber and character possition of ADD in annotations
• Type of the ADD document; I'd rather have the canonical mimetype there than a title. I can assume title title from the mime-type and I can localize it (if needed). The link to spec is a good idea.