(PUP-9747) update bolt transport key description

* Emphasise source of design constraint
* Emphasise recommendation to use these keys when applicable
* Add `password` key following feedback from the bolt team
* Add note on bolt behaviour of `uri` vs `name`

Author: DavidS

language/resource-api/README.md

@@ -432,23 +432,26 @@ Password attributes should also set `sensitive: true` to ensure that the data is
 
 #### Schema
 
-A transport schema accepts the following keywords:
+To line up with [bolt's inventory file](https://puppet.com/docs/bolt/latest/inventory_file.html), a transport schema should prefer the following keywords when relevant:
 
-* `uri`: use when you need to specify a specific URL to connect to. All of the following keys will be computed from the `uri` when possible. In the future more url parts may be computed from the URI.
-* `host`: use to specify an IP or address to connect to.
+* `uri`: use when you need to specify a specific URL to connect to. Bolt will compute the following keys from the `uri` when possible. In the future more url parts may be computed from the URI.
 * `protocol`: use to specify which protocol the transport should use for example `http`, `https`, `ssh` or `tcp`.
-* `user`: the user the transport should connect as.
+* `host`: use to specify an IP or address to connect to.
 * `port`: the port the transport should connect to.
+* `user`: the user the transport should connect as.
+* `password`: the password for the specified user.
 
 Do not use the following keywords when writing a schema:
 
+* `implementations`: reserved by Bolt.
 * `name`: transports should use `uri` instead of name.
 * `path`: reserved as a uri part.
 * `query`: reserved as a uri part.
-* `run-on`: This is used by Bolt to determine which target to proxy to. Transports should not rely on this key.
-* `remote-transport`: This is used to determine which transport to load. It should always be the transport class named "declassified".
 * `remote-*`: any key starting with `remote-` is reserved for future use.
-* `implementations`: reserved by Bolt.
+* `remote-transport`: This is used to determine which transport to load. It should always be the transport class named "declassified".
+* `run-on`: This is used by Bolt to determine which target to proxy to. Transports should not rely on this key.
+
+> Note: Currently bolt inventory requires that a name be set for every target and always uses that name as the URI. This means there is no way to specify `host` separately from the host section of the `name` when parsed as a URI.
 
 #### Implementation