Skip to main content

OptionalSchema

Accepts nil in addition to whatever the wrapped schema accepts. Created by calling :optional() on any schema, which comes last in a chain so that the refinements before it still apply to non-nil values. 

local Nickname = v.string():max(20):optional()

Nickname:parse(nil)        --> nil
Nickname:parse("kyle")     --> "kyle"
Nickname:parse(5)          --> errors

Properties​

isOptional​

This item is read only and cannot be modified. Read OnlyReflection
</>
OptionalSchema.isOptional: boolean

Always true.

access​

This item is read only and cannot be modified. Read OnlyReflection
</>
OptionalSchema.access: "readwrite"

Always "readwrite". Chain :readonly() or :writeonly() to change it.

minimum​

This item is read only and cannot be modified. Read OnlyReflection
</>
OptionalSchema.minimum: number?

Forwarded from the wrapped schema, so v.string():min(3):optional() still reports a minimum of 3.

maximum​

This item is read only and cannot be modified. Read OnlyReflection
</>
OptionalSchema.maximum: number?

Forwarded from the wrapped schema.

Functions​

safeParse​

Parsing
</>
OptionalSchema:safeParse(value: unknown) → Result<T?>

Succeeds with nil when value is nil, and otherwise defers to the wrapped schema.

parse​

Parsing
</>
OptionalSchema:parse(value: unknown) → T?

Validates value and returns it, throwing on failure.

Errors

TypeDescription
"expected ..."Thrown when a non-nil `value` fails validation

optional​

Wrapper
</>
OptionalSchema:optional() → OptionalSchema<T>

Returns the same schema, since it already accepts nil.

readonly​

Wrapper
</>
OptionalSchema:readonly() → ReadonlySchema<T?>

Wraps this schema so that a field using it is typed read. The value type keeps the ?, so the field reads as read name: string?.

writeonly​

Wrapper
</>
OptionalSchema:writeonly() → WriteonlySchema<T?>

Wraps this schema so that a field using it is typed write.

Show raw api
{
    "functions": [
        {
            "name": "safeParse",
            "desc": "Succeeds with `nil` when `value` is `nil`, and otherwise defers to the\nwrapped schema.\n\t",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Result<T?>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "source": {
                "line": 775,
                "path": "src/init.luau"
            }
        },
        {
            "name": "parse",
            "desc": "Validates `value` and returns it, throwing on failure.\n\t",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "T?"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "errors": [
                {
                    "lua_type": "\"expected ...\"",
                    "desc": "Thrown when a non-nil `value` fails validation"
                }
            ],
            "source": {
                "line": 811,
                "path": "src/init.luau"
            }
        },
        {
            "name": "optional",
            "desc": "Returns the same schema, since it already accepts `nil`.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "OptionalSchema<T>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 829,
                "path": "src/init.luau"
            }
        },
        {
            "name": "readonly",
            "desc": "Wraps this schema so that a field using it is typed `read`. The value\ntype keeps the `?`, so the field reads as `read name: string?`.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ReadonlySchema<T?>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 842,
                "path": "src/init.luau"
            }
        },
        {
            "name": "writeonly",
            "desc": "Wraps this schema so that a field using it is typed `write`.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "WriteonlySchema<T?>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 856,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "isOptional",
            "desc": "Always `true`.\n\t",
            "lua_type": "boolean",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 732,
                "path": "src/init.luau"
            }
        },
        {
            "name": "access",
            "desc": "Always `\"readwrite\"`. Chain `:readonly()` or `:writeonly()` to change it.\n\t",
            "lua_type": "\"readwrite\"",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 742,
                "path": "src/init.luau"
            }
        },
        {
            "name": "minimum",
            "desc": "Forwarded from the wrapped schema, so `v.string():min(3):optional()`\nstill reports a minimum of 3.\n\t",
            "lua_type": "number?",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 753,
                "path": "src/init.luau"
            }
        },
        {
            "name": "maximum",
            "desc": "Forwarded from the wrapped schema.\n\t",
            "lua_type": "number?",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 763,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [],
    "name": "OptionalSchema",
    "desc": "Accepts `nil` in addition to whatever the wrapped schema accepts. Created by\ncalling `:optional()` on any schema, which comes last in a chain so that the\nrefinements before it still apply to non-nil values.\n\n```lua\nlocal Nickname = v.string():max(20):optional()\n\nNickname:parse(nil)        --> nil\nNickname:parse(\"kyle\")     --> \"kyle\"\nNickname:parse(5)          --> errors\n```",
    "source": {
        "line": 703,
        "path": "src/init.luau"
    }
}