build-tools icon indicating copy to clipboard operation
build-tools copied to clipboard

any_of markdown output is misleading if each set only has one member

Open Oberon00 opened this issue 4 years ago • 3 comments

E.g. see https://github.com/open-telemetry/opentelemetry-specification/blob/v1.0.1/specification/trace/semantic_conventions/database.md#connection-level-attributes

Additional attribute requirements: At least one of the following sets of attributes is required:

  • net.peer.name
  • net.peer.ip

Obviously the set here is {"net.peer.name", "net.peer.ip"}, so you need both. Except: This is wrong! There are two sets, one contains only net.peer.name and the other only net.peer.ip.

I think if each set contains only one member, the text above the list MUST change to "At least one of the following ~~sets of~~ attributes is required:" (without the ~~sets of~~).

Oberon00 avatar Mar 01 '21 08:03 Oberon00

I am not a native speaker, so I cannot judge properly which is the best phrase to use here. Would you also remove "sets of" in the case where multiple attributes are listed? An example of this is in the HTTP Client semantic convention:

Additional attribute requirements: At least one of the following sets of attributes is required:

  • http.url
  • http.scheme, http.host, http.target
  • http.scheme, net.peer.name, net.peer.port, http.target
  • http.scheme, net.peer.ip, net.peer.port, http.target

thisthat avatar Apr 07 '21 11:04 thisthat

I think if at least one set has more than one member, the current phrasing is clear and in these cases I would keep it as-is.

Oberon00 avatar Apr 07 '21 12:04 Oberon00

Related: #293

lmolkova avatar Mar 12 '24 06:03 lmolkova

Closing this since we no longer support constraints - 310

lmolkova avatar May 30 '24 23:05 lmolkova