Specify mutability and default values for models. Fix descriptions for web apps

This checklist is used to make sure that common issues in a pull request are addressed. This will expedite the process of getting your pull request merged and avoid extra work on your part to fix issues discovered during the review process.
PR information

[x] The title of the PR is clear and informative.
[x] There are a small number of commits, each of which have an informative message. This means that previously merged commits do not appear in the history of the PR. For information on cleaning up the commits in your pull request, see this page.
[x] Except for special cases involving multiple contributors, the PR is started from a fork of the main repository, not a branch.
[x] If applicable, the PR references the bug/issue that it fixes.
[x] Swagger files are correctly named (e.g. the api-version in the path should match the api-version in the spec).

Quality of Swagger

[x] I have read the contribution guidelines.
[x] My spec meets the review criteria:

[x] The spec conforms to the Swagger 2.0 specification.
[x] Validation errors from the Linter extension for VS Code have all been fixed for this spec. (Note: for large, previously checked in specs, there will likely be many errors shown. Please contact our team so we can set a timeframe for fixing these errors if your PR is not going to address them).
[x] The spec follows the patterns described in the Swagger good patterns document unless the service API makes this impossible.

Split deletedWebApps into its own json file
Added x-ms-skip-url-encoding tags to $filter
Added x-ms-mutability extensions
Added default values
Fixed documentation for webapps

This change is

Thanks. @jianghaolu is reviewing

Review status: 0 of 11 files reviewed at latest revision, 17 unresolved discussions.

arm-web/2015-04-01/Domains.json, line 195 at r3 (raw file):

            "description": "Name of the resource group",
            "required": true,
            "type": "string"

regex for resourceGroupName

arm-web/2015-04-01/Domains.json, line 268 at r3 (raw file):

        ],
        "summary": "Creates a domain.",
        "description": "Creates a domain.",

Creates or updates a domain.

arm-web/2015-04-01/Domains.json, line 285 at r3 (raw file):

            "name": "resourceGroupName",
            "in": "path",
            "description": ">Name of the resource group",

Looks like copy paste error. Remove >

arm-web/2015-04-01/Domains.json, line 371 at r3 (raw file):

        ],
        "responses": {
          "204": {

Creating or updating is a long running operation. However, delete isn't. Flagging out of curiosity.

arm-web/2015-04-01/Domains.json, line 385 at r3 (raw file):

          "Domains"
        ],
        "operationId": "Domains_ListDomainOwnershipIdentifiers",

missing description and summary. Please document more information about DomainOwnershipIdentifiers in the description rather than simply saying Lists blah blah.

arm-web/2015-04-01/Domains.json, line 395 at r3 (raw file):

            "name": "resourceGroupName",
            "in": "path",
            "required": true,

parameter description missing for resourceGroupName and domainName. Plus also provide regex for resourcegroupName. On that note should domainName have a regex as well?

arm-web/2015-04-01/Domains.json, line 476 at r3 (raw file):

          "Domains"
        ],
        "operationId": "Domains_CreateOrUpdateDomainOwnershipIdentifier",

After looking at the CRUD pattern on DomainOwnershipIdentifier. I think the recommended patterns are:

DomainOwnershipIdentifier_CreateOrUpdate
Domains_CreateOrUpdateOwnershipIdentifier

Ideal world: Domains_OwnershipIdentifiers_CreateOrUpdate (Autorest does not support multiple underscores right now)

arm-web/2015-04-01/Domains.json, line 512 at r3 (raw file):

            "required": true,
            "schema": {
              "$ref": "#/definitions/RequestMessageEnvelope[DomainOwnershipIdentifier]"

RequestMessageEnvelope[DomainOwnershipIdentifier]. These kind of names are incorrect. Please fix swashbuckle plugin.
Ideally, the input (body parameter) for a PUT operation and the output of PUT operation should be the same type. This enables GET | PUT pipeline scenario out of the box.

arm-web/2015-04-01/Domains.json, line 573 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Object"

General comment: For all delete operations, this is incorrect. Please provide a proper schema in the response. Please remove Object from the model definition as it servers no purpose.
Does the service return  a 204 ?

arm-web/2015-04-01/Domains.json, line 596 at r3 (raw file):

        "parameters": [
          {
            "name": "resourceGroupName",

General comment: missing parameter descriptions.

arm-web/2015-04-01/Domains.json, line 618 at r3 (raw file):

            "required": true,
            "schema": {
              "$ref": "#/definitions/RequestMessageEnvelope[DomainOwnershipIdentifier]"

General comment: Fix model definition names

arm-web/2015-04-01/Domains.json, line 618 at r3 (raw file):

            "required": true,
            "schema": {
              "$ref": "#/definitions/RequestMessageEnvelope[DomainOwnershipIdentifier]"

Usually body parameters for PUT and PATCH should not be same. PATCH operation cannot have top level required properties in the object and it should not have default values in the entire tree.

arm-web/2015-04-01/Domains.json, line 645 at r3 (raw file):

        "summary": "Retrieves the latest status of a domain purchase operation.",
        "description": "Retrieves the latest status of a domain purchase operation.",
        "operationId": "Domains_GetOperation",

If the provisioningState in the CreateOrUpdate() operation reflects the status then we dont need this operation. Please remove this API.

arm-web/2015-04-01/Domains.json, line 706 at r3 (raw file):

      "description": "Address information for domain registration.",
      "type": "object",
      "properties": {

Are there any required properties in this object? May be country and postal code?

arm-web/2015-04-01/Domains.json, line 755 at r3 (raw file):

          "description": "ARM envelope properties",
          "properties": {
            "keyVaultId": {

Is this model used in the body of the request? If yes then should keyvaultId and keyvaultSecretName be required ?

arm-web/2015-04-01/Domains.json, line 806 at r3 (raw file):

          "properties": {
            "certificates": {
              "description": "State of the Key Vault secret.",

description mismatch

arm-web/2015-04-01/Domains.json, line 827 at r3 (raw file):

            "validityInYears": {
              "format": "int32",
              "description": "Duration in years (must be between 1 and 3).",

"minimum": 1,
"maximum": 3

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 21 unresolved discussions.

arm-web/2015-04-01/Domains.json, line 806 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> description mismatch

In fact, AppServiceCertificateOrder is duplicated in AppServiceCertificateOrder.json. This class is not referenced in domains so this definition is redundant.
Amar's comments, however, still apply to AppServiceCertificateOrder in AppServiceCertificateOrder.json.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 349 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Object"

This might have been reported by others. But returning Object on delete is not the best practice. It should either return the delete object in strong type or simply doesn't return anything.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 826 at r3 (raw file):

  },
  "definitions": {
    "Address": {

This is only referenced in Contact, which is not referenced in any path

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 1109 at r3 (raw file):

      }
    },
    "AppServiceEnvironment": {

This is never referenced.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 1333 at r3 (raw file):

      }
    },
    "AppServicePlan": {

This is never referenced.
Looks like the list of definitions are duplicated across individual Swagger docs. I will not mark every single definition that is not referenced.
This is bringing a lot of redundancy in swagger specs.

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 36 unresolved discussions.

arm-web/2016-03-01/Recommendations.json, line 19 at r3 (raw file):

        "summary": "Gets a list of recommendations associated with the specified subscription.",
        "description": "Gets a list of recommendations associated with the specified subscription.",
        "operationId": "Recommendations_Get",

Looking at the other operations, think about the consistency between names (List... vs Get)

arm-web/2016-03-01/Recommendations.json, line 68 at r3 (raw file):

        "summary": "Gets the list of past recommendations optionally specified by the time range.",
        "description": "Gets the list of past recommendations optionally specified by the time range.",
        "operationId": "Recommendations_ListHistoryForWebApp",

Is "ForWebApp" necessary or can it be dropped? Seems wordy.
Same for other operations.

arm-web/2016-03-01/Recommendations.json, line 94 at r3 (raw file):

            "name": "startTime",
            "in": "query",
            "description": "The start time of a time range to query, e.g. $filter=startTime eq '2015-01-01T00:00:00Z' and endTime eq '2015-01-02T00:00:00Z'",

Please clarify this description: this is a query parameter, so what about the odata syntax? Confusing description.
Also: format: date-time
Same applies for endTime

arm-web/2016-03-01/Recommendations.json, line 156 at r3 (raw file):

            "name": "featured",
            "in": "query",
            "description": "If set, this API returns only the most critical recommendation among the others. Otherwise this API returns all recommendations available",

"If set"? So also if it's set to false? Maybe "If true" would be less misleading.

arm-web/2016-03-01/Recommendations.json, line 170 at r3 (raw file):

            "description": "The number of site slots associated to the site",
            "type": "integer",
            "format": "int32"

Doesn't this have a min/max value? E.g. 0 for min and something sane for max?

arm-web/2016-03-01/Recommendations.json, line 175 at r3 (raw file):

            "name": "liveHours",
            "in": "query",
            "description": "If greater than zero, this API scans the last active live site symptoms, dynamically generate on-the-fly recommendations",

Not really clear what this parameter is. The description only explicitly calls out "greater than zero" as a thing, but a flag would do for that purpose.
In case you mean you will scan for symptoms up to liveHours hours in the past, maybe the description could be improved accordingly and min/max values could be specified.

arm-web/2016-03-01/Recommendations.json, line 2802 at r3 (raw file):

        },
        "recommendationId": {
          "description": "A GUID value that each recommendation object is associated with.",

Suggestion: "format": "uuid"

arm-web/2016-03-01/Recommendations.json, line 2810 at r3 (raw file):

        },
        "resourceScope": {
          "description": "Name of a resource type this recommendation applies, e.g. Subscription, ServerFarm, Site.",

Recommendation: provide enum for possible types of resource scope

arm-web/2016-03-01/Recommendations.json, line 2822 at r3 (raw file):

        },
        "message": {
          "description": "Localized text of recommendation, good for UI.",

Since it's "localized": What determines which language this message is in? Might be helpful to say that in the description.

arm-web/2016-03-01/Recommendations.json, line 2865 at r3 (raw file):

        },
        "enabled": {
          "format": "int32",

Sounds like this should be a boolean.

arm-web/2016-03-01/Recommendations.json, line 2871 at r3 (raw file):

        "startTime": {
          "format": "date-time",
          "description": "The beginning time of a range that the recommendation refers to.",

Applies to all date-time properties here: Is this UTC? Does it make sense to state what it is in the description?

arm-web/2016-03-01/Recommendations.json, line 2914 at r3 (raw file):

        },
        "message": {
          "description": "Localized name of the rule (Good for UI)",

same as above: We're curious how this is localized, the user might wonder too.

arm-web/2016-03-01/Recommendations.json, line 2926 at r3 (raw file):

        },
        "actionName": {
          "description": "Name of action that is recommended by this rule in string",

"in string"? Confusing.

arm-web/2016-03-01/Recommendations.json, line 2932 at r3 (raw file):

          "format": "int32",
          "description": "On/off flag indicating the rule is currently enabled or disabled.",
          "type": "integer"

use boolean

arm-web/2016-03-01/Recommendations.json, line 4425 at r3 (raw file):

      "name": "subscriptionId",
      "in": "path",
      "description": "Subscription Id",

Maybe have something more meaningful here, e.g.
"description": "Subscription identifier for the Microsoft Azure subscription."

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 40 unresolved discussions.

arm-web/2015-04-01/Domains.json, line 2523 at r3 (raw file):

        "domainType": {
          "description": "Domain type.",
          "enum": [

Can you provide in the description what is the difference between Regular and SoftDeleted domain types.

arm-web/2015-04-01/Domains.json, line 2539 at r3 (raw file):

      "type": "object",
      "properties": {
        "value": {

value should be required.
"required": [ "value" ].
This will help us in validating the examples.

arm-web/2015-04-01/Domains.json, line 2552 at r3 (raw file):

      }
    },
    "DomainControlCenterSsoRequest": {

Which properties are required in DomainControlCenterSsoRequest?

arm-web/2015-04-01/Domains.json, line 3164 at r3 (raw file):

      "type": "object",
      "properties": {
        "value": {

value is a required property

Comments from Reviewable

  "type": "object",

missing description

Refers to: arm-web/2015-04-01/Domains.json:3036 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

  "properties": {

please describe the required properties of the response model definition if any.

Refers to: arm-web/2015-04-01/Domains.json:2555 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "value": {

value should be a required property

Refers to: arm-web/2015-04-01/Domains.json:3164 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "id": {

is id a required property?

Refers to: arm-web/2015-04-01/Domains.json:3038 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

"AppServiceEnvironment": {

The model is not used anywhere in this spec. Can this be removed from here?

Refers to: arm-web/2015-04-01/Domains.json:952 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "name": {

name, location, provisioningState are properties defined in the Resource model. This model is inheriting from the Resource.Then why do you need to redefine them again in the child class. This is invalid.

Refers to: arm-web/2015-04-01/Domains.json:970 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

"AppServicePlan": {

This model is not being used in the spec. Can you please make sure to delete the models that are not being used in the spec?

Refers to: arm-web/2015-04-01/Domains.json:1176 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 42 unresolved discussions.

arm-web/2016-09-01/AppServiceEnvironments.json, line 969 at r3 (raw file):

            "in": "query",
            "description": "Return only usages/metrics specified in the filter. Filter conforms to odata syntax. Example: $filter=(name.value eq 'Metric1' or name.value eq 'Metric2') and startTime eq '2014-01-01T00:00:00Z' and endTime eq '2014-12-31T23:59:59Z' and timeGrain eq duration'[Hour|Minute|Day]'.",
            "x-ms-skip-url-encoding": true,

Odata filter is supposed to be encoded. It's invalid URL otherwise.

arm-web/2016-09-01/AppServiceEnvironments.json, line 1135 at r3 (raw file):

      }
    },
    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/hostingEnvironments/{name}/operations/{operationId}": {

Long running operation polling APIs shouldn't be exposed

Comments from Reviewable

    "name"

Why is the name required? name should be readOnly: true. The service should get the name of the Resource from the path parameter. There is no reason to make the customer pass the same name in body.

Refers to: arm-web/2015-04-01/Domains.json:3414 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "name": {

This object has properties like name and provisioningState. These properties are present in the Resource and the object is inheriting from Resource. So why are they being redefined again in the child class?

Refers to: arm-web/2015-04-01/Domains.json:1191 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

@amarzavery @fearthecowboy
Looks like every single swagger has the entirety of the model definitions. And from Reviewable it looks like Amar has reviewed the definitions.
Therefore the minimal size of a web app swagger is 130k.

That is correct. However, I am still reviewing the definitions in domains.json Havent completed reiewing all of them yet. @naveedaz - Please make sure to only provide relevant models in that sub swagger spec of the composite model. Providing all of them in all the specs is not beneficial

Review status: 0 of 11 files reviewed at latest revision, 43 unresolved discussions.

arm-web/2016-09-01/AppServicePlans.json, line 29 at r3 (raw file):

            "name": "detailed",
            "in": "query",
            "description": "False to return a subset of App Service Plan properties, true to return all of the properties.\r\n            Retrieval of all properties may increase the API latency.",

Description has windows line endings (\r\n) + random spaces in it. This seem seem to be true for many description fields in this spec. Please correct.

Comments from Reviewable

Also many operations have the same "summary" and "description". In this case, providing only "description" should be sufficient and the best practice.

      "description": "If true then the list of agreements will inclue agreements for domain privacy as well.",

include - missing d

Refers to: arm-web/2015-04-01/TopLevelDomains.json:3817 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "name": {

duplicated property. name is defined in Resource.

Refers to: arm-web/2015-04-01/TopLevelDomains.json:3797 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

  "properties": {

are there any required properties in the TldLegalAgreement model?

Refers to: arm-web/2015-04-01/TopLevelDomains.json:3749 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

      "description": "Size Id of machines: \r\n            0 - Small\r\n            1 - Medium\r\n            2 - Large",

Why do you have \r in the description?

Refers to: arm-web/2015-04-01/TopLevelDomains.json:3699 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 44 unresolved discussions.

arm-web/2016-09-01/AppServicePlans.json, line 184 at r3 (raw file):

            "name": "allowPendingState",
            "in": "query",
            "description": "OBSOLETE: If true, allow pending state for App Service Plan",

Why include an obsolete query parameter? And if it supposed to be included, what is the default value?

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 50 unresolved discussions.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 242 at r3 (raw file):

        "summary": "Associates a Key Vault secret to a certificate store that will be used for storing the certificate once it's ready.",
        "description": "Associates a Key Vault secret to a certificate store that will be used for storing the certificate once it's ready.",
        "operationId": "AppServiceCertificateOrders_CreateOrUpdateCertificate",

The description doesn't sound like "createOrUpdate" a certificate. In fact, by calling this API I get a keyvault secret that is empty. Doesn't seem like "createOrUpdate" either.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 279 at r3 (raw file):

            "name": "keyVaultCertificate",
            "in": "body",
            "description": "Key Vault secret csm Id",

The description doesn't match the type AppServiceCertificate.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 562 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Object"

What does returning Object here mean?

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 733 at r3 (raw file):

        ],
        "summary": "Retrive email histor.",
        "description": "Retrive email histor.",

Retrieve email history.

arm-web/2016-09-01/AppServiceEnvironments.json, line 52 at r3 (raw file):

        ],
        "summary": "Get all hostingEnvironments (App Service Environments) in a resource group.",
        "description": "Get all hostingEnvironments (App Service Environments) in a resource group.",

Is the name hostingEnvironments still a branded name?

arm-web/2016-09-01/AppServiceEnvironments.json, line 211 at r3 (raw file):

          "AppServiceEnvironments"
        ],
        "summary": "Delete a AppServiceEnvironment (App Service Environment).",

Seems redundant to me. And everywhere else.

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 51 unresolved discussions.

arm-web/2016-09-01/AppServicePlans.json, line 250 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Object"

Why do you return an empty object here?

Comments from Reviewable

@amarzavery TldLegalAgreement is doesn't have create or update. So technically it's read-only.

I see. However, it would be nice if the service team can specify the required properties on a model that is used only in the response definition. This will help us in the new tool that we are building to validate data against the schema specified in swagger. In that way the tool can throw if the example  is incorrect.
From: Jianghao Lu<EMAIL_ADDRESS>Sent: Wednesday, November 9, 2016 5:49 PM
To: Azure/azure-rest-api-specs<EMAIL_ADDRESS>Cc: Amar Zavery<EMAIL_ADDRESS>Mention<EMAIL_ADDRESS>Subject: Re: [Azure/azure-rest-api-specs] Specify mutability and default values for models. Fix descriptions for web apps (#669)
@amarzaveryhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Famarzavery&data=01|01|amzavery%40microsoft.com|c16dff5732a84274be7308d4090bae05|72f988bf86f141af91ab2d7cd011db47|1&sdata=m%2BSN9bxFlCgTta%2B67bJhp4YUb31rZDE9xUWVDxo05wg%3D&reserved=0 TldLegalAgreement is doesn't have create or update. So technically it's read-only.
—
You are receiving this because you were mentioned.
Reply to this email directly, view it on GitHubhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2FAzure%2Fazure-rest-api-specs%2Fpull%2F669%23issuecomment-259580246&data=01|01|amzavery%40microsoft.com|c16dff5732a84274be7308d4090bae05|72f988bf86f141af91ab2d7cd011db47|1&sdata=6Pm2gJfkc6RGhIaq12Oh%2Fq65MaZhoFLWfa%2BMjTd79RI%3D&reserved=0, or mute the threadhttps://na01.safelinks.protection.outlook.com/?url=https%3A%2F%2Fgithub.com%2Fnotifications%2Funsubscribe-auth%2FAET9B2eaNeP2CzlxqBsaqLryNNIuZDcpks5q8nfwgaJpZM4KpDVB&data=01|01|amzavery%40microsoft.com|c16dff5732a84274be7308d4090bae05|72f988bf86f141af91ab2d7cd011db47|1&sdata=AGVXYKHcUVYRmkQRiz4MPva9dTqxOKf7yuvPzNU1idw%3D&reserved=0.

    "level": {

is level a required property of FileSystemApplicationLogsConfig? If not then what is the default value? What happens when the client does not provide a value for this?

Refers to: arm-web/2015-04-01/Domains.json:2670 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

      "description": "Maximum size in megabytes that http log files can use.\r\n            When reached old log files will be removed to make space for new ones.\r\n            Value can range between 25 and 100.",

make sure to not use \r in the description

Refers to: arm-web/2015-04-01/Domains.json:2693 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "retentionInMb": {

what are the required properties of this model? What happens if enabled is not provided? Seems like enabled would have a default value of false if it is an optional property

Refers to: arm-web/2015-04-01/Domains.json:2691 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "name": {

name should come from Resource. No need to redefine it again.

Refers to: arm-web/2015-04-01/Domains.json:2719 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 54 unresolved discussions.

arm-web/2016-09-01/AppServicePlans.json, line 370 at r3 (raw file):

          "AppServicePlans"
        ],
        "summary": "Updates an existing Service Bus Hybrid Connection in use on this App Service Plan. This will fail if the Hybrid Connection does not already exist.",

This is an odd constraint for a PUT operation. Can you please verify that it actually is true?

arm-web/2016-09-01/AppServicePlans.json, line 492 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Object"

Please remove all spurious references to #/definitions/Object

arm-web/2016-09-01/AppServicePlans.json, line 661 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Object"

See above. For this, I'm very surprised that a GET operation would return an object.

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 55 unresolved discussions.

arm-web/2016-09-01/AppServicePlans.json, line 856 at r3 (raw file):

            "name": "operationId",
            "in": "path",
            "description": "Id of Server farm operation\">",

> ?

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 56 unresolved discussions.

arm-web/2016-09-01/AppServicePlans.json, line 959 at r3 (raw file):

          },
          {
            "name": "$skipToken",

How can the user retrieve the skipToken value?

Comments from Reviewable

    "level": {

looks like level will have a default value if it is optional. Should sasUrl be a required property?

Refers to: arm-web/2015-04-01/Domains.json:1468 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 57 unresolved discussions.

arm-web/2016-09-01/AppServicePlans.json, line 1553 at r3 (raw file):

            "required": true,
            "schema": {
              "$ref": "#/definitions/VnetRoute"

the #/definitions/VnetRoute model has one or more required parameter. A body parameter for a PATCH operation should not have (top level) required parameters.

Comments from Reviewable

    "sasUrl": {

is sasUrl a required property?

Refers to: arm-web/2015-04-01/Domains.json:1434 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "retentionInDays": {

What is the default value for this if  it is not provided, otherwise this should be required.

Refers to: arm-web/2015-04-01/Domains.json:1438 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 58 unresolved discussions.

arm-web/2016-09-01/AppServicePlans.json, line 1574 at r3 (raw file):

          },
          "404": {
            "description": "Route not found. This will only occur when using the PATCH verb."

Not sure I understand the constraint - this is the documentation for a PATCH operation, so why do we say that this will only occur when using the PATCH verb? That will always be the case for this operation?

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 59 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 1538 at r3 (raw file):

              }
            },
            "pfxBlob": {

Is pfxBlob required for PUT operations? What is the format (presumably BASE64 encoded)? Is the password really the only required property?

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 60 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 1573 at r3 (raw file):

              "type": "string",
              "x-ms-mutability": [
                "create"

Can't I update the password?

Comments from Reviewable

  "properties": {

any required properties over here?

Refers to: arm-web/2015-04-01/Domains.json:1311 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

  "properties": {

are there any required properties?

Refers to: arm-web/2016-08-01/WebApps.json:14274 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 62 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 295 at r3 (raw file):

      }
    },
    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/csrs": {

The operation_id should be Certificates_ListCsrsByResourceGroup. Or, probably better, Certificates_ListSigningRequestsByResourceGroup. If the latter is chosen, please also update the Certificates_GetCsr operation id.

arm-web/2016-03-01/Certificates.json, line 1557 at r3 (raw file):

              "readOnly": true
            },
            "issueDate": {

c

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 63 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 753 at r3 (raw file):

              "readOnly": true
            },
            "csr": {

Please update the name to something that is not an acronym.

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 64 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 540 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Csr"

The body parameter has one or more required properties (location and name). PATH body parameters should not have top-level required parameters.

Comments from Reviewable

Please add a swagger folder for all of your swagger specs as well...

@naveedaz - A general comment. Please make sure to accurately describe the required and readOnly properties of a model definition. I have seen enough model definitions that have all optional properties.By looking at them , intuition says that some of them are required. So please make sure that this aspect is accurately covered in the spec.

        "id": {

when you flatten this, id goes one level up. Plus there will be id from Resource as well. In languages that resolve allof as Composition, this will be a problem.
As the id will collide with the Resource's id.
Same goes for name.

Refers to: arm-web/2015-04-01/Domains.json:1501 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

  "description": "Description of a backup schedule. Describes how often should be the backup performed and what should be the retention policy.",

either all the properties of this object should have default values documented or they should be required. What happens if one of them is not provided? Does the server send back a 400 or applies a default?

Refers to: arm-web/2015-04-01/Domains.json:1602 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

  "properties": {

any required properties over here?

Refers to: arm-web/2015-04-01/Domains.json:1646 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "pfxBlob": {

should the format be base64url ?

Refers to: arm-web/2015-04-01/Domains.json:1693 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "password": {

isnt it possible to update the password?

Refers to: arm-web/2015-04-01/Domains.json:1724 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

          "type": "string"

format should be byte?

Refers to: arm-web/2015-04-01/Domains.json:1743 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "serverFarmId": {

is this readOnly too?  If not then is it required?

Refers to: arm-web/2015-04-01/Domains.json:1777 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

          "type": "string",

format: byte ?

Refers to: arm-web/2015-04-01/Domains.json:1843 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "name": {

shouldnt the name be coming from Resource?

Refers to: arm-web/2015-04-01/Domains.json:1863 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "correlationId": {

should correlationId be readOnly ?

Refers to: arm-web/2015-04-01/Domains.json:1880 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "configureLoadBalancing": {

default: false ?

Refers to: arm-web/2015-04-01/Domains.json:1911 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "trafficManagerProfileId": {

is trafficManagerProfileId and trafficManagerProfileName required or readOnly?

Refers to: arm-web/2015-04-01/Domains.json:1915 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "description": "Additional web app properties to include in the reponse. By default, all properties are included.",

how should the user provide the list of properties? Is it comma separated or semiccoln separated string? Please document it.

Refers to: arm-web/2016-08-01/WebApps.json:70 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "description": "Additional web app properties included in the response",

same as above

Refers to: arm-web/2016-08-01/WebApps.json:182 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = True)

        "enabled": {

should be required or should have a default value.

Refers to: arm-web/2016-08-01/WebApps.json:14768 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "serverFarmId": {

is this readOnly ?

Refers to: arm-web/2016-08-01/WebApps.json:14801 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "serverFarmId": {

since the x-ms-mutability is not defined it seems this is updatable or should this be readOnly?
What happens if the serverFarmId is not provided? Will the server throw?

Refers to: arm-web/2016-08-01/WebApps.json:14801 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

@jianghaolu Yeah, we noticed the duplicates too. We extracted them out so we could focus on just the unique things in the swaggers we're looking at. Looks like @amarzavery has mentioned it already.

          "$ref": "#/definitions/Object"

What does this mean? Why would you ever want to return an Object in the response to a delete operation? What should the user do with it?

Refers to: arm-web/2016-08-01/WebApps.json:298 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "name"

name should not be required and it should be marked as readOnly: true. The name of the resource will be provided from the path.

Refers to: arm-web/2016-08-01/WebApps.json:14445 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 94 unresolved discussions.

arm-web/2016-03-01/ResourceProvider.json, line 5 at r3 (raw file):

  "info": {
    "version": "2016-03-01",
    "title": " API Swagger"

Three things:

something seems to be missing in front of " API Swagger"
"... API Swagger" is not a very intuitive title (and causes unintuitively named classes), maybe go with "...Client", i.e. "Resource Provider Client" in this case (applies to all swagger files)
provide a description  (applies to all swagger files)

arm-web/2016-03-01/ResourceProvider.json, line 40 at r3 (raw file):

      }
    },
    "/subscriptions/{subscriptionId}/providers/Microsoft.Web/checknameavailability": {

Do you have a guideline for casing? Looks inconsistent across different paths.

arm-web/2016-03-01/ResourceProvider.json, line 65 at r3 (raw file):

            "required": true,
            "schema": {
              "$ref": "#/definitions/ResourceNameAvailabilityRequest"

Consider parameter flattening ("x-ms-client-flattening": true), so users don't have to create this object.
Also: "required": true doesn't enforce that properties of that object are required, did you want that? If so, mark the properties of ResourceName... as required

arm-web/2016-03-01/ResourceProvider.json, line 89 at r3 (raw file):

        "summary": "Gets list of available geo regions",
        "description": "Gets list of available geo regions",
        "operationId": "GetSubscriptionGeoRegions",

Would GetGeoRegionsForSubscriptions be a more consistent name?

arm-web/2016-03-01/ResourceProvider.json, line 99 at r3 (raw file):

            "name": "sku",
            "in": "query",
            "description": "Filter only to regions that support this sku",

What are the possible values of this? Are there any restrictions? If so, maybe this is an enum.

arm-web/2016-03-01/ResourceProvider.json, line 139 at r3 (raw file):

            "in": "query",
            "description": "Hosting environment name",
            "required": true,

are there any restrictions for this?

regex?
min/max length?

Example:
"maxLength": 256,
"minLength": 1,
"pattern": "^[a-zA-Z0-9][a-zA-Z0-9_.-]*$"

(Same comment applies to legacy operation)

arm-web/2016-03-01/ResourceProvider.json, line 152 at r3 (raw file):

          "200": {
            "description": "OK",
            "schema": {

strange. Rather have no schema.
Also: How is failure indicated? Feels like there should be more responses.

arm-web/2016-03-01/ResourceProvider.json, line 163 at r3 (raw file):

        "summary": "Whether hosting environment name is available",
        "description": "Whether hosting environment name is available",
        "operationId": "IsHostingEnvironmentWithLegacyNameAvailable",

Is this operation still necessary?
If so, at least mark it as "deprecated": true

arm-web/2016-03-01/ResourceProvider.json, line 200 at r3 (raw file):

        "summary": "List premier add on offers",
        "description": "List premier add on offers",
        "operationId": "ListPremierAddOnOffers",

What does this operation do?
It takes no data, it returns no data.

arm-web/2016-03-01/ResourceProvider.json, line 250 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"

Is it returning those password properties in User? If so, should it? Smells funny.

arm-web/2016-03-01/ResourceProvider.json, line 291 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/User"

What exactly is returned here? Update the description accordingly ("OK" isn't that descriptive in general!)

arm-web/2016-03-01/ResourceProvider.json, line 301 at r3 (raw file):

        "summary": "Get skus",
        "description": "Get skus",
        "operationId": "ListSkus",

Takes no params, gives no results (Object is nonsense), no information on what "skus" are.

arm-web/2016-03-01/ResourceProvider.json, line 373 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Object"

get rid of Object. If it doesn't return anything, provide no schema

arm-web/2016-03-01/ResourceProvider.json, line 383 at r3 (raw file):

        "summary": "Validates if a resource can be created",
        "description": "Validates if a resource can be created",
        "operationId": "Validate",

Applies to other operations as well:
Is the missing noun intentional? I.e. do you want this operation to be bound to the service client instead of an operation group?
If yes, perfectly fine, just wondering whether intentional.

arm-web/2016-03-01/ResourceProvider.json, line 403 at r3 (raw file):

            "description": "Resource group",
            "required": true,
            "type": "string"

Applies to all other occurrences of resourceGroupName: Could be improved with restrictions (min/max length, regex)

arm-web/2016-03-01/ResourceProvider.json, line 411 at r3 (raw file):

            "required": true,
            "schema": {
              "$ref": "#/definitions/ValidateRequest"

This param is required but then no properties of the ValidateRequest are?

arm-web/2016-03-01/ResourceProvider.json, line 433 at r3 (raw file):

    "/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/validateMoveResources": {
      "post": {
        "summary": "Validate specified resources can be moved",

Do you mean "Validate whether ..."? What's the purpose of this method?
Even more, this method does not provide any meaningful result.

arm-web/2016-03-01/ResourceProvider.json, line 477 at r3 (raw file):

            "description": "OK",
            "schema": {
              "$ref": "#/definitions/Object"

Useless schema. How is validation error communicated?

arm-web/2016-03-01/ResourceProvider.json, line 1793 at r3 (raw file):

      "properties": {
        "targetResourceGroup": {
          "type": "string"

Applies to both properties:

description missing
can you give restrictions for those strings (min/max length, regex)?

arm-web/2016-03-01/ResourceProvider.json, line 3287 at r3 (raw file):

        },
        "reason": {
          "description": "Required if nameAvailable is false. 'Invalid' indicates the name provided does not match Azure WebApp service’s naming requirements. 'AlreadyExists' indicates that the name is already in use and is therefore unavailable.",

This should probably be an enum.

arm-web/2016-03-01/ResourceProvider.json, line 3291 at r3 (raw file):

        },
        "message": {
          "type": "string"

description missing

arm-web/2016-03-01/ResourceProvider.json, line 4054 at r3 (raw file):

    },
    "SourceControlCollection": {
      "description": "Collection of soure controls",

"soure" => "source"

arm-web/2016-03-01/ResourceProvider.json, line 4313 at r3 (raw file):

            "publishingPassword": {
              "description": "Password used for publishing",
              "type": "string"

Add "format": "password".
Same for next properties if they are secret.
How do those three publishingPassword... properties relate to each other?

arm-web/2016-03-01/ResourceProvider.json, line 4333 at r3 (raw file):

      "properties": {
        "serverFarmId": {
          "description": "ARM resource id of an app service plan that would host the web app",

Restrictions for this (and the other) strings?

arm-web/2016-03-01/ResourceProvider.json, line 4337 at r3 (raw file):

        },
        "skuName": {
          "description": "Name of the target SKU for the server farm",

Is this an enum?

arm-web/2016-03-01/ResourceProvider.json, line 4346 at r3 (raw file):

        "capacity": {
          "format": "int32",
          "description": "Target capacity of the server farm (number of VM's)",

min/max value?

arm-web/2016-03-01/ResourceProvider.json, line 4381 at r3 (raw file):

        "properties": {
          "$ref": "#/definitions/ValidateProperties",
          "description": "Properties of the resource to validate"

Consider using x-ms-client-flatten

arm-web/2016-03-01/ResourceProvider.json, line 4391 at r3 (raw file):

        "status": {
          "description": "Indicates the result of validation",
          "type": "string"

Could this be an enum?

arm-web/2016-03-01/ResourceProvider.json, line 4394 at r3 (raw file):

        },
        "error": {
          "$ref": "#/definitions/ValidateResponseError",

Your using this to provide errors through an 200 response? Consider using an error response code and a dedicated response object instead.

arm-web/2016-03-01/ResourceProvider.json, line 4405 at r3 (raw file):

        "code": {
          "description": "Validation error code",
          "type": "string"

Enum?

Comments from Reviewable

General notes:
we (@olydis, @dsgouda and myself) have completed initial review on :

Recommendations.json
ResourceProvider.json

As noted before, there are a lot of duplicated model objects that should be either in a separate file or only in the swagger that uses them.
We will follow up once updates are complete.

          "$ref": "#/definitions/Object"

makes no sense

Refers to: arm-web/2016-08-01/WebApps.json:413 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

  "properties": {

what are the required properties over here?
Does preserveVnet have a default value if it is not required?

Refers to: arm-web/2016-08-01/WebApps.json:12799 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "frequencyUnit": {

if this is not a required property then it should have a default value.
On that note, it looks like all the properties of this model should have some sort of default if the property is optional.
Question to ask to yourself as a spec Author: "What will the service do if the user does not provide that value?" If the service chooses a particular value then that is the default. If the service returns a 400 (bad request) then that is a required property.
Cases where the service internally creates/computes something if the user does not provide it. For example a storage account or a keyvault (just making up an example) then please provide that information in the description so the user is aware of it.

Refers to: arm-web/2016-08-01/WebApps.json:12348 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "blobName": {

wouldnt blobName be required as well? What happens if it is not provided?

Refers to: arm-web/2016-08-01/WebApps.json:14654 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "databases": {

From the description it seems this should be required as well. But it could be possible that if the property is not provided then the service does not perform the restore request. What do you think?

Refers to: arm-web/2016-08-01/WebApps.json:14666 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "ignoreConflictingHostNames": {

Looks like the service will choose a path A or path B while restoring based on the value provided over here which could have a significant impact on the outcome. Should this be required? If not then what is the default value?

Refers to: arm-web/2016-08-01/WebApps.json:14673 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "operationType": {

is Default the default ?

Refers to: arm-web/2016-08-01/WebApps.json:14677 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "databaseType": {

is there a default value for this or is it required ?

Refers to: arm-web/2016-08-01/WebApps.json:12951 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "connectionString": {

At minimum wouldnt you expect the customer to provide databaseType and connectionString ? (required properties)

Refers to: arm-web/2016-08-01/WebApps.json:12962 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "description": "Gets a backup of an app (or a deployment slot, if specified) by its ID.",

Incorrect description. The path does not contain a slot parameter. The old description was correct.

Refers to: arm-web/2016-08-01/WebApps.json:593 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "summary": "Deletes a backup of an app (or a deployment slot, if specified) by its ID.",

Incorrect description. Path does not contain a slot parameter.

Refers to: arm-web/2016-08-01/WebApps.json:644 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "summary": "Restores a specific backup to another app (or deployment slot, if specified).",

Incorrect description. slot is not a path parameter

Refers to: arm-web/2016-08-01/WebApps.json:765 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

          "type": "string"

are there any constraints on the name? regex?

Refers to: arm-web/2016-09-01/AppServicePlans.json:2125 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "workerTierName": {

should this string accept specific values? what would be an example of this string?

Refers to: arm-web/2016-09-01/AppServicePlans.json:2127 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "type": "boolean"

should this be an enum in case there are more than 2 values in the future?

Refers to: arm-web/2016-09-01/AppServicePlans.json:30 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "summary": "Updates the application settings of an app (or a deployment slot, if specified).",

Will it replace the existing settings with new one provided in the request? If yes, then please mention it in the doc.

Refers to: arm-web/2016-08-01/WebApps.json:833 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "operationId": "WebApps_UpdateApplicationSettingsSlot",

Will it replace the existing settings with new one provided in the request? If yes, then please mention it in the doc.

Refers to: arm-web/2016-08-01/WebApps.json:5296 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 96 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 694 at r3 (raw file):

              "enum": [
                "StandardDomainValidatedSsl",
                "StandardDomainValidatedWildCardSsl"

When I send this value, I get {"Code":"BadRequest","Message":"The parameter productType has an invalid value."...

Comments from Reviewable

    "name": {

description indicates it's read only, should this property be specified as "readOnly": true ?

Refers to: arm-web/2016-09-01/AppServicePlans.json:3826 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "type": {

description indicates it's read only, should this property be specified as "readOnly": true

Refers to: arm-web/2016-09-01/AppServicePlans.json:3830 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "description": "Updates the application settings of an app (or a deployment slot, if specified).",

When the description text says

"(or a deployment slot, if specified)"

Do you mean that if the slot is specified as a parameter? If that was the intention then please be more clear. Initially I thought that the method will work for the slot if I specify one. But couldnt find a way to provide slot. I hope you get what I am trying to say.
This could be  better written as

"(or a deployment slot, if the operation takes a slot parameter as an input)"

Refers to: arm-web/2016-08-01/WebApps.json:834 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "description": "Application settings of the app or deployment slot. See example.",

This is misleading too. Please find a better way to automate. Our goal is to make customer's life easy (for that it can make our life a little difficult) and not vice-versa.

Refers to: arm-web/2016-08-01/WebApps.json:865 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "tokenRefreshExtensionHours": {

This is an input to a PUT operation. PUT is essentially a replace of the previous copy. What would happen if the user had updated the authsettings previously to 96 hours. This property is not marked as required and the description says that the default is 72 hours. So the next time if the user updates the AuthSettings then will the Server retain the old 96 hours or update it to the default value of 72 hours?

default: 72.00 should be described.

One more thing. Since it is hours, shouldnt this be an integer. Are the decimal values based off 60 or 100 ? Providing an example in the description would help.

Refers to: arm-web/2016-08-01/WebApps.json:14988 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

      "description": "Gets or sets a value indicating whether to durably store platform-specific security tokens\r\n            obtained during login flows. This capability is disabled by default.",

Please remove the phrase Gets or sets...

Refers to: arm-web/2016-08-01/WebApps.json:14963 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "enabled": {

is it required or does it have a default?

Refers to: arm-web/2016-08-01/WebApps.json:14942 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "unauthenticatedClientAction": {

is it required or does it have a default?

Refers to: arm-web/2016-08-01/WebApps.json:14950 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "operationId": "WebApps_ListAuthSettings",

Shouldnt this be WebApps_GetAuthSettings, as you are returning one object? List is used whenever we return a collection.

Refers to: arm-web/2016-08-01/WebApps.json:1002 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "description": "Edited backup configuration. You should edit the JSON response from the POST action and use it as input here.",

You should can edit ...
which POST action are you referring to?

Refers to: arm-web/2016-08-01/WebApps.json:1079 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 97 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 1538 at r3 (raw file):
Previously, johanste (Johan Stenberg (MSFT)) wrote…
> Is pfxBlob required for PUT operations? What is the format (presumably BASE64 encoded)? Is the password really the only required property?

..and if it is BASE64 encoded, the format should be byte, no?

Comments from Reviewable

        "name": {

"x-ms-client-name": "BackupRequestName" to avoid collision

Refers to: arm-web/2016-08-01/WebApps.json:12298 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "enabled": {

should this be required or is there a default value?

Refers to: arm-web/2016-08-01/WebApps.json:12302 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

  "required": [

Why is the type not required? What happens if the type is not provided? If not required then there should be a default, here

Refers to: arm-web/2016-08-01/WebApps.json:12759 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = True)

      "description": "Reason of the sku capability",

should this description provide more context on the property?

Refers to: arm-web/2016-09-01/AppServicePlans.json:2605 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "description": "Updates the connection strings of an app (or a deployment slot, if specified).",

Will this add or replace the dictionary.Please specify that

Refers to: arm-web/2016-08-01/WebApps.json:1200 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

  "description": "Description of a Sku Capability",

Is this description appropriate given that an array of "Capability" is returned by AppServicePlans_ListCapabilities? (is sku still applicable for that case?)
Should there be an extended description of what a Capability is?

Refers to: arm-web/2016-09-01/AppServicePlans.json:2593 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "operationId": "AppServicePlans_GetHybridConnection",

should this be AppServicePlans_GetServiceBusHybridConnection ?

Refers to: arm-web/2016-09-01/AppServicePlans.json:313 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

          "description": "The value of the Service Bus key. This is used to authenticate to Service Bus. In ARM this key will not be returned\r\n            normally, use the POST /listKeys API instead.",

remove \r\n

Refers to: arm-web/2016-09-01/AppServicePlans.json:3896 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

  "post": {

why is this a "post" and not a "get"?

Refers to: arm-web/2016-09-01/AppServicePlans.json:499 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "operationId": "AppServicePlans_ListHybridConnectionWebApps",

Should this be "AppServicePlans_LIstWebAppsByHybridConnection"?

Refers to: arm-web/2016-09-01/AppServicePlans.json:566 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

      "type": "string"

is there a regex for Time grain?

Refers to: arm-web/2016-09-01/AppServicePlans.json:3968 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

      "type": "string"

should retention follow any format?

Refers to: arm-web/2016-09-01/AppServicePlans.json:3972 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "level": {

required or should have a default

Refers to: arm-web/2016-08-01/WebApps.json:13519 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "summary": "Queries for App Serice Plan metrics",

Gets? Retrieves?

Refers to: arm-web/2016-09-01/AppServicePlans.json:767 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

      "format": "int32",

min/max constraints

Refers to: arm-web/2016-08-01/WebApps.json:13541 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "name": {

"x-ms-client-name": "geoRegionName"

Refers to: arm-web/2016-08-01/WebApps.json:13568 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "enabled": {

required or default?

Refers to: arm-web/2016-08-01/WebApps.json:13550 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "level": {

required or default?

Refers to: arm-web/2016-08-01/WebApps.json:12132 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "sasUrl": {

probably required ?

Refers to: arm-web/2016-08-01/WebApps.json:12147 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

  "properties": {

same comments w.r.t default values and requiredness of properties

Refers to: arm-web/2016-08-01/WebApps.json:12112 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

  "properties": {

anything required?

Refers to: arm-web/2016-08-01/WebApps.json:13836 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "enabled": {

only one property. Probably required or has a default ?

Refers to: arm-web/2016-08-01/WebApps.json:13460 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "summary": "Updates the metadata of an app (or a deployment slot, if specified).",

Please mention that this will replace stuff

Refers to: arm-web/2016-08-01/WebApps.json:1411 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

        "name": {

"x-ms-client-name": "username"

Refers to: arm-web/2016-08-01/WebApps.json:16135 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "summary": "Gets a server farm operation",

should it be referred to a server farm or App Service plan?

Refers to: arm-web/2016-09-01/AppServicePlans.json:828 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

        "description": "Id of Server farm operation\">",

remove ">

Refers to: arm-web/2016-09-01/AppServicePlans.json:856 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 106 unresolved discussions.

arm-web/2015-04-01/Domains.json, line 195 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> regex for resourceGroupName

What is the regex used by other RPs for resoruceGroupName? Since this is an ARM concept, I'd rather just reuse it.

Comments from Reviewable

@naveedaz - "pattern": "^[-\w\._\(\)]+$",`

        "routeType": {

should this be an enum?

Refers to: arm-web/2016-09-01/AppServicePlans.json:5665 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

          "description": "The type of route this is:\r\n            DEFAULT - By default, every web app has routes to the local address ranges specified by RFC1918\r\n            INHERITED - Routes inherited from the real Virtual Network routes\r\n            STATIC - Static route set on the web app only\r\n            \r\n            These values will be used for syncing a Web App's routes with those from a Virtual Network. This operation will clear all DEFAULT and INHERITED routes and replace them\r\n            with new INHERITED routes.",

remove \r\n

Refers to: arm-web/2016-09-01/AppServicePlans.json:5666 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

          "description": "The type of route this is:\r\n            DEFAULT - By default, every web app has routes to the local address ranges specified by RFC1918\r\n            INHERITED - Routes inherited from the real Virtual Network routes\r\n            STATIC - Static route set on the web app only\r\n            \r\n            These values will be used for syncing a Web App's routes with those from a Virtual Network. This operation will clear all DEFAULT and INHERITED routes and replace them\r\n            with new INHERITED routes.",

should "This operation..." be removed from the description? which operation is it referring to?

Refers to: arm-web/2016-09-01/AppServicePlans.json:5666 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "operationId": "AppServicePlans_ListtRoutesForVnet",

typo double 't' in List?

Refers to: arm-web/2016-09-01/AppServicePlans.json:1244 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

      "properties": {

What is the bear minimum that the user should provide over here?
name, publishingUserName and publishingPassword sounds reasonable to me. They shoould be required. What do you think?

Refers to: arm-web/2016-08-01/WebApps.json:16134 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

          "$ref": "#/definitions/Object"

what should be this object?

Refers to: arm-web/2016-09-01/AppServicePlans.json:1492 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

    "isPushEnabled": {

is this required?

Refers to: arm-web/2016-08-01/WebApps.json:14304 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

      "description": "Gets or sets a JSON string containing a list of tags that are whitelisted for use by the push registration endpoint.",

do you expect a stringified JSON array ?
How do the tags look like ? Is this an array of strings or array of objects where the object is a key-value pair? Please provide an example in the description.

Refers to: arm-web/2016-08-01/WebApps.json:14309 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

      "description": "[Optional] In auto ramp up scenario this is the step to to add/remove from {Microsoft.Web.Hosting.Administration.RampUpRule.ReroutePercentage} until it reaches \r\n            {Microsoft.Web.Hosting.Administration.RampUpRule.MinReroutePercentage} or {Microsoft.Web.Hosting.Administration.RampUpRule.MaxReroutePercentage}. Site metrics are checked every N minutes specificed in {Microsoft.Web.Hosting.Administration.RampUpRule.ChangeIntervalInMinutes}.\r\n            Custom decision algorithm can be provided in TiPCallback site extension which Url can be specified in {Microsoft.Web.Hosting.Administration.RampUpRule.ChangeDecisionCallbackUrl}",

Why do you have to callout that they are optional?

Refers to: arm-web/2016-08-01/WebApps.json:14337 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

    "allowedOrigins": {

is this a required property?

Refers to: arm-web/2016-08-01/WebApps.json:12754 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

      "description": "Name of the format. Valid values are: \r\n            FileZilla3\r\n            WebDeploy -- default\r\n            Ftp",

The description grammar and punctuation is incorrect

Refers to: arm-web/2016-08-01/WebApps.json:12768 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

      "description": "Name of the format. Valid values are: \r\n            FileZilla3\r\n            WebDeploy -- default\r\n            Ftp",

Looks like an enum candidate?

Refers to: arm-web/2016-08-01/WebApps.json:12768 in 172b998. [](commit_id = 172b998dd292a37b39b60d22d9609a425230b655, deletion_comment = False)

          "$ref": "#/definitions/VnetRoute"

VNetRoute is "allOf" Resource which has location and name as required properties, is this intentional for this patch operation?

Refers to: arm-web/2016-09-01/AppServicePlans.json:1553 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 111 unresolved discussions.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 1860 at r4 (raw file):

        "properties": {
          "description": "ARM envelope properties",
          "properties": {

This extra level of properties is incorrect.
a GET on an AppServiceCertificateOrder returns this:
"properties": {
  "certificates": {...},
  "distinguishedName": "CN=graph-webapp-319.com",
  "domainVerificationToken": "PyR5MJEr",
  "validityInYears": 1,
  "keySize": 2048,
  "productType": "StandardDomainValidatedSsl",
  "autoRenew": true,
  "provisioningState": "Succeeded",
  "status": "Issued",
  "signedCertificate": {
    "version": 3,
    "serialNumber": "0089280562049F418D",
    "thumbprint": "02409E2E1C2F15EBC6310C5B465A8C27A758A75C",
  }
}

where signedCertificate is a CertificateDetails.

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 111 unresolved discussions.

arm-web/2015-04-01/Domains.json, line 195 at r3 (raw file):
Previously, naveedaz (Naveed Aziz) wrote…
> What is the regex used by other RPs for resoruceGroupName? Since this is an ARM concept, I'd rather just reuse it.

Done.

arm-web/2015-04-01/Domains.json, line 285 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> Looks like copy paste error. Remove >

Done.

arm-web/2015-04-01/Domains.json, line 371 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> Creating or updating is a long running operation. However, delete isn't. Flagging out of curiosity.

Done.

arm-web/2015-04-01/Domains.json, line 385 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> missing description and summary. Please document more information about DomainOwnershipIdentifiers in the description rather than simply saying Lists blah blah.

Done.

arm-web/2015-04-01/Domains.json, line 395 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> parameter description missing for resourceGroupName and domainName. Plus also provide regex for resourcegroupName. On that note should domainName have a regex as well?

Done.

arm-web/2015-04-01/Domains.json, line 476 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> After looking at the CRUD pattern on DomainOwnershipIdentifier. I think the recommended patterns are:
> - DomainOwnershipIdentifier_CreateOrUpdate
> - Domains_CreateOrUpdateOwnershipIdentifier
>
> Ideal world: Domains_OwnershipIdentifiers_CreateOrUpdate (Autorest does not support multiple underscores right now)
>

Done.

arm-web/2015-04-01/Domains.json, line 512 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> RequestMessageEnvelope[DomainOwnershipIdentifier]. These kind of names are incorrect. Please fix swashbuckle plugin.
> Ideally, the input (body parameter) for a PUT operation and the output of PUT operation should be the same type. This enables GET | PUT pipeline scenario out of the box.
>

Done.

arm-web/2015-04-01/Domains.json, line 573 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> General comment: For all delete operations, this is incorrect. Please provide a proper schema in the response. Please remove Object from the model definition as it servers no purpose.
>
> Does the service return  a 204 ?

Done.

arm-web/2015-04-01/Domains.json, line 596 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> General comment: missing parameter descriptions.

Done.

arm-web/2015-04-01/Domains.json, line 3164 at r3 (raw file):
Previously, amarzavery (Amar Zavery) wrote…
> value is a required property

Done.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 349 at r3 (raw file):
Previously, jianghaolu (Jianghao Lu) wrote…
> This might have been reported by others. But returning Object on delete is not the best practice. It should either return the delete object in strong type or simply doesn't return anything.

Done.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 562 at r3 (raw file):
Previously, jianghaolu (Jianghao Lu) wrote…
> What does returning `Object` here mean?

Done.

arm-web/2016-03-01/Certificates.json, line 1573 at r3 (raw file):
Previously, johanste (Johan Stenberg (MSFT)) wrote…
> Can't I update the password?

You cannot update the password of an uploaded certificate. The password is tied to the certificate. To update the password you have to recreate the certificate, which would be an entirely new certificate.

Comments from Reviewable

          "$ref": "#/definitions/RequestMessageEnvelope[DomainOwnershipIdentifier]"

Malformed reference

Refers to: arm-web/2015-04-01/Domains.json:512 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 111 unresolved discussions.

arm-web/2016-03-01/ResourceProvider.json, line 373 at r3 (raw file):
Previously, olydis (Johannes Bader) wrote…
> get rid of `Object`. If it doesn't return anything, provide no schema

Done.

arm-web/2016-03-01/ResourceProvider.json, line 383 at r3 (raw file):
Previously, olydis (Johannes Bader) wrote…
> Applies to other operations as well:
> Is the missing noun intentional? I.e. do you want this operation to be bound to the service client instead of an operation group?
> If yes, perfectly fine, just wondering whether intentional.

Yes this is meant to be a the service client level. It applies to multiple resources across the service.

arm-web/2016-03-01/ResourceProvider.json, line 403 at r3 (raw file):
Previously, olydis (Johannes Bader) wrote…
> Applies to all other occurrences of `resourceGroupName`: Could be improved with restrictions (min/max length, regex)

Done.

arm-web/2016-03-01/ResourceProvider.json, line 433 at r3 (raw file):
Previously, olydis (Johannes Bader) wrote…
> Do you mean "Validate *whether* ..."? What's the purpose of this method? Do you have to call it before you move?
> Even more, this method does not provide any meaningful result.

The API returns a 200 when validation succeeds and a 4xx when it fails. Per ARM the validateMoveResources API is called before the moveResources API.
http://sharepoint/sites/AzureUX/Sparta/Shared%20Documents/Specs/Resource%20Move%20API.docx?web=1

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 112 unresolved discussions.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 269 at r4 (raw file):

        ],
        "responses": {
          "200": {

When live testing, I got a 201 in production.

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 114 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 1517 at r1 (raw file):

      }
    },
    "Certificate": {

A GET call returns me the following property bag:
"properties": {
  "friendlyName": "",
  "subjectName": "banana.graph-webapp-319.com,www.banana.graph-webapp-319.com",
  "hostNames": [
    "banana.graph-webapp-319.com",
    "www.banana.graph-webapp-319.com"
  ],
  "pfxBlob": null,
  "siteName": null,
  "selfLink": null,
  "issuer": "Go Daddy Secure Certificate Authority - G2",
  "issueDate": "2016-11-15T01:10:00+00:00",
  "expirationDate": "2017-11-15T01:10:00+00:00",
  "password": null,
  "thumbprint": "C118BC5FCC81561AFFD774BD8CE5DE5CD3C43205",
  "valid": null,
  "toDelete": null,
  "cerBlob": null,
  "publicKeyHash": null,
  "hostingEnvironment": null,
  "hostingEnvironmentProfile": null,
  "keyVaultId": "/subscriptions/0b1f6471-1bf0-4dda-aec3-cb9272f09590/resourcegroups/javacsmrg319/providers/microsoft.keyvault/vaults/bananagraphwebapp319com",
  "keyVaultSecretName": "bananagraphwebapp319com",
  "keyVaultSecretStatus": "Initialized",
  "webSpace": "javacsmrg319-WestUSwebspace",
  "serverFarmId": null,
  "tags": null
}

Looks like keyvault id and secret name are not exposed. These 2 are necessary for associating a web app with a purchased certificate.

Comments from Reviewable

    "produces": [],

Unnecessary empty elements. Please remove.

Refers to: arm-web/2016-03-01/Recommendations.json:70 in 7cf6afe. [](commit_id = 7cf6afe39de67475e53779a4fc4f2bb8109f86a1, deletion_comment = False)

    "consumes": [],

Unnecessary empty elements. Please remove.

Refers to: arm-web/2016-03-01/Recommendations.json:20 in 7cf6afe. [](commit_id = 7cf6afe39de67475e53779a4fc4f2bb8109f86a1, deletion_comment = False)

    "produces": [],

Unnecessary empty elements. Please remove.

Refers to: arm-web/2016-03-01/Recommendations.json:70 in 7cf6afe. [](commit_id = 7cf6afe39de67475e53779a4fc4f2bb8109f86a1, deletion_comment = False)

    "consumes": [],

Unnecessary empty elements. Please remove.

Refers to: arm-web/2016-03-01/Recommendations.json:94 in 7cf6afe. [](commit_id = 7cf6afe39de67475e53779a4fc4f2bb8109f86a1, deletion_comment = False)

    "consumes": [],

Unnecessary empty elements.
(I'll just say it once :D , but please remove empty elements)

Refers to: arm-web/2016-03-01/ResourceProvider.json:17 in 7cf6afe. [](commit_id = 7cf6afe39de67475e53779a4fc4f2bb8109f86a1, deletion_comment = False)

Review status: 0 of 11 files reviewed at latest revision, 114 unresolved discussions.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 269 at r4 (raw file):
Previously, jianghaolu (Jianghao Lu) wrote…
> When live testing, I got a 201 in production.

@naveedaz This blocks Azure management library for .NET and Java. Must be fixed by Wednesday, Nov 16.

arm-web/2016-03-01/Certificates.json, line 1517 at r1 (raw file):
Previously, jianghaolu (Jianghao Lu) wrote…
> A `GET` call returns me the following property bag:
> ```json
> "properties": {
>   "friendlyName": "",
>   "subjectName": "banana.graph-webapp-319.com,www.banana.graph-webapp-319.com",
>   "hostNames": [
>     "banana.graph-webapp-319.com",
>     "www.banana.graph-webapp-319.com"
>   ],
>   "pfxBlob": null,
>   "siteName": null,
>   "selfLink": null,
>   "issuer": "Go Daddy Secure Certificate Authority - G2",
>   "issueDate": "2016-11-15T01:10:00+00:00",
>   "expirationDate": "2017-11-15T01:10:00+00:00",
>   "password": null,
>   "thumbprint": "C118BC5FCC81561AFFD774BD8CE5DE5CD3C43205",
>   "valid": null,
>   "toDelete": null,
>   "cerBlob": null,
>   "publicKeyHash": null,
>   "hostingEnvironment": null,
>   "hostingEnvironmentProfile": null,
>   "keyVaultId": "/subscriptions/0b1f6471-1bf0-4dda-aec3-cb9272f09590/resourcegroups/javacsmrg319/providers/microsoft.keyvault/vaults/bananagraphwebapp319com",
>   "keyVaultSecretName": "bananagraphwebapp319com",
>   "keyVaultSecretStatus": "Initialized",
>   "webSpace": "javacsmrg319-WestUSwebspace",
>   "serverFarmId": null,
>   "tags": null
> }
> ```
> Looks like keyvault id and secret name are not exposed. These 2 are necessary for associating a web app with a purchased certificate.

@naveedaz This blocks Azure management library for .NET and Java. Must be fixed by Wednesday, Nov 16.

arm-web/2016-03-01/Certificates.json, line 694 at r3 (raw file):
Previously, jianghaolu (Jianghao Lu) wrote…
> When I send this value, I get {"Code":"BadRequest","Message":"The parameter productType has an invalid value."...

@naveedaz This blocks Azure management library for .NET and Java. Must be fixed by Wednesday, Nov 16.

Comments from Reviewable

@naveedaz I marked 3 items that are critical for .NET and Java management libraries. We are planning for code complete by November 18 (Friday).

Review status: 0 of 11 files reviewed at latest revision, 114 unresolved discussions.

arm-web/2015-08-01/AppServiceCertificateOrders.json, line 269 at r4 (raw file):
Previously, jianghaolu (Jianghao Lu) wrote…
> @naveedaz This blocks Azure management library for .NET and Java. Must be fixed by Wednesday, Nov 16.

Done.

arm-web/2016-03-01/ResourceProvider.json, line 477 at r3 (raw file):
Previously, olydis (Johannes Bader) wrote…
> Useless schema. How is validation error communicated?

Done.

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 114 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 694 at r3 (raw file):
Previously, jianghaolu (Jianghao Lu) wrote…
> @naveedaz This blocks Azure management library for .NET and Java. Must be fixed by Wednesday, Nov 16.

The wild card ssl certificate needs to actually start with *. Spoke to Jianghao offline. This is not a blocker.

Comments from Reviewable

Review status: 0 of 11 files reviewed at latest revision, 114 unresolved discussions.

arm-web/2016-03-01/Certificates.json, line 694 at r3 (raw file):
Previously, naveedaz (Naveed Aziz) wrote…
> The wild card ssl certificate needs to actually start with *. Spoke to Jianghao offline. This is not a blocker.

Done.

Comments from Reviewable

No modification for Python

No modification for NodeJS

No modification for Ruby

arm-web/2016-08-01/WebApps.json, line 11744 at r5 (raw file):

      "type": "object",
      "properties": {
        "ownershipId": {

The actual payload:
PUT https://management.azure.com/subscriptions/0b1f6471-1bf0-4dda-aec3-cb9272f09590/resourceGroups/javacsmrg319/providers/Microsoft.Web/sites/banana-webapp-319/domainOwnershipIdentifiers/watermeloncert?api-version=2016-08-01
{"properties":{"id":"M9hUCzKC"}}
Response:
{
  "id": "/subscriptions/0b1f6471-1bf0-4dda-aec3-cb9272f09590/resourceGroups/javacsmrg319/providers/Microsoft.Web/sites/banana-webapp-319/domainOwnershipIdentifiers/watermeloncert",
  "name": "banana-webapp-319/watermeloncert",
  "type": "Microsoft.Web/sites/domainOwnershipIdentifiers",
  "location": "West US",
  "tags": null,
  "properties": {
    "id": "M9hUCzKC"
  }
}

Comments from Reviewable

arm-web/2016-03-01/TopLevelDomains.json, line 1903 at r1 (raw file):

              "description": "If true then domain privacy is enabled for this domain",
              "type": "boolean",
              "readOnly": true

Regression: Setting this is how users turn on domain privacy.

Comments from Reviewable

Also, x-ms-parameter-location is missing for resourceGroupName parameter.

  "properties": {

(fixing -- read only properties for this response object)

In reply to: 259567949 [](ancestors = 259567949)

Refers to: arm-web/2016-03-01/Domains.json:2555 in 58a178c. [](commit_id = 58a178cd407d24f940daa3c27eae5bdee3d06c09, deletion_comment = False)


💲[Native Checkout] Reward -> Pledge Transition Feature

📲 What
Feature branch collecting the PR's for the Reward -> Pledge transition animation.
👀 Changelog
#740 Refactor RewardCell to RewardCardView
Refactored RewardCell into RewardCell, RewardCardContainerView, RewardCardView.
#734 - Reward->Pledge Transition Plumbing
The initial plumbing for the transition from RewardCollectionViewController to PledgeViewController.

 Reward Screen to Pledge Screen Animation

This intermediate branch is no longer needed since #741 was reapplied on the feature branch.


Cannot get expression from valueQuantity

Describe the bug
While trying to fetch data from Observation entity - valueQuantity, from data generated via synthea - using databricks - I do receive error
Libraries:
au.csiro.pathling:library-api:6.3.1
latest pathling installed using pypi
IllegalArgumentException: requirement failed: All input types must be the same except nullable, containsNull, valueContainsNull flags. The expression is: if ((NOT instanceof(assertnotnull(input[0, org.hl7.fhir.r4.model.Observation, true]).getValue, class org.hl7.fhir.r4.model.Quantity) OR isnull(objectcast(assertnotnull(input[0, org.hl7.fhir.r4.model.Observation, true]).getValue, ObjectType(class org.hl7.fhir.r4.model.Quantity))))) null else named_struct(value, staticinvoke(class org.apache.spark.sql.types.Decimal, DecimalType(32,6), apply, if (instanceof(assertnotnull(input[0, org.hl7.fhir.r4.model.Observation, true]).getValue, class org.hl7.fhir.r4.model.Quantity)) objectcast(assertnotnull(input[0, org.hl7.fhir.r4.model.Observation, true]).getValue, ObjectType(class org.hl7.fhir.r4.model.Quantity)) else null.getValueElement.getValue, true, true, true)). The input types found are
StructType(StructField(id,StringType,true),StructField(value,DecimalType(32,6),true),StructField(value_scale,IntegerType,true),StructField(comparator,StringType,true),StructField(unit,StringType,true),StructField(system,StringType,true),StructField(code,StringType,true),StructField(_value_canonicalized,StructType(StructField(value,DecimalType(38,0),true),StructField(scale,IntegerType,true)),true),StructField(_code_canonicalized,StringType,true))
StructType(StructField(value,DecimalType(32,6),true)).
If I will remove "valueQuantity" - it works as expected
To Reproduce
Observation - To be checked quantities
observationfhir = json_resources.extract("Observation",
columns=[
exp("id", "Identifier"),
exp("status", "status"),
exp("category.first().coding.first().code", "category"),
exp("code.coding.code", "Observation_Code"),
exp("code.coding.display", "Observation_Name"),
exp("code.text", "Observation_Text"),
exp("subject.reference", "Subject_Reference"),
exp("encounter.reference", "Encounter_Reference"),
exp("valueQuantity.value","Value_Quantity")
]
)
observationfhir = observationfhir.withColumn('source',lit('payorq')).withColumn('sourceFile',lit(today)).withColumn('Value_Quantity', col('Value_Quantity').cast("string"))
display(observationfhir)
Expected behavior
values from FHIR files

Thanks @lakime, we have reproduced the issue and are working on a fix.

Probably it is wrong construct - as:
f```
rom pathling import PathlingContext, Expression as exp
from pyspark.sql.functions import split, explode, col, lit, expr, cast
from datetime import date
today = date.today()
pc = PathlingContext.create()
ndjson_dir = 'dbfs:/mnt/hda/raw/payorq/landing/'
json_resources = pc.read.ndjson(ndjson_dir)

I am able to fetch the data using sql query

`%sql
SELECT
  valueQuantity.value as Value_Quantity_Value,
  valueQuantity.unit as Value_Quantity_Unit,
FROM
  bronzeraw.observation;`

Hi @lakime,
We have done a bit of work to figure out what is happening here.
This is essentially caused by a bug in Spark, or an inability of Spark to deal with the expressions that we generate in certain scenarios. We're working on creating a bug report for this.
This behaviour is specific to reading data directly from a raw FHIR source, such as NDJSON or Bundles.
There are two workarounds, the first one is to simply cache the datasets involved in the query before running extract:
pc = PathlingContext.create()
ndjson_dir = 'dbfs:/mnt/hda/raw/payorq/landing/'
json_resources = pc.read.ndjson(ndjson_dir)

json_resources.read('Observation').cache()

observationfhir = json_resources.extract(  #...

The other workaround is to set the configuration parameter spark.sql.optimizer.nestedSchemaPruning.enabled to false.
Perhaps you could try this and let us know if this solves your problem?

Reported to spark as a bug: SPARK-45766


Submit Workbook button on Dashboard / Landing Page [unfinished ticket]

Why is this issue important?
starting point for report upload flow
Current State
none
Expected State
When user visits the [CPF Reporter URL], dashboard includes Submit Workbook button. Clicking on this page sends user to a Submit Workbook page on the webapp
Implementation Plan
No response
Relevant Code Snippets
No response

todo:
fill in CPF URL

waiting on upload flow to test that uploads show


GitHub registry

This PR replaces Docker Hub with the GitHub registry in the GitHub workflow and updates the used GitHub actions.
Needed for https://github.com/OpenTOSCA/opentosca-docker/pull/57

I guess here we have the same problem as for the container


"This video is unavailable" v2.6,9b4

Was using Vocard v2.6.8 when I originally had this issue but updated to latest beta v2.6.9b4 to see if that would fix it.

When using the /play command and selecting one of the songs I get "This video is unavailable [common]" for every song I try.
When using the /play command and entering in a spotify playlist I get "This video is unavailable! The next song will begin in the next 5 seconds.

This is on a fresh docker container install, with new spotify id, adjusting the password and the host for the lavalink server. Even tried using a non-self hosted lavalink server and still no luck. I am not self-hosting mongo as I am unsure of what to put as the name (url should be mongo:27017 since its locally hosted).
This just started a day ago using v2.6.8. Any advice would be appreciated.

This is lavalink issue. Make sure you're using the latest version of lavalink.

ghcr.io/azarath7/lavalink-jre22:latest
You can try to use my lavalink image

@Azarath7 Thank you your fork worked great!


docs: fix typo on Initial Query Data page

✍ Remove a small typo from the docs

Thanks!

Thanks!

:tada: This PR is included in version 3.5.12 :tada:
The release is available on:

npm package (@latest dist-tag)
GitHub release

Your semantic-release bot :package::rocket:

:tada: This PR is included in version 3.5.12 :tada:
The release is available on:

npm package (@latest dist-tag)
GitHub release

Your semantic-release bot :package::rocket:


Cubic Interpolation on lower bound

This is related to issue #971.
An issue with CubicInterp is that it previously did not work as expected for the lower bound of the range where the interpolation is defined. As an example:
from HARK.interpolation import CubicInterp
import numpy as np
f = lambda x: x**2
df = lambda x: 2*x
x = np.linspace(-1,1,5)
y = f(x)
dy = df(x)
interp = CubicInterp(x,y,dy)
interp(x)

Out[1]: array([ nan, 0.25, 0.  , 0.25, 1.  ])

Clearly, the first element should be 1.. This is fixed when you set lower_extrap=True.
interp = CubicInterp(x,y,dy, lower_extrap=True)
interp(x)

Out[2]: array([1.  , 0.25, 0.  , 0.25, 1.  ])

However, x=-1 is not extrapolation, as it is one of the data points given, so it should return a value without setting lower_extrap=True.
A previous attempt to resolving this was the following line in `CubicInterp':
#972
...
y[x == self.x_list.min()] = self.y_list.min()
...

but this only works for a particular set of cases. A better solution is
#1008
...
y[x == self.x_list[0]] = self.y_list[0]
...

interp = CubicInterp(x,y,dy)
interp(x)

Out[2]: array([1.  , 0.25, 0.  , 0.25, 1.  ])

which explicitly plugs in the lower bound. At some point, this correction was overwritten again, so HARK code is back to #972.
Evidently, #972 does not break any tests, as it creeped back in without notice. The way I realized this is back on HARK is because it created a conflict on #1011.

For background, this was a known bug / intended behavior when I wrote the
original code. I intentionally didn't put the line y[x == self.x_list[0]] = self.y_list[0] because that's a really costly operation to fix a
knife-edge case. It can probably be fixed by changing the "sided-ness" of
the searchsorted operation that gets the segment (and then adjusting other
parts of the algorithm).
On Thu, Aug 19, 2021 at 1:39 PM alanlujan91 @.***>
wrote:

This is related to issue #971
https://github.com/econ-ark/HARK/issues/971.
An issue with CubicInterp is that it previously did not work as expected
for the lower bound of the range where the interpolation is defined. As an
example:
from HARK.interpolation import CubicInterp
import numpy as np
f = lambda x: x**2
df = lambda x: 2*x
x = np.linspace(-1,1,5)
y = f(x)
dy = df(x)
interp = CubicInterp(x,y,dy)
interp(x)
Out[1]: array([ nan, 0.25, 0.  , 0.25, 1.  ])
Clearly, the first element should be 1.. This is fixed when you set
lower_extrap=True.
interp = CubicInterp(x,y,dy, lower_extrap=True)
interp(x)
Out[2]: array([1.  , 0.25, 0.  , 0.25, 1.  ])
However, x=-1 is not extrapolation, as it is one of the data points
given, so it should return a value without setting lower_extrap=True.
A previous attempt to resolving this was the following line in
`CubicInterp':
#972 https://github.com/econ-ark/HARK/pull/972
...
y[x == self.x_list.min()] = self.y_list.min()
...
but this only works for a particular set of cases. A better solution is
#1008 https://github.com/econ-ark/HARK/pull/1008
...
y[x == self.x_list[0]] = self.y_list[0]
...
interp = CubicInterp(x,y,dy)
interp(x)
Out[2]: array([1.  , 0.25, 0.  , 0.25, 1.  ])
which explicitly plugs in the lower bound. At some point, this correction
was overwritten again, so HARK code is back to #972
https://github.com/econ-ark/HARK/pull/972.
Evidently, #972 https://github.com/econ-ark/HARK/pull/972 does not
break any tests, as it creeped back in without notice. The way I realized
this is back on HARK is because it created a conflict on #1011
https://github.com/econ-ark/HARK/pull/1011.
—
You are receiving this because you are subscribed to this thread.
Reply to this email directly, view it on GitHub
https://github.com/econ-ark/HARK/issues/1060, or unsubscribe
https://github.com/notifications/unsubscribe-auth/ADKRAFMKFVGGC5PWMK5UAKTT5U6T3ANCNFSM5COWFZPQ
.
Triage notifications on the go with GitHub Mobile for iOS
https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675
or Android
https://play.google.com/store/apps/details?id=com.github.android&utm_campaign=notification-email
.

Well, it needs to be fixed one way or another (I wasted a fair amount of time running it down a few months ago).
My preference would be just to substituting the scipy version universally.


onColorSelected prototype claims (color: HsvColor) arg, but it's actually (color: string)

The exported IPicker interface has HsvColor as argument for onColorSelected: onColorSelected: (selectedColor: HsvColor) => void;
But the argument is actually a string (tinycolor(...).toHexString()), which makes TypeScript sad. Will file a PR later this week.
Merry Christmas!

thanks

should be fixed in '0.5.0'


Add CBOR support

This resolves issue #22.

@dbohdan So, I can’t actually get pip-2.7 to install cbor2 on my machine. Does it work for you?

Yes, I can install it.  pip2 install cbor2 works for me in a virtualenv on x86_64 Ubuntu 19.10.
> virtualenv /tmp/venv
Running virtualenv with interpreter /usr/bin/python2
New python executable in /tmp/venv/bin/python2
Also creating executable in /tmp/venv/bin/python
Installing setuptools, pkg_resources, pip, wheel...done.
> . /tmp/venv/bin/activate.fish
(venv) > pip2 install cbor2
DEPRECATION: Python 2.7 reached the end of its life on January 1st, 2020. Please upgrade your Python as Python 2.7 is no longer maintained. A future version of pip will drop support for Python 2.7. More details about Python 2 support in pip, can be found at https://pip.pypa.io/en/latest/development/release-process/#python-2-support
Collecting cbor2
  Downloading cbor2-5.0.1.tar.gz (72 kB)
     |████████████████████████████████| 72 kB 245 kB/s
Building wheels for collected packages: cbor2
  Building wheel for cbor2 (setup.py) ... done
  Created wheel for cbor2: filename=cbor2-5.0.1-py2.py3-none-any.whl size=15814 sha256=68ef0c381e34099208989f4841943598102b17bb952d5ac6c432e3945e5417e5
  Stored in directory: /home/dbohdan/.cache/pip/wheels/e8/d5/8c/b721f3cf3d8593df19b7c356686b34c18eb4b3b26337ca1675
Successfully built cbor2
Installing collected packages: cbor2
Successfully installed cbor2-5.0.1

@dbohdan OK I have it passing Travis; I just skipped that test in Python 2. I hope that’s OK.
There’s an AppVeyor failure w/ Python 3.5; do you know what might be going on there?

All right!  This looks ready to merge.
I'm okay with skipping that test, too.  The Python 3.5 problem is due an outdated version of setuptools.  I'll either fix it or (temporarily?) disable Python 3.5 testing on Windows.

Merged to master.  Thanks for contributing this feature!  I'll test it a little manually with CBOR found in the wild and create a new PyPI release.


create a workflow class that implements the jobs from the queues data structure that we implemented.

not completed.
We may not do this, as we can use the workflow.
It may be nice to have a new dependency type so that the dependencies get automatically created
dependency:

fifo

dependency:

lifo

dependency:

random

would for example create a list of the nodes from the first to last or from last to first
random would just create a random order

queues is deprecated. should close


Support IBM Bluemix

File: machine/drivers/soft-layer.md, CC @gbarr01
IBM Softlayer has been migrated to IBM Bluemix.
It is not clear as to whether or not docker-machine supports IBM bluemix. Clarification would be nice even if the new product is not supported.

Closing this ticket due to its age, and the impending refactor. If you think this is in error, feel free to reopen. Thanks!


[UIE-87] Cleanup yarn package extensions config

Looking into some output of yarn install, it turns out .yarnrc.yml had a lot of packageExtensions configuration related to Create React App. Since #4080 removed CRA, we can also remove this config, which results in several unused packages being removed from yarn cache.

Good question. I'm not sure, especially since yarn scatters config between .yarnrc.yml and package.json (the resolutions field). I noticed this after looking into some warnings from yarn install, which we've possibly gotten conditioned to. I'm hoping that we can eventually whittle away these dependency overrides in .yarnrc.yml and package.json entirely.

Rebased to resolve merge conflict.