Add new cli option for generating Canonicalized Swagger

[dinwa-ms]

The canonical model is a data model which is a superset of all the other versions.
By adding canonicalized-version option with true value, it will generate a canonicalized swagger file CanonicalizedVersion.openapi.json

tsp compile . --emit=@azure-tools/typespec-autorest --option=canonicalized-version=true

Below is a general description about our design of Multi-Versioning in Azure Process (Canonical Version)

The canonical model is a data model which is a superset of all the other versions. The canonical model is the format that internal ARM platform components will communicate under (see design for more details). By default, typespec operates under a semi-canonical model. For all api versions typespec operates with one file. Because of this several constraints are automatically applied when authoring in typespec that make it more suitable for developing the canonical model. The idea behind this is that each one of these typespec files represents a fixed Set of Api Version. The model can then be iteratively updated to add or remove Additional Api Versions as long as the new version the model supports following a set of constraints. When these constraints are followed and assuming additional fields are pruned, every version of the canonical model is backwards compatible with any payload created to a previous version and vice versa.

For each RP, it can define only one multi-version schema per resource type. And it can further add new version in multi-version schema or deprecate version from multi-version schema.

This is an initial PR to generate a canonicalized swagger file, which is the superset of all the schemas of all versions. There are constraints like how to deal with @renamedFrom, which are our next step.

[github-actions]

Changes in this PR will be published to the following url to try(check status of TypeSpec Pull Request Try It pipeline for publish status):
Playground: https://cadlplayground.z22.web.core.windows.net/prs/2677/

Website: https://tspwebsitepr.z22.web.core.windows.net/prs/2677/

[timotheeguerin]

Those misc options are some legacy behavior and shouldn't be used, please look at this doc on how to specify emitter options https://microsoft.github.io/typespec/extending-typespec/emitters#custom-configuration-options

[bterlson]

Can you explain more about the goals of this PR, the scenarios it supports/how the output gets used, etc.?

[dinwa-ms]

Can you explain more about the goals of this PR, the scenarios it supports/how the output gets used, etc.?

Below is a general description about our design of Multi-Versioning in Azure Process (Canonical Version)

The canonical model is a data model which is a superset of all the other versions. The canonical model is the format that internal ARM platform components will communicate under (see design for more details). By default, typespec operates under a semi-canonical model. For all api versions typespec operates with one file. Because of this several constraints are automatically applied when authoring in typespec that make it more suitable for developing the canonical model. The idea behind this is that each one of these typespec files represents a fixed Set of Api Version. The model can then be iteratively updated to add or remove Additional Api Versions as long as the new version the model supports following a set of constraints. When these constraints are followed and assuming additional fields are pruned, every version of the canonical model is backwards compatible with any payload created to a previous version and vice versa.

For each RP, it can define only one multi-version schema per resource type. And it can further add new version in multi-version schema or deprecate version from multi-version schema.

This is an initial PR to generate a canonicalized swagger file, which is the superset of all the schemas of all versions. There are constraints like how to deal with @renamedFrom, which are our next step.

[timotheeguerin]

Can you explain more about the goals of this PR, the scenarios it supports/how the output gets used, etc.?

Below is a general description about our design of Multi-Versioning in Azure Process (Canonical Version)

The canonical model is a data model which is a superset of all the other versions. The canonical model is the format that internal ARM platform components will communicate under (see design for more details). By default, typespec operates under a semi-canonical model. For all api versions typespec operates with one file. Because of this several constraints are automatically applied when authoring in typespec that make it more suitable for developing the canonical model. The idea behind this is that each one of these typespec files represents a fixed Set of Api Version. The model can then be iteratively updated to add or remove Additional Api Versions as long as the new version the model supports following a set of constraints. When these constraints are followed and assuming additional fields are pruned, every version of the canonical model is backwards compatible with any payload created to a previous version and vice versa.

For each RP, it can define only one multi-version schema per resource type. And it can further add new version in multi-version schema or deprecate version from multi-version schema.

This is an initial PR to generate a canonicalized swagger file, which is the superset of all the schemas of all versions. There are constraints like how to deal with @renamedFrom, which are our next step.

@dinwa-ms I guess the question is more why do we need this in the openapi emitter? This doesn't really make sense as the service will never accept such payload.
Also from the description it seems like you are looking at the autorest(swagger 2.0) emitter and you changed the openapi3 emitter here. Autorest emitter can be found here https://github.com/Azure/typespec-azure/tree/main/packages/typespec-autorest

[dinwa-ms]

Can you explain more about the goals of this PR, the scenarios it supports/how the output gets used, etc.?

Below is a general description about our design of Multi-Versioning in Azure Process (Canonical Version)

The canonical model is a data model which is a superset of all the other versions. The canonical model is the format that internal ARM platform components will communicate under (see design for more details). By default, typespec operates under a semi-canonical model. For all api versions typespec operates with one file. Because of this several constraints are automatically applied when authoring in typespec that make it more suitable for developing the canonical model. The idea behind this is that each one of these typespec files represents a fixed Set of Api Version. The model can then be iteratively updated to add or remove Additional Api Versions as long as the new version the model supports following a set of constraints. When these constraints are followed and assuming additional fields are pruned, every version of the canonical model is backwards compatible with any payload created to a previous version and vice versa.

For each RP, it can define only one multi-version schema per resource type. And it can further add new version in multi-version schema or deprecate version from multi-version schema.

This is an initial PR to generate a canonicalized swagger file, which is the superset of all the schemas of all versions. There are constraints like how to deal with @renamedFrom, which are our next step.

@dinwa-ms I guess the question is more why do we need this in the openapi emitter? This doesn't really make sense as the service will never accept such payload. Also from the description it seems like you are looking at the autorest(swagger 2.0) emitter and you changed the openapi3 emitter here. Autorest emitter can be found here https://github.com/Azure/typespec-azure/tree/main/packages/typespec-autorest

You are correct. Sorry for this mistake. Will revert changes in openapi

[github-actions]

Changes in this PR will be published to the following url to try(check status of TypeSpec Pull Request Try It pipeline for publish status):
Playground: https://cadlplayground.z22.web.core.windows.net/prs/2677/

Website: https://tspwebsitepr.z22.web.core.windows.net/prs/2677/

[timotheeguerin]

Regardless of this being needed in autorest or not, you shouldn't need to change the versioning library and not resort to miscOptions. To run the versioning projection is an opt-in behavior from the emitter there shouldn't be a global option controlling that.

[dinwa-ms]

Regardless of this being needed in autorest or not, you shouldn't need to change the versioning library and not resort to miscOptions. To run the versioning projection is an opt-in behavior from the emitter there shouldn't be a global option controlling that.

Got that. Will looking into the emitter on this. Thanks

[timotheeguerin]

@dinwa-ms though even for the autorest emitter I don't think we still understand why this is needed, how is this going to be used? It will produce an invalid spec of the service.

[dinwa-ms]

@dinwa-ms though even for the autorest emitter I don't think we still understand why this is needed, how is this going to be used? It will produce an invalid spec of the service.

We found issues that there are components in the ARM ecosystem work in a publisher/consumer pattern. The consumer is tied to specific version, but the publisher decides to change it and the updated swagger is incompatible to the consumer. So, we want to have a multi-version schema and the services be able to convert to and from it. Please let me know if this makes sense to you. Also there is the design doc with more details. Thanks

[markcowl]

I don't think we want to produce a cross-version doc as part of the openapi3 emitter, because OpenAPI is inherently versioned. If we have a special need for canonicalized swagger or json, then we should do this in a separate emitter that is microsoft-specific - this will not be of general use to consumers of OpenAPI.