vsf-tv / gccg-api

Draft API for the Ground-Cloud-Cloud-Ground Working Group: https://vsf.tv/Ground-Cloud-Cloud-Ground.shtml
BSD 2-Clause "Simplified" License
4 stars 2 forks source link

Consider separating JSON for connection and payload #18

Closed pac-work closed 5 months ago

pac-work commented 7 months ago

Reuse of the same JSON structure for both the connection and as the description accompanying actual data seems ambiguous. Some fields are related to the current state and are relevant for the payload JSON and do not seem to be relevant for the connection phase. These two JSONs should be separated and clearly defined using JSON Schema or similar mechanism (mandatory vs. optional fields, etc.). Not doing so will result in different implementations by different vendors not being compatible. I see it improved since my last reading - now the text contains some information regarding this, but still not exact enough. Separation on the GitHub page in the README.md would help a lot.

Examples:

mhhen commented 6 months ago

Will remove the JSON from the README.md and reference new JSON schema files as described below:

connection_schema.json - Schema used by the connection APIs - GccgTxConnectionCreate() and GccgRxConnectionCreate(). ret_connection_schema.json - Schema returned after invoking the connection APIs. payload_schema.json - Schema used by the GccgTxPayload() and GccgRxCallback() APIs.

pac-work commented 5 months ago

Thank you very much, the schemas are great improvement.