GenAI events - yamlify body definitions and cosmetic examples improvements

[lmolkova]

• Adds yaml definitions for GenAI events in preparation for Render events with bodies #1464
• Updates examples to be more concise and readable, fixes small inconsistencies, adds diagrams.

Merge requirement checklist

• CONTRIBUTING.md guidelines followed.
• Change log entry added, according to the guidelines in When to add a changelog entry.
  • If your PR does not need a change log, start the PR title with [chore]
• schema-next.yaml updated with changes to existing conventions.

[github-actions]

This PR was marked stale due to lack of activity. It will be closed in 7 days.

[codefromthecrypt]

thanks

[drewby]

Overall looks good. While the examples at the end of the markdown help clarify, I think the short descriptions of the input messages by role can be clearer.

[jsuereth]

Reviewing for general semconv.

Overall, glad we can now put the ToolCall structure/semantics in the YAML. I think this is a good first step.

I do think seeing the hierarchy with the spaces in markdown still leaves a bit wanting. I'm not sure what options we have with markdown here, unfortunately.

I like the look of what prometheus docs have done here but this requires dropping into HTML table land, and it ruins the readabiltiy of the markdown by itself. That may be ok if it's autogenerated.

[lmolkova]

I do think seeing the hierarchy with the spaces in markdown still leaves a bit wanting. I'm not sure what options we have with markdown here, unfortunately.

We could switch to (pseudo) code or some form of JSON, I've heard you like designing languages, @jsuereth :)

[drewby]

Looks good!