Skip to main content

ObjectSchema

Validates a table field by field. Fields absent from the shape are ignored unless the schema is made ObjectSchema:strict.

The original table is returned untouched unless a field fills in a value — a DefaultSchema field, or a nested object that filled one in. In that case the input is shallow copied and the filled values written to the copy, so the value handed to parse is never modified. 

local User = v.object({
	name = v.string():min(3),
	level = v.number():integer(),
})

The field schemas stay reachable through ObjectSchema.shape, so a single field can be validated on its own.

Properties​

shape​

This item is read only and cannot be modified. Read OnlyReflection
</>
ObjectSchema.shape: S

The schemas this object was built from, so a field can be reused or validated on its own: 

local Profile = v.object({ Level = v.number():integer():min(1) })

Profile.shape.Level:parse(42) --> 42
Profile.shape.Level:parse(0)  --> errors: expected at least 1, got 0

The table is a frozen copy of the one passed to Vet.object, so mutating it fails loudly rather than corrupting the schema.

isOptional​

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

Always false. Objects carry no minimum or maximum; read ObjectSchema.shape to reach a field's own limits.

access​

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

Always "readwrite", and describes this schema as a field of some other object rather than its own fields. Read shape[field].access for those.

Functions​

safeParse​

Parsing
</>
ObjectSchema:safeParse(value: unknown) → Result<objectOutput<S>>

Validates every field in the shape, reporting each failure with its field name in the issue path.

parse​

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

Validates value and returns it, throwing on failure.

Errors

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

strict​

Refinement
</>
ObjectSchema:strict() → ObjectSchema<objectOutput<S>,S>

Returns a schema that also rejects keys absent from the shape. Use it for data crossing a trust boundary, where an unexpected field is more likely a mistake than a spare.

optional​

Wrapper
</>
ObjectSchema:optional() → OptionalSchema<objectOutput<S>>

Wraps this schema so that nil is also accepted.

default​

Wrapper
</>
ObjectSchema:default(
fallback: T--

Value used when parsing nil

) → DefaultSchema<objectOutput<S>>

Wraps this schema so that nil yields fallback instead of failing. Prefer passing a function, since a constant table would be shared by every parse.

defaultWith​

Wrapper
</>
ObjectSchema:defaultWith(
produce: () → T--

Builds the value used when parsing nil

) → DefaultSchema<objectOutput<S>>

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

The produced value is validated each time.

readonly​

Wrapper
</>
ObjectSchema:readonly() → ReadonlySchema<objectOutput<S>>

Wraps this schema so that a field using it is typed read. Only the field is affected; the nested record keeps whatever access its own fields declare.

writeonly​

Wrapper
</>
ObjectSchema:writeonly() → WriteonlySchema<objectOutput<S>>

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

Show raw api
{
    "functions": [
        {
            "name": "safeParse",
            "desc": "Validates every field in the shape, reporting each failure with its\nfield name in the issue path.\n\t",
            "params": [
                {
                    "name": "value",
                    "desc": "",
                    "lua_type": "unknown"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Result<objectOutput<S>>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Parsing"
            ],
            "source": {
                "line": 2891,
                "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 `value` fails validation"
                }
            ],
            "source": {
                "line": 2962,
                "path": "src/init.luau"
            }
        },
        {
            "name": "strict",
            "desc": "Returns a schema that also rejects keys absent from the shape. Use it\nfor data crossing a trust boundary, where an unexpected field is more\nlikely a mistake than a spare.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ObjectSchema<objectOutput<S>, S>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Refinement"
            ],
            "source": {
                "line": 2992,
                "path": "src/init.luau"
            }
        },
        {
            "name": "optional",
            "desc": "Wraps this schema so that `nil` is also accepted.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "OptionalSchema<objectOutput<S>>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 3006,
                "path": "src/init.luau"
            }
        },
        {
            "name": "default",
            "desc": "Wraps this schema so that `nil` yields `fallback` instead of failing.\nPrefer passing a function, since a constant table would be shared by\nevery parse.\n\t",
            "params": [
                {
                    "name": "fallback",
                    "desc": "Value used when parsing `nil`",
                    "lua_type": "T"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DefaultSchema<objectOutput<S>>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 3023,
                "path": "src/init.luau"
            }
        },
        {
            "name": "defaultWith",
            "desc": "Like `:default`, but calls `produce` on every parse instead of reusing\none value. Prefer it here, since a single table would otherwise be\nshared by every caller and mutable through any of them.\n\nThe produced value is validated each time.\n\t",
            "params": [
                {
                    "name": "produce",
                    "desc": "Builds the value used when parsing `nil`",
                    "lua_type": "() -> T"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "DefaultSchema<objectOutput<S>>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 3044,
                "path": "src/init.luau"
            }
        },
        {
            "name": "readonly",
            "desc": "Wraps this schema so that a field using it is typed `read`. Only the\nfield is affected; the nested record keeps whatever access its own\nfields declare.\n\t",
            "params": [],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "ReadonlySchema<objectOutput<S>>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 3060,
                "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<objectOutput<S>>"
                }
            ],
            "function_type": "method",
            "tags": [
                "Wrapper"
            ],
            "source": {
                "line": 3074,
                "path": "src/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "shape",
            "desc": "The schemas this object was built from, so a field can be reused or\nvalidated on its own:\n\n```lua\nlocal Profile = v.object({ Level = v.number():integer():min(1) })\n\nProfile.shape.Level:parse(42) --> 42\nProfile.shape.Level:parse(0)  --> errors: expected at least 1, got 0\n```\n\nThe table is a frozen copy of the one passed to [Vet.object], so\nmutating it fails loudly rather than corrupting the schema.\n\t",
            "lua_type": "S",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2855,
                "path": "src/init.luau"
            }
        },
        {
            "name": "isOptional",
            "desc": "Always `false`. Objects carry no `minimum` or `maximum`; read\n[ObjectSchema.shape] to reach a field's own limits.\n\t",
            "lua_type": "boolean",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2868,
                "path": "src/init.luau"
            }
        },
        {
            "name": "access",
            "desc": "Always `\"readwrite\"`, and describes this schema as a field of some other\nobject rather than its own fields. Read `shape[field].access` for those.\n\t",
            "lua_type": "\"readwrite\"",
            "tags": [
                "Reflection"
            ],
            "readonly": true,
            "source": {
                "line": 2879,
                "path": "src/init.luau"
            }
        }
    ],
    "types": [],
    "name": "ObjectSchema",
    "desc": "Validates a table field by field. Fields absent from the shape are ignored\nunless the schema is made [ObjectSchema:strict].\n\nThe original table is returned untouched unless a field fills in a value —\na [DefaultSchema] field, or a nested object that filled one in. In that case\nthe input is shallow copied and the filled values written to the copy, so\nthe value handed to `parse` is never modified.\n\n```lua\nlocal User = v.object({\n\tname = v.string():min(3),\n\tlevel = v.number():integer(),\n})\n```\n\nThe field schemas stay reachable through [ObjectSchema.shape], so a single\nfield can be validated on its own.",
    "source": {
        "line": 2815,
        "path": "src/init.luau"
    }
}