This document lists the set of automated rules that can be validated against swagger spec by running OAV tool. This document also have some tips for the fix. Most of the time, the error information has the position of violations in swagger. If the error is internal error and doesn't have much meaningful information toward the fix, please create an issue here.
| Code | Id |
|---|---|
| UNUSED_DEFINITION |
Output Message: none.
Description: All the errors without error code are clarified as internal_error.
How to fix the violation: See the inner error details for the fix.
Output Message: Invalid Content-Type {0}. These are supported: {1}.
Description: The request/response doesn't have allowed content-type.
How to fix the violation: Fix the content-type as one of the supported values.
Output Message: Path parameter is defined but is not declared: {0}.
Description: It cannot find the declaration of this path parameter in operation.
How to fix the violation: Add the declaration or remove the definition of this parameter.
Output Message: Path parameter is declared but is not defined: {0}.
Description: It cannot find the definition of this path parameter.
How to fix the violation: Add the detail definition for this path parameter.
Output Message: Operation cannot have a body parameter and a formData parameter.
Description: Body parameter and formData parameter are mutually exclusive.
How to fix the violation: Remove one of these two parameters.
Output Message: Operation cannot have multiple body parameters.
Description: There're multiple body parameters defined for an operation.
How to fix the violation: Remove one of body parameter from this operation.
Output Message: Cannot have multiple operations with the same operationId: {0}.
Description: There're duplicated operation ids defined.
How to fix the violation: Rename one of the operation id.
Output Message: Equivalent path already exists: {0}.
Description: There're equivalent paths defined.
How to fix the violation: Remove one of the equivalent paths or rename it.
Output Message: Missing required property definition: {0}.
Description: Property indicated as required in "required" array for the model is missing its definition.
How to fix the violation: Verify that the properties included in the "required" array have all been defined in swagger.
Output Message: Missing required property: {0}.
Description: Property indicated as required according to OpenAPI 2.0 specification for this schema.
How to fix the violation: Adding this property to schema in swagger.
Output Message: Path parameter declaration cannot be empty: {0}.
Description: The definition for a path parameter is empty.
How to fix the violation: Add the detail definition or remove this parameter from path.
Output Message: Operation cannot have duplicate parameters: {0}.
Description: There're duplicated parameters defined for this operation.
How to fix the violation: Remove the duplicated parameter.
Output Message: Schema object inherits from itself: {0}.
Description: The definition references itself.
How to fix the violation: Break the circular definition reference.
Output Message: Missing required property definition: {0}.
Description: The definition of a required property is missing.
How to fix the violation: Add the definition for the required property.
Output Message: xxx | Invalid JSON Reference.
Description: The value of $ref is invalid.
How to fix the violation: Fix the $ref as per the error details.
Output Message: Value failed JSON Schema validation.
Description: The parameter value doesn't pass schema validation.
How to fix the violation: Look into the inner errors to fix the value.
Output Message: Value is required but was not provided.
Description: Missing required value in example or in traffic payload.
How to fix the violation: Add the required value in example or in traffic payload.
Output Message: Remote reference didn't compile successfully: {0}.
Description: The remote schema reference fails to load and compile.
How to fix the violation: It could be incorrect reference uri or network issue.
Output Message: Schema failed to validate against its parent schema, see inner errors for details.
Description: The schema fails to validate against its parent schema.
How to fix the violation: Fix the schema by comparing against parent schema.
Output Message: Schema failed to validate against its parent schema, see inner errors for details.
Description: The schema fails to validate against its parent schema.
How to fix the violation: Fix the schema by comparing against parent schema.
Output Message: Schema is not an object: {0}.
Description: The schema type is expected to be object.
How to fix the violation: Correct the schema type.
Output Message: {0} asynchronous task(s) have timed out after {1} ms.
Description: The operation fails by time out issue.
How to fix the violation: Retry.
Output Message: Validator was not able to read schema with uri: {0}.
Description: It fails to load the remote schema.
How to fix the violation: Fix the uri of remote schema or network issue.
Output Message: Reference could not be resolved: {0}.
Description: It fails to resolve the reference uri of a remote schema.
How to fix the violation: Fix the uri.
Output Message: Reference has not been resolved during compilation: {0}.
Description: It fails to resolve the reference.
How to fix the violation: Maybe need to fix the format of the reference.
Output Message: {0} must define at least one property if present.
Description: It force a type must have properties.
How to fix the violation: Add at least one property for this type.
Output Message: There is no validation function for format '{0}'.
Description: It doesn't support this format validation.
How to fix the violation: Use another format or raise an design issue.
Output Message: Each element of keyword '{0}' array must be a '{1}'.
Description: The value does not match the defined type.
How to fix the violation: Fix the value to match the type.
Output Message: Keyword '{0}' is not a valid RegExp pattern: {1}'.
Description: The value does not match the defined pattern.
How to fix the violation: Fix the value to match the pattern.
Output Message: Keyword '{0}' requires keyword '{1}'.
Description: Some keywords have dependent keywords which have to be defined as well.
How to fix the violation: Add the dependent keyword definition.
Output Message: Keyword '{0}' must be {1}.
Description: The value of keyword should be strictly correct.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the value.
Output Message: Keyword '{0}' is not expected to appear in the schema.
Description: The schema doesn't allow extra keywords.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and remove the keyword.
Output Message: Keyword '{0}' must be defined in strict mode'.
Description: The array items should have additionalItems defined in swagger.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the array items.
Output Message: Keyword '{0}' is expected to be of type '{1}'.
Description: The value of the keyword in swagger should be the specific type.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the value type of keyword.
Output Message: String does not match pattern {0}: {1}.
Description: The provided string doesn't match defined pattern.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the string value.
Output Message: String is too long ({0} chars), maximum {1}.
Description: The provided string is greater than maximum length.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the string value.
Output Message: String is too short ({0} chars), minimum {1}.
Description: The provided string is less than minimum length.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the string value.
Output Message: Dependency failed - key must exist: {0} (due to key: {1}).
Description: The dependency value is an array, the object should have all the values in the array defined as property.
How to fix the violation: Add the key {1} as property to the object.
Output Message: Too many properties defined ({0}), maximum {1}.
Description: The provided properties amount of a type is greater than the defined maximum properties amount.
How to fix the violation: Delete some properties to meet the maximum requirement.
Output Message: Too few properties defined ({0}), minimum {1}.
Description: The provided properties amount of a type is less than the defined minimum properties amount.
How to fix the violation: Add more properties to meet the minimum requirement.
Output Message: Value {0} is equal or greater than exclusive maximum {1}.
Description: The value provided is greater than or equal to the defined maximum value.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the value.
Output Message: Value {0} is greater than maximum {1}.
Description: The value provided is greater than the defined maximum value.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the value.
Output Message: Value {0} is equal or less than exclusive minimum {1}.
Description: The value provided is less than or equal to defined minimum value.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the value.
Output Message: Value {0} is not a multiple of {1}.
Description: The value provided isn't a multiple of defined value.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the value.
Output Message: Value {0} is less than minimum {1}.
Description: The value provided is less than the defined minimum value.
How to fix the violation: The error info has the position of swagger, look for the position in swagger and fix the value.
Output Message: Additional items not allowed.
Description: The size of array is more than the array items length in schema.
How to fix the violation: Make the size of array less than or equal to the array items length in schema.
Output Message: Array items are not unique (indexes {0} and {1}).
Description: Array items doesn't match the schema of uniqueItems = true.
How to fix the violation: Make array items unique.
Output Message: Array is too long ({0}), maximum {1}.
Description: Array items is too much.
How to fix the violation: Make array items less than maximum number.
Output Message: Array is too short ({0}), minimum {1}.
Description: Array items is too little.
How to fix the violation: Make array have at least minimum item.
Output Message: Data matches schema from 'not'.
Description: Data is valid for the schema but it should not be valid because the not keyword.
How to fix the violation: See inner errors for the detail issue and fix the data to not match the schema.
Output Message: Data is valid against more than one schema from 'oneOf'.
Description: Data is valid for more than one sub-schemas.
How to fix the violation: See inner errors for the detail issue and fix the data to match only one sub-schema.
Output Message: Data does not match any schemas from 'oneOf'.
Description: None of the sub-schemas passes the validation.
How to fix the violation: See inner errors for the detail issue.
Output Message: Data does not match any schemas from 'anyOf'.
Description: None of the sub-schemas passes the validation.
How to fix the violation: See inner errors for the detail issue.
Output Message: Found errors in validating the request for x-ms-example {0} in operation {1} or in validating request payload.
Description: Validate the request of each x-ms-example or traffic payload.
How to fix the violation: The request parameter defined in example or in traffic payload should match with the swagger spec.
Output Message: Following response status codes {0} for operation {1} were present in the swagger spec, however they were not present in x-ms-examples. Please provide them.
Description: All the response cases with different response code should have correspondent response defined in example.
How to fix the violation: Add them to example if they are not present.
Output Message: Invalid parameter ({0}): Value failed JSON Schema validation.
Description: There's error in the request parameter validation.
How to fix the violation: Check the inner errors for the fix solution.
Output Message: This operation does not have a defined {0} response code.
Description: The specified response code is not defined in example file or in traffic payload.
How to fix the violation: Add response code to default, or add response code definition in the swagger.
Output Message:Body is required in response but not provided
Description: Body schema is defined in swagger but body is not found in example or traffic.
How to fix the violation: Add response body.
Output Message: Additional properties not allowed:{0}.
Description: Additional property {0} defined in example or in traffic payload but not defined in swagger spec. It could be the property name does not match exactly.
How to fix the violation: The error info has the position of swagger. Look for the violation location of the swagger, ensure the property name specified in example or in traffic payload appears exact the same in the definition or remove this property from example or from traffic payload if it's not defined in swagger spec. Remind all the characters are case sensitive.
Output Message: Object didn't pass validation for format {0}:{1}.
Description: The format provided for the param {0} is {1} which is not allowed format.
How to fix the violation: The error info has the position of swagger. Look for the violation location of the swagger, correct the format of the param. e.g. error info containing params: [ 'int32', '2'] means the param type is int32, so the format should be number 2 instead of string '2'.
Output Message: Expected type {0} but found type {1}.
Description: The type provided for the property doesn't match to the defined type.
How to fix the violation: Correct the type defined in example file or in traffic payload. Sometimes this could be false positive when it peers with other errors which belongs to same parent ANY_OF_MISSING error or ONE_OF_MISSING error, in this case this error can be ignored and just fix other peer errors eventually this error will be cleared out automatically.
Output Message: Enum does not match case for:{0}.
Description: The enum value provided in example or in traffic payload doesn't match the case of an allowed value.
How to fix the violation: The error info has the position of swagger. Look for the violation location of the swagger, correct the value case in example or in traffic payload.
Output Message: Enum does not match for:{0}.
Description: The enum value provided in example or in traffic payload doesn't match an allowed value.
How to fix the violation: The error info has the position of swagger. Look for the violation location of the swagger, correct the value in example or in traffic payload.
Output Message: ReadOnly property {0}: {1}, cannot be sent in the request.
Description: The value of a readonly property is managed exclusively by the owning authority and cannot be supplied in request.
How to fix the violation: Remove the readonly property from the request parameters in example or in traffic payload.
Output Message: Missing required property: {0}.
Description: The property {0} is required and has to provide in request or response of example (or of traffic payload).
How to fix the violation: Provide the required property in example(or in traffic payload) or remove this property from the required list of the definition in swagger spec. Or add items property if the type is array.
Output Message: Discriminator value "{0}" not found.
Description: The property used as discriminator has a value {0} but it's not found in swagger spec.
How to fix the violation: Add the model that has the discriminator value or fix the discriminator value. The discriminator value could be specified by model name in definitions or by "x-ms-discriminator-value".
Output Message: The value of x-ms-dicriminator-value is not in the discriminator enum list: {0}.
Description: If a discriminator has an enum list, the x-ms-dicriminator-value must in the enum list.
How to fix the violation: Add the value into the enum list or correct the value.
Output Message: Missing discriminator in base model. This derived model has x-ms-dicriminator-value: {0}.
Description: x-ms-dicriminator-value is defined, but base model doesn't have discriminator field.
How to fix the violation: Check whether it needs. If needs, add discriminator field in base model.
Output Message: The property type of discriminator must be string: {0}.
Description: If a property is declared as discriminator, the property type must be string and nothing else.
How to fix the violation: Set the property type to string in swagger.
Output Message: discriminator must be a required property.
Description: The property used as discriminator must be a required property, otherwise it cannot be resolved correctly.
How to fix the violation: Set the property as required property in swagger.
Output Message: Response statusCode {0} for operation {1} has no response body provided in the example, however the response does have a "schema" defined in the swagger spec.
Description: It should have response body provided in example even empty when it has schema defined for this response in swagger.
How to fix the violation: Add the response body in example which could be empty value {}.
Output Message: In operation {0}, example for parameter {1}: {2} starts with a forward slash and the path template: {3} contains a forward slash before the parameter starts. This will cause double forward slashes in the request url. Thus making it incorrect. Please rectify the example.
Description: There's two forward slashes before this parameter.
How to fix the violation: Remove one of it from path or parameter.
Output Message: Could not find provider {0} in the cache.
Description: There's none matched resource provider in the cache.
How to fix the violation: Fix resource provider.
Output Message: Could not find any methods with verb {0} for api-version {1 }and provider {2} in the cache.
Output Message: Could not find exact api-version {0} for provider {1} in the cache.
Description: There's none api methods based on api-version and resource provider.
How to fix the violation: Fix api-version or resource provider.
Output Message: Could not find any methods with verb {0} for api-version {1 }and provider {2} in the cache.
Description: It fails to search for any matched api method based on verb, api-version and resource provider.
How to fix the violation: Fix the verb, api-version or resource provider.
Output Message: Could not find best match operation for verb {0} for api-version {1} and provider {2} in the cache.
Description: It fails to search for any matched operation based on verb, api-version, path and resource provider.
How to fix the violation: Fix the verb, api-version, path or resource provider.
Output Message: Could not find path from requestUrl: {0}.
Description: It fails to search for the matched path in swagger based on the HTTP url.
How to fix the violation: Fix the path.
Output Message: An error occurred while trying to search for potential operations: {0}.
Description: It fails to search for the matched operation in swagger based on the HTTP url and method.
How to fix the violation: Fix the url or http method.
Output Message: requestResponseObj cannot be null or undefined and must be of type "object" | Found errors {0} in the provided input {1}.
Description: The input request/response has issues when running live validation.
How to fix the violation: See inner detail errors toward the fix.
Output Message: Found multiple matching operations with operationIds {0} for request url {1} with HTTP Method {2}.
Description: There're duplicated operations defined with same operationId.
How to fix the violation: Make the operationId as unique across the swagger.
Output Message: The spec {0} has semantic validation errors.
Description: There're errors when run semantic validation against this spec.
How to fix the violation: See inner detail errors toward the fix.
Output Message: Response statusCode {0} for operation {1} has response body provided in the example, however the response does not have a "schema" defined in the swagger spec.
Description: Every type of response provided in example should have correspondent definition in swagger spec.
How to fix the violation: Add the missing schema definition in swagger spec.
Output Message: Response statusCode {0} for operation {1} is provided in exampleResponseValue, however it is not present in the swagger spec.
Description: Every type of response provided in example should have correspondent definition in swagger spec.
How to fix the violation: Add the missing status code definition in swagger spec or remove the unmatched status code part from example.
Output Message: Found errors in validating the response with statusCode {} ...
Description: Found errors when validate the response defined in example.
How to fix the violation: See inner details for the violations and fix.
Description: Error when preparing the request for validation.
How to fix the violation: Fix by the inner error details or raise an issue at oav.
Output Message: In operation {0}, parameter {1} is required in the swagger spec but is not present in the provided example parameter values.
Description: Required parameter is not provided in example.
How to fix the violation: Add the required parameter in example.
Description: Error happens when try to resolve the swagger.
How to fix the violation: See the inner error details for the fix.
Description: Error happens when try to parse the JSON.
How to fix the violation: See the inner error details for the fix.
Output Message: Definition is not used: {0}.
Description: There's none reference to this definition.
How to fix the violation: Remove this definition if it's not used.
Output Message: Secret property {0} cannot be sent in the response.
Description: The secret is not allowed to return in response when it's annotated with x-ms-secret:true.
How to fix the violation: Remove this secret value from the response in example or in traffic payload.
Output Message: Write-only property {0} is not allowed in the response.
Description: Write only property is not allowed to return in response when it's annotated with "x-ms-mutability": ["create", "update"].
How to fix the violation: Remove this property from the response in example or in traffic payload.
Output Message: The property’s value in the GET response is different from what was set in the preceding PUT request. If it is a read-only property, update the swagger definition for this property to mark it as "readOnly": true. Alternatively, keep the property in the GET schema but remove it from the PUT schema. If it is immutable (its value cannot be changed after creation), update the swagger definition for this property to mark it with the "x-ms-mutability": ["create", "read"] annotation. If the property has a default value, update the Swagger definition for this property to mark it with "default": annotation.
Description: The property’s value in the GET response is different from what was set in the preceding PUT request. This usually happens when the property is read-only so its value cannot be set by users, or its value can be set in the initial PUT request but cannot be updated afterwards. It is also possible that the property has a default value, and it is set to that value when a null value is included in the PUT request. There are some other cases where ROUNDTRIP_INCONSISTENT_PROPERTY is raised but cannot be fixed in swagger, for which you might need to send exception requests (please refer to the How to fix the violation section section below for more details).
How to fix the violation:
- Check if the property is read-only. If yes, update the swagger definition for this property to mark it as "readOnly": true. Alternatively, keep the property in the GET schema but remove it from the PUT schema.
- Check if the property's value cannot be updated after creation. If yes, update the swagger definition for this property to mark it with the "x-ms-mutability": ["create", "read"] annotation.
- Check if the property has a static default value that doesn't depend on other properties. If yes, update the Swagger definition for this property to mark it with "default": annotation.
- If none of the above applies, check if one of the following behaviors is true for the property, send an exception request, but consider updating your service implementation to fix the behavior:
- The property has a dynamic default value that depends on other properties / some other resources (violates Property Design Best Practices).
- The property's value always gets normalized (violates ARM PRC).
Output Message: The property is present in the PUT request but is either never returned in the GET response or is returned with a null value. If this is a property that carries a secret such as a password, update the Swagger definition to mark it with the "x-ms-secret": true annotation. If it is write-only but does not carries a secret, update the swagger definition for this property to mark it with the "x-ms-mutability": ["create", "update"] annotation.
Description: The property is present in the PUT request, but in the subsequent GET response, it is either never returned or is returned with a null value, which means the property is write-only and is likely to carry a secret.
How to fix the violation:
- Check if the property carries a secret. If yes, mark the property definition with the "x-ms-secret": true annotation.
- Check if the property does not carry a secret but is still write-only. If yes, mark the property definition with the "x-ms-mutability": ["create", "update"] annotation.
Output Message: The property is returned in the GET response, but it is not declared in the PUT request. If it is a read-only property, update the swagger definition for this property to mark it as "readOnly": true. Alternatively, keep the property in the GET schema but remove it from the PUT schema. If the property has a default value, update the Swagger definition for this property to mark it with "default": annotation.
Description: The property was not in the PUT request, but it is returned in the subsequent GET response. This implies that the property is read-only or has a default value.
How to fix the violation:
- Check if the property is read-only. If yes, update the swagger definition for this property to mark it as "readOnly": true. Alternatively, keep the property in the GET schema but remove it from the PUT schema.
- Check if the property has a default value. If yes, update the Swagger definition for this property to mark it with "default": annotation.
Output Message: Respond to the initial request of a long running operation, Patch/Post call must return 201 or 202, Delete call must return 202 or 204, Put call must return 202 or 201 or 200, but {statusCode} being returned.
Description: Long running operation must return specific response code as per http method type in example or in traffic payload when this operation is annotated with x-ms-long-running-operation:true. See RPC - Asynchronous Operations for more details.
How to fix the violation: Correct the response code per the guidance or remove annotation of x-ms-long-running-operation in example or in traffic payload.
Output Message: Long running operation should return {header} in header but not being provided.
Description: Long running operation must return Operation-Id, Operation-Location, or azure-AsyncOperation header in response when this operation is annotated with x-ms-long-running-operation:true.
How to fix the violation: Adding one of these headers to the response in example or in traffic payload. Refer to this example for the fix.
Output Message: id is required to return in response of GET/PUT resource calls but not being provided.
Description: id is a required field of azure resource to return in response body of each GET or PUT call when this resource is annotated as x-ms-azure-resource: true. This field is important to the platform because it is used as the identifier for references on other objects. e.g. "id": "/subscriptions/{id}/resourceGroups/{group}/providers/{rpns}/{type}/{name}".
How to fix the violation: Adding id to the response body in example or in traffic payload.
Output Message: "x-ms-example" not found in {"operationId"} operation.
Description: Example is required to provide for each operation and it's annotated by "x-ms-example". Example is important because it is displayed in rest API document. See x-ms-examples for details.
How to fix the violation: Adding separated example JSON file and reference it with "x-ms-examples" annotation in swagger.
Output Message: Header {header} is required in response but not provided.
Description: {header} is declared in response schema in swagger but it's not provided in response in example or in traffic payload.
How to fix the violation: Adding this {header} to the response in example or in traffic payload.