Define a JSON schema for appsettings.json

[natemcmaster]

As we start to write more config binders for framework components, it becomes increasingly difficult for developers to discover settings that can be set in static config files. Documentation helps, but it would be even better if we could provide intellisense in the editor. Although config can be loaded from JSON, INI, XML, environment vars, and more, our new project templates and many apps use "appsettings.json" as a convention. It would be nice to provide a JSON schema file that includes common aspnetcore settings.

Usage
Users can reference a schema by adding the $schema property to their JSON file.

{
    "$schema": "https://somethingofficial.com/appsettings.schema.json"
    // the rest of the config there
}

Autocomplete
VS Code and VS already provide autocomplete and doc tooltips for JSON schema.

[Eilon]

@shirhatti - as the proud owner of config, I've assigned this to you.

[Eilon]

@shirhatti - any plans for this issue?

[shirhatti]

Thanks for pinging me on this. It had slipped my radar.

[KevinMarquette]

@shirhatti I have a basic schema for appconfigs that could be used as a starting point. I'm not sure where the best place would be to add it. Any suggestions on where this should live?

[vindicatorr]

I peek in at dotnet every now and again to see where things stand and one great thing about it is the ability to change the appsettings.json and have it reload after the change.
It's much better than hardcoding little parameter/argument/value changes and rebuilding.

With that said, yes, the lack of intellisense/auto-completion for the csproj and json files are the absolute killer for me.
It's bad when I look at the documentation for Kestrel, where it shows an example appsettings.json, and not know where those settings/keys even come from, or how it has to be structured, or what other options I may have available to me.
A specific example IN that kestrel example is the "HttpsInlineCertStore" section which cannot be found if I try to look it up in the ".NET API Browser".

Another example is the "UserSecretsId" in the "PropertyGroup" of the csproj. I would only know how to use it solely by the example given.
I wouldn't know if the "UserSecretsId" is meant to be used in that PropertyGroup as opposed to somewhere else, or if it would need more structure like "<Microsoft.Extensions.Configuration.UserSecrets.UserSecretsId>" or

<Microsoft>
    <Extensions>
...
        ...<UserSecretsId>

As an aside, while that ".NET API Browser" is absolutely fantastic, it would truly be wonderful if we could do it offline with the libraries that already exist on our system.
For example, I'd love to be able to use the "Outline" in Visual Studio Code to browse through external references like System.
If that's something I can post about somewhere more applicable, do let me know.

[shirhatti]

@vindicatorr Can you please open a new issue for what you're requesting? Completions in your csproj is orthogonal to what is being discussed here, but a valuable feature in it's own right.

[vindicatorr]

It doesn't look like a new issue is needed for the csproj auto-completions in general.

I see it has already been brought up in various places like dotnet/msbuild#2787

I also found https://github.com/tintoy/msbuild-project-tools-vscode in the marketplace (note "msbuild" referenced in both locations, showing it isn't an aspnet issue). And while there was A LOT of intellisense stuff going on in the csproj after installing it, the "UserSecretsId" never showed up and the closest thing was "GenerateUserSecretsAttribute" which didn't do anything.

[sliekens]

On topic: json schema doesn't work well with the way settings are merged. I found it's impossible to make a property required in appsettings.json but optional in appsettings.Development.json or vice versa.

[analogrelay]

I don't think we'd make any properties required in our schema. It's just for discoverability. appsettings.json is just one of many possible ways to specify config and it's totally viable to have some settings in appsettings.json, some in appsettings.Development.json, some in environment variables, etc.

[masaeedu]

While this is still being designed, I just wanted to say I actually do want to use it to make settings required. The problem right now is that we have a sprawling system of docker microservices with parameters being set through env vars, appsettings files, etc. This means there's a great deal of diligence required when adding to or modifying the configuration a service depends on; checking whether you're actually passing the right things to all services is hard to automate.

I would ideally like to be able to specify the complete set of inputs, required and optional, for a service as a appSettings.schema.json or whatever, and then be able to calculate whether the combination of:

• the environment
• the appSettings.json file
• any applicable appSettings.whatever.json files

actually ends up satisfying the schema.

If this overall set of provided values doesn't satisfy the schema (including missing values for required properties), I want to be able to tell at an early stage, ideally as a linter over our deployment configs. At the least it should be possible to get the service to refuse to start if the provided configuration doesn't match the schema, so you can detect problems as dead containers.

[masaeedu]

I might have misunderstood the comment above though; if you're saying all the built in settings would be optional, that makes sense. 👍

[analogrelay]

I'm just talking about how we'd structure a JSON schema file. The schema file is just designed for IntelliSense in this case and we'd only put our "built-in" settings in it. Config validation in general, would be a separate feature.

[sliekens]

If the issue is discoverability of settings, didn't NuGet already solve that problem with config transformations? Having both would still be better of course. 😉

[tdreid]

It becomes increasingly difficult for developers to discover settings that can be set in static config files.

Indeed. Several hours deep on this for Kestrel here. Partial examples are fairly easy to find. Some further settings can be intuited from the shape/documentation of the configuration providers. But that just as often leads me astray

Documentation helps

@natemcmaster @shirhatti Until the schema(s) are in place to improve discoverability what's currently the most comprehensive source to determine settings that can (or can't) be set in static config files for kestrel?

So far the following seems to be the best resource. But I'm not confident that it covers everything that can be set, nor every way that any particular setting might be set. I could be wrong.

• https://docs.microsoft.com/en-us/aspnet/core/fundamentals/servers/kestrel?view=aspnetcore-3.0

Thanks!

[0xced]

I just lost so much time because I tried to configure the urls with an array instead of a semicolon-separated string in my appsettings.json file.

❌ Don't use an array for the urls key:

{
  "urls": [ "http://localhost:4999" ]
}

✅ Use a (semicolon-separated) string for the urls key:

{
  "urls": "http://localhost:4999"
}

A json schema would certainly have prevented this error!

(Also, no error and not even a warning log for using the wrong type, the server just started on the default http://localhost:5000 address!)

[0xced]

Apparently, there's some effort to create a JSON schema for appsettings.json at https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/appsettings.json but it currently lacks ASP.NET Core standard configuration keys such as urls.

[ghost]

Thanks for contacting us.
We're moving this issue to the Next sprint planning milestone for future evaluation / consideration. We will evaluate the request when we are planning the work for the next milestone. To learn more about what to expect next and how this issue will be handled you can read more about our triage process here.

[JamesNK]

Done 💪

https://twitter.com/JamesNK/status/1346253986647588864