Hello,

I would like to suggest that you add description fields that describe individual fields so you don't need to look for the description of fields in specific documentation, but the documentation was available in tools that can use descriptions fields.

For example: I have these specifications loaded in Jetbrains IDE.

It makes sure my files are automatically linted while working on them and I get instant feedback.

I can also easily go to the specification if I press CTRL+field.

I would like to be able to read the description as well, but unfortunately it is not included in the specification. Other specs have descriptions which makes my life easier. This is what it looks like in the Workflow or Github Action specification.

As a next step, we can also generate user documentation and publish it on the website but it's an extra effort and it's enough for me that the specification has descriptions. See: #115

Best regards,
Kamil Breguła