Skip to main content

StringSchema

Validates strings. Every refinement returns a new schema, so a base schema can be shared and specialised without being modified. 

local Base = v.string()
local Username = Base:min(3):max(22)

Properties​

minimum​

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

Shortest length this schema accepts, or nil if it is unbounded. Set by StringSchema:min and StringSchema:length.

maximum​

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

Longest length this schema accepts, or nil if it is unbounded. Set by StringSchema:max and StringSchema:length.

isOptional​

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

Always false. Reading it on any schema tells you whether nil is accepted without having to know which kind of schema you hold.

access​

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

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

Functions​

_validate​

Parsing
</>
StringSchema:_validate(value: unknown) → Result<string>

Validates value without throwing. All refinements run, so the returned issues describe every failure rather than only the first.

parse​

Parsing
</>
StringSchema:parse(value: unknown) → string

Validates value and returns it, throwing on failure.

Errors

TypeDescription
"expected ..."Thrown when `value` fails validation

min​

Refinement
</>
StringSchema:min(
n: number--

Minimum length, inclusive

) → StringSchema

Requires the string to be at least n characters long.

max​

Refinement
</>
StringSchema:max(
n: number--

Maximum length, inclusive

) → StringSchema

Requires the string to be at most n characters long.

length​

Refinement
</>
StringSchema:length(
n: number--

Exact length

) → StringSchema

Requires the string to be exactly n characters long.

optional​

Wrapper
</>
StringSchema:optional() → OptionalSchema<string>

Wraps this schema so that nil is also accepted.

default​

Wrapper
</>
StringSchema:default(
fallback: string--

Value used when parsing nil

) → DefaultSchema<string>

Wraps this schema so that nil yields fallback instead of failing.

defaultWith​

Wrapper
</>
StringSchema:defaultWith(
produce: () → string--

Builds the value used when parsing nil

) → DefaultSchema<string>

Like StringSchema:default, but calls produce on every parse instead of reusing one value. Use it when the fallback is a table, since a single table would otherwise be shared by every caller and mutable through any of them.

The produced value is validated each time, so a producer that returns something invalid fails at parse rather than silently passing through.

readonly​

Wrapper
</>
StringSchema:readonly() → ReadonlySchema<string>

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

writeonly​

Wrapper
</>
StringSchema:writeonly() → WriteonlySchema<string>

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

Show raw api
{
    "functions": [
        {
            "name": "_validate",
            "desc": "Validates `value` without throwing. All refinements run, so the returned\nissues describe every failure rather than only the first.",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Result<string>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "source": {
                "line": 1151,
                "path": "src/init.luau"
            }
        },
        {
            "name": "parse",
            "desc": "Validates `value` and returns it, throwing on failure.",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "errors": [
                {
                    "lua_type": "\"expected ...\"",
                    "desc": "Thrown when `value` fails validation"
                }
            ],
            "source": {
                "line": 1177,
                "path": "src/init.luau"
            }
        },
        {
            "name": "min",
            "desc": "Requires the string to be at least `n` characters long.",
            "params": [
                {
                    "name": "n",
                    "desc": "Minimum length, inclusive",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "StringSchema"
                }
            ],
            "function_type": "method",
            "tags": [
                "Refinement"
            ],
            "source": {
                "line": 1195,
                "path": "src/init.luau"
            }
        },
        {
            "name": "max",
            "desc": "Requires the string to be at most `n` characters long.",
            "params": [
                {
                    "name": "n",
                    "desc": "Maximum length, inclusive",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "StringSchema"
                }
            ],
            "function_type": "method",
            "tags": [
                "Refinement"
            ],
            "source": {
                "line": 1213,
                "path": "src/init.luau"
            }
        },
        {
            "name": "length",
            "desc": "Requires the string to be exactly `n` characters long.",
            "params": [
                {
                    "name": "n",
                    "desc": "Exact length",
                    "lua_type": "number"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "StringSchema"
                }
            ],
            "function_type": "method",
            "tags": [
                "Refinement"
            ],
            "source": {
                "line": 1231,
                "path": "src/init.luau"
            }
        },
        {
            "name": "optional",
            "desc": "Wraps this schema so that `nil` is also accepted.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "OptionalSchema<string>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 1248,
                "path": "src/init.luau"
            }
        },
        {
            "name": "default",
            "desc": "Wraps this schema so that `nil` yields `fallback` instead of failing.",
            "params": [
                {
                    "name": "fallback",
                    "desc": "Value used when parsing `nil`",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DefaultSchema<string>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 1263,
                "path": "src/init.luau"
            }
        },
        {
            "name": "defaultWith",
            "desc": "Like [StringSchema:default], but calls `produce` on every parse instead of\nreusing one value. Use it when the fallback is a table, since a single\ntable would otherwise be shared by every caller and mutable through any\nof them.\n\nThe produced value is validated each time, so a producer that returns\nsomething invalid fails at parse rather than silently passing through.",
            "params": [
                {
                    "name": "produce",
                    "desc": "Builds the value used when parsing `nil`",
                    "lua_type": "() -> string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DefaultSchema<string>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 1286,
                "path": "src/init.luau"
            }
        },
        {
            "name": "readonly",
            "desc": "Wraps this schema so that a field using it is typed `read`.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ReadonlySchema<string>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 1300,
                "path": "src/init.luau"
            }
        },
        {
            "name": "writeonly",
            "desc": "Wraps this schema so that a field using it is typed `write`.",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "WriteonlySchema<string>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 1314,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "minimum",
            "desc": "Shortest length this schema accepts, or `nil` if it is unbounded. Set by\n[StringSchema:min] and [StringSchema:length].",
            "lua_type": "number?",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 1102,
                "path": "src/init.luau"
            }
        },
        {
            "name": "maximum",
            "desc": "Longest length this schema accepts, or `nil` if it is unbounded. Set by\n[StringSchema:max] and [StringSchema:length].",
            "lua_type": "number?",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 1112,
                "path": "src/init.luau"
            }
        },
        {
            "name": "isOptional",
            "desc": "Always `false`. Reading it on any schema tells you whether `nil` is\naccepted without having to know which kind of schema you hold.",
            "lua_type": "boolean",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 1122,
                "path": "src/init.luau"
            }
        },
        {
            "name": "access",
            "desc": "Always `\"readwrite\"`. Chain [StringSchema:readonly] or\n[StringSchema:writeonly] to change it.",
            "lua_type": "\"readwrite\"",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 1132,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [],
    "name": "StringSchema",
    "desc": "Validates strings. Every refinement returns a new schema, so a base schema\ncan be shared and specialised without being modified.\n\n```lua\nlocal Base = v.string()\nlocal Username = Base:min(3):max(22)\n```",
    "source": {
        "line": 1064,
        "path": "src/init.luau"
    }
}