Suggest adding a (cut-down) info object at the root

[MikeRalphson]

Which might look something like:

Fixed Fields

Field Name	Type	Description
title	string	REQUIRED. The title of the SEMOASA documentation.
description	string	A short introduction to the documentation. CommonMark syntax MAY be used for rich text representation.
contact	Contact Object	The contact information for the documented extensions.
version	string	REQUIRED. The version (or date in ISO-8601 format) of the SEMOASA document (which is distinct from the openapiExtensionFormat property.

[tedepstein]

Nice idea, especially because this allows self-identification of the publisher, who may or may not be the same party as the provider. I'm thinking that we should make that intention clear in the Description column, also allow a similar contact property in the Provider Object, and add a contacts catalog under components to keep it DRY.

Also, consistent with OAS3, our spec uses the term "document" to refer to the physical file containing a SEMOASA Extensions Object.

Field Name	Type	Description
title	string	REQUIRED. The title of the SEMOASA document.
description	string	A short introduction to the document. CommonMark syntax MAY be used for rich text representation.
contact	Contact Object | Reference Object	The contact information for the publisher of the SEMOASA document.
version	string	REQUIRED. The version (or date in ISO-8601 format) of the SEMOASA document (which is distinct from the openapiExtensionFormat property.

I'm on the fence as to whether title should be required. Is this so we can present the source document in a UI, or in generated human-readable documentation? Or is it for some other purpose?

[MikeRalphson]

Yes, I was mainly thinking of generated human-readable documentation. 😄

I don't think title need be required.

[tedepstein]

Wow!!! :-)

[tedepstein]

Very cool to see this, @MikeRalphson . Did you write a generator to do this, or did Shins auto-magically adapt to this new format? Either way, pretty impressive.

If there's something here that people can use today, to generate similar extension docs from a SEMOASA spec, I'd like to add it to Implementations in the Readme.

[MikeRalphson]

I'd love to say shins could automagically derive such documentation from an arbitrary yaml file, but no, it's just a port of slate to node.js - the 'clever' bit is done by three small templates added to widdershins.

Will PR to the Readme.