Formalize namespacing guidance for resource type

[SteveL-MSFT]

Summary of the new feature / enhancement

Resource type name in the resource manifest is <namespace>/<resource> to avoid conflicts and also provide context. As partners start building resources, we need to formalize our recommended guidance. For example, the registry example resource currently uses Microsoft.Windows/Registry but this could also be Microsoft/Windows.Registry. Note that the $schema URL also provides context of the origination (assuming it uses their company URL), so having long formal URLs as the namespace will make the configuration more noisy and more to type (until intellisense exists).

Proposed technical implementation details (optional)

No response

[Bpoe]

In Azure, resource types are single label only, are camelCased and are plural. In the case of the registry resource, it would be Microsoft.Windows/registryEntries.

[Bpoe]

Another, older example is WBEM. In that case, there is a namespace that can be segmented (root/cimv2), but the segments are separated by a '/', which wouldn't be good because we would need to URL encode them. The individual resources are classes (Win32_Registry).

[NikCharlebois]

Another use case is where resource dev wants to align the DSC resources with back-end APIs (e.g., how Microsoft365DSC aligns its resources with Microsoft Graph APIs). For example, in M365DSC today, we have a resource named AADNamedLocationPolicy. We want to move away from having product names as part of the resource (AAD now has to be rebranded Entra). However, simply keeping NamedLocation as the name to have it aligned with Graph could introduce confusion as to what this represents, but I am afraid their could be multiple workloads defining an object called namedLocations.

Create namedLocation - Microsoft Graph v1.0 | Microsoft Learn

It would be great for us to use the type property to align the resource with the API and provide the namespace path somehow:

{
    "$schema": "https://raw.githubusercontent.com/PowerShell/DSC/main/schemas/2023/08/config/document.json",
    "resources": [
      {
        "name": "NorthAmericas",
        "type": "Microsoft/identity/conditionalAccess/namedLocations",
        "properties": {
            "family": "Windows"
        }
      }
    ]
  }

[Bpoe]

That's an interesting case. I'm not super familiar with M365 APIs. In ARM, we do support multi-segment resources types, but that's when the resource is a child of another resource. For instance, you could have an API like Microsoft.Compute/virtualMachines/MyVmName/disks/disk0. In this case, disk0 is a child of MyVmName. So the resource type would be Microsoft.Compute/virtualMachines/disks but the name would then be MyVmName/disk0.

[Bpoe]

Looking at the API docs, it looks like Microsoft/identity/conditionalAccess is the namespace and namedLocations is the resource. I would model that as Microsoft.Identity.ConditionalAccess/namedLocations

[michaeltlombardi]

Worth referencing the current documentation for type names:

The fully qualified type name of a resource uses the following syntax:

<owner>[.<group>][.<area>]/<name>

Each segment must be string of alphanumeric characters and underscores. No other characters are permitted. Every resource must define an owner and a name. Use the group and area components to organize resources into related namespaces.

Type name segments

Owner

The owner segment of the type name is mandatory. It identifies the person or organization that owns, develops and maintains the resource.

Group

The group segment of the type name is optional. It defines a logical grouping for a collection of resources. For example, resources that manage SQL Server might use the SqlServer group in their type name.

Area

The area segment of the type name is optional. It defines a grouping for a collection of resources by purpose or higher-level component. For example, resources that manage components of a SQL Server database might use the Database area in their type name.

Name

The name segment of the type name is mandatory. It identifies the component that the resource manages. This segment should be a singular noun unless the resource always manages a list of components in a single resource instance. In that case, the resource name should be the plural form of the noun it manages or the singular form of the noun followed by the word List, like JeaRoleCapabilities or JeaRoleCapabilityList.

[SteveL-MSFT]

We are currently standardizing on:

<owner>[.<group>][.<area>]/<name>

For DSC built-in resources, it will be Microsoft.DSC\*

[SteveL-MSFT]

This is complete for the resources we plan to ship and support. Should just be documented now so closing this.