Most Azure services simply accept and return "application/json" bodies, and this is the recommended design (except for PATCH, which should be "application/merge-patch+json".

A few other media types are common and generally acceptable:

• "application/octet-stream", "text/plain", "text/csv"
• "multipart/form-data" when used alone (see below)

But there are cases where services define invalid content types or use valid types in a way that is not recommended:

• "" can only be used for the type or subtype -- not as a wildcard character. So "application/+json" is invalid (according to the BNF in RFC 6838) -- this comes from appconfiguration.json.
• "multipart/form-data" with any other content type. This is a problem because OAS2 does not allow both "form" and "body" parameters on a single operation.
• "text/json" -- commonly seen with "application/json". These are essentially the same thing, so no need to have both of them, especially in "produces"

We may want to decide on whether parameters should be allowed -- there are more than a few instances of ""application/json; charset=utf-8" in the current specs.

It's not helpful and potentially confusing to specify minLength, maxLength, etc on a string property/parameter that has more stringent validation properties. For example, a parameter or property that should contain an access token will be validated by AAD and determined to be valid or not. So we should recommend using minLength and maxLength only when there is not some more specific validation performed on the string.

A JSON response should always be an object to allow opportunity for new properties. But we need to allow type: string responses for other media types, e.g. text/plain.

Looks like the package name to install has become spectral-cli now.

OpenAPI v2 has a number of well-defined type/format combinations.

https://github.com/OAI/OpenAPI-Specification/blob/main/versions/2.0.md#data-types

and autorest recognizes several more.

https://github.com/Azure/autorest/blob/main/packages/libs/openapi/src/formats.ts

Anything outside of this should be flagged for discussion.

The readOnly rule categorizes schemas as "request" or "response" if they are reachable from an operation request or response body, respectively. But the current logic does not handle the OpenAPI 2 polymorphism pattern, where the parent schema does not reference child schemas directly -- instead, the child schema "allOf"s the parent into itself. As a result, the rule is generating false positives, such as in this PR.

the rules az-property-type looks has been defined for OAS2

the condition below is now outdated
given: $..properties[?(@object() && @.$ref == undefined && @.allOf == undefined)]

since OAS 3 new keywords has been introduced like oneOf and anyOf
so the rules need to be amended to

 given: $..properties[?(@object() && @.$ref == undefined && ( @.allOf == undefined  && @.oneOf == undefined && @.anyOf == undefined ))]

thanks for your job @markweitzel

In Azure Ruleset Readmen we talk about overriding the rule set. We should show an example here of how to do this.

If an operation is defined to accept multipart/form-data but only defines a single formData parameter, flag this and recommend to change to application/octet-stream and with a body parameter.

Especially for the stable folder

Add a rule that checks schema names for throw-away words such as "response" and "payload" and recommends dropping those words. Might need to check if recommended name is already present -- to avoid recommending a duplicate.

We could add some exceptions, e.g. ErrorResponse, since this generally won't show up in method signatures in the SDKs.

JSON path is not scoped to the field values of the response object in OAS3.
the first level is content
the second level can be any mime-type

$.paths[*][*].responses[?(@property >= 200 && @property < 300 && @property != 202  && @property != 204)].content[*]

Example:

{
    "openapi": "3.0.0",
    "paths": {
        "/endpoint": {
            "get": {
                "responses": {
                    "200": {
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/SuccessfulResponse"
                                }
                            }
                        },
                        "description": "Success"
                    }
                }
            }
        }
    }
}

AutoRest defines the x-ms-enum extension to add additional information, including descriptions for the values, for properties and parameters defined as enum.

Every enum should have an x-ms-enum extension and use it to provide descriptions for all the enum values.

Hi,

Thanks for providing this great repository,
my Question: Is there a reasoning for az-unique-parameter-names only being applied to OAS2 specs?
I'm trying to build a ruleset which ensures API Specs are within limitations of the API Management import, within which all parameters need to be unique for OAS3 as well.

The az-lro-headers rule that checks for a header named specifically "Operation-location" and issues a message when it is not present.

But the HTTP specification say that header names are case-insensitive, so "Operation-Location" and "operation-location" and even "oPERATION-lOCATION" should all be acceptable.

To enforce the guideline:

DO NOT use "x-" prefix for custom headers, unless the header already exists in production [RFC 6648].

The Azure API guidelines recommend:

☑️ YOU SHOULD support repeatable requests according as defined in OASIS Repeatable Requests Version 1.0.

This involves adding two header parameters, Repeatability-Request-ID and Repeatability-First-Sent, to an operation definition. Recently a service team did this (at our recommendation) but made a few mistakes in doing so.

• They specified x-ms-parameter-location: client on both parameters -- that is incorrect since the value of these headers should be set on each operation.
• They did not specify format: date-time on Repeatability-First-Sent.

We may also want to recommend format: uuid on `

The API guidelines also state:

When [the repeatability header is] understood, all endpoints co-located behind a DNS name MUST understand the header.

This might be another thing to check for.

given the rules az-property-type:

this generate false positive as it catches properties in examples .

use case beeing that i have an API with endpoints returning an object containing a field called
"properties" as part of the payload

for instance

examples:
 Dog:
      description: |
        Creation of a Zero Coupon scenario 
      value:
        type: GOOD_DOG
        properties:
          size: TALL
          legs:
            - id : 1

returns
warning az-property-type Property should have a defined type. components.examples.Dog.value.properties.legs

For client generation, we want to have only one type of object returned from an operation. In terms of the REST API, that means that all the success response codes (2XX) should have the same schema.

Comparing schemas for equality might be a little tricky, so we could simplify the logic somewhat:

• An operation cannot return 200/201 and 204
• We don't need to check 202 since az-lro-reponses-codes flags any 2XX for an operation that returns 202

Maybe we'll start with that.

The MS Docs guidelines forbid the use of html tags in documentation fields.

Do not put HTML tags in any of the documentation fields.

Hi,
i'm encountering an error using this ruleset with the spectral cli executable, whilst everything is working in the VSCode extension.

in my node.js setup the program is exiting with 'undefined' is not defined where i've tracked down to the ?(@.$ref === undefined) expression on L174

In VSCode this rule seems to be running just fine, even showing all found issues with the OAS.

If a schema with "properties" does not specify "type: object", then non-object types can validate successfully against this schema -- typically not what is desired.

Develop a linter rule that says that “if you have a property named etag, it should have format etag”. And probably that you shouldn’t have “etag” if the property name isn’t etag. And if you are a header named etag, I’d argue that we don’t need to specify format. But we could.

Path parameters should be type: string.

Leverage the VS Code snippet capability to show how to implement the rules in the style guide, e.g. error format, error code header, etc.

Some rules are not working for oas3 format API definitions.

• az-api-version-enum
• az-header-disallowed
• az-parameter-default-not-allowed

Sadly there are no oas3 tests for any of these rules so it's unclear whether they ever worked.

In all three cases, the problem appears to be caused by the "filter" in the "given". It is unclear why these "given"s work for oas2 and not for oas3.

The order of path parameters in an operation's parameter list should match the order of the parameters in the path template.

Create a spectral rule to integrate acrolinx for the info.description and the descriptions of the operations.

The Style Guide should be updated with guidelines for documenting the security schemes supported/required by the API.

And we should add some Spectral rules to enforce these guidelines.

The current linterForRule utility method attempts to construct a linter with just one rule enabled -- the rule under test. It uses the spectral ruleset migrator and logic "borrowed" from the Spectral CLI, which also does the conversion of yaml rulesets to the new "js" format. Unfortunately, the logic in linterForRule was simplified from the Spectral logic and does not seem to work with some features of JSONPath-Plus, in particular the @object() condition. We need to fix this going forward so that we can use these important features (and test them).

When a path parameter is a user-specified ID, it should be constrained to a specific set of characters.

YOU SHOULD restrict the characters allowed in user-specified path segments (i.e. path parameters values) to 0-9 A-Z a-z - . _ ~ (do not allow :).

Should also flag missing maxLength and maybe even minLength.

An operation that returns a 202 should not return any other success status code.

YOU SHOULD NOT return any other 2xx status code from the initial request of a status-monitor LRO -- return 202-Accepted and a status monitor URL even if processing was completed before the initiating request returns.

A common error is that date or date-time values do not have type: date or type: date-time specified. We should check for common names for date/date-time parameters and flag them if they are missing a format.

Other possibilities are "created" and "updated" and variants of these.

The pagination-response function currently only checks for the value and nextLink properties in the properties object of the response schema. But these properties could be defined in the children of an allOf in the response schema, so the code will need to nest down into the allOf to find the properties it is looking for.

And this will be complicated because it will also have to keep track of where it found those properties so it can set the paths correctly in any error messages that are issued.

It would be great to be able to run/debug test as your are authoring them on an actual OAPI file. To do this, we could pass in a URL to a file and then use that as the basis of the debug run.

Recently, we had an api review where one of the operations contained correlationId in the body. We could add info messages when we find that "header names" that appear in the body

We want services to use the new URL pattern for actions which has a bare ":" rather than "/:" preceding the action name.

The Style Guide currently recommends that "orderby", "select", and "expand" be defined as an array of strings.

https://github.com/Azure/azure-api-style-guide/blob/main/openapi-style-guide.md#support-for-pagination

This might be inconsistent with the current practice in Azure, as many services appear to define these simply as type: string.

We need to re-evaluate this guidance to make sure we do not inadvertently create more inconsistency.

As per the Guidelines, the ErrorResponse object must have an "error" property, while the Error object must have "code" and "message" properties. The az-error-response rule requires that these properties are marked as "required" in the swagger spec. However, my understanding is that all these properties must be marked as "readOnly", since they are only ever used in responses, and because of this, they cannot be simultaneously marked as "required" as per the OpenAPI specification 2.0.

The JSON schema additionalProperties is a potential source of confusion and error. Restricting its use to very specific applications might be a good style.

One possible restriction is to only allow additionalProperties when not a sibling of properties -- which is just a way of defining a map. This is a very common pattern in Azure:

        "tags": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          },
          "description": "Application specific metadata in the form of key-value pairs."
        }

• GET/PUT/PATCH on a path that ends in /{id} should return a schema named "resource"
• PUT/PATCH on a path that ends in /{id} should accept a schema named "resource"
• GET on path that ends in should return "ResourceList"

Ref:

• PutRequestResponseSchema

The Azure API Guidelines say:

⚠️ YOU SHOULD NOT return any other 2xx status code from the initial request of a status-monitor LRO

So we should add a rule that flags any operation that defines a 202 response and other 2XX responses. (ARM does this routinely but we want to avoid this practice in data plane APIs.

There are a few rules -- in particular the ones that use "advanced" JSON Path features -- that are not currently working in the VSCode extension because that extension has not been updated to use Spectral 6.0. Some specific rules that are not working correctly are:

• az-additional-properties-and-properties
• az-lro-extension

The rules do work correctly from the CLI.

It looks like there is an effort to get the Spectral VSCode plugin updated to v6:

stoplightio/vscode-spectral#107