noctcore-contracts/zod-field-describe
noctcore-contracts/zod-field-describe
- Package
- contracts v1.1.0
- Preset
- none opt-in
- Severity
- off
- Autofix
- No
- Suggestions
- No
- Options
- Optional
- Type info
- Not needed
Every property of a zod object schema carries a description.
A zod field description is the documentation that travels with the schema. It becomes the
description of the JSON Schema a docs or tool-definition generator emits, the hint a model sees for
a tool argument, and the text an API reference shows beside the field. A field without one is silent
in all three, and nothing fails at runtime to say so.
What it flags
Section titled “What it flags”Every property of a z.object / z.strictObject / z.looseObject shape, and of the shape passed to
.extend / .safeExtend, whose value chain has no .describe('...') with non-empty text and no
.meta({ description: '...' }). The description may sit anywhere in the chain, so
z.string().describe('x').min(1) and z.string().min(1).describe('x') both pass. The check is per
property: a .describe() on the enclosing object does not cover its fields. An empty or blank
description counts as missing. Member chains on the zod namespace count as zod factories, so
z.coerce.string().min(1) and z.iso.date() are checked like z.string().
export const UserSchema = z.object({ id: z.string().describe('Stable identifier'), name: z.string().min(1), email: z.string().email().describe(''), age: z.number().meta({ title: 'Age' }), tags: z.array(z.string()).optional(),});export const UserSchema = z.object({ id: z.string().describe('Stable identifier'), name: z.string().min(1).describe('Display name'), email: z.string().email().describe('Contact address'), age: z.number().meta({ description: 'Age in years' }), tags: z.array(z.string()).optional().describe('Free-form labels'),});What it does not flag
Section titled “What it does not flag”- A field whose value is a reference to another schema (
user: UserSchema,user: Schemas.User,user: UserSchema.optional()) whileallowSchemaReferencesistrue: that schema carries its own description. - A description or
metaargument that is computed (.describe(TEXT.name), a template with expressions,.meta(base),.meta({ ...base })): the rule cannot read it, so it trusts it. - A description inside the first argument of
z.optionalorz.nullable(z.optional(z.string().describe('x'))): the wrapper is followed, so the field counts as described. - Spread entries and values that are not a zod chain or a schema reference, such as a conditional.
- Schemas built from a namespace not listed in
zodIdentifiers, and anyz.object(shape)whose shape is not an object literal.
Options
Section titled “Options”| Option | Type | Default | Meaning |
|---|---|---|---|
zodIdentifiers |
string[] |
['z'] |
Names zod is imported under. |
allowSchemaReferences |
boolean |
true |
Do not report a field whose value is a reference to another schema. |
Set allowSchemaReferences: false to require a description at every use site, including references:
'noctcore-contracts/zod-field-describe': ['error', { allowSchemaReferences: false }]Scope the rule to your schema modules with the config block’s files (for example
files: ['**/*.schemas.ts']); the rule itself assumes no layout.
When not to use it
Section titled “When not to use it”If your schemas are never turned into JSON Schema, tool definitions or API docs, a description on every field is ceremony. Leave the rule off, or enable it only for the modules that feed a generator.