Traits proposal

[darrelmiller]

To improve the process around working on the traits feature, the contents of the Overlay issue have been moved into a markdown file that lives in the proposals folder in the master branch. The goal is to bring this document to the point where it can be copied and pasted into the official spec when finalized.

[darrelmiller]

• 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)

[darrelmiller]

This should be a JSON ref, not just a simple string.

[darrelmiller]

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

[cmheazel]

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

[cmheazel]

@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.

[earth2marsh]

Regarding use cases, there were a few from OAI/Overlay-Specification#35 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.

[darrelmiller]

@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.

[MikeRalphson]

As a result of #2604 the filename for this proposal should change to use a dated prefix. Please could you update this PR to match? You can use the original PR date. Apologies for the extra work.