Schema vs Doc inconsistency regarding key vs identifier vs id attributes?

[AliSoftware]

The inconsistency

• In the JSON schema, there is a definition for a #/definitions/commonOptions/identifier (whose description is "A string identifier"), that is then used as reference for both attributes id and identifier in steps
• Also, the JSON schema also have a separate definition for #/definitions/commonOptions/key (whose description is "A unique identifier for a step, must not resemble a UUID"), that is used as reference for the key attribute in steps
• Meanwhile, the documentation for command steps (and many other step types, for that matter) mention the attribute key, and that identifier is a valid alias for key, while not mentioning id.

My understanding of the current state

I believe the doc is correct, as it matches the behavior we see in practice.

My guess is that maybe (?) key was named id/identifier a long time ago, but Buildkite changed it to key since, and kept the identifier as an alias for backwards compatibility… while making id private because it would probably now be a generated UUID (the one corresponding to the BUILDKITE_STEP_ID env var value?) instead of a user-provided one. So they updated the docs accordingly… but forgot to fully update the schema in line, only adding a definition for the key attribute but not updating the schema definition to remove id nor to make identifier backwards-compat alias now point to #/definitions/commonOptions/key instead of #/definitions/commonOptions/identifier?

[thejcannon]

Wonder if https://json-schema.org/draft/2019-09/json-schema-validation#rfc.section.9.3 could be leveraged

[thejcannon]

FWIW just tried a pipeline with id: mykey and identifier: mykey and the resulting build has a step whose key was mykey.

Additionally, you're (seemingly) allowed to pass multiple and key takes precedence over id which also takes precedence over identifier.

[thejcannon]

Last bit: all of the above have the same "cannot look like UUID" restriction.

[AliSoftware]

Thanks for the investigation!

I'm surprised that defining a id attribute on a step works (and seems to be an alias for key according to your findings above), especially given that the BUILDKITE_STEP_ID env var is a UUID—while given its name sounds like it would be expected to reflect the value of that id attribute, which you're saying isn't expected to be one according to your tests… 🤔

Clearly some documentation and schema update needed to clarify all that anyway

[thejcannon]

Ok, PR up.

I also made one for the docs: buildkite/docs#3011