ts-sdk: Provide helpful subcategories for validation error cases

[ships]

Feature Request

Packages to improve:

• OWL/SHACL definitions
• ts-sdk
• ts-etl
• spa

Description

Provide some helpful code that makes error cases of decode easier to work with.

Use case

Describe how you plan to use this feature and why it is important to you.

Proposed solution

There are a few approaches and it is unclear exactly which is best. See these notes:

https://github.com/gcanti/io-ts/blob/616583de0198632cad7820ed8701b15f654c7fd2/index.md?plain=1#L332-L336
https://github.com/gcanti/io-ts/blob/616583de0198632cad7820ed8701b15f654c7fd2/index.md?plain=1#L308-L326

and
https://gcanti.github.io/io-ts/#error-reporters

I think Reporters would be a fine approach, at least in the api-server we can explicitly call the reporter to categorize parse failures if needed. However it is worth considering if we can wrap the error case in all our codecs with reporters such that they get best-effort interpretations as well as the original validation error as appropriate. For example it is helpful if we pass in Docmap.parse(undefined) that we could recognize that as a different family of error than if a key is missing or wrongly typed in a mostly-correct Docmap.

Otherwise, something like withMessage might be helpful for ensuring that even if a consumer does not use a Reporter, they are able to get a good message.

Additional information