What I am now hoping to find is an endpoint that will describe what to expect in terms of custom fields.
Ideally the field name (which I can see in the data), and perhaps the field type, whether there are any enumeration values, min and max length if the field is an integer, etc etc.
I can find references to the same fields in /api/v2/flows but they only seem to describe how the fields apply to flows, rather than describing the fields themselves.
There is no dictionary for the custom. They're custom. There is no endpoint that can describe them because they're entirely adhoc, not something architected and patterned in the platform.
You would either have to create your own dictionary and ensure your developers follow it and update it or wait for the schematized ones to be implemented which would theoretically have to have some form of what you've asked for.
So to be clear, if a customer's data has a field in almost every case called say participants.attribute.OrderNumber, then that is the result of agents remembering to type "OrderNumber" as a key on the case, adhoc?
I realise now having typed that, that participant.{CustomFieldName} and participant.attribute.{CustomField} are not the same, and perhaps I asked the wrong question?
In my experience it's not usually an agent entering data into those, it's some action within a flow such as a data pull from a remote system or other API, or other scripted action. There probably is a way to get agent input but I wouldn't recommend it since it would be subject to the problem you described, yes.
I realise now having typed that, that participant.{CustomFieldName} and participant.attribute.{CustomField} are not the same, and perhaps I asked the wrong question?
I believe it's all the same in this case, just different way of referencing it depending on whether you're in architect or via the various apis. Hopefully if I am confusing topics someone will correct me.