http://testanything.org/wiki/index.php/TAP_diagnostic_syntax is the details.

This is being implemented in TB2-TAP-structured-diagnostics

At the start, its fine to use an existing YAML and JSON library. Later, we'll probably copy in YAML::Tiny or JSON::Tiny or the YAML emitter used by MakeMaker to do META.yaml which specializes in making things look pretty.

Taking a look at the spec, does the result normally get the have/want/file/line stuff? or is that something else that the Formatter needs to dig up else where. In the tests we've been building up result objects on the fly so they are non-standard with the're payload.

Be aware, the spec has some bit rot.

have/want/file/line are all optional, the spec just provides some standard key names to use for those concepts. If they're in $result->diagnostics, use them. If not, don't. You should already see this with the way the TAP::v13 formatter builds up its failure comment.

You'll probably find that having $result->diagnostics contain an array is cumbersome. The idea was to preserve order and the same key being set multiple times, but I really don't think that's important. Feel free to change it to a hash.