API Blueprint should require a version/format

[kylef]

This is up for discussion and a question based on feedback I've seen. In API Blueprint we support arbitary metadata at the top of the document. Some integrations such as Apiary, APIMatic and Dredd require FORMAT to be declared. For example, APIMatic will not understand that the document is an API Blueprint unless it contains the FORMAT metadata.

As far as the API Blueprint spec and parser is concerned, there isn't a concept called "FORMAT" it is purely a construct that was designed in the Apiary ecosystem which was used so that Apiary could distinquish between Apiary Blueprint and API Blueprint back in the day. At that time Apiary also required FORMAT to be declared in API Blueprint else it treated the document as Apiary Blueprint. This is no longer the case these days as API Blueprint became the default and Apiary Blueprint began to get phased out.

Since API Description has signficantly evolved since API Blueprint was created, there is now a bunch of API Description formats. It is important to have a way to identify them between one and another programatically. Perhaps it is time to consider adding an identifier for this use in API Blueprint specification and parser. I am not nessecerily suggesting that we should require it in 1A as that would be a breaking change, although in future versions we will likely need to contain a version identifier and it should be required.

[fariadev22]

Any kind of an identifier that helps differentiate API Blueprint from other ordinary Markdown or API description files would indeed be very helpful. Swagger uses a property that has the keywords swagger/openapi in it. Similary RAML files require a comment line with the RAML keyword in it. So maybe a required text at the start of the file that follows a pattern like the following would do:
API Blueprint Version 1B