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.

[samtstern]

If anyone is still waiting on this, you can check out a JSON Schema for firebase.json here:
https://github.com/firebase/firebase-tools/blob/master/schema/firebase-config.json

This is just our first attempt to define the schema officially so it's possible that there are some configurations allowed in the real world that disagree with that file, please let me know if you find anything like that!

Right now if we find JSON schema errors it's only exposed in firebase-debug.log but in a future CLI version we will make those more visible.

[jthegedus]

This is a great step @samtstern cheers!

A use case that I am not sure JSON Schemas can cover is when a rewrite rule is defined to rewrite to a function, but the functions field is missing. I guess the default values for the functions object would be used 🤔 So I guess the request would be to the ability to parse a config that:

1. validates a provided config against the JSON schema
2. returned the computed config. That is, the config combined with the defaults.

Currently even if I were to use this JSON Schema (and I will) to validate a config, I still have to hardcode the default values in my tool, like config.functions.source = "functions".

[samtstern]

@jthegedus yeah the implicit defaults for products like Functions are definitely a bit of a problem here.

Can you explain why you'd need to hardcode config.functions.source = "functions"? The config is valid without that.

[jthegedus]

Sorry, that example goes back to my prior comments above.

I've built svelte-adapter-firebase which parses a users firebase.json file. If they define a rewrite rule to a function, I need to then parse their functions entrypoint, which requires knowing functions.source or fallback to the default value defined in firebase-tools. So my tool hardcodes the default location of ./functions/.

firebase-tools CLI is run after my tool. As a plugin for SvelteKit it runs during app build, so I have to parse the config myself to ensure it has a valid configuration before this tool is even executed. It would be great if this tool provided a parser, similar to other IaC CLIs/APIs/Packages like https://github.com/architect/parser , that not only validated, but returned the computed final config with the defaults and all if omitted in the input config.

---

Some missing items from the schema (I realise it is a first release):

• site for Hosting
• target for RTDB, Storage, Hosting
• hosting.rewrites[].run.region can only be us-central1 (not sure if string literals can be enforced here)
• hosting is valid as both an object and array
• predeploy/postdeploy for most resources
• predeploy/postdeploy are valid as both string and array of strings.
• functions.runtime

[jthegedus]

An alternative to my above suggestiong would be to have all the default config values defined in a single JS object so consumers could object spread computedConfig = {...defaultConfig, ...providedConfig}. Last I checked the defaults are spread throughout the source code and difficult to find. As are the validation checks.

[samtstern]

@jthegedus wow good eye! If you want to update the schema, you could send a PR here. The TypeScript is the source of truth:
https://github.com/firebase/firebase-tools/blob/master/src/firebaseConfig.ts

I agree we need to centralize the defaults. One of the issues is that they're a bit context dependent! For instance it's not true to say that the default for functions is { source: "functions" } because actually we only consider that default if you run a functions-specific command and we detect a functions/package.json file. So it's a bit of a mess!

[jthegedus]

For instance it's not true to say that the default for functions is { source: "functions" } because actually we only consider that default if you run a functions-specific command and we detect a functions/package.json file. So it's a bit of a mess!

In the context of my usage I only look for functions if I first detect a Hosting Rewrite Rule that rewrites to a function, then I perform the lookup of functions.source or fallback.

The context-dependent implementation does make this difficult.

[zanona]

It would be great if you could allow the $schema field on the JSON, so we could do this:

firebase.json

{
  "$schema": "./node_modules/firebase-tools/schema/firebase-config.json",
  "hosting": [...]
}

similar to what turborepo does, as it's great for validation.

[junaga]

why is my VS Code complaining?

[o-az]

Pointing to the schema file from firebase-tools repo directly is the most convenient

{
  "$schema": "https://raw.githubusercontent.com/firebase/firebase-tools/master/schema/firebase-config.json",
  "functions": {
    "source": "./"
  },
  // ...
}

[Goldziher]

can you guys publish this?