Format of a string schema is unknown

Issue ID: v3-schema-string-unknown-format

Average severity: Low

This issue ID and article have been deprecated and will be removed.

Description

The format you have defined for a string schema does not match formats defined in either the OpenAPI Specification (OAS) or JSON Schema Specification. Unknown formats cannot be enforced to protect your API, so it is like you had not defined a format at all.

For more details, see the OpenAPI Specification and JSON Schema Validation.

Example

The following is an example of how this type of risk could look in your API definition. The format mail for the property userName is unknown and therefore does not restrict the accepted values:

{
    "post": {
        "description": "Creates a new user",
        "operationId": "addUser",
        "requestBody": {
            "description": "User to add",
            "required": true,
            "content": {
                "application/json": {
                    "schema": {
                        "$ref": "#/components/schemas/NewUser"
                    }
                }
            }
        }
    },
    // ...
    "NewUser": {
        "type": "object",
        "description": "JSON defining a User object",
        "additionalProperties": false,
        "required": [
            "name",
            "userName"
        ],
        "properties": {
            "name": {
                "type": "string"
            },
            "userName": {
                "type": "string",
                "format": "mail" 
            }
        }
    }
}

Possible exploit scenario

If you do not define a known format for strings, no restrictions can be enforced and any string is accepted as the input. This could open your backend server to various attacks, such as SQL injection.

Using your internal, company-specific formats is not currently supported.

Remediation

Make sure that you only use known formats for strings. This ensures that only parameters of the expected format get passed to the backend.

{
    "post": {
        "description": "Creates a new user",
        "operationId": "addUser",
        "requestBody": {
            "description": "User to add",
            "required": true,
            "content": {
                "application/json": {
                    "schema": {
                        "$ref": "#/components/schemas/NewUser"
                    }
                }
            }
        }
    },
    // ...
    "NewUser": {
        "type": "object",
        "description": "JSON defining a User object",
        "additionalProperties": false,
        "required": [
            "name",
            "userName"
        ],
        "properties": {
            "name": {
                "type": "string"
            },
            "userName": {
                "type": "string",
                "format": "email"         
            }
        }
    }
}

If you want to use your internal, company-specific format, make sure to also use properties like maximum, minimum, pattern, and maxLenght to constrain the accepted values.