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