[configuration] Clarify that the boolean value environment variable guidance is not applicable to other configuration interfaces

[mx-psi]

Updates #4344

Changes

Clarifies that environment variable guidance regarding boolean values is not applicable to other configuration interfaces. This does not explicitly state what the guidance should be in other cases.

[dashpole]

I agree with the intent of the change, but it seems like it will create more confusion to me, as it implies (but doesn't specify) that the rest of the document applies to declarative configuration. I would prefer splitting the env var spec into a "common" config spec (excluding the boolean spec), and the env var spec with the current bool spec + anything else that only applies to env vars.

[mx-psi]

Makes sense, I will wait for a few more days and apply the suggested change if there is no dissent :)

[mx-psi]

I agree with the intent of the change, but it seems like it will create more confusion to me, as it implies (but doesn't specify) that the rest of the document applies to declarative configuration. I would prefer splitting the env var spec into a "common" config spec (excluding the boolean spec), and the env var spec with the current bool spec + anything else that only applies to env vars.

@dashpole I pushed an attempt to split the guidance:

1. I renamed "configuration type" to " Type-specific guidance"
2. I moved type-specific guidance that is not applicable to env variables into a new common.md document. I kept in the SDK env variables one:

• The guidance about boolean variables
• The guidance about fail to parse for numeric variables (I assume failure to parse is going to lead to an error and not a warning in implementations since it will be handled by the JSON/YAML parsing library)

Other parts of the spec were using these sections as "here are the type definitions" and now the links for "type definitions" are split among two documents. We were never too consistent with this, so I feel like it is okay to do this

[trask]

cc @open-telemetry/configuration-approvers

[jack-berg]

Couple small comments but I agree with the direction 👍

[jack-berg]

"via any source in this specification" What does this refer to? The other configuration interfaces?

[jack-berg]

It appears that this sentence was adapted from the env var spec:

Implementations MAY choose to allow configuration via the environment variables in this specification, but are not required to. If they do, they SHOULD use the names listed in this document.

In which case, "source" refers to a data type?

[mx-psi]

Any 'configuration source' was the intended meaning. Do you have suggestions on how to reword this to make it clearer?

[mx-psi]

I added 'configuration' to that sentence let me know if that is clearer

[jack-berg]

This might not be possible in declarative config. In JSON schema, an enum type is specified as part of the schema (for example). The validation of a config file's adherence to the schema is often done with 3rd party JSON schema tools, and since there is no way to specify a case-insensitive enum in JSON schema, there's (likely) no way for the 3rd party JSON schema tools to ignore case.

Case insensitive enums are also problematic for the programmatic config interface.

Consider moving this back to the env var specific section.

[mx-psi]

Should I also move the sentence that says:

When reporting configuration errors, implementations SHOULD display the original
user-provided value to aid debugging.

It seems to be there only because of the case in-sensitiveness and I think it is hard to apply in all contexts (does it mean that if I set a: "foo" I should get a different message than when I set a: 'foo' or a: !!str foo?)