Firebase-tools: Document complete schema for `firebase.json`

[samtstern]

Originally suggested by @matheo here:
https://github.com/firebase/firebase-tools/issues/1303#issuecomment-502407506

We should document the complete schema of firebase.json in both human-readable and machine-readable formats. This file has expanded a lot and it's not always clear what's there and what the defaults are.

[bkendall]

Related: https://firebase.google.com/docs/cli/#the_firebasejson_file

[long1eu]

Any news on this?

[johnnyasantoss]

Any updates?

The provided link has a section called "The firebase.json file" that is not helpful. I still think that a json schema (like these ones) would be a better way to add documentation to this mysterious file.

[george43g]

so this repo: https://github.com/SirWindfield/vscode-firebase-configuration-schema-plugin

Is a plugin for Vscode that supplies it with a schema for firebase.json

I agree that a schema is needed, at least for autocomplete benefits. That repo is outdated and archived, I do not believe it's maintained. However, it contains a valid and working schema for firebase.json.

PS: I'm tempted to fork the repo and update it... does anyone else want to help out?

[samtstern]

@george43g if you do decide to contribute to that repo I would be happy to review your pull requests (I can't approve them, but I can at least give a Firebase stamp of approval).

We actually have a few different needs around documenting the firebase.json schema:

1. It would be great to have a TypeScript definition for use within this repository, right now it's all a lot of any when dealing with firebase.json
2. We need some way to generate reference documentation for this file to host on firebase.google.com ... we use externs.js files in a lot of places now because our tooling supports it but I don't want to double down on that.
3. We need to give developers like all of you autocomplete support in your editors. I assume JSON Schema is the most standardized way to do this? But maybe not ...