Support for $ref tags/JSON schema in extension's package.json

[bryceitoc9]

I work on a VS Code Extension, and I'm following up on #95033 . It looks like this issue was caused by the fact that we were using a $ref field within the package.json manifest. This appears to be an invalid use of package.json, given the unusual behavior shown in #95033. Could you please explain whether or not this is valid in package.json?

To offer some insight, we have embedded a JSON Schema into the debugger contribution point. The motivation was to use a code generator against the JSON schema to ensure the extension code remains in sync with the structure defined in the manifest. If this scenario is not valid, we'd be interested in hearing a recommended way to keep the manifest and code structures in sync.

Thanks in advance!

[weinand]

@isidorn @aeschli we are combining the json schemas from all debuggers into a single schema and then use this for the launch.json editor. Are there any limitations what this schema can use? Or are we merging the fragments in a problematic way?

[isidorn]

Well the issue is probably due to the $ref field as @bryceitoc9 suggests.
@aeschli do you treat this $ref special in the json schema land? Was it always like this?

[aeschli]

$ref can not be used in such schema fragment as the path is resolved against the composed schema that users don't know how it looks like and should not know.
Maybe in the future when we support using $id in $ref (#92042) this can be allowed.

[aeschli]

Not a bug but a feature request.

[awschristou]

It sounds like there is a restriction to not have $ref fields (and maybe embedded json schemas?) within the package.json file. Is this documented somewhere?

[aeschli]

@weinand This needs to be documented with the debuggers contributions point.
We already do the same for the configuration contributions point: https://code.visualstudio.com/api/references/contribution-points#Configuration-property-schema
(implicitly, by describing what is supported)

[matepek]

(implicitly, by describing what is supported)

From the site: https://code.visualstudio.com/api/references/contribution-points#Configuration-property-schema

Configuration keys are defined using a superset of JSON Schema.

You can use any the properties defined by JSON Schema to describe other constraints on configuration values.

Without ref I cannot define a recursive schema.

Do I miss something?😏

[aeschli]

You can only use other properties that define a constraint.

I made this more explicit: microsoft/vscode-docs@7108f81

[bwateratmsft]

The Docker extension has a substantial amount of repetition in its package.json; this would be a very nice feature to have.

[bwateratmsft]

Update since some folks might be interested. I found a rather hacky way to accomplish this--I tried it for settings but it may also work for tasks/launch configs as well. Please note, it only helps with the settings JSON editor, not in the settings UI (which will simply send you to the JSON).

You can use "$ref" if you feed it an absolute URI to a schemas file, but the scheme for that URI can be anything. It seems internally VSCode uses vscode://, for example. By registering a FileSystemProvider with a custom scheme (let's say, myschemas://), I was able to reference schema files from package.json and get working validation / autocomplete / etc.

Basically what I did is:

1. Add an activation event in package.json, "onFileSystem:myschemas"
2. Register said filesystem provider: vscode.workspace.registerFileSystemProvider("myschemas", new MySchemasFilesystemProvider())
3. Implement just stat and readFile on MySchemasFilesystemProvider, using the extension install directory as the root (so your schemas.json file can be adjacent to your package.json)
4. Have settings that use "$ref": "myschemas:///schemas.json#/definitions/mycomplexobjectdefn"

If there is already some built-in FileSystemProvider for getting at extension files, steps 1-3 could be skipped, but I'm not aware of one.