Suggest we reference a specific version of CommonMark

[webron]

[webron]

http://spec.commonmark.org/0.27/

[DavidBiesack]

CommonMark is updated every few months (four times in 2016; it is not even a 1.x release, and it will probably rev several times in OpenAPI 3.0's lifetime) I suggest we claim a minimum version and not fix it on 0.27, but note that a 1.x version may have incompatible changes and OpenAPI 3.0 tools need only support CommonMark features compatible with 0.27

[darrelmiller]

I'm going to add a new paragraph near the beginning of the spec that talks about using Markdown and references the CommonMark spec.

@DavidBiesack I'm not sure what the difference is between saying "OpenAPI supports CommonMark 0.27" and saying "at minimum 0.27 is supported". If a tooling vendor decides to support something only introduced in markdown 0.28 I doubt that validators will raise an error. Giving a warning might not be a bad idea, because some tooling might not support it.
Once we set a minimum any feature beyond that version steps into unknown territory.