meta-schemas: Descriptions or no descriptions?

[handrews]

hyper-schema.json has descriptions for its fields. json.schema does not. We should pick one or the other appraoch.

In favor of descriptions:

• It makes the meta-schema something of a quick-ref guide

Problems with descriptions:

• Easily get out of sync with the specification
• Long strings are annoying in JSON, but short descriptions can leave out important parts while giving a false sense of security to people who do not read the actual spec or longer tutorials.

I prefer no descriptions, but I'd be OK with adding descriptions everywhere.

[Relequestual]

In principal I agree, but I also see the potential issue.
There's no reason we couldn't have the default / standard meta-schema having the more lengthy detailed comments, while having a smaller meta-schema without comments. The smaller version would need to be automatically built to avoid issues.

I agree somewhat over the concern that it could become out of sync, but then that's something we need to be aware and careful of. We need to make clear that the meta-schema is only a GUIDE and the spec document should be read for the full picture.

I'm as of yet unsure about this either way.

[Anthropic]

I like description and would like to see it part of the core as in my mind it is part of the data definition.
I am not too concerned with the description getting out of sync, I've never had that issue, so it is up to the user how well they manage.

Personally I like first person documentation, the docs practically write themselves.

Perhaps it is worth adding examples that clearly indicate purpose/intent for the property. I would like to see hint added to ui-schema to provide a short comment for end users of a form. I see too many descriptions like "please enter your name", which is partially the fault of the original design on Angular Schema Form using description as a hint. But I want to change that at some point.

[handrews]

@Anthropic this isn't about removing the description keyword, rather it's about the fact that the core+validation schema does not include descriptions, but for some reason Hyper-Schema does.

We've definitely had situations where the meta-schema descriptions are out of sync with the spec. Since there is a very clear place to go for explanations in this case, I'm making an executive decision (assuming no one stops me) and removing them. Most of them are either trivial, or totally inadequate since we have always avoided going into detail in them.

[handrews]

Fixed in #406.