From b7876856ec2713f5ab3fa96d70123944f5b534a1 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 10:58:49 -0700 Subject: [PATCH 01/17] updating directory structure --- DirectoryStrucure.md | 172 +++++++++++++++++++++++++++++++++++++++++++ README.md | 153 +------------------------------------- 2 files changed, 174 insertions(+), 151 deletions(-) create mode 100644 DirectoryStrucure.md diff --git a/DirectoryStrucure.md b/DirectoryStrucure.md new file mode 100644 index 000000000000..3a7ebd099e79 --- /dev/null +++ b/DirectoryStrucure.md @@ -0,0 +1,172 @@ +# Directory Structure + +The the directory structure (aka folder layout) of this repository should strictly follow these rules: + +## profile + +The `profile` folder contains the profiles' definition files. The profile definition targets for hybrid applications that could run on Azure Stack general availability versions and Azure Cloud. + +## specification + +The `specification` folder is the root folder for all TypeSpec and OpenAPI specs +and related documents. Each child of `specification` corresponds to a `specification family`. + +## specification family + +Each child folder of a `specification` folder is root of given `specification family`. + +Example specification family root folder: [`specification/containerservice`]. + +Given specification family may have the following sub-folders: + +- `resource-provider`: TODO +- `data-plane`: TODO + + +1. **{RP-Name} Folders** - each resource provider should have at least one separate folder. + > If multiple folders are required? It depends on the following considerations: + > + > - An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities? + > - Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future? + > - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). + > - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). + + RP folders may contain resource manager or data plane TypeSpec "specs". TypeSpec is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Explore more by visiting the tutorial in the TypeSpec repo: [TypeSpec tutorial](http://aka.ms/cadlTutorial). You can also ask questions for providing feedback in the internal Teams channel [TypeSpec Discussion](https://teams.microsoft.com/l/channel/19%3a906c1efbbec54dc8949ac736633e6bdf%40thread.skype/Cadl%2520Discussion%2520%25F0%259F%2590%25AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47). + + For more information about the structure of TypeSpec files in the repo see [TypeSpec repo structure](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md). + +2. **'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else). There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present. + +3. **'Microsoft.{ARMNamespace}' Folders**: the folders are only required under the 'resource-manager' folder, which means only management-plane API specs require to have ARM Namespace in the file path. For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding](https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting). + +4. **'preview' and 'stable' Folders**: This maps to the service/component lifecycle stage: Preview and GA. For example, if a service is in Preview stage, no matter Private Preview or Public Preview, the API specs of the service should be placed in the `preview` folder. If the service is GAed, but a component is in preview, then the API version contains the preview component entity should be placed in the `preview` folder as well. The `stable` folder should contain API versions of a GAed service and all GAed components. + + > How's the Azure Breaking Change Policy apply to API specs in `preview` and `stable` folders? In fact, it is more relevant to if the repo is public or private. + > - API specs with components or resource types in Private Preview, or Limited Public Preview (behind [AFEC](https://armwiki.azurewebsites.net/rp_onboarding/afec/FeatureExposureControl.html) or managing visible subscriptions) are better to launch PR review in the private repository, aka., [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr). And these API specs are free of breaking changes. + > + > - On the other hand, everything public in the main branch of the public repository, aka., [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), no matter in the `preview` folder or in the `stable` folder, should be treated as contract with Azure customers, must follow [Azure Breaking Changes Policy](http://aka.ms/AzBreakingChangesPolicy). + +5. **API Versions Folders**: this folder is the direct child of the `preview` or `stable` folder. This folder contains the REST API Specs, and the `examples` folder. + +6. **'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples. + +> Note: some general guidance for folder names, and file names under `specification`: +> +> - Folder names should be singular (ie, 'profile' not 'profiles' ) -- this removes ambiguity for some non-english speakers. +> - Generic folder names should be lower-case +> - Namespace folders can be PascalCased (ie, "KeyVault") +> - Files are whatever case you think is good for your soul. + + +The structure should appear like so: +```bash +. +\---specification +| +---automation +| | \---resource-manager +| | +---Microsoft.Automation +| | | \---stable +| | | \---2015-10-31 +| | | \---examples +| | \---readme.md +| +---batch +| | +---data-plane +| | | +---stable +| | | | +---2016-07-01 +| | | | | \---examples +| | | | \---2017-01-01 +| | | | \---examples +| | | +---preview +| | | | \---2017-05-01-preview +| | | | \---examples +| | | \---readme.md +| | \---resource-manager +| | +---Microsoft.Batch +| | | \---stable +| | | +---2015-12-01 +| | | | \---examples +| | | +---2017-01-01 +| | | | \---examples +| | | \---2017-05-01 +| | | \---examples +| | \---readme.md +| \---playfab +| +---Playfab +| | \---tspconfig.yaml +| | \---main.tsp +| \--resource-manager +| +---Microsoft.Playfab +| | +---stable +| | | \---2017-02-27-preview +| | | \---examples +| | \---preview +| | \---2017-04-24-preview +| | \---examples +| \---readme.md +``` + +## Folder Structure for Service Group + +If you are working on API specification of a service group, then you may choose to build a folder structure as below. This folder structure brings more flexibility in multiple service teams collaboration, especially supporting: + +- To collect API definition of multiple components/services with different versioning cycle in one rp folder +- To share some common entity types among services or components under the same rp folder. + +In the following folder structure sample, there is only 'resource-manager' folder. There could be a similar folder structure under 'data-plane' folder, while the sub-component/sub-service folders may not be the same. + +Ensure to consult [API Spec Review](https://aka.ms/azsdk/support/specreview-channel) for the first time creating the folder structure or if you want to change current folder structure. + +```bash +. +\---specification +| +---compute +| | \---resource-manager +| | +---Microsoft.Compute +| | | +---compute +| | | | \---stable +| | | | \---2021-11-01 +| | | | +---compute.json +| | | | +---runCommands.json +| | | | \---examples +| | | +---sku +| | | | \---stable +| | | | \---2021-07-01 +| | | | +---skus.json +| | | | \---examples +| | | +---disk +| | | | \---stable +| | | | \---2021-12-01 +| | | | +---disk.json +| | | | \---examples +| | | +---gallery +| | | | \---stable +| | | | \---2021-10-01 +| | | | +---gallery.json +| | | | \---examples +| | | +---sharedgallery +| | | | \---stable +| | | | \---2021-07-01 +| | | | +---sharedGallery.json +| | | | +---communityGallery.json +| | | | \---examples +| | | +---cloudService +| | | | \---stable +| | | | \---2021-03-01 +| | | | +---cloudService.json +| | | | \---examples +| | | \---common-types +| | | \---v1 +| | | \---entity-types.json +| | | +| | \---readme.md +``` + +If the AutoRest configuration file (aka. the readme.md) is placed out of sub-service/sub-component folders, then there will be only one SDK package that holds all sub-services/sub-components. If the file is placed in each sub-service/sub-component folder, then there will be separate SDK packages of each sub-service/sub-component. Ensure to consult [Azure SDK ArchBoard](https://aka.ms/azsdk/onboarding/archboardschedule) for SDK packaging strategy when consolidating AutoRest configuration file for SDK generation. + +## common-types + +Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Entity type definition that can be shared cross resource providers or services should to be placed and maintained either under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types) under specification, or under **common-types** folder of service group folder structure. The former supports the entity type sharing cross rp folders, while the latter supports the entity type sharing cross components or services under the same rp folder. + +Refer to [Resource-Management](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management) common types for example. + +[`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice diff --git a/README.md b/README.md index 838227728eb7..8092515357bc 100644 --- a/README.md +++ b/README.md @@ -20,157 +20,7 @@ External Contributors can read [Getting Started with OpenAPI Specifications](htt ## Directory Structure -The structure of the directory should strictly follow these rules: - -1. **Profile**: The profile folder contains the profiles' definition files. The profile definition targets for hybrid applications that could run on Azure Stack general availability versions and Azure Cloud. - -2. **Specification**: This folder is the root folder for all Specs (Management Plane and Data Plane) related documents. - -3. **{RP-Name} Folders** - each resource provider should have at least one separate folder. - > If multiple folders are required? It depends on the following considerations: - > - > - An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities? - > - Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future? - > - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). - > - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). - - RP folders may contain resource manager or data plane TypeSpec "specs". TypeSpec is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Explore more by visiting the tutorial in the TypeSpec repo: [TypeSpec tutorial](http://aka.ms/cadlTutorial). You can also ask questions for providing feedback in the internal Teams channel [TypeSpec Discussion](https://teams.microsoft.com/l/channel/19%3a906c1efbbec54dc8949ac736633e6bdf%40thread.skype/Cadl%2520Discussion%2520%25F0%259F%2590%25AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47). - - For more information about the structure of TypeSpec files in the repo see [TypeSpec repo structure](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md). - -5. **'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else). There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present. - -6. **'Microsoft.{ARMNamespace}' Folders**: the folders are only required under the 'resource-manager' folder, which means only management-plane API specs require to have ARM Namespace in the file path. For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding](https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting). - -7. **'preview' and 'stable' Folders**: This maps to the service/component lifecycle stage: Preview and GA. For example, if a service is in Preview stage, no matter Private Preview or Public Preview, the API specs of the service should be placed in the `preview` folder. If the service is GAed, but a component is in preview, then the API version contains the preview component entity should be placed in the `preview` folder as well. The `stable` folder should contain API versions of a GAed service and all GAed components. - - > How's the Azure Breaking Change Policy apply to API specs in `preview` and `stable` folders? In fact, it is more relevant to if the repo is public or private. - > - API specs with components or resource types in Private Preview, or Limited Public Preview (behind [AFEC](https://armwiki.azurewebsites.net/rp_onboarding/afec/FeatureExposureControl.html) or managing visible subscriptions) are better to launch PR review in the private repository, aka., [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr). And these API specs are free of breaking changes. - > - > - On the other hand, everything public in the main branch of the public repository, aka., [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), no matter in the `preview` folder or in the `stable` folder, should be treated as contract with Azure customers, must follow [Azure Breaking Changes Policy](http://aka.ms/AzBreakingChangesPolicy). - -8. **API Versions Folders**: this folder is the direct child of the `preview` or `stable` folder. This folder contains the REST API Specs, and the `examples` folder. - -9. **'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples. - -> Note: some general guidance for folder names, and file names under `specification`: -> -> - Folder names should be singular (ie, 'profile' not 'profiles' ) -- this removes ambiguity for some non-english speakers. -> - Generic folder names should be lower-case -> - Namespace folders can be PascalCased (ie, "KeyVault") -> - Files are whatever case you think is good for your soul. - - -The structure should appear like so: -```bash -. -\---specification -| +---automation -| | \---resource-manager -| | +---Microsoft.Automation -| | | \---stable -| | | \---2015-10-31 -| | | \---examples -| | \---readme.md -| +---batch -| | +---data-plane -| | | +---stable -| | | | +---2016-07-01 -| | | | | \---examples -| | | | \---2017-01-01 -| | | | \---examples -| | | +---preview -| | | | \---2017-05-01-preview -| | | | \---examples -| | | \---readme.md -| | \---resource-manager -| | +---Microsoft.Batch -| | | \---stable -| | | +---2015-12-01 -| | | | \---examples -| | | +---2017-01-01 -| | | | \---examples -| | | \---2017-05-01 -| | | \---examples -| | \---readme.md -| \---playfab -| +---Playfab -| | \---tspconfig.yaml -| | \---main.tsp -| \--resource-manager -| +---Microsoft.Playfab -| | +---stable -| | | \---2017-02-27-preview -| | | \---examples -| | \---preview -| | \---2017-04-24-preview -| | \---examples -| \---readme.md -``` - -### Folder Structure for Service Group - -If you are working on API specification of a service group, then you may choose to build a folder structure as below. This folder structure brings more flexibility in multiple service teams collaboration, especially supporting: - -- To collect API definition of multiple components/services with different versioning cycle in one rp folder -- To share some common entity types among services or components under the same rp folder. - -In the following folder structure sample, there is only 'resource-manager' folder. There could be a similar folder structure under 'data-plane' folder, while the sub-component/sub-service folders may not be the same. - -Ensure to consult [API Spec Review](https://aka.ms/azsdk/support/specreview-channel) for the first time creating the folder structure or if you want to change current folder structure. - -```bash -. -\---specification -| +---compute -| | \---resource-manager -| | +---Microsoft.Compute -| | | +---compute -| | | | \---stable -| | | | \---2021-11-01 -| | | | +---compute.json -| | | | +---runCommands.json -| | | | \---examples -| | | +---sku -| | | | \---stable -| | | | \---2021-07-01 -| | | | +---skus.json -| | | | \---examples -| | | +---disk -| | | | \---stable -| | | | \---2021-12-01 -| | | | +---disk.json -| | | | \---examples -| | | +---gallery -| | | | \---stable -| | | | \---2021-10-01 -| | | | +---gallery.json -| | | | \---examples -| | | +---sharedgallery -| | | | \---stable -| | | | \---2021-07-01 -| | | | +---sharedGallery.json -| | | | +---communityGallery.json -| | | | \---examples -| | | +---cloudService -| | | | \---stable -| | | | \---2021-03-01 -| | | | +---cloudService.json -| | | | \---examples -| | | \---common-types -| | | \---v1 -| | | \---entity-types.json -| | | -| | \---readme.md -``` - -If the AutoRest configuration file (aka. the readme.md) is placed out of sub-service/sub-component folders, then there will be only one SDK package that holds all sub-services/sub-components. If the file is placed in each sub-service/sub-component folder, then there will be separate SDK packages of each sub-service/sub-component. Ensure to consult [Azure SDK ArchBoard](https://aka.ms/azsdk/onboarding/archboardschedule) for SDK packaging strategy when consolidating AutoRest configuration file for SDK generation. - -### common-types - -Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Entity type definition that can be shared cross resource providers or services should to be placed and maintained either under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types) under specification, or under **common-types** folder of service group folder structure. The former supports the entity type sharing cross rp folders, while the latter supports the entity type sharing cross components or services under the same rp folder. - -Refer to [Resource-Management](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management) common types for example. +See [DirectoryStructure.md](./DirectoryStructure.md) for details on the directory structure of this repository. ## Next steps @@ -180,3 +30,4 @@ External Contributors can read [Getting Started with OpenAPI Specifications](htt --- _This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments._ + From b792702efccaaa3e04d50f419c5ccbd8f090d852 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 11:53:15 -0700 Subject: [PATCH 02/17] ongoing --- README.md | 2 +- .../directory-structure.md | 88 ++++++++++++++----- 2 files changed, 67 insertions(+), 23 deletions(-) rename DirectoryStrucure.md => documentation/directory-structure.md (66%) diff --git a/README.md b/README.md index 8092515357bc..49db1c9d7156 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ External Contributors can read [Getting Started with OpenAPI Specifications](htt ## Directory Structure -See [DirectoryStructure.md](./DirectoryStructure.md) for details on the directory structure of this repository. +See [directory-structure.md](./documentation/directory-structure.md) for details on the directory structure of this repository. ## Next steps diff --git a/DirectoryStrucure.md b/documentation/directory-structure.md similarity index 66% rename from DirectoryStrucure.md rename to documentation/directory-structure.md index 3a7ebd099e79..37fcf82aa20f 100644 --- a/DirectoryStrucure.md +++ b/documentation/directory-structure.md @@ -9,46 +9,73 @@ The `profile` folder contains the profiles' definition files. The profile defini ## specification The `specification` folder is the root folder for all TypeSpec and OpenAPI specs -and related documents. Each child of `specification` corresponds to a `specification family`. +and related documents. Each child of `specification` corresponds to a `resource provider`. -## specification family +## resource provider -Each child folder of a `specification` folder is root of given `specification family`. +Each child folder of a `specification` folder is a root of given `resource provider`. -Example specification family root folder: [`specification/containerservice`]. +Example resource provider families root folders: -Given specification family may have the following sub-folders: +- [`specification/containerservice`] +- [`specification/confidentialledger`] -- `resource-provider`: TODO -- `data-plane`: TODO +Given resource provider `rp` has following structure, +for multiple values of `rpnamespace` (`rpnamespace` stands for **resource provider namespace**, see relevant section): +- `specification/rp/rpnamespace` +- `specification/rp/data-plane/rpnamespace` +- `specification/rp/resource-manager/rpnamespace` -1. **{RP-Name} Folders** - each resource provider should have at least one separate folder. - > If multiple folders are required? It depends on the following considerations: - > - > - An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities? - > - Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future? - > - Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). - > - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). +The `specification/rp/rpnamespace` directories contain TypeSpec sources. +To learn about TypeSpec, see [aka.ms/azsdk/typespec] and [aka.ms/typespec]. +To learn these directories structure, see [TypeSpec directory structure] article. +The rest of this article pertains to the `specficiation` directory structure +**excluding** the contents of `specification/rp/rpnamespace`. + + +## `resource-manager` and `data-plane` folders + +The OpenAPI specs in `specification/rp/resource-manager` pertain to ARM resources while +the OpenAPI specs in `specification/rp/data-plane` pertain to everything else. + +There should be an AutoRest configuration file (`readme.md`) at the root of each +of these directories when present. + +If TypeSpec sources are present, OpenAPI specs in the `resource-manager` +and `data-plane` folders are generated from TypeSpec sources. + +## Resource provider namespace (`rpnamespace`) folders + +Each `rpnamespace` folder (whether in `specification/rp`, in `specification/rp/data-plane` or `specification/rp/resource-manager`) corresponds to a resource provider namespace. - RP folders may contain resource manager or data plane TypeSpec "specs". TypeSpec is a language for describing cloud service APIs and generating other API description languages, client and service code, documentation, and other assets. Explore more by visiting the tutorial in the TypeSpec repo: [TypeSpec tutorial](http://aka.ms/cadlTutorial). You can also ask questions for providing feedback in the internal Teams channel [TypeSpec Discussion](https://teams.microsoft.com/l/channel/19%3a906c1efbbec54dc8949ac736633e6bdf%40thread.skype/Cadl%2520Discussion%2520%25F0%259F%2590%25AE?groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47). +Its name is of form `Microsoft.`. Strictly speaking specs in `data-plane` +folder are not required to be organized by `rpnamespace`. - For more information about the structure of TypeSpec files in the repo see [TypeSpec repo structure](https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md). - -2. **'resource-manager' and 'data-plane' Folders**: the RPs can put specs in one of two categories: `resource-manager` (for ARM resources) and `data-plane` (for everything else). There should be an AutoRest configuration file (`readme.md`) for the RP inside both of these folders when present. +For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding]. -3. **'Microsoft.{ARMNamespace}' Folders**: the folders are only required under the 'resource-manager' folder, which means only management-plane API specs require to have ARM Namespace in the file path. For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding](https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting). +## Resource provider namespace (`rpnamespace`) folders layout -4. **'preview' and 'stable' Folders**: This maps to the service/component lifecycle stage: Preview and GA. For example, if a service is in Preview stage, no matter Private Preview or Public Preview, the API specs of the service should be placed in the `preview` folder. If the service is GAed, but a component is in preview, then the API version contains the preview component entity should be placed in the `preview` folder as well. The `stable` folder should contain API versions of a GAed service and all GAed components. +Each `rpnamespace` folder within `resource-manager` and `data-plane` may contain the following: + +`rpnamespace/stable/api_version` +`rpnamespace/preview/api_version` + +If the contents of `data-plane` folder are not organized by `rpnamespace`, we treat +the `data-plane` folder itself as the "default namespace" for the purposes of describing +the required layout. + + +2. **'preview' and 'stable' Folders**: This maps to the service/component lifecycle stage: Preview and GA. For example, if a service is in Preview stage, no matter Private Preview or Public Preview, the API specs of the service should be placed in the `preview` folder. If the service is GAed, but a component is in preview, then the API version contains the preview component entity should be placed in the `preview` folder as well. The `stable` folder should contain API versions of a GAed service and all GAed components. > How's the Azure Breaking Change Policy apply to API specs in `preview` and `stable` folders? In fact, it is more relevant to if the repo is public or private. > - API specs with components or resource types in Private Preview, or Limited Public Preview (behind [AFEC](https://armwiki.azurewebsites.net/rp_onboarding/afec/FeatureExposureControl.html) or managing visible subscriptions) are better to launch PR review in the private repository, aka., [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr). And these API specs are free of breaking changes. > > - On the other hand, everything public in the main branch of the public repository, aka., [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), no matter in the `preview` folder or in the `stable` folder, should be treated as contract with Azure customers, must follow [Azure Breaking Changes Policy](http://aka.ms/AzBreakingChangesPolicy). -5. **API Versions Folders**: this folder is the direct child of the `preview` or `stable` folder. This folder contains the REST API Specs, and the `examples` folder. +3. **API Versions Folders**: this folder is the direct child of the `preview` or `stable` folder. This folder contains the REST API Specs, and the `examples` folder. -6. **'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples. +4. **'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples. > Note: some general guidance for folder names, and file names under `specification`: > @@ -169,4 +196,21 @@ Specification files and AutoRest configuration files in one RP folder are better Refer to [Resource-Management](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management) common types for example. +## FAQ + +### Are multiple RP folders required? + +If multiple folders are required? It depends on the following considerations: + +- An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities? +- Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future? +- Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). +- For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). + + [`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice +[`specification/confidentialledger`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/confidentialledger +[aka.ms/azsdk/typespec]: https://aka.ms/azsdk/typespec +[aka.ms/typespec]: https://aka.ms/typespec +[TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md +[RP Onboarding]: https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting From 89eb49fe028f0057601d87475d7d82e9d346d8a6 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 12:13:37 -0700 Subject: [PATCH 03/17] ongoing --- documentation/directory-structure.md | 45 +++++++++++++++++----------- 1 file changed, 28 insertions(+), 17 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index 37fcf82aa20f..9c4bdec0f589 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -1,10 +1,21 @@ # Directory Structure -The the directory structure (aka folder layout) of this repository should strictly follow these rules: +- [Directory Structure](#directory-structure) + - [specification](#specification) + - [resource provider](#resource-provider) + - [`resource-manager` and `data-plane` folders](#resource-manager-and-data-plane-folders) + - [Resource provider namespace (`rpnamespace`) folders](#resource-provider-namespace-rpnamespace-folders) + - [Resource provider namespace (`rpnamespace`) folders layout](#resource-provider-namespace-rpnamespace-folders-layout) + - [API version (`api_version`) folders layout](#api-version-api_version-folders-layout) + - [`examples` folder](#examples-folder) + - [General folder naming guidance for contents of `specification` folder](#general-folder-naming-guidance-for-contents-of-specification-folder) + - [Folder Structure for Service Group](#folder-structure-for-service-group) + - [common-types](#common-types) + - [FAQ](#faq) + - [Are multiple RP folders required?](#are-multiple-rp-folders-required) -## profile -The `profile` folder contains the profiles' definition files. The profile definition targets for hybrid applications that could run on Azure Stack general availability versions and Azure Cloud. +The the directory structure (aka folder layout) of this repository should strictly follow these rules: ## specification @@ -56,7 +67,7 @@ For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboar ## Resource provider namespace (`rpnamespace`) folders layout -Each `rpnamespace` folder within `resource-manager` and `data-plane` may contain the following: +Each `rpnamespace` folder within `resource-manager` and `data-plane` may contain the following, for multiple values of `api_version`: `rpnamespace/stable/api_version` `rpnamespace/preview/api_version` @@ -65,25 +76,23 @@ If the contents of `data-plane` folder are not organized by `rpnamespace`, we tr the `data-plane` folder itself as the "default namespace" for the purposes of describing the required layout. +Here `api_version` is an versioned set of OpenAPI specs. `stable` and `preview` correspond to the lifecycle stages of the API versions within. Learn more about API version and their lifecycle +stages at [aka.ms/azsdk/pr-api-versions]. -2. **'preview' and 'stable' Folders**: This maps to the service/component lifecycle stage: Preview and GA. For example, if a service is in Preview stage, no matter Private Preview or Public Preview, the API specs of the service should be placed in the `preview` folder. If the service is GAed, but a component is in preview, then the API version contains the preview component entity should be placed in the `preview` folder as well. The `stable` folder should contain API versions of a GAed service and all GAed components. +## API version (`api_version`) folders layout - > How's the Azure Breaking Change Policy apply to API specs in `preview` and `stable` folders? In fact, it is more relevant to if the repo is public or private. - > - API specs with components or resource types in Private Preview, or Limited Public Preview (behind [AFEC](https://armwiki.azurewebsites.net/rp_onboarding/afec/FeatureExposureControl.html) or managing visible subscriptions) are better to launch PR review in the private repository, aka., [azure-rest-api-specs-pr](https://github.com/Azure/azure-rest-api-specs-pr). And these API specs are free of breaking changes. - > - > - On the other hand, everything public in the main branch of the public repository, aka., [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs), no matter in the `preview` folder or in the `stable` folder, should be treated as contract with Azure customers, must follow [Azure Breaking Changes Policy](http://aka.ms/AzBreakingChangesPolicy). +Each `api_version` folder is the direct child of the `preview` or `stable` folder. This folder contains the REST OpenAPI Specs `.json` files, and the `examples` folder. -3. **API Versions Folders**: this folder is the direct child of the `preview` or `stable` folder. This folder contains the REST API Specs, and the `examples` folder. +### `examples` folder -4. **'examples' Folders**: the example folder will contain the x-ms-examples files. it will reside under the APIs or Resources' version folders as different APIs or Resource types version can have different examples. +Each `api_version/examples` folder contains the `x-ms-examples` files. -> Note: some general guidance for folder names, and file names under `specification`: -> -> - Folder names should be singular (ie, 'profile' not 'profiles' ) -- this removes ambiguity for some non-english speakers. -> - Generic folder names should be lower-case -> - Namespace folders can be PascalCased (ie, "KeyVault") -> - Files are whatever case you think is good for your soul. +## General folder naming guidance for contents of `specification` folder +- Folder names should be singular (e.g. `keyvault` not `keyvaults` ) -- this removes ambiguity for some non-english speakers. +- Generic folder names should be lower-case +- Namespace (`rpnamespace`) folders can be PascalCased (e.g. `KeyVault`) +- Files are whatever case you think is good for your soul. The structure should appear like so: ```bash @@ -214,3 +223,5 @@ If multiple folders are required? It depends on the following considerations: [aka.ms/typespec]: https://aka.ms/typespec [TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md [RP Onboarding]: https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting + +[aka.ms/azsdk/pr-api-versions]: https://aka.ms/azsdk/pr-api-versions From 83e49928eadf6dc1f46fcdee6cc352ead7c5f0b4 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 13:49:37 -0700 Subject: [PATCH 04/17] ongoing --- documentation/directory-structure.md | 145 +++++++++++---------------- 1 file changed, 61 insertions(+), 84 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index 9c4bdec0f589..c89f93014026 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -1,47 +1,60 @@ -# Directory Structure +# Specification directory Structure -- [Directory Structure](#directory-structure) - - [specification](#specification) - - [resource provider](#resource-provider) + + +- [Specification directory Structure](#specification-directory-structure) + - [`specification` folder](#specification-folder) + - [Resource provider (`rp`) folder](#resource-provider-rp-folder) + - [TypeSpec sources](#typespec-sources) - [`resource-manager` and `data-plane` folders](#resource-manager-and-data-plane-folders) - [Resource provider namespace (`rpnamespace`) folders](#resource-provider-namespace-rpnamespace-folders) - [Resource provider namespace (`rpnamespace`) folders layout](#resource-provider-namespace-rpnamespace-folders-layout) - [API version (`api_version`) folders layout](#api-version-api_version-folders-layout) - [`examples` folder](#examples-folder) - - [General folder naming guidance for contents of `specification` folder](#general-folder-naming-guidance-for-contents-of-specification-folder) - - [Folder Structure for Service Group](#folder-structure-for-service-group) + - [Naming guidelines for `specification` folder contents](#naming-guidelines-for-specification-folder-contents) + - [Example layout of a `specification` folder](#example-layout-of-a-specification-folder) + - [Folder Structure for service groups](#folder-structure-for-service-groups) - [common-types](#common-types) - [FAQ](#faq) - - [Are multiple RP folders required?](#are-multiple-rp-folders-required) + - [Should my service team have one or multiple resource provider folders?](#should-my-service-team-have-one-or-multiple-resource-provider-folders) + +This article described the directory structure / folder layout of the `specification` folder. +The layout described in this article is strictly enforced. There exist +some exceptions for historical reasons. These exceptions are not allowed going forward. -The the directory structure (aka folder layout) of this repository should strictly follow these rules: -## specification +## `specification` folder The `specification` folder is the root folder for all TypeSpec and OpenAPI specs and related documents. Each child of `specification` corresponds to a `resource provider`. +There is a special case of a `service group`: see [Folder Structure for service groups](#folder-structure-for-service-groups). -## resource provider +## Resource provider (`rp`) folder -Each child folder of a `specification` folder is a root of given `resource provider`. +Each child folder of the `specification` folder is a root of given `resource provider`. -Example resource provider families root folders: +Example resource providers root folders: - [`specification/containerservice`] - [`specification/confidentialledger`] Given resource provider `rp` has following structure, -for multiple values of `rpnamespace` (`rpnamespace` stands for **resource provider namespace**, see relevant section): +for multiple values of `rpnamespace` (`rpnamespace` stands for **resource provider namespace**; see [relevant section](#resource-provider-namespace-rpnamespace-folders)): - `specification/rp/rpnamespace` - `specification/rp/data-plane/rpnamespace` - `specification/rp/resource-manager/rpnamespace` +### TypeSpec sources + The `specification/rp/rpnamespace` directories contain TypeSpec sources. To learn about TypeSpec, see [aka.ms/azsdk/typespec] and [aka.ms/typespec]. To learn these directories structure, see [TypeSpec directory structure] article. -The rest of this article pertains to the `specficiation` directory structure +The rest of this article pertains to the `specification` directory structure **excluding** the contents of `specification/rp/rpnamespace`. @@ -76,25 +89,25 @@ If the contents of `data-plane` folder are not organized by `rpnamespace`, we tr the `data-plane` folder itself as the "default namespace" for the purposes of describing the required layout. -Here `api_version` is an versioned set of OpenAPI specs. `stable` and `preview` correspond to the lifecycle stages of the API versions within. Learn more about API version and their lifecycle -stages at [aka.ms/azsdk/pr-api-versions]. - ## API version (`api_version`) folders layout -Each `api_version` folder is the direct child of the `preview` or `stable` folder. This folder contains the REST OpenAPI Specs `.json` files, and the `examples` folder. +`api_version` within given `rpnamespace/stable` or `rpnamespace/preview` is a versioned set of OpenAPI specs. `stable` and `preview` correspond to the lifecycle stages of the API versions within. Learn more about API versions, their directory layout and their lifecycle stages at [aka.ms/azsdk/pr-api-versions]. + +Each `api_version` folder is a direct child of the `preview` or `stable` folder. This folder contains the REST OpenAPI Specs `.json` files, and the `examples` folder. ### `examples` folder -Each `api_version/examples` folder contains the `x-ms-examples` files. +Each `api_version/examples` folder contains [`x-ms-examples`] files. -## General folder naming guidance for contents of `specification` folder +## Naming guidelines for `specification` folder contents - Folder names should be singular (e.g. `keyvault` not `keyvaults` ) -- this removes ambiguity for some non-english speakers. -- Generic folder names should be lower-case -- Namespace (`rpnamespace`) folders can be PascalCased (e.g. `KeyVault`) +- Generic folder names should be lower-case. +- Namespace (`rpnamespace`) folders can be PascalCased (e.g. `KeyVault`). - Files are whatever case you think is good for your soul. -The structure should appear like so: +## Example layout of a `specification` folder + ```bash . \---specification @@ -132,88 +145,47 @@ The structure should appear like so: | | \---main.tsp | \--resource-manager | +---Microsoft.Playfab -| | +---stable -| | | \---2017-02-27-preview -| | | \---examples | | \---preview | | \---2017-04-24-preview | | \---examples | \---readme.md ``` -## Folder Structure for Service Group +In the example above: -If you are working on API specification of a service group, then you may choose to build a folder structure as below. This folder structure brings more flexibility in multiple service teams collaboration, especially supporting: +`rp` folders are `automation`, `batch`, `playfab`. +TypeSpec folders are `specification/playfab/Playfab`. +`rpnamespace` names present are: `Microsoft.Automation` (in `automation` rp), `Microsoft.Batch` (in `batch` rp) and `Microsoft.Playfab` (in `playfab` rp). -- To collect API definition of multiple components/services with different versioning cycle in one rp folder -- To share some common entity types among services or components under the same rp folder. +## Folder Structure for service groups -In the following folder structure sample, there is only 'resource-manager' folder. There could be a similar folder structure under 'data-plane' folder, while the sub-component/sub-service folders may not be the same. +In some existing cases the `specification/rp` folder is not a root of one resource provider, +but of a **service group**. A service group combines multiple resource providers, +from multiple teams, in one `specification/rp` folder. In this situation the layout +constraints described in this article are partially violated, e.g. given `rpnamespace` instead +of having `stable` and `preview` as direct children, has extra layer of "sub-service" name, like `rpnamespace/compute`. This scenario is not allowed going forward and existing teams will migrate away from it, eventually. -Ensure to consult [API Spec Review](https://aka.ms/azsdk/support/specreview-channel) for the first time creating the folder structure or if you want to change current folder structure. +Examples of an existing services groups: +- [`specification/compute`] +- [`specification/workloads`] -```bash -. -\---specification -| +---compute -| | \---resource-manager -| | +---Microsoft.Compute -| | | +---compute -| | | | \---stable -| | | | \---2021-11-01 -| | | | +---compute.json -| | | | +---runCommands.json -| | | | \---examples -| | | +---sku -| | | | \---stable -| | | | \---2021-07-01 -| | | | +---skus.json -| | | | \---examples -| | | +---disk -| | | | \---stable -| | | | \---2021-12-01 -| | | | +---disk.json -| | | | \---examples -| | | +---gallery -| | | | \---stable -| | | | \---2021-10-01 -| | | | +---gallery.json -| | | | \---examples -| | | +---sharedgallery -| | | | \---stable -| | | | \---2021-07-01 -| | | | +---sharedGallery.json -| | | | +---communityGallery.json -| | | | \---examples -| | | +---cloudService -| | | | \---stable -| | | | \---2021-03-01 -| | | | +---cloudService.json -| | | | \---examples -| | | \---common-types -| | | \---v1 -| | | \---entity-types.json -| | | -| | \---readme.md -``` - -If the AutoRest configuration file (aka. the readme.md) is placed out of sub-service/sub-component folders, then there will be only one SDK package that holds all sub-services/sub-components. If the file is placed in each sub-service/sub-component folder, then there will be separate SDK packages of each sub-service/sub-component. Ensure to consult [Azure SDK ArchBoard](https://aka.ms/azsdk/onboarding/archboardschedule) for SDK packaging strategy when consolidating AutoRest configuration file for SDK generation. ## common-types -Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Entity type definition that can be shared cross resource providers or services should to be placed and maintained either under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types) under specification, or under **common-types** folder of service group folder structure. The former supports the entity type sharing cross rp folders, while the latter supports the entity type sharing cross components or services under the same rp folder. +Specification files and AutoRest configuration files in one resource provider folder are better to refer to files in the same resource provider folder. Entity type definition that can be shared cross resource providers or services should to be placed and maintained either under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types) under specification, or under **common-types** folder of service group folder structure. The former supports the entity type sharing cross rp folders, while the latter supports the entity type sharing cross components or services under the same rp folder. Refer to [Resource-Management](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management) common types for example. ## FAQ -### Are multiple RP folders required? +### Should my service team have one or multiple resource provider folders? -If multiple folders are required? It depends on the following considerations: +Should given service team add multiple `specification/rp` folders, or just one? +It depends on the following considerations: -- An RP folder leads to a separate SDK package. Is it expected to have separate SDK packages for different service/component entities? -- Service/component entities in one folder share the same versioning cycle. Can service/component entities in one folder share the same version label, and upgrade together in the future? -- Specification files and AutoRest configuration files in one RP folder are better to refer to files in the same RP folder. Note: Entity type definition that needs to be referred cross RP folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). +- An rp folder leads to a separate SDK package. Is it expected to have separate SDK packages for different services? +- Service in one folder share the same versioning cycle. Can service in one folder share the same version label, and upgrade together in the future? +- Specification files and AutoRest configuration files in one rp folder are better to refer to files in the same rp folder. Note: Entity type definition that needs to be referred cross rp folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). @@ -225,3 +197,8 @@ If multiple folders are required? It depends on the following considerations: [RP Onboarding]: https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting [aka.ms/azsdk/pr-api-versions]: https://aka.ms/azsdk/pr-api-versions +[`x-ms-examples`]: https://azure.github.io/autorest/extensions/#x-ms-examples + +[`specification/workloads`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/workloads/resource-manager/Microsoft.Workloads + +[`specification/compute`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute From 21821e26b86e1b4fb6bcc62f83c532e3d5301caf Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 13:52:21 -0700 Subject: [PATCH 05/17] remove extra empty line --- documentation/directory-structure.md | 1 - 1 file changed, 1 deletion(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index c89f93014026..f5b458e7d105 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -26,7 +26,6 @@ This article described the directory structure / folder layout of the `specifica The layout described in this article is strictly enforced. There exist some exceptions for historical reasons. These exceptions are not allowed going forward. - ## `specification` folder The `specification` folder is the root folder for all TypeSpec and OpenAPI specs From 4481b43b5158ad8f5e9f32ff82775a046daab038 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 14:02:51 -0700 Subject: [PATCH 06/17] remove empty lines --- documentation/directory-structure.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index f5b458e7d105..7cf9c7fe935d 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -56,7 +56,6 @@ To learn these directories structure, see [TypeSpec directory structure] article The rest of this article pertains to the `specification` directory structure **excluding** the contents of `specification/rp/rpnamespace`. - ## `resource-manager` and `data-plane` folders The OpenAPI specs in `specification/rp/resource-manager` pertain to ARM resources while @@ -168,7 +167,6 @@ Examples of an existing services groups: - [`specification/compute`] - [`specification/workloads`] - ## common-types Specification files and AutoRest configuration files in one resource provider folder are better to refer to files in the same resource provider folder. Entity type definition that can be shared cross resource providers or services should to be placed and maintained either under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types) under specification, or under **common-types** folder of service group folder structure. The former supports the entity type sharing cross rp folders, while the latter supports the entity type sharing cross components or services under the same rp folder. @@ -187,7 +185,6 @@ It depends on the following considerations: - Specification files and AutoRest configuration files in one rp folder are better to refer to files in the same rp folder. Note: Entity type definition that needs to be referred cross rp folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). - [`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice [`specification/confidentialledger`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/confidentialledger [aka.ms/azsdk/typespec]: https://aka.ms/azsdk/typespec From 7e22c8e9f3b66b1c921794df547c261ede28f620 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 14:03:57 -0700 Subject: [PATCH 07/17] reorder references --- documentation/directory-structure.md | 15 ++++++--------- 1 file changed, 6 insertions(+), 9 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index 7cf9c7fe935d..4cbd62d44b0a 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -185,16 +185,13 @@ It depends on the following considerations: - Specification files and AutoRest configuration files in one rp folder are better to refer to files in the same rp folder. Note: Entity type definition that needs to be referred cross rp folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). - For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). -[`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice -[`specification/confidentialledger`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/confidentialledger +[aka.ms/azsdk/pr-api-versions]: https://aka.ms/azsdk/pr-api-versions [aka.ms/azsdk/typespec]: https://aka.ms/azsdk/typespec [aka.ms/typespec]: https://aka.ms/typespec -[TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md [RP Onboarding]: https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting - -[aka.ms/azsdk/pr-api-versions]: https://aka.ms/azsdk/pr-api-versions -[`x-ms-examples`]: https://azure.github.io/autorest/extensions/#x-ms-examples - -[`specification/workloads`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/workloads/resource-manager/Microsoft.Workloads - +[TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md [`specification/compute`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute +[`specification/confidentialledger`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/confidentialledger +[`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice +[`specification/workloads`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/workloads/resource-manager/Microsoft.Workloads +[`x-ms-examples`]: https://azure.github.io/autorest/extensions/#x-ms-examples From 886e0550f100298b7190818a71995995761b784f Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 14:07:12 -0700 Subject: [PATCH 08/17] update --- documentation/directory-structure.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index 4cbd62d44b0a..b9d83292a32c 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -15,7 +15,7 @@ https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one - [API version (`api_version`) folders layout](#api-version-api_version-folders-layout) - [`examples` folder](#examples-folder) - [Naming guidelines for `specification` folder contents](#naming-guidelines-for-specification-folder-contents) - - [Example layout of a `specification` folder](#example-layout-of-a-specification-folder) + - [Example layout of the `specification` folder](#example-layout-of-the-specification-folder) - [Folder Structure for service groups](#folder-structure-for-service-groups) - [common-types](#common-types) - [FAQ](#faq) @@ -104,7 +104,7 @@ Each `api_version/examples` folder contains [`x-ms-examples`] files. - Namespace (`rpnamespace`) folders can be PascalCased (e.g. `KeyVault`). - Files are whatever case you think is good for your soul. -## Example layout of a `specification` folder +## Example layout of the `specification` folder ```bash . From 6f4513c7248c51f23aae434d407d3b2a5ffffb7e Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Tue, 26 Mar 2024 14:11:25 -0700 Subject: [PATCH 09/17] add resource provider list --- documentation/directory-structure.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index b9d83292a32c..b7e131f4e040 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -48,6 +48,9 @@ for multiple values of `rpnamespace` (`rpnamespace` stands for **resource provid - `specification/rp/data-plane/rpnamespace` - `specification/rp/resource-manager/rpnamespace` +For a list of existing resource providers and their corresponding Azure services, +consult the [resource provider list]. + ### TypeSpec sources The `specification/rp/rpnamespace` directories contain TypeSpec sources. @@ -188,6 +191,7 @@ It depends on the following considerations: [aka.ms/azsdk/pr-api-versions]: https://aka.ms/azsdk/pr-api-versions [aka.ms/azsdk/typespec]: https://aka.ms/azsdk/typespec [aka.ms/typespec]: https://aka.ms/typespec +[resource provider list]: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service [RP Onboarding]: https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting [TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md [`specification/compute`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute From 436864fdb39a3494e90e7a6e6d053ed769ac061a Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Wed, 3 Apr 2024 19:06:03 -0700 Subject: [PATCH 10/17] rewrite based on Jeffrey's input --- documentation/directory-structure.md | 316 +++++++++++++++------------ 1 file changed, 178 insertions(+), 138 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index b7e131f4e040..fdbf84040264 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -1,201 +1,241 @@ -# Specification directory Structure +# `specification` directory structure -- [Specification directory Structure](#specification-directory-structure) +- [`specification` directory structure](#specification-directory-structure) - [`specification` folder](#specification-folder) - - [Resource provider (`rp`) folder](#resource-provider-rp-folder) - - [TypeSpec sources](#typespec-sources) - [`resource-manager` and `data-plane` folders](#resource-manager-and-data-plane-folders) - - [Resource provider namespace (`rpnamespace`) folders](#resource-provider-namespace-rpnamespace-folders) - - [Resource provider namespace (`rpnamespace`) folders layout](#resource-provider-namespace-rpnamespace-folders-layout) - - [API version (`api_version`) folders layout](#api-version-api_version-folders-layout) - - [`examples` folder](#examples-folder) + - [AutoRest configuration `README.md` files](#autorest-configuration-readmemd-files) + - [`stable` and `preview` folders](#stable-and-preview-folders) + - [A complete example directory structure of `specification/AzureTeamFolder`](#a-complete-example-directory-structure-of-specificationazureteamfolder) - [Naming guidelines for `specification` folder contents](#naming-guidelines-for-specification-folder-contents) - - [Example layout of the `specification` folder](#example-layout-of-the-specification-folder) - - [Folder Structure for service groups](#folder-structure-for-service-groups) - - [common-types](#common-types) - - [FAQ](#faq) - - [Should my service team have one or multiple resource provider folders?](#should-my-service-team-have-one-or-multiple-resource-provider-folders) + - [`specification/common-types`](#specificationcommon-types) + - [Advanced scenario: service group](#advanced-scenario-service-group) + - [Service group `common-types`](#service-group-common-types) + - [Versioning services in a service group](#versioning-services-in-a-service-group) + - [Legacy layouts and OpenAPI specs](#legacy-layouts-and-openapi-specs) -This article described the directory structure / folder layout of the `specification` folder. +This article describes the directory structure / folder layout of the `specification` folder. +You may be also interested in following: +- [Specification index] +- [Resource Provider list] -The layout described in this article is strictly enforced. There exist -some exceptions for historical reasons. These exceptions are not allowed going forward. +> [!IMPORTANT] +> The layout described in this article is strictly enforced. There exist some exceptions for historical reasons. These exceptions are not allowed going forward. ## `specification` folder -The `specification` folder is the root folder for all TypeSpec and OpenAPI specs -and related documents. Each child of `specification` corresponds to a `resource provider`. -There is a special case of a `service group`: see [Folder Structure for service groups](#folder-structure-for-service-groups). +The `specification` folder is the root folder for all service specifications. -## Resource provider (`rp`) folder +Each child of the `specification` folder corresponds to a `service` specification for given Azure team. Here we denote such folder as `AzureTeamFolder`. -Each child folder of the `specification` folder is a root of given `resource provider`. +Given `AzureTeamFolder` has following structure: -Example resource providers root folders: +- `AzureTeamFolder/TypeSpecFolder` (multiple folders) +- `AzureTeamFolder/resource-manager` +- `AzureTeamFolder/data-plane` -- [`specification/containerservice`] -- [`specification/confidentialledger`] +The `AzureTeamFolder/TypeSpecFolder` folders contain the TypeSpec specification for the given `service`. +You can find details on the name and contents of these folders in [TypeSpec directory structure]. +You can learn more about TypeSpec at [aka.ms/azsdk/typespec] and [aka.ms/typespec]. -Given resource provider `rp` has following structure, -for multiple values of `rpnamespace` (`rpnamespace` stands for **resource provider namespace**; see [relevant section](#resource-provider-namespace-rpnamespace-folders)): +## `resource-manager` and `data-plane` folders -- `specification/rp/rpnamespace` -- `specification/rp/data-plane/rpnamespace` -- `specification/rp/resource-manager/rpnamespace` +The `AzureTeamFolder/resource-manager` contains the ARM OpenAPI specifications emitted from TypeSpec in `AzureTeamFolder/TypeSpecFolder`. -For a list of existing resource providers and their corresponding Azure services, -consult the [resource provider list]. +The `resource-manager` folder has exactly one child folder whose name matches the **Resource Provider (RP) Namespace** (`RPNS`), +such as `Microsoft.Automation` (full list of namespaces is [here][Resource Provider list]). +There is 1 to 1 correspondence between an RP and an RP namespace. +There must be **exactly one** RP namespace folder under given `resource-manager` folder. +We denote such folder as `resource-manager/RPNS`. -### TypeSpec sources +The `AzureTeamFolder/data-plane` contains the data-plane OpenAPI specifications emitted from TypeSpec in `TypeSpecFolder`. +The `data-plane` folder has no child `RPNS` folder. However, it can have a set of `dataPlaneSubfolder` folders. -The `specification/rp/rpnamespace` directories contain TypeSpec sources. -To learn about TypeSpec, see [aka.ms/azsdk/typespec] and [aka.ms/typespec]. -To learn these directories structure, see [TypeSpec directory structure] article. -The rest of this article pertains to the `specification` directory structure -**excluding** the contents of `specification/rp/rpnamespace`. +## AutoRest configuration `README.md` files -## `resource-manager` and `data-plane` folders +Both the `AzureTeamFolder/resource-manager` and `AzureTeamFolder/data-plane` folders must contain an AutoRest configuration file, `README.md`. +Learn more about this file at [aka.ms/azsdk/autorest]. + + + +Each `README.md` describes a single `service` and is used as an SDK package and documentation for each version of the service. +Inside the `README.md` file there are lists of paths to OpenAPI spec `.json` files making up given service version. + +> [!NOTE] +> All OpenAPI specs for given service version (i.e. the list of paths in given `input-file:` block in the `README.md`) must have the same service version, +> which also means being in the same [API version lifecycle stage][aka.ms/azsdk/api-versions]. + +## `stable` and `preview` folders + +Both `AzureTeamFolder/resource-manager/RPNS` and `AzureTeamFolder/data-plane/dataPlaneSubfolder` folders, in addition to containing `README.md`, also can contain +`stable` and `preview` folders. These folders contain OpenAPI specs in the `stable` and `preview` [lifecycle stages][aka.ms/azsdk/api-versions] +respectively, organized in `apiVersion` subfolders for each service API version. For example, `AzureTeamFolder/resource-manager/RPNS/stable/apiVersion` or +`AzureTeamFolder/data-plane/dataPlaneSubfolder/preview/apiVersion-preview`. + +Each such API version folder directly contains a set of `.json` files containing OpenAPI specs emitted from TypeSpec, as well as an `examples` child folder +with `.json` files having the contents of [`x-ms-examples`] referenced from the OpenAPI specs. + +## A complete example directory structure of `specification/AzureTeamFolder` + +Putting everything together discussed, the directory structure of a singular `specification/AzureTeamFolder/` is as follows: + +``` yaml +/TypeSpecFolder1/... +/TypeSpecFolder2/... # multiple 'TypeSpecFolder' folders + +/resource-manager/README.md +/resource-manager/RPNS/stable/apiVersion1/*.json +/resource-manager/RPNS/stable/apiVersion1/examples/*.json + /apiVersion2/ ... # multiple 'apiVersion' folders +/resource-manager/RPNS/preview/apiVersion3-preview/*.json +/resource-manager/RPNS/preview/apiVersion3-preview/examples/*.json + /apiVersion4-preview/ ... # multiple 'apiVersion-preview' folders + +/data-plane/README.md +/data-plane/dataPlaneSubfolder1/stable/apiVersion5/*.json +/data-plane/dataPlaneSubfolder1/stable/apiVersion5/examples/*.json + /apiVersion6/ ... # multiple 'apiVersion' folders +/data-plane/dataPlaneSubfolder1/preview/apiVersion7-preview/*.json +/data-plane/dataPlaneSubfolder1/preview/apiVersion7-preview/examples/*.json + /apiVersion8-preview/ ... # multiple 'apiVersion-preview' folders + /dataPlaneSubfolder2/ ... # multiple 'dataPlaneSubfolder' folders + +``` + +As a specific example of the above, consider [`specification/confidentialledger`] `AzureTeamFolder` which has the following structure: -The OpenAPI specs in `specification/rp/resource-manager` pertain to ARM resources while -the OpenAPI specs in `specification/rp/data-plane` pertain to everything else. +``` yaml -There should be an AutoRest configuration file (`readme.md`) at the root of each -of these directories when present. +# ===== TypeSpecFolders -If TypeSpec sources are present, OpenAPI specs in the `resource-manager` -and `data-plane` folders are generated from TypeSpec sources. +/Microsoft.CodeTransparency/ +/Microsoft.ManagedCcf/ -## Resource provider namespace (`rpnamespace`) folders +# ===== data-plane -Each `rpnamespace` folder (whether in `specification/rp`, in `specification/rp/data-plane` or `specification/rp/resource-manager`) corresponds to a resource provider namespace. +/data-plane/README.md -Its name is of form `Microsoft.`. Strictly speaking specs in `data-plane` -folder are not required to be organized by `rpnamespace`. +# ----- dataPlaneSubfolder: Microsoft.CodeTransparency -For ARM Namespace and ARM onboarding, please refer to the ARM wiki of [RP Onboarding]. +/data-plane/Microsoft.CodeTransparency/preview/2024-01-11-preview +/data-plane/Microsoft.CodeTransparency/preview/2024-01-11-preview/examples -## Resource provider namespace (`rpnamespace`) folders layout +# ----- dataPlaneSubfolder: Microsoft.ConfidentialLedger -Each `rpnamespace` folder within `resource-manager` and `data-plane` may contain the following, for multiple values of `api_version`: +/data-plane/Microsoft.ConfidentialLedger/stable +/data-plane/Microsoft.ConfidentialLedger/stable/2022-05-13 +/data-plane/Microsoft.ConfidentialLedger/stable/2022-05-13/examples -`rpnamespace/stable/api_version` -`rpnamespace/preview/api_version` +/data-plane/Microsoft.ConfidentialLedger/preview +/data-plane/Microsoft.ConfidentialLedger/preview/2023-01-18-preview +/data-plane/Microsoft.ConfidentialLedger/preview/2023-01-18-preview/examples +# ... more previews here -If the contents of `data-plane` folder are not organized by `rpnamespace`, we treat -the `data-plane` folder itself as the "default namespace" for the purposes of describing -the required layout. +# ----- dataPlaneSubfolder: Microsoft.ManagedCcf -## API version (`api_version`) folders layout +/data-plane/Microsoft.ManagedCcf/preview/2023-06-01-preview +/data-plane/Microsoft.ManagedCcf/preview/2023-06-01-preview/examples -`api_version` within given `rpnamespace/stable` or `rpnamespace/preview` is a versioned set of OpenAPI specs. `stable` and `preview` correspond to the lifecycle stages of the API versions within. Learn more about API versions, their directory layout and their lifecycle stages at [aka.ms/azsdk/pr-api-versions]. +# ===== resource-manager -Each `api_version` folder is a direct child of the `preview` or `stable` folder. This folder contains the REST OpenAPI Specs `.json` files, and the `examples` folder. +/resource-manager/README.md -### `examples` folder +# ----- resource-manager RP Namespace (RPNS): Microsoft.ConfidentialLedger -Each `api_version/examples` folder contains [`x-ms-examples`] files. +/resource-manager/Microsoft.ConfidentialLedger/stable/2022-05-13 +/resource-manager/Microsoft.ConfidentialLedger/stable/2022-05-13/examples + +/resource-manager/Microsoft.ConfidentialLedger/preview/2023-06-28-preview +/resource-manager/Microsoft.ConfidentialLedger/preview/2023-06-28-preview/examples +# ... more previews here +/resource-manager/Microsoft.ConfidentialLedger/preview/2020-12-01-preview +/resource-manager/Microsoft.ConfidentialLedger/preview/2020-12-01-preview/examples + +``` + +For another example, see [`specification/eventgrid`]. ## Naming guidelines for `specification` folder contents - Folder names should be singular (e.g. `keyvault` not `keyvaults` ) -- this removes ambiguity for some non-english speakers. - Generic folder names should be lower-case. -- Namespace (`rpnamespace`) folders can be PascalCased (e.g. `KeyVault`). -- Files are whatever case you think is good for your soul. - -## Example layout of the `specification` folder - -```bash -. -\---specification -| +---automation -| | \---resource-manager -| | +---Microsoft.Automation -| | | \---stable -| | | \---2015-10-31 -| | | \---examples -| | \---readme.md -| +---batch -| | +---data-plane -| | | +---stable -| | | | +---2016-07-01 -| | | | | \---examples -| | | | \---2017-01-01 -| | | | \---examples -| | | +---preview -| | | | \---2017-05-01-preview -| | | | \---examples -| | | \---readme.md -| | \---resource-manager -| | +---Microsoft.Batch -| | | \---stable -| | | +---2015-12-01 -| | | | \---examples -| | | +---2017-01-01 -| | | | \---examples -| | | \---2017-05-01 -| | | \---examples -| | \---readme.md -| \---playfab -| +---Playfab -| | \---tspconfig.yaml -| | \---main.tsp -| \--resource-manager -| +---Microsoft.Playfab -| | \---preview -| | \---2017-04-24-preview -| | \---examples -| \---readme.md -``` +- Resource Provider Namespace (`RPNS`) folders can be PascalCased (e.g. `KeyVault`). +- For file names, any casing is allowed. +- When in doubt, mimic naming of the examples provided in this article. + +## `specification/common-types` + +The special directory of [`specification/common-types`] contains shared definitions that can be reused across all Azure team services in their +`specification` child folders. + +## Advanced scenario: service group + +In case of big Azure teams, their `specification/AzureTeamFolder` hosts multiple services, together known as `service group`. +The main difference between one service and a service group is how they are presented to Azure customers: +One service has one SDK package and one documentation portal, while a service group has separate SDK package for each service and separate documentation. + +For example, [`specification/containerservice`] is a `service group` for both `aks` and `fleet` services. + +The doc for `aks` is [Azure Kubernetes Service]. It points to aks REST reference e.g. for [API version `2024-01-01`][aks REST reference 2024-01-01], +which corresponds to [`specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01`]. + +The doc for `fleet` is [Azure Kubernetes Fleet Manager]. It point to fleet REST reference, e.g. for [API version `2023-10-15`][fleet REST reference 2023-10-15], +which corresponds to [`specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15`]. -In the example above: +Note the most important directory structure difference of a `service group` scenario as compared to singular `service`: -`rp` folders are `automation`, `batch`, `playfab`. -TypeSpec folders are `specification/playfab/Playfab`. -`rpnamespace` names present are: `Microsoft.Automation` (in `automation` rp), `Microsoft.Batch` (in `batch` rp) and `Microsoft.Playfab` (in `playfab` rp). +- The `resource-manager/Microsoft.ContainerService` folder has multiple child service folders which contain `stable` and `preview` folders for each service, + instead of directly containing `stable` and `preview` folders. +- Each of the `aks` and `fleet` subfolders have their own `README.md` file, instead of there being one `README.md` in the `resource-manager` folder. + As a result, the SDKs of these serivces are separated. -## Folder Structure for service groups +### Service group `common-types` -In some existing cases the `specification/rp` folder is not a root of one resource provider, -but of a **service group**. A service group combines multiple resource providers, -from multiple teams, in one `specification/rp` folder. In this situation the layout -constraints described in this article are partially violated, e.g. given `rpnamespace` instead -of having `stable` and `preview` as direct children, has extra layer of "sub-service" name, like `rpnamespace/compute`. This scenario is not allowed going forward and existing teams will migrate away from it, eventually. +A service group can also introduce its own set of `common-types` which are too general to be shared across all Azure teams but common enough to be +shared across all services in given service group. For an example, see [`Microsoft.Compute/common-types`]. -Examples of an existing services groups: -- [`specification/compute`] -- [`specification/workloads`] +### Versioning services in a service group -## common-types +The versioning policy for API and SDK packages applies independently to each service in the service group. +This means that each service in the service group must obey the same versioning rules as it were a singular service. +However, multiple separate services can have different versioning cycles, including different SDK packages. Refer to the aforementioned `aks` and `fleet` +services for examples of different versioning cycles in a service group -Specification files and AutoRest configuration files in one resource provider folder are better to refer to files in the same resource provider folder. Entity type definition that can be shared cross resource providers or services should to be placed and maintained either under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types) under specification, or under **common-types** folder of service group folder structure. The former supports the entity type sharing cross rp folders, while the latter supports the entity type sharing cross components or services under the same rp folder. +## Legacy layouts and OpenAPI specs -Refer to [Resource-Management](https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types/resource-management) common types for example. +As mentioned at the beginning of this article, for historical reasons, some `specification/AzureTeamFolder` folders may +violate some of the constraints presented in this article. This includes violations like: -## FAQ +- More deeply nested subfolders than allowed +- Incorrect lack of `-preview` suffix in `preview` API versions +- Mixing of `stable` and `preview` API versions in the same folder subtree +- Mixing of multiple API versions in given README.md package, including mixing of multiple API version lifecycle stages. -### Should my service team have one or multiple resource provider folders? +In addition, some `AzureTeamFolder` folders have OpenAPI specs that have been written manually instead of emitted from TypeSpec. In some cases +the folders have mixture: some OpenAPI specs are written manually, while others are emitted from TypeSpec. -Should given service team add multiple `specification/rp` folders, or just one? -It depends on the following considerations: - -- An rp folder leads to a separate SDK package. Is it expected to have separate SDK packages for different services? -- Service in one folder share the same versioning cycle. Can service in one folder share the same version label, and upgrade together in the future? -- Specification files and AutoRest configuration files in one rp folder are better to refer to files in the same rp folder. Note: Entity type definition that needs to be referred cross rp folders should be placed and maintained under the folder [**common-types**](https://github.com/Azure/azure-rest-api-specs#common-types). -- For more considerations, you may consult the reviewer in API design review. To initiate the review, Please submit an [Azure SDK intake questionnaire](https://aka.ms/sdk-apex). +All of the aforementioned cases are considered legacy and are not allowed going forward. -[aka.ms/azsdk/pr-api-versions]: https://aka.ms/azsdk/pr-api-versions +[aka.ms/azsdk/api-versions]: https://aka.ms/azsdk/api-versions +[aka.ms/azsdk/autorest]: https://aka.ms/azsdk/autorest [aka.ms/azsdk/typespec]: https://aka.ms/azsdk/typespec [aka.ms/typespec]: https://aka.ms/typespec -[resource provider list]: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service -[RP Onboarding]: https://armwiki.azurewebsites.net/rp_onboarding/process/onboarding.html#0-on-boarding-meeting +[aks REST reference 2024-01-01]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01 +[Azure Kubernetes Fleet Manager]: https://learn.microsoft.com/en-us/azure/kubernetes-fleet/ +[Azure Kubernetes Service]: https://learn.microsoft.com/en-us/azure/aks/ +[fleet REST reference 2023-10-15]: https://learn.microsoft.com/en-us/rest/api/fleet/operation-groups?view=rest-fleet-2023-10-15 +[Resource Provider list]: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service +[Specification index]: https://azure.github.io/azure-sdk/releases/latest/all/specs.html [TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md -[`specification/compute`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute +[`Microsoft.Compute/common-types`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/common-types/ +[`specification/common-types`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types [`specification/confidentialledger`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/confidentialledger +[`specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01 +[`specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15 [`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice -[`specification/workloads`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/workloads/resource-manager/Microsoft.Workloads +[`specification/eventgrid`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/eventgrid [`x-ms-examples`]: https://azure.github.io/autorest/extensions/#x-ms-examples From 9a8b9b3cc7a97b1bf7777589c29613fdb151dec3 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Wed, 3 Apr 2024 22:41:26 -0700 Subject: [PATCH 11/17] fix typos --- documentation/directory-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index fdbf84040264..12b631b483a7 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -191,7 +191,7 @@ Note the most important directory structure difference of a `service group` scen - The `resource-manager/Microsoft.ContainerService` folder has multiple child service folders which contain `stable` and `preview` folders for each service, instead of directly containing `stable` and `preview` folders. - Each of the `aks` and `fleet` subfolders have their own `README.md` file, instead of there being one `README.md` in the `resource-manager` folder. - As a result, the SDKs of these serivces are separated. + As a result, the SDKs of these services are separate. ### Service group `common-types` From b329b74f7b8299586aeabc7bc6f3d97fd0340113 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Wed, 3 Apr 2024 22:42:57 -0700 Subject: [PATCH 12/17] grammar --- documentation/directory-structure.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index 12b631b483a7..76199cf4c299 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -213,10 +213,10 @@ violate some of the constraints presented in this article. This includes violati - More deeply nested subfolders than allowed - Incorrect lack of `-preview` suffix in `preview` API versions - Mixing of `stable` and `preview` API versions in the same folder subtree -- Mixing of multiple API versions in given README.md package, including mixing of multiple API version lifecycle stages. +- Mixing of multiple API versions in given `README.md` package, including mixing of multiple API version lifecycle stages. -In addition, some `AzureTeamFolder` folders have OpenAPI specs that have been written manually instead of emitted from TypeSpec. In some cases -the folders have mixture: some OpenAPI specs are written manually, while others are emitted from TypeSpec. +In addition, some `AzureTeamFolder` folders have OpenAPI specs that have been written manually instead of emitted from TypeSpec. +In some cases the folders have mixture of manually-written and TypeSpec-emitted OpenAPI specs. All of the aforementioned cases are considered legacy and are not allowed going forward. From 85bd31035162bc4d3f8857c733157584d980d597 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Wed, 3 Apr 2024 22:45:09 -0700 Subject: [PATCH 13/17] Add missing period --- documentation/directory-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index 76199cf4c299..a4f1937ad149 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -203,7 +203,7 @@ shared across all services in given service group. For an example, see [`Microso The versioning policy for API and SDK packages applies independently to each service in the service group. This means that each service in the service group must obey the same versioning rules as it were a singular service. However, multiple separate services can have different versioning cycles, including different SDK packages. Refer to the aforementioned `aks` and `fleet` -services for examples of different versioning cycles in a service group +services for examples of different versioning cycles in a service group. ## Legacy layouts and OpenAPI specs From ee5ac33ef50ca4ffbf969e33c89df8f1ce62b94e Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Thu, 4 Apr 2024 16:07:55 -0700 Subject: [PATCH 14/17] Update directory-structure.md: add short link --- documentation/directory-structure.md | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index a4f1937ad149..37c46436bd4c 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -1,4 +1,5 @@ -# `specification` directory structure +| Short Link: | [aka.ms/azsdk/spec-dirs](https://aka.ms/azsdk/spec-dirs) | +|--|--| @@ -75,46 +74,46 @@ Inside the `README.md` file there are lists of paths to OpenAPI spec `.json` fil ## `stable` and `preview` folders -Both `AzureTeamFolder/resource-manager/RPNS` and `AzureTeamFolder/data-plane/dataPlaneSubfolder` folders, in addition to containing `README.md`, also can contain +Both `/resource-manager/` and `/data-plane/` folders, in addition to containing `README.md`, also can contain `stable` and `preview` folders. These folders contain OpenAPI specs in the `stable` and `preview` [lifecycle stages][aka.ms/azsdk/api-versions] -respectively, organized in `apiVersion` subfolders for each service API version. For example, `AzureTeamFolder/resource-manager/RPNS/stable/apiVersion` or -`AzureTeamFolder/data-plane/dataPlaneSubfolder/preview/apiVersion-preview`. +respectively, organized in `` subfolders for each service API version. For example, `/resource-manager//stable/` or +`/data-plane//preview/`. Each such API version folder directly contains a set of `.json` files containing OpenAPI specs emitted from TypeSpec, as well as an `examples` child folder with `.json` files having the contents of [`x-ms-examples`] referenced from the OpenAPI specs. -## A complete example directory structure of `specification/AzureTeamFolder` +## A complete example directory structure of `specification/` -Putting everything together discussed, the directory structure of a singular `specification/AzureTeamFolder/` is as follows: +Putting everything together discussed, the directory structure of a singular `specification//` is as follows: ``` yaml -/TypeSpecFolder1/... -/TypeSpecFolder2/... # multiple 'TypeSpecFolder' folders +/1/... +/2/... # multiple '' folders /resource-manager/README.md -/resource-manager/RPNS/stable/apiVersion1/*.json -/resource-manager/RPNS/stable/apiVersion1/examples/*.json - /apiVersion2/ ... # multiple 'apiVersion' folders -/resource-manager/RPNS/preview/apiVersion3-preview/*.json -/resource-manager/RPNS/preview/apiVersion3-preview/examples/*.json - /apiVersion4-preview/ ... # multiple 'apiVersion-preview' folders +/resource-manager//stable//*.json +/resource-manager//stable//examples/*.json + // ... # multiple 'apiVer' folders +/resource-manager//preview//*.json +/resource-manager//preview//examples/*.json + // ... # multiple 'apiVer-preview' folders /data-plane/README.md -/data-plane/dataPlaneSubfolder1/stable/apiVersion5/*.json -/data-plane/dataPlaneSubfolder1/stable/apiVersion5/examples/*.json - /apiVersion6/ ... # multiple 'apiVersion' folders -/data-plane/dataPlaneSubfolder1/preview/apiVersion7-preview/*.json -/data-plane/dataPlaneSubfolder1/preview/apiVersion7-preview/examples/*.json - /apiVersion8-preview/ ... # multiple 'apiVersion-preview' folders - /dataPlaneSubfolder2/ ... # multiple 'dataPlaneSubfolder' folders +/data-plane//stable//*.json +/data-plane//stable//examples/*.json + // ... # multiple 'apiVer' folders +/data-plane//preview//*.json +/data-plane//preview//examples/*.json + // ... # multiple 'apiVer-preview' folders + // ... # multiple '' folders ``` -As a specific example of the above, consider [`specification/confidentialledger`] `AzureTeamFolder` which has the following structure: +As a specific example of the above, consider [`specification/confidentialledger`] `` which has the following structure: ``` yaml -# ===== TypeSpecFolders +# ===== s /Microsoft.CodeTransparency/ /Microsoft.ManagedCcf/ @@ -123,12 +122,12 @@ As a specific example of the above, consider [`specification/confidentialledger` /data-plane/README.md -# ----- dataPlaneSubfolder: Microsoft.CodeTransparency +# ----- : Microsoft.CodeTransparency /data-plane/Microsoft.CodeTransparency/preview/2024-01-11-preview /data-plane/Microsoft.CodeTransparency/preview/2024-01-11-preview/examples -# ----- dataPlaneSubfolder: Microsoft.ConfidentialLedger +# ----- : Microsoft.ConfidentialLedger /data-plane/Microsoft.ConfidentialLedger/stable /data-plane/Microsoft.ConfidentialLedger/stable/2022-05-13 @@ -139,7 +138,7 @@ As a specific example of the above, consider [`specification/confidentialledger` /data-plane/Microsoft.ConfidentialLedger/preview/2023-01-18-preview/examples # ... more previews here -# ----- dataPlaneSubfolder: Microsoft.ManagedCcf +# ----- : Microsoft.ManagedCcf /data-plane/Microsoft.ManagedCcf/preview/2023-06-01-preview /data-plane/Microsoft.ManagedCcf/preview/2023-06-01-preview/examples @@ -148,7 +147,7 @@ As a specific example of the above, consider [`specification/confidentialledger` /resource-manager/README.md -# ----- resource-manager RP Namespace (RPNS): Microsoft.ConfidentialLedger +# ----- resource-manager RP Namespace (): Microsoft.ConfidentialLedger /resource-manager/Microsoft.ConfidentialLedger/stable/2022-05-13 /resource-manager/Microsoft.ConfidentialLedger/stable/2022-05-13/examples @@ -167,7 +166,7 @@ For another example, see [`specification/eventgrid`]. - Folder names should be singular (e.g. `keyvault` not `keyvaults` ) -- this removes ambiguity for some non-english speakers. - Generic folder names should be lower-case. -- Resource Provider Namespace (`RPNS`) folders can be PascalCased (e.g. `KeyVault`). +- Resource Provider Namespace (``) folders can be PascalCased (e.g. `KeyVault`). - For file names, any casing is allowed. - When in doubt, mimic naming of the examples provided in this article. @@ -178,7 +177,7 @@ The special directory of [`specification/common-types`] contains shared definiti ## Advanced scenario: service group -In case of big Azure teams, their `specification/AzureTeamFolder` hosts multiple services, together known as `service group`. +In case of big Azure teams, their `specification/` hosts multiple services, together known as `service group`. The main difference between one service and a service group is how they are presented to Azure customers: One service has one SDK package and one documentation portal, while a service group has separate SDK package for each service and separate documentation. @@ -209,9 +208,9 @@ This means that each service in the service group must obey the same versioning However, multiple separate services can have different versioning cycles, including different SDK packages. Refer to the aforementioned `aks` and `fleet` services for examples of different versioning cycles in a service group. -## Legacy layouts and OpenAPI specs +## Deprecated structure and hand-written OpenAPI specs -As mentioned at the beginning of this article, for historical reasons, some `specification/AzureTeamFolder` folders may +As mentioned at the beginning of this article, for historical reasons, some `specification/` folders may violate some of the constraints presented in this article. This includes violations like: - More deeply nested subfolders than allowed @@ -219,11 +218,19 @@ violate some of the constraints presented in this article. This includes violati - Mixing of `stable` and `preview` API versions in the same folder subtree - Mixing of multiple API versions in given `README.md` package, including mixing of multiple API version lifecycle stages. -In addition, some `AzureTeamFolder` folders have OpenAPI specs that have been written manually instead of emitted from TypeSpec. +In addition, some `` folders have OpenAPI specs that have been written manually instead of emitted from TypeSpec. In some cases the folders have mixture of manually-written and TypeSpec-emitted OpenAPI specs. All of the aforementioned cases are considered legacy and are not allowed going forward. +[`Microsoft.Compute/common-types`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/common-types/ +[`specification/common-types`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types +[`specification/confidentialledger`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/confidentialledger +[`specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01 +[`specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15 +[`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice +[`specification/eventgrid`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/eventgrid +[`x-ms-examples`]: https://azure.github.io/autorest/extensions/#x-ms-examples [aka.ms/azsdk/api-versions]: https://aka.ms/azsdk/api-versions [aka.ms/azsdk/autorest]: https://aka.ms/azsdk/autorest [aka.ms/azsdk/typespec]: https://aka.ms/azsdk/typespec @@ -235,11 +242,3 @@ All of the aforementioned cases are considered legacy and are not allowed going [Resource Provider list]: https://learn.microsoft.com/en-us/azure/azure-resource-manager/management/azure-services-resource-providers#match-resource-provider-to-service [Specification index]: https://azure.github.io/azure-sdk/releases/latest/all/specs.html [TypeSpec directory structure]: https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md -[`Microsoft.Compute/common-types`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/compute/resource-manager/Microsoft.Compute/common-types/ -[`specification/common-types`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/common-types -[`specification/confidentialledger`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/confidentialledger -[`specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/aks/stable/2024-01-01 -[`specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15 -[`specification/containerservice`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/containerservice -[`specification/eventgrid`]: https://github.com/Azure/azure-rest-api-specs/tree/main/specification/eventgrid -[`x-ms-examples`]: https://azure.github.io/autorest/extensions/#x-ms-examples From 28b960c148b6878898d3e4e61425d764fc74ad9d Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Fri, 5 Apr 2024 13:30:40 -0700 Subject: [PATCH 16/17] add mention of service groups in spec folder section --- documentation/directory-structure.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index c16d36346f6d..9af1e21cb12d 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -27,13 +27,16 @@ You may be also interested in following: - [Resource Provider list] > [!IMPORTANT] -> The layout described in this article is strictly enforced. There exist some exceptions for historical reasons. These exceptions are not allowed going forward. +> The structure described in this article is strictly enforced. There exist some exceptions for historical reasons. +> These exceptions are not allowed going forward. ## `specification` folder The `specification` folder is the root folder for all service specifications. Each child of the `specification` folder corresponds to a `service` specification for given Azure team. Here we denote such folder as ``. +In advanced cases for big teams the `` folder can host multiple services, known as `service group`. +Read [the relevant section](#advanced-scenario-service-group) for details. Given `` has following structure: @@ -41,7 +44,7 @@ Given `` has following structure: - `/resource-manager` - `/data-plane` -The `/` folders contain the TypeSpec specification for the given `service`. +The `/` folders contain the TypeSpec specification for the given `service` or `service group`. You can find details on the name and contents of these folders in [TypeSpec directory structure]. You can learn more about TypeSpec at [aka.ms/azsdk/typespec] and [aka.ms/typespec]. From b072d2bf91d0c30e946d6ab1a6409fe6f30296a5 Mon Sep 17 00:00:00 2001 From: Konrad Jamrozik Date: Fri, 5 Apr 2024 13:35:27 -0700 Subject: [PATCH 17/17] minor fixups --- documentation/directory-structure.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/documentation/directory-structure.md b/documentation/directory-structure.md index 9af1e21cb12d..adb8b6bee041 100644 --- a/documentation/directory-structure.md +++ b/documentation/directory-structure.md @@ -192,7 +192,7 @@ which corresponds to [`specification/containerservice/resource-manager/Microsoft The doc for `fleet` is [Azure Kubernetes Fleet Manager]. It point to fleet REST reference, e.g. for [API version `2023-10-15`][fleet REST reference 2023-10-15], which corresponds to [`specification/containerservice/resource-manager/Microsoft.ContainerService/fleet/stable/2023-10-15`]. -Note the most important directory structure difference of a `service group` scenario as compared to singular `service`: +Using our example, note the most important directory structure difference of a `service group` scenario as compared to singular `service`: - The `resource-manager/Microsoft.ContainerService` folder has multiple child service folders which contain `stable` and `preview` folders for each service, instead of directly containing `stable` and `preview` folders. @@ -216,9 +216,9 @@ services for examples of different versioning cycles in a service group. As mentioned at the beginning of this article, for historical reasons, some `specification/` folders may violate some of the constraints presented in this article. This includes violations like: -- More deeply nested subfolders than allowed -- Incorrect lack of `-preview` suffix in `preview` API versions -- Mixing of `stable` and `preview` API versions in the same folder subtree +- More deeply nested subfolders than allowed. +- Incorrect lack of `-preview` suffix in `preview` API versions. +- Mixing of `stable` and `preview` API versions in the same folder subtree. - Mixing of multiple API versions in given `README.md` package, including mixing of multiple API version lifecycle stages. In addition, some `` folders have OpenAPI specs that have been written manually instead of emitted from TypeSpec.