Re-build the JSON Schema Implementations page - (Design)

[benjagm]

With the release of the new JSON Schema website, we still have plenty of range of improvement in the Implementations page. A new data-driven page, with filters and more call to actions to add implementations or try bowtie will improve the UX and the impact of this very important page.

Current page: https://json-schema.org/implementations

Inspirations:

• https://tools.openapis.org/
• LFX Landscapes: https://landscape.prestodb.io/card-mode

Live Low-fi Prototype: https://docs.google.com/presentation/d/1cCjQO0tdUqf74iEtYYv7E2dHxYyZbbzL_sEQ1_64W1Y/edit?usp=sharing

Slack thread: https://json-schema.slack.com/archives/CT8QRGTK5/p1697620659557929

[benjagm]

Feedback provided by @Relequestual on Slack:

• For filters
  • When on Desktop, have them across the top, and sticky (stay when you scroll, and not on mobile)
  • For mobile, a filter button which opens an overlay with the filter options (like the main menu)

I don't want to take up more horizontal space. Some implementations have a lot of text, so the small width design might not work.

Should default to only showing draft-07 and above, but make it clear that a filter is enabled.

For categories, we should have some information that details what they mean. How and where we display that data can be discussed.

I know this is more of a technical detail, bot for many of the non-validation implementations, we do not know what drafts/versions are supported. We should have a filter for "unknown" or "undefined".

A link for adding an implementation is a good idea. Where we position that if we choose to put filters horizontally about the content, I'm not sure.

I think having a filter and maybe a column for Bowtie report ("Bowtie report (compliance)") would make sense. We would need to explain what that means.

For the "adding your tool", maybe we want "Something missing/wrong?" to include updates or changes and not just new tools.

Could do:

• We may want to add a filter for licence which is "All OSI approved licences"
• When selecting language/s, show number of results based on other filters (or grey out 0 result options)
• Reset all filters button
• Options in "drafts" to select all "modern" aka draft-07 and up, in one go

Aside: Do we want to say "drafts" or "versions"?
Under versions, we could say "draft-07" etc, but then "2019-09" and "2020-12" without "draft".
Great start! =]

[big-andy-coates]

Hi @benjagm,

What's the plan for the Benchmarks section on the existing implementations page?

I ask as I totally missed there were benchmarks when I was researching which JVM based validator implementation to use (and ended up writing my own).

I know we're moving towards Bowtie:heart: for functional comparison, but the performance comparison these benchmarks provide are also very useful.

Until Bowtie covers performance testing as well, it would be great if the new page could make the presence of these benchmarks more visible.

The new page is data-driven, so maybe there should be a section in the data for benchmarks, which can list the implementations they cover. Then use this to add a column to the table of validators with links to all benchmarks that cover a specific implementation.

The same pattern could be used to highlight any benchmarks the community has written for other sections, e.g. schema generators, etc.

An alternative would be to allow each implementation to list the benchmarks that are available for it. Though we should be careful to not allow implementations to remove unfavourable benchmarks without good cause.

Thoughts?

[benjagm]

Then use this to add a column to the table of validators with links to all benchmarks that cover a specific implementation.

I like a lot you proposal of a Benchmark column with Bowtie and the rest of benchmark tools like yours. I think we can do it and we'll have that in mind when designing the data model and when building the new page.

[Relequestual]

Hey @big-andy-coates. I think I understand what you're asking here. You're asking that, for benchmarking solutions/tools, you'd like for there to be space in the data for listing what implementations have been benchmarked?

The space for columns is pretty limited. Very much open to ideas though.
There aren't many benchmarking solutions. Do you think it would be enough to just add "has benchmark" with a link to the benchmarking section appended to the "about" column data?

[big-andy-coates]

Yes, that would work. Ideally, linking to the correct language section of the benchmarks

[big-andy-coates]

Would be great if it could link to the benchmark section, with it pre-filtered to only the benchmarks that cover it.

Though, given the small number of benchmarks it might not be worth the effort

[benjagm]

Additional requirement captured in the last OCWM #536:

We'll add old implementations to the source datamodel of the new implementers page so we have everything in one single database and we can better tune the data shown in the implementers page.

[benjagm]

Adding here the last version of the designs

[benjagm]

Note than we have an open discussion about the behaviour of the Bowtie/Benchmark column, but we don't need another design for it.

[jdesrosiers]

The old site had additional notes about compatibility that I'm now noticing aren't on the new site. For example, ajv included a note that you need to turn off strict mode to get spec compliant behavior. I think that's important information that needs to be expressed somehow on this page and there doesn't seem to be a place for that kind of information in the proposed design.

[Relequestual]

Overall this looks better than what we have currently.

I don't think we need a "subscribe to our newsletter" banner half way through.

I am not sure about the filters being on the left on the deskop. What I said in my previous comment still stands and I prefer the other design. Open to other's thoughts.

For the desktop version, I do not think it best to hide away details and require a mouse over/hover to see details/comments. These should be visible and obvious.
For mobile, I know space is limited, but there is also no mouse hover.

In relation to the "add your tool" call to action, I think this might be better as an "Edit on GitHub" CTA, which takes people to a readme whcih explains they can either make a PR or raise an Issue for someone else to add/modify the data.

When a filter is active, the number of implementations should change, and show something like "100 implementations (of 258)".

On mobile, we should show the active filters when the filter selection menu is closed.

I realise most of these are functional requirements rather than design, but we may ask for some elements to be designed. Or we can just capture the requirements (if we agree) as a task list to check off in this Issue when reviewing the PR.

[benjagm]

The old site had additional notes about compatibility that I'm now noticing aren't on the new site.

Thanks a lot for finding this bug. I created this issue #270 and I am working on it.

[benjagm]

The old site had additional notes about compatibility that I'm now noticing aren't on the new site.

@jdesrosiers this is fixed with this PR: #271

[benjagm]

Another requirement for the page is the availability to properly track with UTMs how JSON Schema users are accessing the implementations so we can identify trends and insights.

[aialok]

@benjagm , I would love to work on this issue : )

[Sanket-0510]

@benjagm I would like to give it a try!

[benjagm]

Thanks everyone for your interest!

Please get yourself familiar with the project by completing one the the good first issues available in this board: https://github.com/orgs/json-schema-org/projects/16

[Michael-Obele]

Feature request: Dark theme option

I'd like to propose adding a dark theme option to the website. I believe it would improve the user experience by offering a more comfortable viewing option in low-light environments and for users (like me) who prefer dark themes.

[Michael-Obele]

Feature request: Dark theme option

I'd like to propose adding a dark theme option to the website. I believe it would improve the user experience by offering a more comfortable viewing option in low-light environments and for users (like me) who prefer dark themes.

My bad, seems like this is an already-open issue (#130)

[AdityaSingh-02]

Hello @benjagm

Hello! I'm Aditya Singh, a Computer Science undergraduate from India with a passion for open-source contributions. Previously, I had the opportunity to participate in Google Summer of Code 2023 at Rocket.chat, which was an enriching experience. This season, I'm eager to channel my skills and knowledge into contributing to JSON Schema. The project's requirement matches my tech stack, and I'm excited about the potential impact I can make by contributing to JSON Schema. I'm looking forward to making some worthy contributions🚀

x - https://twitter.com/Go_D_Aditya

[AdityaSingh-02]

For Developing a new version of JSON schema Implementations page -

• The main focus of this project would be to improve overall user experience for the implementations page.

• I would focus on building new version for both mobile as well as desktop keeping the page responsive.

• I would create a filter that would-

  • When on Desktop, have them across the top, and sticky (stay when you scroll, and not on mobile)
  • For mobile, a filter button which opens an overlay with the filter options (like the main menu)

• This project would mainly include of creating new components and replace the existing components with the newer one’s…

• Further discussing, I have gone through the designs for both desktop and mobile view, This project uses NextJS and tailwind CSS for the frontend styling and I have hands on prcatice with it.

[VivekJaiswal18]

Hey @benjagm, since it has no assignees can I be assigned this issue. I would love to contribute to this issue

[lowkya]

Hey @benjagm

The mockups are good. I like the features such as adding filters and ordering the options in the filter alphabetically, as well as adding descriptions on hover, etc.

However, I do have a few suggestions that I believe would enhance the overall user experience:

1. There appears to be some misalignment between the table headers and the table values. Aligning these properly would improve the user's view.
2. Currently, all the data is bold, which I think imposes too much cognitive load on the user. Selectively using bold text for emphasis rather than bolding everything would be more effective.
3. The languages are repeated excessively in the table content. For instance, in the 'Validators' table, 'C++' is mentioned as both a column header and a value in the subsequent three lines. This repetition seems unnecessary and could be streamlined by removing one instance.
4. The use of bold for 'Bowtie' in the text for 'Try Bowtie' seems unnecessary and could be omitted.
5. It would be beneficial to have a designated area to display selected filters and provide users with the option to remove filters from there. This feature would enhance usability.
6. If applying filters results in an empty table, it would be helpful to display a message such as 'No results found' within the table's content. This aspect was not entirely clear from the mockups.

[benjagm]

Let's continue the discussion in #716