You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The standard status-monitor id remains an ordinary response property. Only explicitly selected auxiliary properties are exposed through this metadata contract.
SDK metadata
SdkLroServiceMetadata gains an optional status metadata collection:
Each entry returns the exact effective cached SdkModelPropertyType, preserving client and wire names, optionality, decorators, encoding, serialization, access, and type identity. Inherited non-overridden properties are supported; overridden base properties are not treated as effective metadata.
Selected property type graphs receive output usage and standard TCGC access propagation so they remain available to emitters even when they are not part of the final LRO result. Propagation is limited to selected metadata graphs and does not expose unrelated sibling properties. Existing scoped @usage remains additive and scoped property-level @access remains authoritative.
Validation
The decorator diagnoses duplicate active declarations, projected client-name conflicts, and attempts to select structural LRO fields such as status, result, error, polling location, or final location. Properties excluded by emitter scope or lifecycle visibility are also excluded from metadata and graph promotion.
This PR includes a Content Understanding-shaped Azure HTTP Specs scenario whose terminal response returns a typed nested usage value with optional numeric fields and token counts. It intentionally does not mark the normal status-monitor id as status metadata.
Validated with:
TCGC build and TypeSpec library lint;
focused status-metadata tests: 19 passed;
full TCGC tests: 1,737 passed, 2 skipped;
Azure HTTP Specs build and scenario validation;
mock API validation for all scenarios;
live CU Spector flow: POST, running GET, succeeded GET (3/3 requests);
regenerated TCGC definitions/reference docs and Spector summary;
repository format, lint, and git diff --check.
Related split
URI-derived operation ID metadata is reviewed separately in #5782. This PR supersedes the Content Understanding/status-metadata portion of #5740.
Packed = gzipped .tgz published to npm. Unpacked = total extracted size. 🆕 added, 🗑️ removed. Packages from the core/ submodule are not included. 🔴 grew · 🟢 shrank — only changes of at least 512 B and 0.5% are marked.
The reason will be displayed to describe this comment to others. Learn more.
Found three correctness issues in the new polling metadata paths, reproduced with native LRO specs: excluded properties are reintroduced, property-level access overrides are lost, and a body-valued polling URI is rejected.
Adds TCGC-owned decorators for exposing long-running operation IDs and typed polling metadata without changing Azure.Core protocol semantics, supporting the L10–L11 proposal in #5432.
Changes:
Adds scoped decorators and optional SDK metadata fields.
Integrates property selection, validation, and usage/access propagation.
Adds tests, diagnostic guidance, reference documentation, and a release note.
This lookup runs before hierarchy reconciliation (types.ts:2631), so it still selects an own property that the rebase later discards. When the monitor is used only for polling, Output usage reaches the discarded property's type rather than the replacement type eventually exposed in pollingMetadata; the replacement remains LroPolling-only and is skipped by TypeScript's model emission. Apply selected-property usage/access propagation to the reconciled hierarchy before access overrides and type filtering. Add a regression without a separate monitor-read operation: the current test's public getJobStatus independently supplies Output and masks this failure.
Initialize serialization for polling metadata properties
With generate-convenience-methods: false and a monitor referenced only through ResourceLocation<Monitor>, the model-wide serialization initialization at lines 2073–2089 is skipped. This call initializes only the selected property's type, leaving the polling-metadata property's serializationOptions empty even when it has @encodedName. Initialize the selected property itself as well, and cover this configuration so emitters retain its JSON wire name.
The reason will be displayed to describe this comment to others. Learn more.
🔵 Needs a closer look
Hierarchy reconciliation can leave selected metadata types without output usage, and referenced whole-body polling links carry an incorrect source location.
No open issues 🎉
2 previously missed issues
In code that hasn't changed since last review
Correct polling URI location for body-based operation IDs
For a fully bound @pollingOperation whose initial response supplies the polling URI as an @body or @bodyRoot value, lro-info.ts:410–415 labels the link ResponseBody. Copying that location here makes the new operation-ID source describe a named property rather than the entire body (Self). Use createOperationLink, which already distinguishes these cases, and add a compiled reference-plus-body regression; the current whole-body test covers only nextOperationLink.
Propagate selected-property usage after hierarchy reconciliation
This propagation runs before handleLegacyHierarchyBuilding (types.ts:2665), not against the final reconciled properties. A selected property from a removed ancestor is absent here until reconciliation lifts it; a selected own property replaced by the new base still resolves to the old property. Without a separately exposed polling operation supplying output usage, the published metadata can therefore reference types that lack Output usage, and newly lifted, otherwise-unused types are omitted from the SDK package. Apply selected-property usage/access/serialization propagation after reconciliation while preserving scoped overrides. Add link-only monitor regressions for both lifted inherited properties and replacement properties; the existing rebasing test's getJobStatus supplies independent output usage.
The example on PR description not even have a model for UsageDetails
@lroStatusMetadata
usage?: UsageDetails;
Even with the spec PR, I still don't get what's the difference of this usage without @lroStatusMetadata decorator.
How do we know what is this used for this lroStatusMetadata? What polling (or other process) in SDK that is affected by this decorator? What's it relationship with @lroResult or @lroStatus?
OK, seems @lroStatusMetadata not much relate to Java. It already has way to get the raw response. And user can inspect anything through this.
The example on PR description not even have a model for UsageDetails
@lroStatusMetadata
usage?: UsageDetails;
Even with the spec PR, I still don't get what's the difference of this usage without @lroStatusMetadata decorator.
How do we know what is this used for this lroStatusMetadata? What polling (or other process) in SDK that is affected by this decorator? What's it relationship with @lroResult or @lroStatus?
OK, seems @lroStatusMetadata not much relate to Java. It already has way to get the raw response. And user can inspect anything through this.
The current Java customization adds a non-exist property to a JSON model, which is not a good practice in the first place.
hey Weidong Xu (@weidongxu-microsoft), agreed, @lroStatusMetadata is more for languages that don't expose the full lro polling response to users, but also it doesn't necessarily mean the decorator is meaningless to java, it can tell the emitter which properties to bubble up. For example, in CU it appears you guys bubble up getId() and getUsage() methods.
i agree with your point on @lroOperationId actually, chatting it through with Mark Cowlishaw (@markcowl) but in the meantime, i'm goign to separate it out into a separate pr from @lroStatusMetadata
hey Weidong Xu (Weidong Xu (@weidongxu-microsoft)), agreed, @lroStatusMetadata is more for languages that don't expose the full lro polling response to users, but also it doesn't necessarily mean the decorator is meaningless to java, it can tell the emitter which properties to bubble up. For example, in CU it appears you guys bubble up getId() and getUsage() methods.
i agree with your point on @lroOperationId actually, chatting it through with Mark Cowlishaw (Mark Cowlishaw (@markcowl)) but in the meantime, i'm goign to separate it out into a separate pr from @lroStatusMetadata
For DI, maybe we should check response from other devs. The agent did refresh my memory on that lib (and made some investigation and confirmation), but that lib was done 1 year ago (dug up a long conversation with Sameeksha from 2024, and Java PR).
Regenerate the TCGC decorator contract with inherited scope documentation and format the LRO status metadata Spector scenario.
Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
Copilot-Session: 89522062-e8a5-40cb-8ec1-1f5a5426133b
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
lib:azure-coreIssues for @azure-tools/typespec-azure-core librarylib:azure-http-specsFor issues/prs related to the @azure-tools/typespec-azure-http-specs packagelib:tcgcIssues for @azure-tools/typespec-client-generator-core librarymeta:websiteTypeSpec.io updates
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
microsoft-github-policy-service
Bot
added
lib:tcgc
JoshLove-msft
left a comment
Mark Cowlishaw (markcowl)
left a comment
Summary
Adds a scoped, property-level
@lroStatusMetadatadecorator for selecting auxiliary typed values from an LRO status-monitor response:The standard status-monitor
idremains an ordinary response property. Only explicitly selected auxiliary properties are exposed through this metadata contract.SDK metadata
SdkLroServiceMetadatagains an optional status metadata collection:Each entry returns the exact effective cached
SdkModelPropertyType, preserving client and wire names, optionality, decorators, encoding, serialization, access, and type identity. Inherited non-overridden properties are supported; overridden base properties are not treated as effective metadata.Selected property type graphs receive output usage and standard TCGC access propagation so they remain available to emitters even when they are not part of the final LRO result. Propagation is limited to selected metadata graphs and does not expose unrelated sibling properties. Existing scoped
@usageremains additive and scoped property-level@accessremains authoritative.Validation
The decorator diagnoses duplicate active declarations, projected client-name conflicts, and attempts to select structural LRO fields such as status, result, error, polling location, or final location. Properties excluded by emitter scope or lifecycle visibility are also excluded from metadata and graph promotion.
This PR includes a Content Understanding-shaped Azure HTTP Specs scenario whose terminal response returns a typed nested
usagevalue with optional numeric fields and token counts. It intentionally does not mark the normal status-monitoridas status metadata.Validated with:
git diff --check.Related split
URI-derived operation ID metadata is reviewed separately in #5782. This PR supersedes the Content Understanding/status-metadata portion of #5740.