• Decide on the name.
• Decided : Mixin references should be array of JSON references
• Merging rules as defined here https://github.com/OAI/OpenAPI
• Specification/issues/1442#issuecomment-418549259 by @jstoiko (Array merging semantics instead)

We need to collect a set of use cases for internal vs external "overlay/trait/mixin/whatever". @tedepstein volunteered to help.

Yes, we will do the same thing with Alternative Schema.

@darrelmiller where will the use cases live? Should we have discrete directories for each proposal? That way we don't have to include use cases and other supporting material in the markup targeted for the OAS spec.

Regarding use cases, there were a few from #1442 I'll bring over here:

1. As a way to keep any implementation details for a spec separate from the consumer-oriented doc, such as API management concerns from the API provider's perspective, for example attaching a policy to an operation.
2. To allow a writer to create better descriptions/summaries/titles for attributes like a parameter or an operation without having to edit the spec itself. But since parameters are an array, in order to edit a single description, I would have to reproduce the entire array, no? Is there a way to more precisely target?
3. To identify an SLA. You might have a valid spec that doesn't have that information, but you could ask for the SLA variant for that spec.
4. Codegen is another, as we're polluting specs with metadata for codegen. This gives us a way to separate that out.

@cmheazel I was considering the use cases as living in the comments here, but I see your point that it is going to get just as messy. Perhaps each proposal should have a folder and the spec wording and all related documents, e.g. examples, use cases, spec wording should all live in that folder.

Having a permenant record of why we created a feature is definitely not a bad thing.