Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Feature Request] Add official json schema definition for docfx.json and toc.json #8968

Closed
filzrev opened this issue Jul 14, 2023 · 3 comments · Fixed by #9852
Closed

[Feature Request] Add official json schema definition for docfx.json and toc.json #8968

filzrev opened this issue Jul 14, 2023 · 3 comments · Fixed by #9852
Labels
fundamental Engineering system and core components

Comments

@filzrev
Copy link
Contributor

filzrev commented Jul 14, 2023

Is your feature request related to a problem? Please describe.

When editing docfx.json and toc.yml.
It'll be helpful intellisense are supported by default. (It require json schema definition)

Describe the solution you'd like

Add json schema definition files to docfx repository's following directory.

https://github.com/dotnet/docfx/tree/main/schemas
├ docfx.json
└ toc.json

These json schemas should be generated from C# code to minimize maintenance cost.
(with tool like NJsonSchema or JsonSchema.Net.Generation)
and should be tested by CI automatically.

Additional context
There is unofficial schema definition for docfx.json exists.
and schema for toc.yml is discussed at #7736 (expanded and dropdown options are added for toc.json recently)

@yufeih yufeih added the fundamental Engineering system and core components label Jul 15, 2023
@KalleOlaviNiemitalo
Copy link

KalleOlaviNiemitalo commented Jul 17, 2023

How can a JSON schema be generated from C#, for a property whose value can be a string or an object? Like in the file mapping settings.

@filzrev
Copy link
Contributor Author

filzrev commented Apr 8, 2024

There are limitations on automatically generated JSON schemas.
And JSON schema generation from C# code is not recommended for production usage.
https://docs.json-everything.net/schema/schemagen/schema-generation/#schema-schemagen-disclaimer

So I've decided to manually write JSON schema based on generated schema.


Currently It Visual Studio don't supports JSON Schema 2019-09 or later.
It need to write JSON Schema with Draft-07 version for auto completion.

@KalleOlaviNiemitalo
Copy link

There's schema-generation work at dotnet/aspire#3309; but that looks specific to Microsoft.Extensions.Configuration.Binder and wouldn't recognize the JSON-specific attributes that DocFX uses in its configuration classes.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
fundamental Engineering system and core components
Projects
None yet
Development

Successfully merging a pull request may close this issue.

3 participants