Implementations page: structure, compliant configs, last-updated tracking, built-on links

[handrews]

While this PR does a lot, its primary purpose is to add a structured way of tracking implementations that need configuration in order to be in compliance (or maximize compliance) with the specification, which fixes issue #390. I believe this approach accomplishes that with appropriate neutral language.

Adding this information overloaded the layout we were using, so I have changed it to give each implementation a list of named fields and values, which is much easier to skim over as a casual reader, and allows us to add more information as needed.

At this point, it made sense to add a proper schema for the data files, which also involve tweaking the files to fit. Since I was going through all the implementations to find configuration issues anyway, I updated the draft support, and took advantage of the new structure to add an "Information last updated field" as these sorts of lists always have issues with stale information. While doing that, I noticed how some implementations build on each other, so I added a field to link those as well.

This was done over the course of several commits, the messages for which are included below from oldest to newest. You can look at the individual commit diffs to see the steps. The first commit is a bit noisy in the data files as I decided to forbid blank (null) fields and either deleted them or set them to empty arrays as appropriate. The last-updated additions are verbose but boring as they are all the same- you have to quote the date strings as YAML will turn them into date objects otherwise, at least in some implementations. The compliant config and built-on commits are fairly straightforward.

Schema (with conformance fixes)

Schema for the impls data file, structured page

This does two things in preparation for showing more
information on this page in a way that is easy to see
when quickly skimming the list.

It adds a schema (in yaml because it will get pulled
in to the jekyll/liquid template in the future) which
documents the current fields.

It also makes the rendered form of the list more
structured by giving each implementation a field list.
I anticipate more fields as important information that
is currently inconsistenlty reported in the notes gets
pulled out, starting with the configuration compliance
information in the next commit.

This commit also fixes where the language-level notes
were not being rendered correctly, and updates the draft
list for ajv-cli because I happened to notice it was
out of date.

For hyper-schema, the updated layout is simpler because
there is only one modern implementation anyway.
The other was moved to obsolete following the similar
recent moves of validators that have not followed
through on draft-06 or newer support.

The obsolete data files are supported by changing a
handful of license values from arrays to strings,
which display identically. Allowing arrays didn't
seem worth the trouble since the modern file doesn't
use them. I did not change the layout of the obsolete
page because really we'd rather people not look at it
at all. Also, one obsolete validator did not specify
which draft it supported, but from the last modified
date in the repo it must have been draft-03. At this
point, I doubt it matters anyway.

Drafts support updates

Update draft support values.

Since I just went through every implementation looking at
various things anyway. I might have missed some updates,
but hopefully not.

Last-updated tracking

Add last-updated tracking.

Since I just went through and looked at all of these, this adds
a date stamp for such things. It is required throughout the data
file if it is used at all, but it can be left out entirely
(because I am not going to look through the obsolete files).

All four data files (validator/hyper + modern/obsolete) are valid
against the schema as of this commit.

Compliant configurations

Add a compliance section to the impl data
This adds a structured section on compliance, specifically how
to configure for it. This is not intended to be the same sort
of compliance information that the test suite provides. Rather,
it is about things that implementations document that don't
necessarily show up in test suite results.

This format includes brief instructions and optionally
(ideally) a documentation link. I think this langauge is
appropriately neutral, and particularly when there is a doc link
it feels more like calling attention to something that is already
advertised rather than being judgemental.

The AJV and Opis cases are straightfoward.

The Common Lisp implementation's case of needing to disable
automatic downloading is worth a bit of thought as that is a
SHOULD NOT rather than a MUST NOT, but this is why the schema
description notes that it is the most compliant config,
and other configs may still be compliant.

Similary, the networknt Java implementation having nullable
on by default is not technically non-compliant, but it is more
compliant to not have it.

There may be other compliance configuration changes that need
documenting, but these were the ones that I could find with
a reasonable amount of effort.

Built-on links

Add built-on field

Some implementations, particularly but not exclusively CLI and
web ones, are implemented on top of other validator libraries.

This adds a structured field to account for that, and updates
all known cases where it is relevant.

It was necessary to also support an anchor-name field for
implementations as with programming languages, and in the
process disambiguate a few duplicate names.

[netlify]

✅ Deploy Preview for condescending-hopper-c3ed30 ready!

Name	Link
🔨 Latest commit	1e7b146
🔍 Latest deploy log	https://app.netlify.com/sites/condescending-hopper-c3ed30/deploys/6310116d9d4809000922704a
😎 Deploy Preview	https://deploy-preview-471--condescending-hopper-c3ed30.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site settings.

[handrews]

I've also pushed a commit that actually runs the schema validation through .travis.yml... although... are we still using that? Or is the netlify preview stuff something different? I'm a bit confused.

[gregsdennis]

While we're piling on, it'd be cool to have badges like and . Things like this are automatically generated, so we wouldn't need to update them.

We'd need to know repos...

[gregsdennis]

This looks great, though! Nice work.

[handrews]

@gregsdennis yeah that's a great follow-up idea!

[jdesrosiers]

Wow! That must have been a lot of work.