rfc-healthcheck icon indicating copy to clipboard operation
rfc-healthcheck copied to clipboard

Fix text describing the checks object key

Open smoyer64 opened this issue 5 years ago • 0 comments

In the The Checks Object section, the second paragraph reads:

The key identifying an element in the object SHOULD be a unique string within the details section. It MAY have two parts: “{componentName}:{measurementName}”, in which case the meaning of the parts SHOULD be as follows:

The first sentence of this paragraph should be changed to read (emphasis only to highlight the changes):

The key identifying an element in the object ~~SHOULD~~MUST be a unique string within the ~~details~~checks section.

The JSON structure that this specification describes will fail in many linters and languages if the keys are not unique. The linters I tried all show a duplicate key error. When marshaling and unmarshaling in Go or Java, there doesn't seem to be validation to reject the duplicate keys so the first item with the duplicate key is simply overwritten when the second duplicate key is encountered. I know the JSON specification doesn't explicitly state that duplicate keys aren't allowed but even in the underlying JavaScript, duplicate keys are almost certainly an error

I'm currently working on implementing this specification in Go and the bigger issue is with the second sentence - there is no way to tell a {componentName}:{measurementName} from a simple unique string. The following ambiguities occur:

  1. Since both componentName and measurementName are optional, you might end up with a composite key of either ```` or : - both an empty string and a colon are valid keys in JSON but I think those should be avoided.

  2. If only a componentName is present, should the colon be appended to this value?

  3. If only a measurementName is provided, should the colon be prepended to this value?

  4. If the answer to ambiguities 2 and 3 is no, how do I programmatically tell the difference between a simple string and a composite key that only contains a componentName or measurementName?

  5. How do I programmatically tell the difference between a simple string that happens to contain a colon (or more than one colon) and a composite key?

In general, I think I like the idea of a key that has a semantic meaning so I'm in favor of continuing with the idea rather than just stating the key is a unique string.

smoyer64 avatar Apr 10 '19 14:04 smoyer64