Consider using collection properties for namespaces & extension properties

[tedepstein]

I have so far resisted using namespaces to group the Namespace Objects. Since namespace properties use reverse-DNS notation, the SEMOASA schema (when we get around to creating it) can use patternProperties to distinguish them from statically defined properties.

Similarly, there's no extensionProperties collection to hold the Extension Property Objects within a namespace. Right now, these Extension Property Objects are the only properties of a namespace. And if needed, we could again use patternProperties to distinguish these x- prefixed property names from other statically defined properties.

If we introduced collection properties, we'd have something like this:

openapiExtensionFormat: 0.1.0
namespaces:
  com.amazon.aws:
    extensionProperties:
      x-amazon-apigateway-integration:
        summary: Specifies the integration of the method with the backend.
        description: |
          Specifies details of the backend integration used for this method. 
          This extension is an extended property of the Swagger Operation object.
          The result is an API Gateway integration object.
        externalDocs:
          description: AWS documentation page in the  Amazon API Gateway Developer Guide 
          url: http://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions-integration.html
     ...

Should we use collection properties?

Pros

• Consistency with OpenAPI style.
• Internal consistency, since there are cases where we need collection properties:
  • objectTypes
  • schemas
  • providers
  • externalDocs
  • ... and maybe others, as the spec evolves.
• It makes the format less fragile, because we could conceivably introduce sibling properties that would break our patternProperties assumptions, or force us to define an even more specific regex to distinguish a certain group of properties.
• It might make things easier for parsing and in-memory object representation of a SEMOASA document in strongly-typed languages like Java, C#, etc. If the collection properties make a significant difference in this area, that almost certainly tips the scale in favor of using them.

Cons

I don't like collection properties. If find them, and the extra indent levels they introduce, kind of cumbersome and verbose. They're one of my gripes about YAML, or the use of YAML as a simplified DSL for JSON.

And if we choose to add extension as another level in the hierarchy, as suggested in #1, it exacerbates this exploding indent effect.

All that said, I will bow to reality, if I have to.