Azure
[Cosmos DB] Microsoft.DocumentDB New API Version 2024-05-15-preview
ARM (Control Plane) API Specification Update Pull Request
[!TIP] Overwhelmed by all this guidance? See the
Getting helpsection at the bottom of this PR description.
[!NOTE] As of January 2024 there is no PR assignee. This is expected. See https://aka.ms/azsdk/pr-arm-review.
PR review workflow diagram
Please understand this diagram before proceeding. It explains how to get your PR approved & merged.
Click here to see the details of Step 1, Breaking Changes review
If you are in purview of Step 1 of the diagram, follow the Breaking Changes review process.
IMPORTANT! This applies even if you believe your PR was mislabeled, for any reason, including tool failure.
Click here to see the details of Step 2, ARM review
See https://aka.ms/azsdk/pr-arm-review.
Click here to see the diagram footnotes
Diagram footnotes
[1] See ARM review queue (for PR merge queues, see [2]).
[2] public repo merge queue, private repo merge queue (for ARM review queue, [1])
The ARM reviewer on-call engineer visits the merge queue twice a day, so the approximate ETA for merges is 12 - 24 hours.
Purpose of this PR
What's the purpose of this PR? Check the specific option that applies. This is mandatory!
- [ ] New resource provider.
- [ ] New API version for an existing resource provider. (If API spec is not defined in TypeSpec, the PR should have been generated using OpenAPI Hub).
- [ ] Update existing version for a new feature. (This is applicable only when you are revising a private preview API version.)
- [ ] Update existing version to fix OpenAPI spec quality issues in S360.
- [ ] Other, please clarify:
- edit this with your clarification
Due diligence checklist
To merge this PR, you must go through the following checklist and confirm you understood and followed the instructions by checking all the boxes:
- [ ] I confirm this PR is modifying Azure Resource Manager (ARM) related specifications, and not data plane related specifications.
- [ ] I have reviewed following Resource Provider guidelines, including
ARM resource provider contract and
REST guidelines (estimated time: 4 hours).
I understand this is required before I can proceed to the diagram Step 2, "ARM API changes review", for this PR.
Additional information
Viewing API changes
For convenient view of the API changes made by this PR, refer to the URLs provided in the table
in the Generated ApiView comment added to this PR. You can use ApiView to show API versions diff.
Suppressing failures
If one or multiple validation error/warning suppression(s) is detected in your PR, please follow the suppressions guide to get approval.
Getting help
- First, please carefully read through this PR description, from top to bottom. Please fill out the
Purpose of this PRandDue diligence checklist. - To understand what you must do next to merge this PR, see the
Next Steps to Mergecomment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state. - For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure and https://aka.ms/ci-fix.
- For help with PR workflow diagram Step 2 (ARM review), see https://aka.ms/azsdk/pr-arm-review.
- If the PR CI checks appear to be stuck in
queuedstate, please add a comment with contents/azp run. This should result in a new comment denoting aPR validation pipelinehas started and the checks should be updated after few minutes. - If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.
Next Steps to Merge
✅ All automated merging requirements have been met! To get your PR merged, see aka.ms/azsdk/specreview/merge.![openapi-pipeline-app[bot] avatar](https://avatars.githubusercontent.com/in/65541?v=4 "Published by a pub.dev verified publisher"){kind=small}
Swagger Validation Report
️️✔️BreakingChange succeeded [Detail] [Expand]
There are no breaking changes.
️❌Breaking Change(Cross-Version): 30 Errors, 10 Warnings failed [Detail]
| Compared specs (v0.10.8) | new version | base version |
|---|---|---|
| cosmos-db.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| cosmos-db.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| dataTransferService.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| managedCassandra.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| managedCassandra.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| mongorbac.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| mongorbac.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| notebook.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| notebook.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| privateEndpointConnection.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| privateEndpointConnection.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| privateLinkResources.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| privateLinkResources.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| rbac.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| rbac.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| restorable.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| restorable.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| services.json | 2024-05-15-preview(4e2ec21) | 2023-11-15(main) |
| services.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
| throughputpool.json | 2024-05-15-preview(4e2ec21) | 2024-02-15-preview(main) |
The following breaking changes are detected by comparison with the latest stable version:
Only 30 items are listed, please refer to log for more details.
The following breaking changes are detected by comparison with the latest preview version:
️️✔️CredScan succeeded [Detail] [Expand]
There is no credential detected.
️🔄LintDiff inProgress [Detail]
️❌Avocado: 7 Errors, 0 Warnings failed [Detail]
| Rule | Message |
|---|---|
|
The default tag should contain all APIs. The API path /subscriptions/{}/providers/Microsoft.DocumentDB/mongoClusters is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json |
|
The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json |
|
The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{} is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json |
|
The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/firewallRules/{} is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json |
|
The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/firewallRules is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json |
|
The default tag should contain all APIs. The API path /subscriptions/{}/providers/Microsoft.DocumentDB/locations/{}/checkMongoClusterNameAvailability is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json |
|
The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/listConnectionStrings is not in the default tag. Please make sure the missing API swaggers are in the default tag.readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json |
️️✔️SwaggerAPIView succeeded [Detail] [Expand]
️️✔️TypeSpecAPIView succeeded [Detail] [Expand]
️️✔️ModelValidation succeeded [Detail] [Expand]
Validation passes for ModelValidation.
️️✔️SemanticValidation succeeded [Detail] [Expand]
Validation passes for SemanticValidation.
️️✔️PoliCheck succeeded [Detail] [Expand]
Validation passed for PoliCheck.
️️✔️SpellCheck succeeded [Detail] [Expand]
Validation passes for SpellCheck.
️️✔️Lint(RPaaS) succeeded [Detail] [Expand]
Validation passes for Lint(RPaaS).
️️✔️PR Summary succeeded [Detail] [Expand]
Validation passes for Summary.
️️✔️Automated merging requirements met succeeded [Detail] [Expand]
Swagger Generation Artifacts
️️✔️ApiDocPreview succeeded [Detail] [Expand]
Please click here to preview with your @microsoft account.
️⚠️ azure-sdk-for-python warning [Detail]
⚠️Warning in generating from 28b00f30a5b86aaadabb18cb7273d582bffb67f6. SDK Automation 14.0.0command sh scripts/automation_init.sh ../azure-sdk-for-python_tmp/initInput.json ../azure-sdk-for-python_tmp/initOutput.json cmderr [automation_init.sh] WARNING: Skipping azure-nspkg as it is not installed. cmderr [automation_init.sh] cmderr [automation_init.sh] npm notice New minor version of npm available! 10.5.0 -> 10.7.0 cmderr [automation_init.sh] npm notice Changelog: <https://github.com/npm/cli/releases/tag/v10.7.0> cmderr [automation_init.sh] npm notice Run `npm install -g [email protected]` to update! cmderr [automation_init.sh] npm notice command sh scripts/automation_generate.sh ../azure-sdk-for-python_tmp/generateInput.json ../azure-sdk-for-python_tmp/generateOutput.json
️✔️azure-mgmt-cosmosdb [Preview SDK Changes]- azure_mgmt_cosmosdb-0.7.0-py3-none-any.whl
- azure-mgmt-cosmosdb-0.7.0.zip
️️✔️ azure-sdk-for-net-track2 succeeded [Detail] [Expand]
️✔️Succeeded in generating from 28b00f30a5b86aaadabb18cb7273d582bffb67f6. SDK Automation 14.0.0command pwsh ./eng/scripts/Automation-Sdk-Init.ps1 ../azure-sdk-for-net_tmp/initInput.json ../azure-sdk-for-net_tmp/initOutput.json command pwsh ./eng/scripts/Invoke-GenerateAndBuildV2.ps1 ../azure-sdk-for-net_tmp/generateInput.json ../azure-sdk-for-net_tmp/generateOutput.json
️✔️Azure.ResourceManager.CosmosDB [Preview SDK Changes] Breaking Change Detected- Azure.ResourceManager.CosmosDB.1.4.0-alpha.20240513.1.nupkg
info [Changelog] Breaking Changes: /home/cloudtest/.nuget/packages/microsoft.dotnet.apicompat/5.0.0-beta.20467.1/build/Microsoft.DotNet.ApiCompat.targets(82,5): error : TypesMustExist : Type 'Azure.ResourceManager.CosmosDB.Models.CosmosDBServiceType' does not exist in the implementation but it does exist in the contract. [/mnt/vss/_work/1/s/azure-sdk-for-net/sdk/cosmosdb/Azure.ResourceManager.CosmosDB/src/Azure.ResourceManager.CosmosDB.csproj::TargetFramework=netstandard2.0], info [Changelog] /home/cloudtest/.nuget/packages/microsoft.dotnet.apicompat/5.0.0-beta.20467.1/build/Microsoft.DotNet.ApiCompat.targets(96,5): error : ApiCompat failed for '/mnt/vss/_work/1/s/azure-sdk-for-net/artifacts/bin/Azure.ResourceManager.CosmosDB/Debug/netstandard2.0/Azure.ResourceManager.CosmosDB.dll' [/mnt/vss/_work/1/s/azure-sdk-for-net/sdk/cosmosdb/Azure.ResourceManager.CosmosDB/src/Azure.ResourceManager.CosmosDB.csproj::TargetFramework=netstandard2.0]
Parse Suppression File Errors No suppression file added.
Please refer to https://aka.ms/azsdk/sdk-suppression for more information.
️️✔️ azure-sdk-for-java succeeded [Detail] [Expand]
️✔️Succeeded in generating from 28b00f30a5b86aaadabb18cb7273d582bffb67f6. SDK Automation 14.0.0command ./eng/mgmt/automation/init.sh ../azure-sdk-for-java_tmp/initInput.json ../azure-sdk-for-java_tmp/initOutput.json command ./eng/mgmt/automation/generate.py ../azure-sdk-for-java_tmp/generateInput.json ../azure-sdk-for-java_tmp/generateOutput.json
️✔️azure-resourcemanager-cosmos-generated [Preview SDK Changes]- pom.xml
- azure-resourcemanager-cosmos-generated-1.0.0-beta.1-sources.jar
- azure-resourcemanager-cosmos-generated-1.0.0-beta.1.jar
️️✔️ azure-sdk-for-go succeeded [Detail] [Expand]
️✔️Succeeded in generating from 28b00f30a5b86aaadabb18cb7273d582bffb67f6. SDK Automation 14.0.0command sh ./eng/scripts/automation_init.sh ../../../../../azure-sdk-for-go_tmp/initInput.json ../../../../../azure-sdk-for-go_tmp/initOutput.json command generator automation-v2 ../../../../../azure-sdk-for-go_tmp/generateInput.json ../../../../../azure-sdk-for-go_tmp/generateOutput.json
️✔️sdk/resourcemanager/cosmos/armcosmos [Preview SDK Changes]
️️✔️ azure-sdk-for-js succeeded [Detail] [Expand]
️✔️Succeeded in generating from 28b00f30a5b86aaadabb18cb7273d582bffb67f6. SDK Automation 14.0.0command sh .scripts/automation_init.sh ../azure-sdk-for-js_tmp/initInput.json ../azure-sdk-for-js_tmp/initOutput.json warn File azure-sdk-for-js_tmp/initOutput.json not found to read command sh .scripts/automation_generate.sh ../azure-sdk-for-js_tmp/generateInput.json ../azure-sdk-for-js_tmp/generateOutput.json
️✔️@azure/arm-cosmosdb [Preview SDK Changes]- azure-arm-cosmosdb-16.0.0-beta.8.tgz
️❌ azure-resource-manager-schemas failed [Detail]
❌Code Generator Failed in generating from 28b00f30a5b86aaadabb18cb7273d582bffb67f6. Schema Automation 14.0.0command .sdkauto/initScript.sh ../azure-resource-manager-schemas_tmp/initInput.json ../azure-resource-manager-schemas_tmp/initOutput.json cmderr [initScript.sh] Submodule 'bicep-types-az' (https://github.com/Azure/bicep-types-az) registered for path 'bicep-types-az' cmderr [initScript.sh] Cloning into '/mnt/vss/_work/1/s/azure-resource-manager-schemas/bicep-types-az'... cmderr [initScript.sh] Submodule 'bicep-types' (https://github.com/Azure/bicep-types) registered for path 'bicep-types-az/bicep-types' cmderr [initScript.sh] Cloning into '/mnt/vss/_work/1/s/azure-resource-manager-schemas/bicep-types-az/bicep-types'... cmderr [initScript.sh] notice cmderr [initScript.sh] npm notice New minor version of npm available! 10.5.0 -> 10.7.0 cmderr [initScript.sh] npm notice Changelog: <https://github.com/npm/cli/releases/tag/v10.7.0> cmderr [initScript.sh] npm notice Run `npm install -g [email protected]` to update! cmderr [initScript.sh] npm notice error Script return with result [failed] code [1] signal [null] cwd [azure-resource-manager-schemas]: .sdkauto/initScript.sh warn File azure-resource-manager-schemas_tmp/initOutput.json not found to read command .sdkauto/generateScript.sh ../azure-resource-manager-schemas_tmp/generateInput.json ../azure-resource-manager-schemas_tmp/generateOutput.json cmderr [generateScript.sh] /mnt/vss/_work/1/a/unified-pipeline-runtime/common/temp/node_modules/.pnpm/[email protected][email protected]/node_modules/ts-node/src/index.ts:500 cmderr [generateScript.sh] return new TSError(diagnosticText, diagnosticCodes) cmderr [generateScript.sh] ^ cmderr [generateScript.sh] TSError: ⨯ Unable to compile TypeScript: cmderr [generateScript.sh] cmd/generateall.ts(6,20): error TS2307: Cannot find module 'colors' or its corresponding type declarations. cmderr [generateScript.sh] cmd/generateall.ts(10,19): error TS2307: Cannot find module 'yargs' or its corresponding type declarations. cmderr [generateScript.sh] cmd/generateall.ts(11,18): error TS2307: Cannot find module 'path' or its corresponding type declarations. cmderr [generateScript.sh] cmd/generateall.ts(13,35): error TS2307: Cannot find module 'fs' or its corresponding type declarations. cmderr [generateScript.sh] cmd/generateall.ts(14,23): error TS2307: Cannot find module 'strip-ansi' or its corresponding type declarations. cmderr [generateScript.sh] cmd/generateall.ts(42,9): error TS2584: Cannot find name 'console'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'. cmderr [generateScript.sh] cmd/generateall.ts(53,9): error TS2584: Cannot find name 'console'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'. cmderr [generateScript.sh] cmd/generateall.ts(69,67): error TS7006: Parameter 'x' implicitly has an 'any' type. cmderr [generateScript.sh] cmd/generateall.ts(70,49): error TS7006: Parameter 'f' implicitly has an 'any' type. cmderr [generateScript.sh] cmd/generateall.ts(94,21): error TS2584: Cannot find name 'console'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'. cmderr [generateScript.sh] cmd/generateall.ts(105,21): error TS2584: Cannot find name 'console'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'. cmderr [generateScript.sh] cmd/generateall.ts(106,21): error TS2584: Cannot find name 'console'. Do you need to change your target library? Try changing the 'lib' compiler option to include 'dom'. cmderr [generateScript.sh] cmd/generateall.ts(157,13): error TS2591: Cannot find name 'process'. Do you need to install type definitions for node? Try `npm i --save-dev @types/node` and then add 'node' to the types field in your tsconfig. cmderr [generateScript.sh] at createTSError (/mnt/vss/_work/1/a/unified-pipeline-runtime/common/temp/node_modules/.pnpm/[email protected][email protected]/node_modules/ts-node/src/index.ts:500:12) cmderr [generateScript.sh] at reportTSError (/mnt/vss/_work/1/a/unified-pipeline-runtime/common/temp/node_modules/.pnpm/[email protected][email protected]/node_modules/ts-node/src/index.ts:504:19) cmderr [generateScript.sh] at getOutput (/mnt/vss/_work/1/a/unified-pipeline-runtime/common/temp/node_modules/.pnpm/[email protected][email protected]/node_modules/ts-node/src/index.ts:739:36) cmderr [generateScript.sh] at Object.compile (/mnt/vss/_work/1/a/unified-pipeline-runtime/common/temp/node_modules/.pnpm/[email protected][email protected]/node_modules/ts-node/src/index.ts:955:32) cmderr [generateScript.sh] at Module.m._compile (/mnt/vss/_work/1/a/unified-pipeline-runtime/common/temp/node_modules/.pnpm/[email protected][email protected]/node_modules/ts-node/src/index.ts:1043:43) cmderr [generateScript.sh] at Module._extensions..js (node:internal/modules/cjs/loader:1422:10) cmderr [generateScript.sh] at Object.require.extensions.<computed> [as .ts] (/mnt/vss/_work/1/a/unified-pipeline-runtime/common/temp/node_modules/.pnpm/[email protected][email protected]/node_modules/ts-node/src/index.ts:1046:12) cmderr [generateScript.sh] at Module.load (node:internal/modules/cjs/loader:1203:32) cmderr [generateScript.sh] at Function.Module._load (node:internal/modules/cjs/loader:1019:12) cmderr [generateScript.sh] at Function.executeUserEntryPoint [as runMain] (node:internal/modules/run_main:128:12) error Script return with result [failed] code [1] signal [null] cwd [azure-resource-manager-schemas]: .sdkauto/generateScript.sh warn Skip package processing as generation is failed error ERROR: The 'breakingChangesLabel' configuration is missing or incorrect from the 'swagger_to_sdk_config.json file.
️⚠️ azure-powershell warning [Detail]
⚠️Warning in generating from 28b00f30a5b86aaadabb18cb7273d582bffb67f6. SDK Automation 14.0.0command sh ./tools/SwaggerCI/init.sh ../azure-powershell_tmp/initInput.json ../azure-powershell_tmp/initOutput.json command pwsh ./tools/SwaggerCI/psci.ps1 ../azure-powershell_tmp/generateInput.json ../azure-powershell_tmp/generateOutput.json
⚠️Az.cosmos-db.DefaultTag [Preview SDK Changes]
Generated ApiView
| Language | Package Name | ApiView Link |
|---|---|---|
| Go | sdk/resourcemanager/cosmos/armcosmos | https://apiview.dev/Assemblies/Review/b6c1e0c0f6e54f6b8de67946304e3b9f?revisionId=56dcd6210f6345e1a7dd90b0c8dc9cce |
| Java | azure-resourcemanager-cosmos-generated | https://apiview.dev/Assemblies/Review/06cb8d7a951f40a8810a0ffbd3cabd77?revisionId=cb5f009e67d64166a3b9f4f6819d6ff4 |
| JavaScript | @azure/arm-cosmosdb | https://apiview.dev/Assemblies/Review/06c23e48548143fb8df81695f9f5b2d6?revisionId=1f1f91fa1d914c63b8600ea45dee5457 |
| .Net | Azure.ResourceManager.CosmosDB | https://apiview.dev/Assemblies/Review/aeace554aba64a019566bba99b89d569?revisionId=9cc92208be7844189c3660d3ac2bbca4 |
| Swagger | Microsoft.DocumentDB | https://apiview.dev/Assemblies/Review/ac373549b7d34a108e5add93e45b3e3f?revisionId=b8f6d3e60d55488f958cce52c6c58f6d |
Please address or respond to feedback from the ARM API reviewer.
When you are ready to continue the ARM API review, please remove the ARMChangesRequested label.
This will notify the reviewer to have another look.
If the feedback provided needs further discussion, please use this Teams channel to post your questions - aka.ms/azsdk/support/specreview-channel.
Please include [ARM Query] in the title of your question to indicate that it is ARM-related.
![openapi-workflow-bot[bot] avatar](https://avatars.githubusercontent.com/in/81125?v=4 "Published by a pub.dev verified publisher"){kind=small}
are mongocluster resources not present now ? Dont see mongoCluster.json file
"description": "End time in UTC of the last successful capacity mode change."
could you mention the format in description ? #Resolved
Refers to: specification/cosmos-db/resource-manager/Microsoft.DocumentDB/preview/2024-05-15-preview/cosmos-db.json:11001 in 28e77df. [](commit_id = 28e77df275bc704bb21e1bb58d137f2a44e38c94, deletion_comment = False)
Do I see rightly that you're reviewing, at the same time, both a preview, and a non preview version, for the same exact month/version string? That sounds potentially quite confusing to customers, they could wonder why they want to use this preview version when there's already a GA of it available. I guess there are reasons you want to do it, but could you think about whether this is going to be impactful for your marketing announcements, and confirm you still want to do it?
Do I see rightly that you're reviewing, at the same time, both a preview, and a non preview version, for the same exact month/version string? That sounds potentially quite confusing to customers, they could wonder why they want to use this preview version when there's already a GA of it available. I guess there are reasons you want to do it, but could you think about whether this is going to be impactful for your marketing announcements, and confirm you still want to do it?
Yes - our existing versioning has been very similar and our customers have been using this style of versioning for years as well. I have discussed this with Jeffrey too and will attend the next office hours to discuss better alternatives. For now, we do want to continue with this versioning style.
I'm seeing errors from a circular reference issue, I think that might be making it hard to validate this properly. Can we remove any circular references between json, such as by moving some definitions out to another json file?
'The JSON file has a circular reference. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-05-15-preview/privateEndpointConnection.json'
"Invalid",
Consider documenting what customers are supposed to do about 'invalid' if they see it
Refers to: specification/cosmos-db/resource-manager/Microsoft.DocumentDB/preview/2024-05-15-preview/cosmos-db.json:10948 in d8a5483. [](commit_id = d8a5483047acff55177b06714438916b41c3211a, deletion_comment = False)
"description": "Indicates the previous capacity mode of the account before successful transition.",
interesting pattern! I'm a little curious about what before successful transition means in practice. Like whether it never changes during failed operations. Maybe there's a clearer wording.
Refers to: specification/cosmos-db/resource-manager/Microsoft.DocumentDB/preview/2024-05-15-preview/cosmos-db.json:10973 in 28e77df. [](commit_id = 28e77df275bc704bb21e1bb58d137f2a44e38c94, deletion_comment = False)
},
For sake of codegen/maintainability you probably shouldn't define CapacityMode enum inline twice, instead you should make it a top level definition and reference it in two places - if its really the same exact concept #Resolved
Refers to: specification/cosmos-db/resource-manager/Microsoft.DocumentDB/preview/2024-05-15-preview/cosmos-db.json:10984 in d8a5483. [](commit_id = d8a5483047acff55177b06714438916b41c3211a, deletion_comment = False)
"capacityModeTransitionBeginTimestamp": {
Friendlier names derived from naming guidelines I'm aware of might be
'capacityModeTransitionBeganAt' 'capacityModeTransitionCompletedAt' 'capacityModeTransitionLastSucceededAt'
...but do we really have to prefix them all with capacityMode?
Maybe not, in the context of the CapacityModeChangeTransitionState? The implied property paths in e.g. code are e.g.
resource.capacityModeChangeTransitionState.capacityModeLastSuccessfulTransitionEndTimestamp which is quite a lot of letters
Refers to: specification/cosmos-db/resource-manager/Microsoft.DocumentDB/preview/2024-05-15-preview/cosmos-db.json:10985 in d8a5483. [](commit_id = d8a5483047acff55177b06714438916b41c3211a, deletion_comment = False)
Given we don't yet seem to have a proper network security perimeter definitions common types thing to use, I've manually diffed your definitions with another RPs to look for possible consistency issues. The bad news is there are some. The good news is that the semantic diff is small, and I think all the examples stay the same.
PS, FWIW storage RP swagger seems to think the NSP reference's location mutability should be read/create-only. I guess not every RP is the same - maybe, but you might want to consider how to document it like you've implemented it:
"location": {
"description": "Location of the resource",
"type": "string",
"x-ms-mutability": [
"create",
"read"
]
![azure-pipelines[bot] avatar](https://avatars.githubusercontent.com/in/9426?v=4 "Published by a pub.dev verified publisher"){kind=small}
@vandit15 @pjohari-ms I'm working on adding NetworkSecurityPerimeters to common types, as something like this is clearly urgently needed! Please help me review my PR. https://github.com/Azure/azure-rest-api-specs/pull/28958
I have a lingering worry that some of the avocado errors might matter (e.g. missing a link to an example could stop it showing in docs, or perhaps impact model validation), have you looked into fixing them?
Unfortunately some tools struggle to understand circular references, you can try normalizing them to a noncircular structure by moving definitions between jsons -- or by refactoring using common-types version of privatelinks.json if its sufficiently compatible. (Did we already reject that option? Too many PRs to remember them all properly, sorry!)
❌ UNREFERENCED_JSON_FILE The example JSON file is not referenced from the swagger file. readme: specification/cosmos-db/resource-manager/readme.md json: preview/2024-05-15-preview/examples/CosmosDBManagedCassandraCommandResultList.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/providers/Microsoft.DocumentDB/mongoClusters is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{} is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/firewallRules/{} is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/firewallRules is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/providers/Microsoft.DocumentDB/locations/{}/checkMongoClusterNameAvailability is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/listConnectionStrings is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ⚠️ CIRCULAR_REFERENCE The JSON file has a circular reference. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-05-15-preview/privateEndpointConnection.json
Using github to add a TODO here - Independent of ARM API review and manifest rollout: Please let us update this PR to use the common types definition for networkSecurityPerimeter.json here #28958 (PR will be merged asap) before actually merging.
ACK. Will wait for the PR to be edited by the maintainers before merging.
I have a lingering worry that some of the avocado errors might matter (e.g. missing a link to an example could stop it showing in docs, or perhaps impact model validation), have you looked into fixing them?
Unfortunately some tools struggle to understand circular references, you can try normalizing them to a noncircular structure by moving definitions between jsons -- or by refactoring using common-types version of privatelinks.json if its sufficiently compatible. (Did we already reject that option? Too many PRs to remember them all properly, sorry!)
❌ UNREFERENCED_JSON_FILE The example JSON file is not referenced from the swagger file. readme: specification/cosmos-db/resource-manager/readme.md json: preview/2024-05-15-preview/examples/CosmosDBManagedCassandraCommandResultList.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/providers/Microsoft.DocumentDB/mongoClusters is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{} is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/firewallRules/{} is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/firewallRules is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/providers/Microsoft.DocumentDB/locations/{}/checkMongoClusterNameAvailability is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ❌ MISSING_APIS_IN_DEFAULT_TAG The default tag should contain all APIs. The API path /subscriptions/{}/resourceGroups/{}/providers/Microsoft.DocumentDB/mongoClusters/{}/listConnectionStrings is not in the default tag. Please make sure the missing API swaggers are in the default tag. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-02-15-preview/mongoCluster.json ⚠️ CIRCULAR_REFERENCE The JSON file has a circular reference. readme: specification/cosmos-db/resource-manager/readme.md json: Microsoft.DocumentDB/preview/2024-05-15-preview/privateEndpointConnection.json
These are fixed. MISSING_APIS ones are expected.
All comments other than the incorrect api-version in examples are addressed. Signing off as its not blocking, please merge after the commit for NSP updates by Api Reviewer team is made. Placed a DoNotMerge label that can be removed once ready.
Merge without branch refresh should be OK per comment in API Spec Review team here: https://teams.microsoft.com/l/message/19:[email protected]/1715629299216?tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&parentMessageId=1715624451175&teamName=Azure%20SDK&channelName=API%20Spec%20Review&createdTime=1715629299216.
However, merge is currently blocked by @TimLovellSmith pending review comments. Tim, please approve or comment.
@TimLovellSmith Can this be merged? The PR merge is being delayed and we have to work for achieving BUILD timelines.
@pjohari-ms update, hopefully this is unblocked for refactor real soon. The adding NSP common-types PR should be merge-ready now, it should just need the checks to come back alive and tell us if its all clear to merge.