reprezen / semoasa Goto Github PK

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.

The spec says that extension property schemas should be OpenAPI Schema Objects. At first blush, this seems consistent with this stated design goal:

Common Technology Stack with OpenAPI, so that essential functions like YAML editing, schema validation, and JSON reference resolution can be performed by the same components used with OpenAPI tool implementations.

But, while Schema Object is implemented by certain OpenAPI tools and components (parsers, documentation UIs, code generators, etc.), it's not part of the technology stack used to implement those tools and components.

Pros

• Puts limits on the use of certain features of JSON schema. (Both a 'pro' and a 'con')
• Adds its own syntax and semantics for discriminators, format, etc. (Both a 'pro' and a 'con')
• Lets us use the OpenAPI convention of allowing markdown in description in top-level schemas, property sub-schemas, etc. This could be useful if we want to use SEMOASA to produce rich-formatted documentation of Specification Extensions, though that is not stated as one of the intended use cases.

Cons

• Puts limits on the use of certain features of JSON schema. (Both a 'pro' and a 'con')
• Adds its own syntax and semantics for discriminators, format, etc. (Both a 'pro' and a 'con')
• Libraries that enforce these constraints, implement these extended semantics, and render markdown descriptions may not be readily available, except in OpenAPI tools. Making them available in a lower-level stack, used by tool providers to create those tools might require significant refactoring. It might just not be practical to do this.

The draft lists tagging an extension for oas2 or oas3 . It would be useful to allow indicating that an extension applies to other specifications, such as AsyncAPI, json:api an so one. An individual extension may apply to one or more specifications.

From a brief reading of the relevant part of the spec all we may be missing is an optional displayName.

A friendly name used only for display or documentation purposes. The default is the element key, the name of the annotation itself.

As this seems distinct from the summary, and description maps 1:1.

A raml1 - RAML1 Context Object may not be necessary if the allowedTargets can be deduced from whichever oas2 or oas3 one is converting from.

My example is Microsoft's x-ms-paths (docs). Where x-ms-paths is an analogue of the paths property (i.e. it contains pathItem Objects).

I'm assuming MS will continue to use x-ms-paths with OASv3, as the problem it 'solves' is unchanged in OASv3. So in OASv2 it will be structured like a container of OASv2 pathItem Objects and OASv3 pathItem Objects in OASv3.

So, would something like the following be valid?

#...
com.microsoft:
  x-ms-paths:
  #...
    schema:
      oneOf:
      - $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/master/schemas/v2.0/schema.json#/definitions/Paths
      - $ref: https://raw.githubusercontent.com/OAI/OpenAPI-Specification/49e784d7b7800da8732103aa3ac56bc7ccde5cfb/schemas/v3.0/schema.yaml#/definitions/Paths

And does it provide enough information as to the context for the use of each schema? Without some kind of hint, it seems to me that the schema would be only really suitable for validation, not auto-completion (generated documentation would be partially useful).

I think an OASv2 schema object is a proper subset of the OASv3 schema object, unless it references type: file or discriminator.

One option would be to have a schema property under the oas2 and oas3 properties which overrides the default schema. Then each could be defined as their appropriate type from the relevant spec. version (refs #4, #8 (comment)), and we gain a mechanism to support OASv4 etc. It would still be up for debate as to whether the top-level schema should be JSON-Schema draft X or some version of OpenAPI-Schema.

I think the title case is a little easier on the eye, easier on the fingers, and makes the acronym seem a bit less forced.

Which might look something like:

Fixed Fields

Semoasa == Specification Extension Metadata for OAS Annotations

Right now, the structure section in the README serves as a placeholder for a specification. Once this starts to settle, I would want to write that formal spec.

We might keep a Structure section in the README as a quick reference guide, if it's not too much maintenance overhead. (Extra brownie points for auto-extracting the summary from the spec markdown.)

I.e. in the example, OperationObject -> operationObject. The rationale for this is that fragment identifiers are case-sensitive. This would aid linking to the relevant area of the specifications.

It might also help those who want to produce (and keep up to date) a combined specification from the source OAS specification plus their extensions. Cf SmartAPI (ping @newgene).

An alternative would be to use the property names from the OpenAPI schemas (once an official 3.0.0 schema is settled upon), thus OperationObject -> operation for OASv2 or the gnostic 3.0 schema, -> Operation for webron's 3.0 schema. This wouldn't be my favoured option, as the schema may impose its own model (e.g. ParameterWithSchemaWithExample).

Hi @tedepstein - some discussions have taken place within the OpenAPI and AsyncAPI communities where we'd very much like something like Semoasa to have a place in defining a machine-readable format for API specification extensions.

In time we may be able to find a home within one of those communities for the Semoasa specification, but in the near term, would you be interested in possibly transferring the repo to a cross-spec working group where we can continue development? There is also a Slack instance for cross-spec activity.

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.