Problems with upstream Swagger/JSON schemas

[matthchr]

This is a place to catalog issues we've noticed with upstream Swagger/JSON specs. Once we've got a large list we can submit PRs or Issues to the corresponding specs. Note that this isn't complete and should be combined with an examination of the azure-arm.yaml configuration file to see what other problems we are working around with config overrides.

Issues with Swagger

Storage

• StorageAccountPropertiesCreateParameters is listed as optional on the spec, but really has a required field AccessTier without which the account will not create successfully.
• StorageAccountsQueueServicesQueue uses a regex that doesn’t conform to the JSON Schema recommendations and cannot be parsed by the Go stdlib (^[a-z0-9]([a-z0-9]|(-(?!-))){1,61}[a-z0-9]$)
• NetworkAcls bypass is documented as an enum but actually accepts a comma-separated list of values, which isn't what enum means.

Compute

• Uses anyOf when we think they want oneOf. Affected types:
  • extensions (2015-08-01, 2017-03-30, 2017-12-01)
  • extensionsChild (2015-08-01, 2017-03-30, 2017-12-01)
• vmssExtensions (2017-12-01)
• VirtualMachineScaleSetExtension (2018-06-01, 2018-10-01, 2019-03-01, 2019-07-01)
• virtualMachines_extensions (2018-06-01, 2018-10-01, 2019-03-01, 2019-07-01)
• virtualMachineScaleSets_extensions (2018-06-01, 2018-10-01, 2019-03-01, 2019-07-01)
• VirtualMachineScaleSetIPConfiguration inherits Id from SubResource, but as far as I can tell that Id field isn't actually ever used in a PUT. If that's the ID of the ARM resource created by the PUT (and no other way?) then it should be readonly? The whole "can only make this resource as a property of another resource" is weird in general.
• I think that when compute SubResource is used directly (as a property or something), it's meaning is that of a reference. When it's used via inheritance, then the reference is to self.

Container Services

• ContainerServiceWindowsProfile and ManagedClusterWindowsProfile use a regex that doesn’t conform to the JSON Schema recommendations and cannot be parsed by the Go stdlib (^(?=.*[a-z])(?=.*[A-Z])(?=.*[!@#$%\\^&\\*\\(\\)])[a-zA-Z\\d!@#$%\\^&\\*\\(\\)]{12,123}$)

Healthcare

• Uses anyOf when we think they want oneOf. Affected types (in 2019-09-16):
  • ServiceCorsConfigurationInfo

Not present any more as of this commit.

Insights

• Uses anyOf when we think they want oneOf. Affected types (in 2016-03-01):
  • RuleDataSource
  • RuleCondition
  • RuleAction

Not present any more as of this commit.

• 2020-02-02 REST API for components has component.workspaceId documented as required but not actually marked required in the schema. In reality it is not required as far as I can tell, so it's just a documentation issue.
• The 2018-05-01-preview API says there are only 2 allowed fields for kind, but in reality there are at least a few more, standard is one of the additional ones. Actually you can see this in the other kind defined in this file. I think the issue is they should just prune the top level kind in the WebTest.

KeyVault

• Uses anyOf when we think they want oneOf. Affected types (in 2015-06-01):
  • permissions

Fixed in 2016-10-01.

RecoveryServices

• Uses anyOf when we think they want oneOf. Affected types (in 2018-01-10):
  • FabricSpecificCreationInput
  • EnableProtectionProviderSpecificInput
  • FabricSpecificCreateNetworkMappingInput
  • PolicyProviderSpecificInput
  • RecoveryPlanActionDetails

Sendgrid

• Uses anyOf when we think they want oneOf. Affected types (in 2015-01-01):
  • accounts

ServiceBus

• SBNamespaceProperties in 2021-01-01-preview APIVersion has privateEndpointConnections which should be marked readOnly but isn't.

Issues with JSON Schema

Common

i.e. in https://schema.management.azure.com/schemas/common/definitions.json

• Uses anyOf when we think they want oneOf. Affected types:
  • resourceLocations
• Handling on readonly types in schema autogeneration: ConfigurationStoreProperties only has no properties and should be fixed azure-resource-manager-schemas#835

Network

• Virtual Network (2017-10-01):
  • has ProvisioningState in its spec
  • location marked optional but is not
  • addressspace/addressprefixes are required but not marked as such
  • WHAT IS RESOURCEGUID

[matthchr]

We should push this back up to the Swagger repo at least (JSON schema ones we already have, for the most part)

[matthchr]

We should work with the upstream Swagger folks on this

[matthchr]

No change on the above - we should work towards resolving this issue in favor of fixing upstream Swagger issues and/or opening issues.

[matthchr]

@matthchr will go through the Swagger issues and convert them to issues on the azure-rest-api-specs repo

[matthchr]

No change from above -- Matt will work on this (it's on the list)

[matthchr]

No change from above