Personally, I’m not sure it’s a good idea to use fields as vehicles for explaining how the type should work. The content of a field is entity-dependent.
It strikes me that what is perhaps more needed is a way to describe an app and its purpose (including how to use the types within it) which is more of a meta-level than the actual entities within an app.
Perhaps there is something valuable in these other discussions: