Human URL, Machine URL

[OriPekelman]

Both attributes are ambiguous. This is about documentation. I imagined MachineURL to be the initial entry point of the API.

Please think about the Hypermedia crowd where the API is the "Machine Readable" documentation.

        "documentation":{
        "humanURL": "https://api-commons.3scale.net/docs",
        "machineURL": "http://api.apicommons.org/swagger-spec.json"
        },

Please consider some API provider will provide multiple metadata / documentation formats.

Better provide an array of entry points. Which you basically have with the "urls" element. But better call this links and instead of "URL" use the more common "href" attribute name. Something like

 "links":
 {
   "documentation":
   [
     {
       "type":"text/html",
       "href":"https://api-commons.3scale.net/docs",
       "title":"Human readable docs",
       "titles":
       {
         "en-us":"Human readable docs",
         "fr-fr":"Documentation à visée humaine"
       }
     },
 {
       "type":"application/json+swagger",
       "href":"https://api-commons.3scale.net/docs",
       "title":"Swagger formatted documention",
       "titles":
       {
         "en-us":"Swagger format docs",
         "fr-fr":"documentation en mode swagger"
       }
     },