StorageCache base commit for API version 2026-01-01

[Aman-Jain-14]

ARM (Control Plane) API Specification Update Pull Request

[!TIP] Overwhelmed by all this guidance? See the Getting help section at the bottom of this PR description.

PR review workflow diagram

Please understand this diagram before proceeding. It explains how to get your PR approved & merged.

Purpose of this PR

What's the purpose of this PR? Check the specific option that applies. This is mandatory!

• [ ] New resource provider.
• [X] New API version for an existing resource provider. (If API spec is not defined in TypeSpec, the PR should have been created in adherence to OpenAPI specs PR creation guidance).
• [ ] 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.
• [ ] Convert existing OpenAPI spec to TypeSpec spec (do not combine this with implementing changes for a new API version).
• [ ] 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:

• [X] I confirm this PR is modifying Azure Resource Manager (ARM) related specifications, and not data plane related specifications.
• [X] 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.
• [X] A release plan has been created. If not, please create one as it will help guide you through the REST API and SDK creation process.

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 PR and Due diligence checklist.
• If you don't have permissions to remove or add labels to the PR, request write access per aka.ms/azsdk/access#request-access-to-rest-api-or-sdk-repositories
• To understand what you must do next to merge this PR, see the Next Steps to Merge comment. 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 ARM review (PR workflow diagram Step 2), see https://aka.ms/azsdk/pr-arm-review.
• If the PR CI checks appear to be stuck in queued state, please add a comment with contents /azp run. This should result in a new comment denoting a PR validation pipeline has 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.
• For guidance on SDK breaking change review, refer to https://aka.ms/ci-fix.

[github-actions[bot]]

Next Steps to Merge

✅ All automated merging requirements have been met! To get your PR merged, see aka.ms/azsdk/specreview/merge.

Comment generated by summarize-checks workflow run.

[github-actions[bot]]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.StorageCache-StorageCache
Go	sdk/resourcemanager/storagecache/armstoragecache
Java	com.azure.resourcemanager:azure-resourcemanager-storagecachestoragecache
JavaScript	@azure/arm-storagecache
Python	azure-mgmt-storagecache

[mentat9]

        "$ref": "../../../../../../common-types/resource-management/v3/types.json#/parameters/ResourceGroupNameParameter"

Can you use a newer common types, e.g. v6? #Resolved

---

Refers to: specification/storagecache/resource-manager/Microsoft.StorageCache/StorageCache/stable/2026-01-01/amlfilesystem.json:1382 in 1f48d2a. [](commit_id = 1f48d2a1add8f72925236382767a4fb81dea5e03, deletion_comment = False)

[mentat9]

          "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse"

Any reason your request and response use a different version of common types? Recommend using the same version, and as new as possible (v6). #Resolved

---

Refers to: specification/storagecache/resource-manager/Microsoft.StorageCache/StorageCache/stable/2026-01-01/amlfilesystem.json:1417 in 1f48d2a. [](commit_id = 1f48d2a1add8f72925236382767a4fb81dea5e03, deletion_comment = False)

[mentat9]

          "$ref": "storagecache.json#/definitions/CloudError"

@Aman-Jain-14 - Use common types (v5 or newer).

---

Refers to: specification/storagecache/resource-manager/Microsoft.StorageCache/StorageCache/stable/2026-01-01/amlfilesystem.json:1665 in 1f48d2a. [](commit_id = 1f48d2a1add8f72925236382767a4fb81dea5e03, deletion_comment = False)

[mentat9]

          "type": "string",

Add format: uuid

---

Refers to: specification/storagecache/resource-manager/Microsoft.StorageCache/StorageCache/stable/2026-01-01/amlfilesystem.json:1870 in 1f48d2a. [](commit_id = 1f48d2a1add8f72925236382767a4fb81dea5e03, deletion_comment = False)

[mentat9]

          "type": "string",

Can this be enum (or integer if there are too many values)? #Resolved

---

Refers to: specification/storagecache/resource-manager/Microsoft.StorageCache/StorageCache/stable/2026-01-01/amlfilesystem.json:3306 in 1f48d2a. [](commit_id = 1f48d2a1add8f72925236382767a4fb81dea5e03, deletion_comment = False)

[mentat9]

        "startTimeUTC": {

Recommend startTimeUtc (debatable, I know. I prefer camelCase for acronyms of more than two letters). #Resolved

---

Refers to: specification/storagecache/resource-manager/Microsoft.StorageCache/StorageCache/stable/2026-01-01/amlfilesystem.json:3314 in 1f48d2a. [](commit_id = 1f48d2a1add8f72925236382767a4fb81dea5e03, deletion_comment = False)

[mentat9]

        "completionTimeUTC": {

Recommend completionTimeUtc. #Resolved

---

Refers to: specification/storagecache/resource-manager/Microsoft.StorageCache/StorageCache/stable/2026-01-01/amlfilesystem.json:3320 in 1f48d2a. [](commit_id = 1f48d2a1add8f72925236382767a4fb81dea5e03, deletion_comment = False)

[Aman-Jain-14]

@mentat9

Thank you so much for your review. I have pushed the changes to update the spec to use v5/types.json for the new sub-resource (ExpansionJob), and couple other changes as you requested.

Please find my responses to your comments:

 "$ref": "../../../../../../common-types/resource-management/v3/types.json#/parameters/ResourceGroupNameParameter"
Can you use a newer common types, e.g. v6?

          "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse"
Any reason your request and response use a different version of common types? Recommend using the same version, and as new as possible (v6).

          "$ref": "storagecache.json#/definitions/CloudError"
Use common types (v5 or newer).

Thank you for catching that. I updated the ExpansionJob spec to use v5/types.json We will need some time to understand the changes in v6/types.json, even though it looks mostly backwards compatible. We can start using v6 in our next API release which is slated for Q4 2026.

"type": "string",
Add format: uuid

Added format: uuid

 "type": "string",
Can this be enum (or integer if there are too many values)?

The statusCode is used across multiple platforms (REST, Geneva Actions, DashBoards, KVS, Reliable Collections (RC)), so we chose string to ensure that the enum conversion across platforms does not result in information loss. This is consistent with our other sub-resources (importJobs, autoExportJobs, autoImportJobs), so it'll be great if we can keep this as string.

 "startTimeUTC": {
Recommend startTimeUtc (debatable, I know. I prefer camelCase for acronyms of more than two letters).

"completionTimeUTC": {
Recommend completionTimeUtc.

Sorry, again making a case for consistency across other sub-resource types that we have. We have 9 other instances of using 'UTC' in this spec.

[Aman-Jain-14]

@mentat9

I have to revert the changes for adding GUID format as that is making the Linter check to fail:

[mentat9]

@mentat9

I have to revert the changes for adding GUID format as that is making the Linter check to fail:

@Aman-Jain-14 - Actually, you should just suppress the error (expand the "Suppressing failures" comment above for links/info). While the idea behind that linter check is valid, it doesn't make any sense as a linter rule: it's just telling everyone to pretend their property is not a guid when it is a guid. It was supposed to be disabled by now but obviously hasn't been: I always forget to warn people about it.

[mentat9]

@mentat9

Thank you so much for your review. I have pushed the changes to update the spec to use v5/types.json for the new sub-resource (ExpansionJob), and couple other changes as you requested.

Please find my responses to your comments:

 "$ref": "../../../../../../common-types/resource-management/v3/types.json#/parameters/ResourceGroupNameParameter"
Can you use a newer common types, e.g. v6?

          "$ref": "../../../../../../common-types/resource-management/v5/types.json#/definitions/ErrorResponse"
Any reason your request and response use a different version of common types? Recommend using the same version, and as new as possible (v6).

          "$ref": "storagecache.json#/definitions/CloudError"
Use common types (v5 or newer).

Thank you for catching that. I updated the ExpansionJob spec to use v5/types.json We will need some time to understand the changes in v6/types.json, even though it looks mostly backwards compatible. We can start using v6 in our next API release which is slated for Q4 2026.

"type": "string",
Add format: uuid

Added format: uuid

 "type": "string",
Can this be enum (or integer if there are too many values)?

The statusCode is used across multiple platforms (REST, Geneva Actions, DashBoards, KVS, Reliable Collections (RC)), so we chose string to ensure that the enum conversion across platforms does not result in information loss. This is consistent with our other sub-resources (importJobs, autoExportJobs, autoImportJobs), so it'll be great if we can keep this as string.

 "startTimeUTC": {
Recommend startTimeUtc (debatable, I know. I prefer camelCase for acronyms of more than two letters).

"completionTimeUTC": {
Recommend completionTimeUtc.

Sorry, again making a case for consistency across other sub-resource types that we have. We have 9 other instances of using 'UTC' in this spec.

@Aman-Jain-14 - The v6 common types are backward compatible, but moving from v5 to v6 later is fine.

Regarding the point about consumers of your APIs, we only review stuff that's being added, so that's the best time to make these kinds of changes. In this case, it may not be enough benefit if it affects clients too much: my suggestions won't block ARM signoff.

I see the point about staying consistent with naming of UTC, but not sure I see the information loss issue related to statusCode. Union/enum are string on the wire, so it should interchange fine with other string implementations unless you have a scenario where some other API's status codes are getting reported via this new API (which I assume is not the case).

Final point: looks like you missed one comment (line 1665 of amlfilesystem.json) where you are using a different definition (CloudError) for the default response branch. That looks like a mistake that should be fixed.

[Aman-Jain-14]

@mentat9

Final point: looks like you missed one comment (line 1665 of amlfilesystem.json) where you are using a different definition (CloudError) for the default response branch. That looks like a mistake that should be fixed.

Using CloudError is not an error here. Our service tree originally had 2 services: HPCCache (hence the name storage cache) and AmlFilesystems, which had the effect of us starting with one spec file (storagecache.json) but eventually splitting it between two (storagecache.json and amlfilesystem.json).

The HPCCache product is End-Of-Lifed, and we will be deprecating and removing all traces of it from our swagger after we launch the new API version which has a new customer facing feature (ExpansionJob).

The storagecache.json spec file has a lot of global resources that were carried over or referenced in amlfilesystem.json

I know its not an ideal design but unfortunately it has been grand-fathered in since 5 years now.

We are in the process of cleaning up storagecache.json as I mentioned, and all these will be reviewed and if needed fixed up.

[Aman-Jain-14]

Following the guidelines to request a temporary suppression until this issue is fixed:

The new ClusterUuid field is a UUID but the LintDiff check doesn't agree with using uuid format in the PR.

Comment from PR reviewer: While the idea behind that linter check is valid, it doesn't make any sense as a linter rule: it's just telling everyone to pretend their property is not a guid when it is a guid. It was supposed to be disabled by now but obviously hasn't been.

Please add a LintDiff suppression tag on the PR.

[psah434]

has the lintdiff suppression been added?

[Aman-Jain-14]

@psah434 No, the documentation says that we have to give the justification and ask the PR assignee to apply it for us.