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

Markdown language provider #414

Open
mwadams opened this issue Aug 31, 2024 · 1 comment
Open

Markdown language provider #414

mwadams opened this issue Aug 31, 2024 · 1 comment

Comments

@mwadams
Copy link
Contributor

mwadams commented Aug 31, 2024

It would be useful to be able to create markdown documentation from JSON Schema.

There are other (excellent) tools in the wild but they have a number of deficiencies or limitations, including one or more of:

  1. They don't provide universal tools that "just work" on Windows/Linux/MacOS without a containerload of dependencies
  2. They don't support all keywords in all drafts from Draft 4 to 2020-12.
  3. They don't link back to canonical documentation
  4. They don't allow you to add additional documentation in external files to target particular schema or elements within the schema (if you are not the owner of the schema itself.)
  5. They don't perform semantic analysis on the types, allowing us to document common patterns e.g. tuple, strongly-typed map, strongly-typed array.

In order to support this we should

  1. Create a MarkdownLanguageProvider implementing ILanguageProvider
  2. Refactor the unnecessary "capabilities" out of ILanguageProvider in the same way as IHierarchicalLanguageProvider so that we don't need NOP implementations of things we don't need (like validation).
  3. Create the provider's Options type that gives us the ability to provide external documentation files
  4. Add a canonical documentation uri to the IKeyword interface (or possibly to a new "documented keyword" interface, and link to the appropriate docs. e.g. https://www.learnjsonschema.com/2019-09/, https://www.learnjsonschema.com/2020-12
  5. Implement the single code file provider
    i. Title
    ii. Description
    iii. Semantic detail
    iv. keywords by classification (e.g. applicator, validation), with hyperlinks to the relevant schema
@mwadams
Copy link
Contributor Author

mwadams commented Sep 2, 2024

There are two motivations to provide this:

  1. To encourage better schema documentation and understanding
  2. To illustrate how to build a custom language provider leveraging the output of the type analysis.

The MD provider does not need to support hierarchy, validation or naming, so it is comparatively simple.

But we can illustrate how we can make the provider extensible so it can support new capabilities.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant