specs

specs copied to clipboard

Closes #33. Part of #84.

This removes the use of arbitrary keys in JSON objects. As a result we are no longer using "patternProperties" in our own JSON schemas. This is obviously a big breaking change, which I intend to bundle with other breaking changes related to #84 (such as #91).

I made some choices in the process, and they are debatable:

• for reconciliation queries and responses, I propose to just have an array of queries and an array of responses, with order being preserved. One could keep the use of unique ids to identify queries and responses, but I feel like this is a bit heavy and not needed.
• for data extension responses, I went for a slightly heavier format, where the identifiers of the entities and properties are explicitly included. One could have also have relied on the order in the original query, but it felt a bit harder to read and generate in this context. But that is really a matter of aesthetics.

This looks like a good step in roughly the right direction. What I dislike is the use of top level arrays in JSON, instead of objects. The main argument against this is the lack of extensibility - you cannot easily add more fields later (see e.g. this blog post and this SO discussion).

For the queries, instead of [ query1, query2, query3... ], I suggest this:

{
  "queries": [ query1, query2, query3... ]
}

and similarly for the responses:

{
  "responses": [ response1, response2, response3... ]
}

This would allow adding new fields later (e.g. related to count of results or paging) if that becomes necessary.

That makes a lot of sense! I have just fixed that following your suggestion. Let me know if you can think of anything else.