[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.