Define & Validate APIsValidation RulesetsOpenAPI Rulesets
OpenAPI v3 Syntax Validation
Validation checks performed on provided OpenAPI v3 file to check its conformance to OpenAPI 3.n syntax rules.
| Property | Value |
|---|---|
| Ruleset ID | openapi-v3-syntax-validation |
| Code prefix | OPENAPI3SYNTAX_V |
| Type | Validation |
| Default severity | Error |
| Rule system | Syntax |
| Rules | 21 |
Servers
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V001 | valid-server-url-format | Error | Value must be in the format of a URL. A URL can either be absolute or relative and can contain variables wrapped in {}. |
Components
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V020 | valid-component-name | Error | Component name must contain only alphanumeric, dash (-), underscore (_) and period (.) characters. Spaces are not allowed. |
Paths
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V040 | path-name-begin-with-forward-slash | Error | A path name represents a relative path from the server at which the API is served. Therefore, it must start with a forward slash (/). |
Responses
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V060 | valid-response-status-code-or-range | Error | The Responses Object key must be a valid HTTP status code/range or set to default. The key must be enclosed in quotation marks for compatibility between JSON and YAML. If the key is an explicit HTTP status code, then it must be valid according to RFC7231 and possibly listed in the registered status codes in the IANA Status Code Registry. if the key represents a range of status codes it must contain the uppercase wildcard character X e.g. 2XX represents all response codes between [200-299]. Only the following range definitions are allowed: 1XX, 2XX, 3XX, 4XX, and 5XX. To represent undeclared responses, the key default can be used. |
OPENAPI3SYNTAX_V061 | valid-response-link-key | Error | The key of response links map is a name for the link which must contain only alphanumeric, dash (-), underscore (_) and period (.) characters. Spaces are not allowed. |
Callbacks
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V080 | valid-callback-key-expression | Blocking | Callback key is a string used for identifying the Path Item Object and is capable of supporting runtime expressions which are evaluated in the context of a runtime HTTP request/response to identify the URL to be used for the callback request. The key must use valid runtime expression syntax. Expressions can be embedded into string values by surrounding the expression with {} curly braces. |
Links
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V100 | valid-operation-ref | Error | operationRef must be a valid relative or absolute URI reference to an OAS operation. In the use of operationRef, the escaped forward-slash is necessary when using JSON references. |
OPENAPI3SYNTAX_V101 | valid-link-parameter-expression | Warning | Link parameter value is a string used for determining the parameter value that needs to be sent as part of the callback request. This value is capable of supporting runtime expressions which are evaluated in the context of a runtime HTTP request/response. The value must use valid runtime expression syntax. Expressions can be embedded into string values by surrounding the expression with {} curly braces. |
OPENAPI3SYNTAX_V102 | valid-link-request-body-expression | Warning | Link request body value is a string used for determining the request body value that needs to be sent as part of the callback request. This value is capable of supporting runtime expressions which are evaluated in the context of a runtime HTTP request/response. The value must use valid runtime expression syntax. Expressions can be embedded into string values by surrounding the expression with {} curly braces. |
References
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V120 | valid-dollar-ref-path | Error | $ref values must be RFC3986-compliant percent-encoded URIs. |
Schemas
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V140 | valid-schema-dollar-id-format | Error | The value of $id in a Schema Object must be a URI-reference (absolute URI or relative reference). If a relative path is used it must resolve to an absolute URI. $id must not contain a non-empty fragment value. |
OPENAPI3SYNTAX_V141 | valid-schema-dollar-anchor-format | Error | Property $anchor in a Schema Object is an identifier keyword used for creation of named fragments. The value of this property must start with a letter ([A-Za-z]) or underscore (_), followed by any number of letters, digits ([0-9]), hyphens (-), underscores (_), and periods (.). |
OPENAPI3SYNTAX_V142 | valid-schema-dollar-dynamic-anchor-format | Error | Property $dynamicAnchor in a Schema Object is an identifier keyword used for creation of named fragments. The value of this property must start with a letter ([A-Za-z]) or underscore (_), followed by any number of letters, digits ([0-9]), hyphens (-), underscores (_), and periods (.). |
OPENAPI3SYNTAX_V143 | valid-schema-content-media-type | Error | Media type of string content can be defined using the contentMediaType property of a Schema Object which must be in compliance with RFC2046. |
Discriminators
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V160 | valid-discriminator-mapping-key | Error | Discriminator mapping keys must be string values. |
XML
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V180 | valid-xml-namespace | Error | The XML namespace value must be a proper URI with an absolute path. |
Specification Extensions
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V200 | specification-extension-name-begin-with-x-dash | Error | If any additional property needs to be added in the OpenAPI specification that is otherwise not part of the actual standard, specification extensions can be used for this purpose at certain points. The extension name must begin with x- (e.g. x-internal-id). An exception to this rule is only for Schema Objects of OpenAPI v3.1.x documents that allows extension names to start even without x-. |
Miscellaneous
| Code | Rule | Severity | What it checks |
|---|---|---|---|
OPENAPI3SYNTAX_V220 | valid-url-format | Error | String value should be in the format of a proper URL. The URL path can be relative only if a server URL exists in the API document to help resolve the URL path into an absolute path. |
OPENAPI3SYNTAX_V221 | valid-email-address | Error | String value must be in the format of an email. |
OPENAPI3SYNTAX_V222 | valid-property-value-type | Error | Value of an OpenAPI standard property must be in accordance with the type set by the standard for that property. |
OPENAPI3SYNTAX_V223 | valid-uri-format | Error | String value should be in the format of a proper URI. The URI path can be relative if the Base URI of the referring document is known to help resolve the URI path into an absolute path. |