reconciliation-api
Suggestion: add more easy-to-understand explanation of examples
It is a bit hard to understand what examples in the specs try to do (especially for new comers). Little suggestion to add more easy-to-understand explanation of examples. For instance, Example7 could be described as follows:
give up to 5 entities with a name similar to "Christel Hanewinckel", of type "DifferentiatedPerson" and whose "professionOrOccupation" matches either the string "Politik*" or the entity with id "wissenschaftler".
Optionally, it would also be helpful to add what kind of results (response syntax) would be expected.
Concerning the response syntax, did you have a look at the section just below Example 7? https://reconciliation-api.github.io/specs/draft/#reconciliation-query-responses If you missed it, how would you make it easier to find it?
This suggestion came from Open Refine community support.
I understand the query section and result section are separate. It's OK, but as a matter of taste, people like me would prefer to have query and results as a pair, because you can try the query and see the results together, when testing them. If they are separate and the examples of query and results do not correspond each other, it might be confusing. I don't know the best way, but it would be a good idea to show some kind of connections between the examples in the query and result section.