Update Libdoc's JSON schema

[pekkaklarck]

Libdoc spec files were enhanced in RF 5.0 but the JSON schema was not updated. Change were:

• New typedocs section to list all type information used by a library. This is related to Libdoc: Include automatic argument conversion info #4160 and Ability to register custom converters for keyword arguments #4088.
• Old dataTypes section is deprecated in favor of the new typedocs.
• Each keyword argument has typedocs that contains a mapping of type names it uses to typedocs in the aforementioned typedocs section.

The XSD schema documenting XML spec has been updated.

[pekkaklarck]

All schema files can be found under https://github.com/robotframework/robotframework/blob/master/doc/schema.

As you can see, Libdoc's XSD schema is versioned so that each version has a separate file and the current latest version is ibdoc.04.xsd. The JSON schema is libdoc_schema.json and has no such versioning. Do you @Snooz82 have an opinion should we add file name based versioning for the JSON schema as well?

The actual work to be done is updating the JSON schema so that it matches the latest XSD schema. The main change is that nowadays specs have typedocs section containing all type info objects. The old dataTypes still exits but a comment could be added to the schema that it's deprecated.

[pekkaklarck]

Another thing to think about is enhancing Libdoc's tests so that also the JSON schema is used in them. That may not be worth the effort before RF 5.0, though, unless it actually would help making sure that the schema is valid.

[pekkaklarck]

Yet another thing to decide is what JSON schema version to use. The current schema uses draft 7, but http://json-schema.org seems to encourage using newer ones. I don't know this domain well enough to be able to make a decision right away.

[pekkaklarck]

I earlier commented that we probably should version Libdoc's JSON schema like we version other schemas. With other schemas we both use version in the file name like libdoc.04.xsd and robot.03.xsd, and have a separate specversion (Libdoc) or schemaversion (output.xml) attribute.

Having an attribute denoting the schema version is definitely a good idea and I believe Libdoc's JSON schema should get that as well. Probably it should be specversion to be compatible with Libdoc's XSD schema. It would also be convenient if spec version in both Libdoc schemas would be same, but it's possible there are changes affecting only one schema.

I'm not that big fan of file name based versioning. Because we use version control system, it's easy to get old specs anyway if needed. Is there some other concrete benefit from that? If not, I suggest we don't do that with the JSON schema and stop doing that with others as well. Updating the schema becomes easier if there's no need to create a new file and update README linking to schemas.

The JSON schema file name libdoc_schema.json is inconsistent with libdoc.xsd and robot.xsd. I propose we rename it just to libdoc.json.

[pekkaklarck]

Things to do:

• Decide schema standard version.
• Add specversion attribute.
• Decide should specversion be same as libdoc.xsd uses (4 w/ RF 5.0) or should it start from 1.
• Decide should files names contain version info. I believe they shouldn't.
• Rename to libdoc.json to be consistent with other schemas.
• Add tests to make sure Libdoc JSON specs actually match the schema.

There's so much work to do and decisions to be made that getting everything done before the planned RF 5.0 final release tomorrow is not possible. I don't consider this important enough issue to postpone the release, so I move this to RF 5.0.1 scope. The schema isn't included in release packages either, so if we update it soon it will be soon available for those needing it.

[pekkaklarck]

@Snooz82 recommended on Slack that the schema could be modeled using pydantic and then the JSON schema autogenerated. That seems to work fine and I have the first version ready to be committed. After that I plan to integrate it to Libdoc acceptance tests to make sure the schema really covers everything.

[pekkaklarck]

Validating JSON specs as part of acceptance tests turned out to be pretty easy and surprisingly the initial schema version worked pretty well. Tests are failing on CI because there's too old jsonschema version for our needs, but that ought to be easy to fix. (After that tests are still likely to fail due to problems with PyPy but they aren't related to this.)

Specs are validated using jsonschema.Draft202012Validator so apparently we support Draft 2020-12 which is the latest JSON Schema version. It's already over a year old so I assume using it is safe. Still need to explicitly specify the schema version because pydantic doesn't do that automatically (pydantic/pydantic#1478).

[pekkaklarck]

JSON Schema version was explicitly added to out schema in c43fb46. Forgot to link it to this issue.

[pekkaklarck]

Decided to start spec version from 1. It doesn't match XML spec version but there's a change specs are enhanced in future releases and version numbers could anyway get out of sync. If it turns out using same version would be beneficial, we can change that later.