I am developing a (Java) library providing an API to read a file in a specific format into an object. The format is basically a map, and specifies valid values for some of the keys, and valid types for values for others.

E.g., the value for colour may only be one of red, green or blue, while the key date must be provided in YYYY-MM-DD format.

Also, the file in this format must have a specific name.

Obviously, the API could be used with invalid data, e.g., a file of the wrong name, or a file containing invalid values, e.g., colour: orange or date: last year.

Additionally, the API will have to deal with scenarios such as non-existing files, files in completely different formats, etc.

Are there best practices for this kind of scenario? E.g., should I throw runtime exceptions for the latter kind of issues (other format, file not found, I/O exception) that I catch during the read, and custom exceptions for the other issues (invalid file name/values)?

Or should I return some sort of result object wrapping, e.g., the data object when it is valid and has been successfully read, or a list of error messages collected during the read when something went wrong? (Should the respective other fields then be null or contain an empty value?)