JSON schema instead-of/for the Configuration File

[MahdiBM]

Description

There should be a JSON schema file for the sourcekit-lsp Configuration File.
Then we can integrate it with editors, perhaps in extensions like the Swift VS Code extension.

Note: VS Code only support JSON schema format up to draft-07 version.

[ahoppen]

Synced to Apple’s issue tracker as rdar://140037971

[MahdiBM]

There may be a need for sourcekit-lsp CLI to show that schema.

Then I assume there would be a way for the VS Code extension to instruct VS Code to use that schema info for the sourcekit-lsp configuration file.

Perhaps sourcekit-lsp should itself output a dictionary of keys of glob patterns and values of json schema so the VS Code extention can just use that.

[ahoppen]

Do you know if there is a way to ingest a JSON schema into editors eg. from a Swift toolchain that’s installed on your system?

[MahdiBM]

@ahoppen see swiftlang/vscode-swift#1208.

We need to include the JSON schema file's URL in the package.json file of the VS Code extension.
That URL should probably point to swift.org and swift.org can just fetch it from this repo. Or that URL can just directly be pointed at this repo but then we won't be able to move the file around etc... .

I think the most correct way would be for the VS Code extension to point to the current sourcekit-lsp version's JSON schema file, but that'll be a lot harder, and I don't see other extensions like rust-analyzer bothering themselves with that.

[MahdiBM]

rust-analyzer's JSON validation URLs point at https://schemastore.org/.

It's probably a good idea for use to go that way as well.
It'll also enable free JSON validations for those not using the Swift VS Code extension, who only have that specific schemastore VS Code extension installed.

Unless you think there are security concerns.

[MahdiBM]

Digging more into this, I noticed that rust-analyzer doesn't seem to store the schema in their repo.
I think they are auto-generating it in someway from the actual object, and submitting it to schemastore in another way (didn't find an automation for the submission, but not sure).
I haven't investigated this throughly, but we could use a project like ajevans99/swift-json-schema to autogenerate the schema from the configuration object 🤔

[MahdiBM]

@ahoppen both ways look fine to me and have their own advantages.
We could go with a good ol' boring manually-created JSON schema file and try to manually keep it up to date.
Or we could try to give that swift-json-schema package a try.

What do you think? Will the dependency be worth it?

Actually now that I think more, you probably don't want to pull the whole swift-syntax in here due to the build problems it causes?

[ahoppen]

Thanks for your analysis, @MahdiBM. My preference would be to include the JSON scheme in the toolchain and make the VS Code extension pick up the schema from the toolchain you have currently selected. That way, the IDE assistance exactly matches the SourceKit-LSP you have installed.

I would prefer to not pull in an external dependency to SourceKit-LSP’s build. If it’s possible to write a script (probably based on swift-syntax) that generates the JSON schema (and while at it maybe also Configuration File.md) from the SourceKitLSPOptions.swift, I think that would be the best solution. We could then add a phase to Swift CI that ensures the committed files match what would have been generated. We do a similar trick with swift-syntax’s CodeGenration package. What do you think?

[MahdiBM]

Thanks to @kateinoigakukun for getting the bulk (or whole?) of the work done in #1849.

I just noticed that PR and wanted to sync this issue with the new state of the things.

[A Few Moments Later ...]

I'm trying the schema file but I'm getting this error. @kateinoigakukun 🙂

[kateinoigakukun]

@MahdiBM Could you try https://raw.githubusercontent.com/swiftlang/sourcekit-lsp/refs/heads/main/config.schema.json instead?

[MahdiBM]

@kateinoigakukun ahh right, thank you. That did solve the problem. I see I used the GitHub page link before, instead of using a raw file link ... my bad.

The error there also didn't help. Thought there is a legitimate parsing issue.