Azure Guidelines
Findings and affected intents at a glance; expand for expected guidance and actual changes.
1 of 1 semantic intents assessed · 4 documents selected
Paging behavior changes without API versioningThe paging annotation matches the documented paging shape, but introducing its caller-visible SDK behavior into an existing API version does not preserve existing client behavior as the versioning guidance requires.Affected intents (1)failed
Expected
Use `@list` with a paged return shape, and apply behavior-changing operation evolution through versioning so existing clients retain their prior contract.
To enable pagination for an operation the first step is to decorate it with the `@list` decorator and have the return type contain a property decorated with `@pageItems`
@list op listPets(...): { @pageItems items: Pet[]; };Versioning allows you to evolve your API without breaking existing clients. By using versioning decorators, you can specify when resources, operations, or properties are added, removed, or changed.
Actual
The return shape contains page items and a next link, but `@list` is added directly to the existing 2026-03-01 operation and changes its generated SDK method from LRO to LRO-paging.
specification/cognitiveservices/CognitiveServices.Management/ManagedNetworkSettingsPropertiesBasicResource.tsp:28-104, specification/cognitiveservices/CognitiveServices.Management/ManagedNetworkSettingsPropertiesBasicResource.tsp:79-89
28+ @listDownstream breaking changes
Method impact and affected intents at a glance; expand for before/after evidence.
OutboundRules.postThe normalized SDK method contract changes directly.Affected intents (1)Direct method change
Target normalized SDK method: Microsoft.CognitiveServices.ManagedNetworkSettingsPropertiesBasicResources.post
| Contract area | Before | After |
|---|---|---|
| SDK methodMethod kindThe post method changes from an LRO to an LRO-paging method, altering generated invocation and result-consumption behavior for existing SDK callers. | lro | lropaging |
| SDK methodPagingThe post method newly follows OutboundRuleListResult.value and nextLink as pages, so existing callers receive paging behavior instead of a single result wrapper. | none | {} |
| SDK methodReturn type (body output) | OutboundRuleListResult | OutboundRuleBasicResource[] |
Constant headers (not numbered caller inputs): Baseline: Content-Type (header): "application/json"; Baseline: Accept (header): "application/json"; Target: Content-Type (header): "application/json"; Target: Accept (header): "application/json"
- The post method changes from returning OutboundRuleListResult to a pageable array of OutboundRuleBasicResource, so existing SDK callers must replace wrapper-based result consumption with paging iteration.
- The post method changes from an LRO to an LRO-paging method, altering generated invocation and result-consumption behavior for existing SDK callers.
- The post method newly follows OutboundRuleListResult.value and nextLink as pages, so existing callers receive paging behavior instead of a single result wrapper.
Language-neutral TCGC evidence is shown; generated language signatures are not fabricated.
Semantic intents
Impact links are visible at a glance; expand for changed TypeSpec source, followed by affected operations.
Mark the batch outbound-rules operation as pagedAdds `@list` to the existing ManagedNetworkSettingsPropertiesBasicResources.post operation, causing OutboundRules_Post to be emitted as a long-running paged operation while preserving its HTTP route and response wire shape.modify
Changed TypeSpec source (1)
*/ @tag("ManagedNetwork") @action("batchOutboundRules") + @list post is ArmResourceActionAsync< ManagedNetworkSettingsPropertiesBasicResource, Request = ManagedNetworkSettingsBasicResource,
specification/cognitiveservices/CognitiveServices.Management/ManagedNetworkSettingsPropertiesBasicResource.tsp:28
Affected operations (1)
OutboundRules_PostPOST/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CognitiveServices/accounts/{accountName}/managedNetworks/{managedNetworkName}/batchOutboundRules2026-03-01
| Contract area | Before | After |
|---|---|---|
| PagingnextLinkName | not present | nextLink |
HTTP signature and represented payload contract unchanged; SDK paging metadata changed.
REST breaking changes
Operation impact and affected intents at a glance; expand for before/after evidence.
Documentation Completeness
Checks only whether newly added operation, model, enum, and interface declarations have a nonempty effective TypeSpec description.
0 findings · 0 declarations checked
Appendix
Potential limits
None
Projects and compiler status
| Project | Mode | Baseline commit@version | Target commit@version | Baseline AutoRest / TCGC | Target AutoRest / TCGC |
|---|---|---|---|---|---|
specification/cognitiveservices/CognitiveServices.Management | existing-api-version | 2ddde2a55d4c8eb6d0bdf22592dfb7c849dfd904@2026-03-01base · affected-existing-version | 96eae0e7d5c7ede040ee0cc646d397e5d8375912@2026-03-01current · affected-existing-version | succeeded / succeeded | succeeded / succeeded |
Pull request: Not available for this local pre-PR assessment.
Guidance fetched
Guidance coverage and retrieval evidence
{
"status": "failed",
"coverage": {
"semanticIntentCount": 1,
"assessedIntentCount": 1,
"selectedDocumentCount": 4,
"unassessedIntentIds": []
},
"sharedSearch": {
"catalogRanking": [
{
"rank": 1,
"catalogOrder": 19,
"title": "TypeSpec pagination",
"canonicalUrl": "https://typespec.io/docs/standard-library/pagination/",
"score": {
"exactSymbol": 4,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 10
},
"selectionRationale": "Names the changed @list decorator and data-plane paging pattern for the modified operation."
},
{
"rank": 2,
"catalogOrder": 16,
"title": "ARM long-running operations",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/long-running-operations/",
"score": {
"exactSymbol": 4,
"patternCategory": 3,
"servicePlane": 0,
"changeContext": 1,
"total": 8
},
"selectionRationale": "Names the retained Location and Retry-After constructs and the operation's long-running response pattern."
},
{
"rank": 3,
"catalogOrder": 1,
"title": "Evolving APIs",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/versioning/06-evolving-apis/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Governs modifications to operations in an existing versioned API."
},
{
"rank": 4,
"catalogOrder": 14,
"title": "TypeSpec.Rest decorators",
"canonicalUrl": "https://typespec.io/docs/libraries/rest/reference/decorators/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Covers operation decorators and list resource semantics for a data-plane operation."
},
{
"rank": 5,
"catalogOrder": 17,
"title": "Azure.Core long-running operations",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/azure-core/long-running-operations/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Matches the data-plane long-running operation category but not the changed paging decorator directly."
},
{
"rank": 6,
"catalogOrder": 24,
"title": "Decorators",
"canonicalUrl": "https://typespec.io/docs/language-basics/decorators/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Matches the decorator change category but provides only general decorator guidance."
},
{
"rank": 7,
"catalogOrder": 25,
"title": "Built-in decorators",
"canonicalUrl": "https://typespec.io/docs/standard-library/built-in-decorators/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Matches standard decorator usage but does not name the paging decorator."
},
{
"rank": 8,
"catalogOrder": 26,
"title": "OpenAPI decorators",
"canonicalUrl": "https://typespec.io/docs/libraries/openapi/reference/decorators/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Matches the decorator and operation categories but not the changed TypeSpec standard-library decorator."
},
{
"rank": 9,
"catalogOrder": 29,
"title": "Content negotiation",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/azure-core/content-negotiation/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Matches data-plane operation decorators, but the change does not alter content negotiation."
},
{
"rank": 10,
"catalogOrder": 12,
"title": "ARM resource operations",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/resource-operations/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 0,
"changeContext": 1,
"total": 4
},
"selectionRationale": "Matches list-operation patterns but not the request's data-plane classification."
},
{
"rank": 11,
"catalogOrder": 13,
"title": "Azure.ResourceManager interface reference",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/reference/interfaces/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 0,
"changeContext": 1,
"total": 4
},
"selectionRationale": "Matches operation interfaces but not the request's data-plane classification."
},
{
"rank": 12,
"catalogOrder": 15,
"title": "Azure.ResourceManager decorators",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/reference/decorators/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 0,
"changeContext": 1,
"total": 4
},
"selectionRationale": "Matches decorator and list categories but not the data-plane service classification."
},
{
"rank": 13,
"catalogOrder": 18,
"title": "Azure.ResourceManager data types",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/reference/data-types/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 0,
"changeContext": 1,
"total": 4
},
"selectionRationale": "Matches paging but covers ARM paging parameters rather than the changed data-plane decorator."
},
{
"rank": 14,
"catalogOrder": 27,
"title": "Change provider namespace",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/change-provider-namespace/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 0,
"changeContext": 1,
"total": 4
},
"selectionRationale": "Matches the broad decorator category but not the changed paging behavior."
},
{
"rank": 15,
"catalogOrder": 28,
"title": "Azure Portal default experiences",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/azure-portal/default-experiences/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 0,
"changeContext": 1,
"total": 4
},
"selectionRationale": "Matches the broad decorator category but not the modified operation's paging contract."
},
{
"rank": 16,
"catalogOrder": 2,
"title": "Versioning overview",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/versioning/01-about-versioning/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 1,
"total": 3
},
"selectionRationale": "Applies generally to the existing versioned data-plane service but not specifically to paging."
},
{
"rank": 17,
"catalogOrder": 21,
"title": "Models",
"canonicalUrl": "https://typespec.io/docs/language-basics/models/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 1,
"total": 3
},
"selectionRationale": "Applies generally to referenced data-plane models but no model declaration changed."
},
{
"rank": 18,
"catalogOrder": 22,
"title": "Enums",
"canonicalUrl": "https://typespec.io/docs/language-basics/enums/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 1,
"total": 3
},
"selectionRationale": "Applies generally to referenced data-plane enums but no enum declaration changed."
},
{
"rank": 19,
"catalogOrder": 23,
"title": "Scalars",
"canonicalUrl": "https://typespec.io/docs/language-basics/scalars/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 1,
"total": 3
},
"selectionRationale": "Applies generally to referenced data-plane scalars but no scalar declaration changed."
},
{
"rank": 20,
"catalogOrder": 3,
"title": "Add preview after preview",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/versioning/02-preview-after-preview/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 0,
"total": 2
},
"selectionRationale": "Applies to data-plane versioning, but this change adds no preview version."
},
{
"rank": 21,
"catalogOrder": 4,
"title": "Add stable after preview",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/versioning/03-stable-after-preview/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 0,
"total": 2
},
"selectionRationale": "Applies to data-plane versioning, but this change adds no stable version."
},
{
"rank": 22,
"catalogOrder": 5,
"title": "Add preview after stable",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/versioning/04-preview-after-stable/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 0,
"total": 2
},
"selectionRationale": "Applies to data-plane versioning, but this change adds no preview version."
},
{
"rank": 23,
"catalogOrder": 6,
"title": "Add stable after stable",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/versioning/05-stable-after-stable/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 0,
"total": 2
},
"selectionRationale": "Applies to data-plane versioning, but this change adds no stable version."
},
{
"rank": 24,
"catalogOrder": 30,
"title": "Directives",
"canonicalUrl": "https://typespec.io/docs/language-basics/directives/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 2,
"changeContext": 0,
"total": 2
},
"selectionRationale": "Applies across service planes, but no directive or suppression changed."
},
{
"rank": 25,
"catalogOrder": 7,
"title": "ARM resource types and modeling",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/resource-type/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 0,
"changeContext": 0,
"total": 0
},
"selectionRationale": "No matching changed resource declaration or data-plane paging guidance."
},
{
"rank": 26,
"catalogOrder": 8,
"title": "Specific extension resource sample",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/samples/resource-manager/resource-types/specific-extension/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 0,
"changeContext": 0,
"total": 0
},
"selectionRationale": "No matching extension resource or service-plane signal."
},
{
"rank": 27,
"catalogOrder": 9,
"title": "Private endpoints",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/private-endpoints/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 0,
"changeContext": 0,
"total": 0
},
"selectionRationale": "No matching private endpoint construct or service-plane signal."
},
{
"rank": 28,
"catalogOrder": 10,
"title": "Private links",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/private-links/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 0,
"changeContext": 0,
"total": 0
},
"selectionRationale": "No matching private link construct or service-plane signal."
},
{
"rank": 29,
"catalogOrder": 11,
"title": "Network security perimeter",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/network-security-perimeter/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 0,
"changeContext": 0,
"total": 0
},
"selectionRationale": "No matching network security perimeter construct or service-plane signal."
},
{
"rank": 30,
"catalogOrder": 20,
"title": "ARM common types",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/add-common-types/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 0,
"changeContext": 0,
"total": 0
},
"selectionRationale": "No ARM common-type declaration or related decorator changed."
},
{
"rank": 31,
"catalogOrder": 31,
"title": "Azure Core `no-openapi` rule",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-openapi/",
"score": {
"exactSymbol": 0,
"patternCategory": 0,
"servicePlane": 0,
"changeContext": 0,
"total": 0
},
"selectionRationale": "No OpenAPI-specific decorator or suppression changed."
}
],
"documents": [
{
"rank": 1,
"catalogOrder": 19,
"title": "TypeSpec pagination",
"canonicalUrl": "https://typespec.io/docs/standard-library/pagination/",
"score": {
"exactSymbol": 4,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 10
},
"selectionRationale": "Names the changed @list decorator and data-plane paging pattern for the modified operation.",
"guidance": [
{
"section": "Pagination",
"excerpt": "To enable pagination for an operation the first step is to decorate it with the `@list` decorator and have the return type contain a property decorated with `@pageItems`",
"queryTerms": [
"@list",
"@pageItems",
"paging"
],
"examples": [
"@list op listPets(...): { @pageItems items: Pet[]; };"
],
"applicableDeclarationIds": [
"declaration-6ab6c44b437678cb",
"declaration-e54c2e2399e5428a"
]
}
],
"noRelevantGuidance": false,
"retrievedAt": "2026-09-17T11:16:25.9383608Z",
"contentHash": "sha256:8ed4ca24bb17b71035b082af46fafd03216e6e9dc8135ae0a03c8ec2b14e8e73"
},
{
"rank": 2,
"catalogOrder": 16,
"title": "ARM long-running operations",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/arm/long-running-operations/",
"score": {
"exactSymbol": 4,
"patternCategory": 3,
"servicePlane": 0,
"changeContext": 1,
"total": 8
},
"selectionRationale": "Names the retained Location and Retry-After constructs and the operation's long-running response pattern.",
"guidance": [
{
"section": "ARM long-running operation headers",
"excerpt": "Each header model accepts a `FinalResult` parameter that indicates the type of the logical result of the operation. It is important that this value matches what the operation actually returns.",
"queryTerms": [
"ArmAcceptedLroResponse",
"Location",
"Retry-After"
],
"examples": [],
"applicableDeclarationIds": [
"declaration-6ab6c44b437678cb",
"declaration-e54c2e2399e5428a"
]
}
],
"noRelevantGuidance": false,
"retrievedAt": "2026-09-17T11:16:25.9383608Z",
"contentHash": "sha256:1eaf2a3a9898427a9fbde5ce8970dc084c3b376ce5fd900645634168b647d891"
},
{
"rank": 3,
"catalogOrder": 1,
"title": "Evolving APIs",
"canonicalUrl": "https://azure.github.io/typespec-azure/docs/howtos/versioning/06-evolving-apis/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Governs modifications to operations in an existing versioned API.",
"guidance": [
{
"section": "Evolving APIs",
"excerpt": "Versioning allows you to evolve your API without breaking existing clients. By using versioning decorators, you can specify when resources, operations, or properties are added, removed, or changed.",
"queryTerms": [
"modify operation",
"versioning decorators",
"existing clients"
],
"examples": [],
"applicableDeclarationIds": [
"declaration-6ab6c44b437678cb",
"declaration-e54c2e2399e5428a"
]
}
],
"noRelevantGuidance": false,
"retrievedAt": "2026-09-17T11:16:25.9383608Z",
"contentHash": "sha256:5faf5fd80807690729c00dab44ebcfa1d698166dfb0caefc516bdf325fcfd630"
},
{
"rank": 4,
"catalogOrder": 14,
"title": "TypeSpec.Rest decorators",
"canonicalUrl": "https://typespec.io/docs/libraries/rest/reference/decorators/",
"score": {
"exactSymbol": 0,
"patternCategory": 3,
"servicePlane": 2,
"changeContext": 1,
"total": 6
},
"selectionRationale": "Covers operation decorators and list resource semantics for a data-plane operation.",
"guidance": [
{
"section": "listsResource",
"excerpt": "Specify that this is a List operation for a given resource. `@TypeSpec.Rest.listsResource(resourceType: Model)`.",
"queryTerms": [
"list operation",
"operation decorator"
],
"examples": [],
"applicableDeclarationIds": [
"declaration-6ab6c44b437678cb",
"declaration-e54c2e2399e5428a"
]
}
],
"noRelevantGuidance": false,
"retrievedAt": "2026-09-17T11:16:25.9383608Z",
"contentHash": "sha256:01e3bd654da3c23517b4b60044b6d9717733280a916902c26cd33f76d58f05f3"
}
]
},
"intentAssessments": [
{
"semanticIntentId": "semantic-200facaaa7a2fda3",
"decision": "applicable-fail",
"blockers": []
}
],
"retrievalFailures": [],
"blockers": []
}Changed files
specification/cognitiveservices/CognitiveServices.Management/ManagedNetworkSettingsPropertiesBasicResource.tsp(committed)
Timing and model input
{
"timings": {
"metadataMs": 1001,
"fetchMs": 166,
"scopeDiscoveryMs": 80,
"setupExcludingFetchMs": 25362,
"comparisonMs": 123,
"changeDiscoveryMs": 68,
"workspacePreparationMs": 23839,
"projectDiscoveryMs": 48,
"totalMs": 111431,
"semanticAnalysisMs": 4948,
"restAnalysisMs": 107,
"downstreamAnalysisMs": 21,
"documentQualityAnalysisMs": 1
},
"inputAccounting": {
"budgetTier": "small",
"budgetBytes": 131072,
"bytes": 20115,
"estimatedTokens": 5029,
"retained": {
"evidenceSets": 4,
"facts": 4,
"semanticReviewUnits": 1,
"restCandidates": 1,
"downstreamCandidates": 3,
"downstreamRootCauses": 1,
"complianceSearchRequests": 1,
"inferenceRequests": 0
},
"omittedRedundant": {
"rawEmitterArtifacts": true,
"compilerLogs": true,
"unchangedInventories": true,
"unreferencedFacts": true,
"unreferencedDeterministicFacts": true,
"sourceChanges": true,
"repeatedDeclarationIds": true,
"repeatedReviewUnitEvidence": true
},
"compliance": {
"catalogEntriesScored": 31,
"documentsFetched": 4,
"documentBytesFetched": 670,
"guidanceExcerptsRetained": 4,
"guidanceExcerptBytesRetained": 670
}
}
}
Provenance: model-input.json, dimensions/document-quality-input.json, compliance-search-evidence.json, assessment-judgment.json, preparation-manifest.json