Use normative key words for Asynchronous and Synchronous API paramete…

…rs (#3074)

* Use normative key words for inst API params

Communicate the which parameters are absolute requirement for the
Synchronous and Asynchronous instrument APIs to accept and the other
parameters which are truly optional by using key words adopted by this
specification and defined in BCP-14.

* Update specification/metrics/api.md

Co-authored-by: Joao Grassi <[email protected]>

* Restructure based on PR feedback

* Update specification/metrics/api.md

Co-authored-by: Tristan Sloughter <[email protected]>

* Update specification/metrics/api.md

Co-authored-by: Tristan Sloughter <[email protected]>

* Recommend no validation instead of requiring

---------

Co-authored-by: Joao Grassi <[email protected]>
Co-authored-by: Tristan Sloughter <[email protected]>
Co-authored-by: Joshua MacDonald <[email protected]>

specification/metrics/api.md

@@ -339,12 +339,39 @@ pattern](https://en.wikipedia.org/wiki/Asynchronous_method_invocation).
 
 The API to construct synchronous instruments MUST accept the following parameters:
 
-* The `name` of the Instrument, following the [instrument naming
-  rule](#instrument-naming-rule).
-* An optional `unit` of measure, following the [instrument unit
-  rule](#instrument-unit).
-* An optional `description`, following the [instrument description
-  rule](#instrument-description).
+* A `name` of the Instrument.
+
+  The `name` needs to be provided by a user. If possible, the API SHOULD be
+  structured so a user is obligated to provide this parameter. If it is not
+  possible to structurally enforce this obligation, the API MUST be documented
+  in a way to communicate to users that this parameter is needed.
+
+  The `name` needs to follow the [instrument naming
+  rule](#instrument-naming-rule). The API SHOULD be documented in a way to
+  communicate to users that this parameter needs to conform to the linked
+  syntax. The API SHOULD NOT validate the `name`, that is left to
+  implementations of the API.
+* A `unit` of measure.
+
+  Users can provide a `unit`, but it is up to their discretion. Therefore, this
+  API needs to be structured to accept a `unit`, but MUST NOT obligate a user
+  to provide one.
+
+  The `unit` parameter needs to support the [instrument unit
+  rule](#instrument-unit). Meaning, the API MUST accept a case-sensitive string
+  that supports ASCII character encoding and can hold at least 63 characters.
+  The API SHOULD NOT validate the `unit`.
+* A `description` describing the Instrument in human-readable terms.
+
+  Users can provide a `description`, but it is up to their discretion.
+  Therefore, this API needs to be structured to accept a `description`, but
+  MUST NOT obligate a user to provide one.
+
+  The `description` needs to support the [instrument description
+  rule](#instrument-description). Meaning, the API MUST accept a string that
+  supports at least [BMP (Unicode Plane
+  0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane)
+  encoded characters and hold at least 1023 characters.
 
 ##### Asynchronous Instrument API
 
@@ -355,14 +382,45 @@ order of callback execution is not specified.
 
 The API to construct asynchronous instruments MUST accept the following parameters:
 
-* The `name` of the Instrument, following the [instrument naming
-  rule](#instrument-naming-rule).
-* An optional `unit` of measure, following the [instrument unit
-  rule](#instrument-unit).
-* An optional `description`, following the [instrument description
-  rule](#instrument-description).
-* Zero or more `callback` functions, responsible for reporting
-  [Measurement](#measurement) values of the created instrument.
+* A `name` of the Instrument.
+
+  The `name` needs to be provided by a user. If possible, the API SHOULD be
+  structured so a user is obligated to provide this parameter. If it is not
+  possible to structurally enforce this obligation, the API MUST be documented
+  in a way to communicate to users that this parameter is needed.
+
+  The `name` needs to follow the [instrument naming
+  rule](#instrument-naming-rule). The API SHOULD be documented in a way to
+  communicate to users that this parameter needs to conform to the linked
+  syntax. The API SHOULD NOT validate the `name`, that is left to
+  implementations of the API.
+* A `unit` of measure.
+
+  Users can provide a `unit`, but it is up to their discretion. Therefore, this
+  API needs to be structured to accept a `unit`, but MUST NOT obligate a user
+  to provide one.
+
+  The `unit` parameter needs to support the [instrument unit
+  rule](#instrument-unit). Meaning, the API MUST accept a case-sensitive string
+  that supports ASCII character encoding and can hold at least 63 characters.
+  The API SHOULD NOT validate the `unit`.
+* A `description` describing the Instrument in human-readable terms.
+
+  Users can provide a `description`, but it is up to their discretion.
+  Therefore, this API needs to be structured to accept a `description`, but
+  MUST NOT obligate a user to provide one.
+
+  The `description` needs to support the [instrument description
+  rule](#instrument-description). Meaning, the API MUST accept a string that
+  supports at least [BMP (Unicode Plane
+  0)](https://en.wikipedia.org/wiki/Plane_(Unicode)#Basic_Multilingual_Plane)
+  encoded characters and hold at least 1023 characters.
+* `callback` functions that report [Measurements](#measurement) of the created
+  instrument.
+
+  Users can provide `callback` functions, but it is up to their discretion.
+  Therefore, this API MUST be structured to accept a variable number of
+  `callback` functions, including none.
 
 The API MUST support creation of asynchronous instruments by passing
 zero or more `callback` functions to be permanently registered to the