Add ValidationReport class for validation results

[sejalpunwatkar]

This change introduces a new ValidationReport dataclass to provide a structured representation of NWB validation results. Instead of returning raw validation errors alone, validation now returns report objects containing contextual metadata while preserving existing validation behavior.

[oruebel]

Could you please add a docstring for the ValidationReport calss and its functions/parameters

[sejalpunwatkar]

Thanks for the suggestion! I’ll add docstrings for the ValidationReport class and its methods/parameters.

[Copilot]

Pull request overview

Introduces a ValidationReport dataclass intended to provide a structured representation of NWB validation results (including metadata like path/namespace/timestamp) rather than returning only raw validation errors.

Changes:

• Added a new ValidationReport dataclass and exported it via __all__.
• Updated validation flow to construct and return ValidationReport objects per namespace validated.
• Updated the validate docval return description to refer to validation “reports”.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

_validate_single_file now returns a list of ValidationReport objects, which changes the public validate() return value from a flat list of error strings to report objects. This is a breaking API change and also breaks internal consumers that assume a list of strings (e.g., src/pynwb/testing/testh5io.py uses "\n".join(errors) and src/pynwb/validation_cli.py treats len(val_errors)>0 as “has errors”). To preserve existing behavior, keep validate() returning the original flat list of error strings by default and introduce reports behind a new API (e.g., validate(..., return_reports=True) or a separate validate_with_report() function), or otherwise update all in-repo call sites and deprecation notes accordingly.

[oruebel]

@rly thoughts on this suggestion by Copilot

[Copilot]

ValidationReport uses errors: list and created_at: str with datetime.utcnow().isoformat(), which produces a timezone-naive timestamp string and loses type information for consumers. Consider using precise typing for errors (e.g., List[str] if these are error strings) and storing created_at as a timezone-aware datetime (or, if you need a string, use datetime.now(timezone.utc).isoformat() and include the UTC offset).