Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update the specification directory structure article #28464

Merged
merged 18 commits into from
Apr 5, 2024
Merged

Update the specification directory structure article #28464

Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
b787685
updating directory structure
Mar 26, 2024
b792702
ongoing
Mar 26, 2024
89eb49f
ongoing
Mar 26, 2024
83e4992
ongoing
Mar 26, 2024
21821e2
remove extra empty line
Mar 26, 2024
4481b43
remove empty lines
Mar 26, 2024
7e22c8e
reorder references
Mar 26, 2024
886e055
update
Mar 26, 2024
6f4513c
add resource provider list
Mar 26, 2024
436864f
rewrite based on Jeffrey's input
Apr 4, 2024
9a8b9b3
fix typos
Apr 4, 2024
b329b74
grammar
Apr 4, 2024
85bd310
Add missing period
Apr 4, 2024
ee5ac33
Update directory-structure.md: add short link
Apr 4, 2024
229e663
Merge branch 'main' into users/kojamroz/dir_struct
Apr 5, 2024
1add6f2
apply review remarks
Apr 5, 2024
28b960c
add mention of service groups in spec folder section
Apr 5, 2024
b072d2b
minor fixups
Apr 5, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
153 changes: 2 additions & 151 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
konrad-jamrozik marked this conversation as resolved.
Show resolved Hide resolved

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.
konrad-jamrozik marked this conversation as resolved.
Show resolved Hide resolved

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 [directory-structure.md](./documentation/directory-structure.md) for details on the directory structure of this repository.

## Next steps

Expand All @@ -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._

Loading