Skip to content

Latest commit

 

History

History
217 lines (155 loc) · 12 KB

directory-structure.md

File metadata and controls

217 lines (155 loc) · 12 KB
Short Link: aka.ms/azsdk/spec-dirs

specification directory structure

This article describes the directory structure / folder layout of the specification folder. You may be also interested in following:

Important

The structure described in this article is recommended. There exist some exceptions for historical reasons. These exceptions are strongly discouraged going forward.

Key concepts

The directory structure is a reflection of a few key concepts.

Familiarize yourself with the concepts of service, service group, grouping directory and uniform versioning as explained in the glossary.

specification folder

The specification folder is the root folder for all service specifications.

Each child of the specification folder corresponds to <azureTeam>. All the service (see glossary) specifications owned by that team are rooted in their <azureTeam> folder.

Given <azureTeam> folder has following structure:

  • <azureTeam>/<typeSpecSrc> (multiple <TypeSpecSrc> folders are allowed)
  • <azureTeam>/resource-manager/<RPNS> (exactly one <RPNS> folder is allowed)
  • <azureTeam>/data-plane/<groupingDir> (multiple <groupingDir> folders are allowed)

<typeSpecSrc> folders

The <azureTeam>/<typeSpecSrc> folders contain the TypeSpec specifications for the services owned by the team.

The content of these folders is used as input to emit OpenAPI specifications placed within <azureTeam>/resource-manager/<RPNS> folder and <azureTeam>/data-plane/<groupingDir> folders.

Note

Some services may not have <typeSpecSrc> folders. In such case, these services OpenAPI specs are hand-written.
This is legacy, deprecated practice and is not allowed going forward.

You can find details on the name and contents of <typeSpecSrc> folders in TypeSpec directory structure. You can learn more about TypeSpec at aka.ms/azsdk/typespec and aka.ms/typespec.

resource-manager/<RPNS> folder

The <azureTeam>/resource-manager/<RPNS> is a folder corresponding to ARM Resource Provider (RP) namespace.

An example RPNS is Microsoft.Automation. A list of RPs can be found in the Resource Provider list.

This folder corresponds to a service group (see glossary) for all ARM services owned by the team.

An <RPNS> folder has one or more child <service> folders corresponding to the services belonging to the service group represented by the <RPNS> folder.

For example, specification/containerservice/resource-manager/Microsoft.ContainerService/aks is a folder for the aks service within the Microsoft.ContainerService ARM Resource Provider namespace.

Note

Many Azure teams that have one ARM service instead of rooting it in specification/<azureTeam>/resource-manager/<RPNS>/<service> root it in specification/<azureTeam>/resource-manager.
This is legacy, deprecated structure and is strongly discouraged going forward.

In addition, the <RPNS> folder may contain common-types child folder that usually is of form common-types/v<versionInt>/common.json and contains types shared across API versions. E.g. Microsoft.Compute/common-types.

data-plane/<groupingDir> folders

The <azureTeam>/data-plane folder is the equivalent of <azureTeam>/resource-manager but with following distinctions:

  • <azureTeam>/data-plane pertains to data-plane service APIs, not ARM service APIs.
  • <azureTeam>/data-plane has no concept of Resource Provider Namespace (<RPNS>). Instead, it has or more <groupingDir> child folders (see also glossary).

Each <groupingDir> folder has one or more child <service> folders corresponding to the services grouped in given <groupingDir>.

Note

Many Azure teams that have one data-plane service instead of rooting it in specification/<azureTeam>/data-plane/<groupingDir>/<service> root it in specification/<azureTeam>/data-plane.
This is legacy, deprecated structure and is strongly discouraged going forward.

Service folder structure

As described above, ARM service folder path is:

specification/<azureTeam>/resource-manager/<RPNS>/<service>

while data-plane service folder path is:

specification/<azureTeam>/data-plane/<groupingDir>/<service>.

A service folder has the following elements:

The stable and preview folders contain OpenAPI specs in the stable and preview lifecycle stages respectively, organized in <apiVersion> subfolders for each service API version.

For example:

  • <azureTeam>/resource-manager/<RPNS>/<service>/stable/<apiVersion>
  • <azureTeam>/resource-manager/<RPNS>/<service>/preview/<apiVersion-preview>
  • <azureTeam>/data-plane/<groupingDir>/<service>/stable/<apiVersion>
  • <azureTeam>/data-plane/<groupingDir>/<service>/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.

Read API versioning guidelines to learn more.

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.

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.
  • 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.

About legacy, deprecated directory structure for services and service groups

Many teams follow a legacy, deprecated directory structure which usually has following differences:

  • If a team owns only one service, instead of rooting it in specification/<azureTeam>/resource-manager/<RPNS>/<service>, it is rooted inspecification/<azureTeam>/resource-manager.
  • If a team first owned one service and then expanded to a service group, it contains mixture of both the deprecated structure (for the first service) as well as the correct structure (for the 2nd and following services).

This legacy structure is strongly discouraged going forward.

Migrating from a singular service to service group in a legacy directory structure

In case an Azure SDK team owns a singular service following the legacy, deprecated layout, and wants to expand to a full service group, it can do the following:

  • Keep the existing service as-is, without any changes.
  • Introduce the new services using the new, correct structure.

Deprecated directory structure and hand-written OpenAPI specs

As mentioned multiple times in this article, for historical reasons, some specification/<azureTeam> folders may violate some of the constraints presented in this article. This includes violations like:

  • More deeply nested subfolders than allowed.
  • README.md placed in a wrong folder (thus incorrectly denoting it as a service folder).
  • Lack of <service> directory for given service path.
  • Incorrect lack of -preview suffix in preview API versions.
  • Multiple <RPNS> subfolders of resource-manager folder.
  • 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 <azureTeam> 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 & deprecated, and are strongly discouraged going forward.