Proposal: Enable use of undocumented features

[hyperupcall]

Description of the feature / enhancement.

I have observed that there seems to be an unwritten rule that all fields within the schema must be documented, because if the feature is not documented there is higher potential for the feature to be suddenly changed or removed.

I have encountered such incidents through #3175, and more recently through #3367. Although well-intentioned, this policy can break down when our schemas are used in places like megalinter. If a file contains undocumented features (which are not included in the JSON schema), it will fail linting. Additionally, if a JSON config works, but our schema says it's invalid, it can be very confusing. I think schemas should aim to be as accurate as possible, correctly validating what exists and works in the Real World.

I created this issue to gather feedback and document the changes in how we accept schema contributions (if accepted). I propose to change the "policy" so that:

1. It is now permitted to add undocumented features to the JSON Schema
2. If a feature is undocumented, its "description" or equivalent field must begin with UNDOCUMENTED. to make clear its stability. if that is not possible, then a note should be added in a $comment

This change both addresses the "sudden undocumented changes" and "does not pass linting" concerns. Down the line, it may be worth considering adding an actual "x-stability"-like field to the schema itself, but I wanted to keep things simple and straightfoward for now.

cc @madskristensen @GerryFerdinandus - looking for approval for these changes / your thoughts

Are you making a PR for this?

No, someone else must create the PR.

[madskristensen]

That's a great idea. I love it