Thanks much for your reply. Surely it will help to begin my work :). But would like to know is this spec will be maintained going fwd with the release version? My concern is our product will be dependent on these metadata :).
It will be definitely maintained but it is not guaranteed to be immediately consistent with released versions. Documentation and Developer Portal interactive tools update cycle is decoupled from Sandbox and Production update cycle. Also there may be different versions of API deployed in Sandbox and Production. So this topic is pretty complicated.
If you can share your use case I may try to suggest the best possible solution.