Consider three-level identity: namespace.extension.property

[tedepstein]

The current spec uses a namespace and a property name to establish unique identity. So the fully qualified name of an extension property would be namespace.property. In the readme example, the FQN of the property would be com.amazon.aws.x-amazon-apigateway-integration.

Should we introduce an extension object as an extension property or closely related set of extension properties defined within a namespace?

That would give us something like this:

openapiExtensionFormat: 0.1.0
# namespace
com.amazon.aws:
  # extension
  apiGateway:
    name:  Amazon API Gateway Extension to OpenAPI
    summary: The API Gateway extension supports the AWS-specific authorization and API Gateway-specific API integrations.
    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.html
    # extension property
    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
    provider:
      name: Amazon Web Services
      url: https://aws.amazon.com/

In this structure, the FQN would be com.amazon.aws.apiGateway.x-amazon-apigateway-integration.

Pros

OpenAPI uses the term "specification extensions," to communicate extensibility through x- prefixed properties. But it doesn't define how we should use that term to refer to a concrete thing. I would think of a specification extension as a written spec (machine- and/or human-readable) that defines one or more extension properties. It might be nice to formalize that meaning here, so we can talk about "specification extensions" as real things that have an unambiguous meaning, and a well-bounded representation in our format.

(Along the way, I've found myself referring to extension properties, though I haven't formally defined that term. I think we need that bit of terminology. We wouldn't want to say "specification extension" every time we refer to one of these properties, because it's too abstract, and because the term "specification extension" just doesn't sound like it means a single property. That term wants to refer to a spec that defines one or more such properties.)

As shown in the example above, the Extension Object can have its own name, summary, externalDocs, and possibly other metadata.

Cons

Even without defining Extension as its own thing, it's possible for a provider to use hierarchical namespaces. So Amazon could define extension properties under the namespaces com.amazon.aws.apiGateway, com.amazon.aws.lambda, etc. From this perspective, the extension starts look like it's just the last segment of the namespace.

Introducing extension as another level in the taxonomy could be seem like too much structural weight, or overhead, for a provider who wants to define a single a single extension property.

We could solve the terminology problem by:

• making specification extension synonymous with extension property; or
• defining specification extension as the set of extension properties defined within a namespace; or
• ignoring the terminology problem and muddling through.