Just take a look at the gitlab ci reference. It is huge. And there are competing features in there that are intended to "deprecate" the older feature but this doesn't happen. They are also constantly held back on providing backwards support. For instance, adding dpeendency-like flow as opposed to stage based flow has been added but it's not possible to model dependencies from same stage making the whole thing kind of useless.

Versioning the yaml specs/apis is the correct move. I hope future CI systems take note.