Folder Structure

Table of Contents

• Overview
• Versions
  • Version 2
  • Version 1

Overview

Specifications in this repository must organize their files and folders according to strict guidelines.

In June 2025, the guidelines were updated to version 2. New specs are encouraged to start with v2, and existing specs are encouraged to convert to v2 when convenient. The widget sample uses v2.

Prior to June 2025, all specs were using v1. The contosowidgetmanager sample uses v1.

Versions

Version 2

Release Date: June 2025

TODO: Describe folder structure and naming conventions

Documentation changes

When migrating an existing service that has documentation on learn.microsoft.com to Folder Structure v2, readme.md files used for docs may be affected. If the location of such readme.md files do change, visit https://aka.ms/publish-on-docs/reference and click the Onboard reference content link. In the issue, note that the location of the readme.md file has changed and onboarding information may need to be updated.

Version 1

https://github.com/Azure/azure-rest-api-specs/blob/main/documentation/typespec-structure-guidelines.md