JSON schema for `spin.toml`?

[radu-matei]

I would really like to get some documentation and completion support when writing a spin.toml file, and apparently, the Even better TOML VS Code extension lets you do that:

There is a configuration key a user would need to add to get schema support, but I think this would be a really good improvement to the user experience for writing spin.toml files.

[itowlson]

related: https://taplo.tamasfe.dev/configuration/developing-schemas.html#visual-studio-code-extensions (they did this for us so we should get around to making use of it!)

[itowlson]

and indeed https://github.com/fermyon/spin-vscode/issues/2

[vdice]

Is this work still in progress?

[cardoso]

If anyone wants to play, here's a schema auto-generated from Master:

https://gist.github.com/cardoso/24a75d9c7f3b1f9e9a0390d5d3ac08a3

Taplo crashes like crazy with the anyOf that's generated with the old/new schema version enum, so it's better to remove that by hand:

https://gist.github.com/cardoso/03613b5b53ca005fd91d869d3e78f000

#:schema https://gist.githubusercontent.com/cardoso/03613b5b53ca005fd91d869d3e78f000/raw/66e533898e1cd12c61ce6eab8d99678a75f2a8b8/spin.toml.schema.simple.json

name = "spin-sandbox-rust"
spin_manifest_version = "1"
version = "1"
[trigger]
    http = { base = "" }


[[component]]
    id = "spin-sandbox-rust"
    source = "file"
    trigger = { route = "" }

Probably good to keep in mind for #1396 .

[radu-matei]

Ooh, thanks for the schema, @cardoso!

@itowlson — is this something we can use for the VS Code extension?

[cardoso]

@radu-matei yep, just some superficial tweaks to the manifest models to fix some gaps in the hints and it should be good.

You can use the link @itowlson posted above: https://taplo.tamasfe.dev/configuration/developing-schemas.html#publishing

I remember testing that a few months ago and it worked pretty well just by adding the contribution.

I'll see if I can push what I have locally. Would this be better as a build script or a command in the CLI?

[radu-matei]

I think a build script would work well here.

Thoughts, @itowlson ?

[radu-matei]

Having a language server tell me about a wrong spin.toml file is still something I'd love to see.

[lann]

It would be pretty straightforward to manually maintain a schema that covers the trigger-agnostic + common trigger (i.e. HTTP) fields. It would also be possible to build a system into spin that would generate schema semi-automatically from code but Spin's trigger and factor systems make that significantly less straightforward than manual maintenance.

[itowlson]

I recall generating and installing a schema for Even Better TOML / Taplo / whatever it's called, but being dissatisfied with the results when I installed it into VS Code (to the point of frustration). Things have moved on since then, though, so I can take another look.

[cardoso]

@itowlson I had the same experience back when I used schemars to generate the json schema (https://github.com/fermyon/spin/issues/930#issuecomment-1523765443). It was unusable due to a top-level anyOf in the json schema. If you removed that it worked pretty well.

Here's the diff: https://gist.github.com/cardoso/24a75d9c7f3b1f9e9a0390d5d3ac08a3/revisions

This is old and I don't know what the manifest structure look like today, what improvements Taplo and Schemars implemented since, but I doubt it's possible to fully auto-generate a schema that works well.

It probably needs some manual tweaks, the obvious ones being instances of anyOf.

The real deal would be a dedicated LSP for the manifest, but it'd be a seriously overkill project.

[itowlson]

@cardoso Lovely to see you again! Thanks for sharing that - I think that might be the v1 manifest, so the anyOf stuff might be more containable now - I will take a look!

[itowlson]

Having a play around with this now. The v2 manifest schema is causing schemars some problems, because we use a lot more third-party types (toml::Table, wasm_pkg_common::PackageRef, etc.), so we're gonna need to do some with-ing or some newtype-ing or some other shenanigans. I'll maybe try to lash something together even if it's partial, so we can test if the VS Code experience is viable without investing too much in the generation side for now.

[itowlson]

Okay there is a "schema so far" at https://gist.github.com/itowlson/030eca82b43bd3f4abc1c3291e159dd4

Even Better TOML users can try it by adding this at the top of a manifest file:

#:schema https://gist.githubusercontent.com/itowlson/030eca82b43bd3f4abc1c3291e159dd4/raw/23ae665cc76ba3a8d2d3090a431667a58f0b9bdc/gistfile1.txt

You may well need to reload the VS Code window.

This doesn't do trigger-specific fields (such as HTTP route) because it's just generated off the manifest schema, in which triggers are opaque. But in limited testing it seems to provide reasonable popups and validation for most other fields. The handling of untagged enums (e.g. dependencies) is unlovely, but actually less unlovely than I expected.

[itowlson]

Updated with HTTP and Redis triggers. Auto suggest doesn't feel great in the triggers but errors seem to be redlined and it seems reasonably free of false negatives.

#:schema https://gist.githubusercontent.com/itowlson/080922335ea080a185b77a17b9f1eb03/raw/3c24973fbeec3f3c78a1adc34284c235eba6df23/manifest.v2.triggy.json

[radu-matei]

Tried this out just now and it feels great! Thank you for looking into this.

Here's how it looks in nvim + the Taplo language server:

[itowlson]

We are now generating schemas as part of the release workflow (canary and, in time, official versions), and folks should be able to reference the GH release assets in #:schema directives.

I'm closing this as complete - I'm sure there are things that could be better but let's punt those to new issues.