JSON documentation from API responses and system hooks

When developing the Haskell library for the GitLab API (Rob Stewart / gitlab-haskell · GitLab), my approach was trial and error to understand the optional and mandatory fields in the returned JSON objects, as well as the nature of each JSON field e.g. nested JSON objects, strings, integers, etc. I.e. I made some GitLab API calls, inspected the JSON, then wrote JSON parsers for those examples.

The API documentation always gives examples, e.g. Projects API | GitLab . That is, for each API resource address there’s a JSON example given, but I’m never sure if that’s the structure for all possible queries e.g. with different levels of permissions with my access token, or just an example.

For example the documentation for

GET /projects


only public projects with “simple” fields are returned.

Are the “simple” fields (i.e. the fields that will always be present) documented somewhere? And are the optional JSON fields for each API response documented somewhere?

This question also applies to the system hooks functionality. There is a JSON example for the system hook when a project is created, here: System hooks | GitLab

To build a file hook, will I need to do this by trial and error for different events ( project_create, user_update_for_team etc) to get a feel for the JSON returned. Or is there documentation for simple/optional fields in the JSON, any nested JSON objects in the returned JSON for each event?