Skip to content

Update the migration guide to remove the flatten part #36993

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

Merged
MaryGao merged 1 commit into from
Jan 28, 2026
Merged

Update the migration guide to remove the flatten part #36993

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
76 changes: 0 additions & 76 deletions documentation/migration-guide-for-libraries-generated-from-TypeSpec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,6 @@ If you’re updating an existing application from **libraries generated with Aut

1. **Long-running operations (LROs)** – Updated method signatures and poller behavior
2. **List operations (paging)** – Simplified continuation token handling
3. **Model property flattening** – **Libraries generated from TypeSpec** no longer support client-side flattening. This decision was based on customer feedback to reduce confusion and maintenance overhead

### Long-running Operations (LROs)

Expand Down Expand Up @@ -174,81 +173,6 @@ const firstPage = await iter.byPage().next();
const continuationToken = firstPage.value.continuationToken;
```


### Model Property Flattening

Previously, **libraries generated with AutoRest** supported the `x-ms-client-flatten` extension, which allowed deeply nested payloads to be flattened into a top-level object structure. For example, a payload like this:

```json
{
"hcxEnterpriseSite": {
"name": "hcxEnterpriseSiteName",
"properties": {
"provisioningState": "succeed",
"activationKey": "value2",
"status": "ok"
},
},
}
```
would generate a model where `activationKey` and other properties were surfaced at the top level:
```ts
/** An HCX Enterprise Site resource */
export interface HcxEnterpriseSite extends ProxyResource {
/**
* The provisioning state of the resource.
* NOTE: This property will not be serialized. It can only be populated by the server.
*/
readonly provisioningState?: HcxEnterpriseSiteProvisioningState;
/**
* The activation key
* NOTE: This property will not be serialized. It can only be populated by the server.
*/
readonly activationKey?: string;
/**
* The status of the HCX Enterprise Site
* NOTE: This property will not be serialized. It can only be populated by the server.
*/
readonly status?: HcxEnterpriseSiteStatus;
}
```

#### What changed?
**Libraries generated from TypeSpec** no longer support client-side flattening. This decision was based on customer feedback to reduce confusion and maintenance overhead. Models now preserve the original structure, so properties are grouped under a `properties` object (as defined in TypeSpec):
```ts
/** An HCX Enterprise Site resource */
export interface HcxEnterpriseSite extends ProxyResource {
/** The resource-specific properties for this resource. */
properties?: HcxEnterpriseSiteProperties;
}

/** The properties of an HCX Enterprise Site */
export interface HcxEnterpriseSiteProperties {
/** The provisioning state of the resource. */
readonly provisioningState?: HcxEnterpriseSiteProvisioningState;
/** The activation key */
readonly activationKey?: string;
/** The status of the HCX Enterprise Site */
readonly status?: HcxEnterpriseSiteStatus;
}
```

#### What does this mean for you?
Update your code to access nested properties through `properties`. For example:

```ts
// Before (AutoRest-generated)
const result = await client.hcxEnterpriseSites.get("resourceGroupName", "privateCloudName", "hcxEnterpriseSiteName");
console.log(result.activationKey);

// After (TypeSpec-generated)
const result = await client.hcxEnterpriseSites.get("resourceGroupName", "privateCloudName", "hcxEnterpriseSiteName");
console.log(result.properties?.activationKey);
```

> **Tip:** In most Azure resource models, flattening occurred under the `properties` bag, so expect to adjust references accordingly.


## Need help

If you have encountered an issue during migration, please file an issue via [GitHub Issues](https://github.com/Azure/azure-sdk-for-js/issues) and make sure you add the 'Preview' label to the issue.