Add an intro and other missing sections

[lornajane]

We had some "TBD" sections, I removed one (data types, I don't think we can add this after so many people have implemented, and Overlays could span multiple OpenAPI versions!?!?), wrote an intro, and used a version of the Arazzo wording, acknowledging the retroactive nature of the 1.0.0 version specifically.

Hopefully this fills the main gaps! Fixes #44

[kevinswiber]

Thank you for doing this, @lornajane!

[ralfhandl]

+1, minor nits only

[mikekistler]

Looks good! 👍

[mikekistler]

This mostly looks good, but I think we need to be clear about whether Overlays can be used on JSON or YAML docs other than OpenAPI descriptions.

[mikekistler]

Do we want to restrict Overlays to only operate on OpenAPI documents? For the most part the spec could easily be applied to any JSON or YAML doc. And in several places we seem to allow base documents of other types, e.g. target is described as

URL to the target document (such as an [[OpenAPI]] document) ...

[ralfhandl]

The repo README.md says

The Overlay specification defines a way of creating documents that contain information to be merged with an OpenAPI description at some later point in time, for the purpose of updating the OpenAPI description with additional information.

Given that with RFC6902 and RFC7386 there are already two document formats for modifying arbitrary JSON documents, I'd keep to the original scope.

@kevinswiber @lornajane?

[ralfhandl]

@mikekistler How about merging this PR and continuing the discussion in

• Are Overlays restricted to operate on OpenAPI documents? #56