[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