Have you looked at Swagger's IDL?

The big problem with an IDL that people want to avoid is tight coupling, IOW, all systems have to be upgraded at once to use a change in API.