[Feature Request] Add @describe attribute to ZModel language (or any other way of attaching meta data to properties)

[DawidWraga]

Is your feature request related to a problem? Please describe.

I want to centralize as much of my data model definition as possible in schema.zmodel.

The addition of typed JSON fields is absolutely amazing and could be super helpful in this regard.

However, my application extensively uses AI to generate JSON data, so it's essential for the properties to be annotated with descriptions

For this reason, even though zenstack generates zod schemas, I have to rewrite the zod schemas to add descriptions to them.

Here is an usecase / example of what would solve my problem:

model MetricLog extends Base {
  key             String    @describe("the label of the metric eg 'Focus-quality' or 'Energy-levels'")    
  valueLabel      String    @describe("a descriptive measurement of the key based on evidence (eg 'Low', 'Medium', 'High')")
  confidenceLabel String    @describe("a description of the evidence strength eg 'low', 'medium', 'high'")
  value           Float     @describe("a normalized numberic representation of valueLabel (between 0 and 1)")
  confidence      Float     @describe("a normalized numberic representation of confidenceLabel (between 0 and 1)") 
  evidence        Evidence[]@json
 
}


type Evidence {
    quote       String  @describe("a specific unedited quote from the user")
    timestamp   String  @describe("the time during record where quote is extracted from")
}

and then the generated zod schemas to include those descriptions

Or perhaps for flexibility something like this could be better?

model MetricLog extends Base {
      key         String  @meta({
                              description: "..."
                              examples: ["...", "..."],
                              tags: ['ai-generated']
                              })
        // ...
}

Additionally, this would be really helpful for generating openapi schemas eg when using zenstack generated zod models in trpc.

[jiashengguo]

That's a good one. I’ve always believed that Zenstack's declarative schema is a good bridge between AI and humans. My only concern is that combining too many elements into a single schema could make it somewhat cluttered. Perhaps partial models could offer a solution to this:
#1077

[DawidWraga]

That's a good one. I’ve always believed that Zenstack's declarative schema is a good bridge between AI and humans. My only concern is that combining too many elements into a single schema could make it somewhat cluttered. Perhaps partial models could offer a solution to this: #1077

If the schema becomes cluttered I'd much prefer to move the model into a separate file, but keep the definition and meta data close together, than to keep all the models in one file, and then all the metadata in a separate file.

To be honest, having to redefine all my zod schema with metadata in my codebase has started to become a major pain point and causing issues so this feature would truly mean a lot to me.

In particular, the flexible @meta tag, rather than @description, would be INCREDIBLY helpful for my current use-case.

Also, would be really helpful if it was possible to add @meta or @decscription to a model rather than only properties.

How difficult do you think it would be to add this to Zenstack, integrating it into the generated Zod schema as well as the vscode syntax highlighting? Would this make a good candidate for first PR? (I mean I've written some docs for Zenstack before but not familiar with the core codebase)

Also not sure if it's worth making another issue or mentioning this here- being able to add depreciated to the meta, or having @depreciated would be huge.

[jiashengguo]

Understood. The implementation efforts are not big; however, it does require adding an additional attribute tag to the ZModel schema.

If it's not urgent, I recommend waiting for ZenStack V3. It will offer a clearer and simpler way to add this feature.

[DawidWraga]

Few updates:

With the new meta api in Zod 4, the @meta tag would definitely be preferable to @describe

Also, a great great suggestion to on discord use standard-schema to make it work across schema validation packages. Although personally I always use zod so I wouldn't mind if it was zod only.

Does he potentially mean implementing standard schema this would allow users to use any schema validation that also implements it such as Valibot, Zod etc. Rather than being made to use Zod.
Brandan King — 22/04/2025 09:44

Really can't wait for Zenstack v3 particularly the meta tag, more flexibility and computed fields. Any rough idea on when it might be ready to use? is it closer to 3 months or 1 year +?

Edit: found this on the discord - so beta should be here around Q2 2025 🎉🎉🎉

"Right now we're focusing on building a comprehensive POC to prove all planned approaches will work as planned. Functionality wise, I'll say 80% of Prisma's CRUD features have been replicated based on Kysely. But there's still lots of work ahead - testing, migrating existing upstream features, perf benchmark, documentation, etc. I think a rough but reasonable estimate is there'll be a Beta release within this quarter."
ymc9 — 11/04/2025 01:32