Repository: promptfoo/promptfoo
Issue: Questions & Improvements: Eval output file version property, outdated docs & example, differences
Root cause: Documentation Deficiency

# Questions:
1. When I am creating an output file via `pf eval -c <EVAL_CONFIG_FILENAME> --output <OUTPUT_FILENAME>`, the result always has a version of **2**. Is this a bug or desired and is the version of the output file format?
   - Example output.json: 
![image](https://github.com/user-attachments/assets/79d2a09c-6628-49d8-9265-5e7143ad9855)
2. The official docs (https://www.promptfoo.dev/docs/configuration/parameters/#output-file) and the linked example (https://github.com/promptfoo/promptfoo/tree/main/examples/simple-cli) seem to be kinda outdated. It would be great to have a reference for the whole output object (for instance EvaluateOutput) under: https://www.promptfoo.dev/docs/configuration/reference/#evaluation-outputs
   - Current structure of output.json: 
![image](https://github.com/user-attachments/assets/1bb3cb44-eddd-4741-b149-707e1cec6141)
3. I generated outputs of the different file types and they seem to be subsets. So some contain more than others. For instance YAML and JSON contain most from what I see.


@hci2 
Thanks for the feedback. I'm actually working on a new output version now in this PR - https://github.com/promptfoo/promptfoo/pull/1776

That version number is the version of `EvaluateSummary`. The table is going away in the next version as part of my PR. It unnecessarily duplicates all of the data in the results.

I'll update the docs to be clearer on the output. 

How are you using these output files? I want to make sure the changes I'm making don't break your use case.

Oh looks very promising and I am excited of what we will be changed and have a look into it for sure. Thank you! 👏 

Ah makes sense but then the parent wrapper object of that was missing. It is also good to document that because it contains the `evalId`. which can be used later via `pf show eval <EVAL_ID>` command. 

> How are you using these output files? I want to make sure the changes I'm making don't break your use case.
For now we only store the latest eval in our repository to later access the eval results without running the eval again. So you won't break anything.

## New question about the format
I also noticed that the format of the exported eval JSON  (via `pf export <EVAL_ID>`) looks slightly different as you can see below. Shouldn't the property key be named the same and the property description be available everywhere. The `createdAt` property could be in the same format (ISO 8601 datetime) as `timestamp` in my opinion. What do you think about it?

![image](https://github.com/user-attachments/assets/f4a0fc0b-f336-4cbc-a79d-219ae56956d7)


Hi @hci2,

Thanks for raising these questions about the output file format! 

As @sklein12 mentioned, **PR #1776 was merged on October 7, 2024** which addressed your concerns:
- The output format was normalized and improved
- The eval results structure was redesigned 
- Documentation was updated with the new format

Since this issue was resolved over a year ago and you seemed satisfied with the response, I'm closing this now.

If you have any follow-up questions about the current output format, feel free to open a new issue.

Thanks!