Document complete schema for `firebase.json`

[samtstern]

Originally suggested by @matheo here:
#1303 (comment)

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 ...

[jthegedus]

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?

@samtstern Yes, JSON Schema is the most standard way to support autocomplete in editors. IntelliJ uses this by default and VSCode can have support added by individual extensions as @george43g shows or by using popular plugins like the RedHat YAML plugin which pulls from JSON Schema store and provides both YAML and JSON autocomplete for all available schemas.

[sshquack]

Came here form #2233 (comment) Currently it very confusing to piece together globs of json from multiple locations without knowing the source of truth. Here are some of the scattered configs from the docs for reference:

https://firebase.google.com/docs/cli#the_firebasejson_file
https://firebase.google.com/docs/hosting/full-config#firebase-json_example
https://firebase.google.com/docs/hosting/full-config
https://firebase.google.com/docs/functions/manage-functions
https://firebase.google.com/docs/hosting/test-preview-deploy

Also as @jthegedus pointed out JSON schemas for popular plugins are embedded in IntelliJ (see https://www.jetbrains.com/help/idea/json.html#ws_json_using_schemas) using SchemaStore (see https://www.schemastore.org/json/)

It would be very beneficial to have the full firebase.json schema documented for developer productivity.

[jthegedus]

I'd like to add, having a utility function that validates a Firebase configuration would also be helpful (whether by the json schema or otherwise). I implemented a tool recently that reads a provided Firebase config and needed to implement a large Joi validation to check to ensure when Firebase Hosting rewrites to a Cloud Funtion that the functions config exists and is valid. It was painful and probably full of bugs.

Additionally, it appears there are multple places in this repo where functions are validated but with different rules.