Update info about available schema files.

The final part of and thus fixes #4281.

doc/schema/README.rst

@@ -1,65 +1,51 @@
 Robot Framework and Libdoc schema definitions
 =============================================
 
-Introduction
-------------
-
-This directory contains schema definitions for Robot Frameworks output.xml files
-as well as for spec files created by Libdoc_.
+This directory contains schema definitions for Robot Frameworks XML output files
+as well as for XML and JSON spec files created by Libdoc_.
 
-output.xml schema
------------------
+Only the latest schema versions are directly available and they may not be
+compatible with older Robot Framework versions. If you need to access old
+schema files, switch to an appropriate version control tag using the selector
+at the top of the page.
 
-While Robot Framework is running tests, it generates an XML output file
-containing all information about the execution. After execution is over it
-creates, by default, log and report files based on the output.xml file.
-Logs and reports can be generated also afterwards both using the standalone
-Rebot_ tool and programmatically__. The output.xml file format can be useful
-both for people interested in parsing the output and for people interested
-to create Robot Framework compatible outputs.
+Schema files
+------------
 
-This directory contains XSD_ schema definitions that are compatible with
-different Robot Framework versions. Newer output.xml files have ``schemaversion``
-attribute telling which version they support and older implicitly support schema
-version 1.
+- `<robot.xsd>`_ - Robot Framework XML output schema in XSD_ format.
+- `<libdoc.xsd>`_ - Libdoc XML spec schema in XSD_ format.
+- `<libdoc.json>`_ - Libdoc JSON spec schema in `JSON Schema`_ format.
 
-  * `<robot.03.xsd>`__ - Compatible with Robot Framework >= 5.0.
-  * `<robot.02.xsd>`__ - Compatible with Robot Framework >= 4.0, < 5.0.
-  * `<robot.01.xsd>`__ - Compatible with Robot Framework < 4.0.
+Schema standard versions
+------------------------
 
-Due to XSD 1.1 not being widely adopted, these schema definitions use XSD 1.0.
-Newer schema definitions contain embedded documentation and comments explaining
+XML schema definitions use XSD 1.0 due to XSD 1.1 not being widely adopted.
+Schema files themselves contain embedded documentation and comments explaining
 the structure in more detail. They also contain instructions how to make them
 XSD 1.1 compatible if needed.
 
-.. _Rebot: http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#rebot
-__ http://robot-framework.readthedocs.org/en/latest/autodoc/robot.html#robot.rebot.rebot
-.. _XSD: http://en.wikipedia.org/wiki/XML_Schema_(W3C)
-
-Libdoc schema
--------------
+Libdoc's JSON schema uses JSON Schema Draft 2020-12.
 
-Libdoc_ tool distributed with Robot Framework can generate machine readable spec files
-both in XML and JSON format. XML spec files have XSD_ 1.0 compatible schema definition
-and JSON spec schema is JSON Schema `DRAFT-7`__ compatible.
+Updating schemas
+----------------
 
-  * `<libdoc.04.xsd>`__ - Compatible with Robot Framework >= 5.0.
-  * `<libdoc.03.xsd>`__ - Compatible with Robot Framework >= 4.0, < 5.0.
-  * `<libdoc.02.xsd>`__ - Compatible with Robot Framework == 3.2.
-  * `<libdoc.01.xsd>`__ - Compatible with Robot Framework < 3.2.
-  * `<libdoc_schema.json>`__ - Compatible with Robot Framework >= 4.0.
+XSD schemas are created by hand and updates need to be done directly to them.
 
-.. _Libdoc: http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc
-__ https://json-schema.org/specification-links.html#draft-7
+Libdoc's JSON schema is generated based on a model created using pydantic_.
+To modify the schema, update the model in `<libdoc_json_schema.py>`_ file
+and execute the file to regenerate `<libdoc.json>`_.
 
 Testing schemas
 ---------------
 
-Both output.xml and Libdoc schema definitions are tested as part of `acceptance test
-runs <../../atest/README.rst>`__ by validating created outputs against the appropriate
-schemas. Most output.xml files created during test runs are not validated, however,
-because that would slow down test execution a bit too much. Full validation `can be
-enabled separately`__ and that should be done if the schema is updated or output.xml
-structure is changed.
+Schema definitions are tested as part of `acceptance test runs <../../atest/README.rst>`__
+by validating created outputs against the appropriate schemas. Most output.xml
+files created during test runs are not validated, however, because that would
+slow down test execution a bit too much. Full validation `can be enabled separately`__
+and that should be done if the schema is updated or output.xml structure is changed.
 
+.. _Libdoc: http://robotframework.org/robotframework/latest/RobotFrameworkUserGuide.html#libdoc
+.. _XSD: http://en.wikipedia.org/wiki/XML_Schema_(W3C)
+.. _JSON Schema: https://json-schema.org
+.. _pydantic: https://pydantic-docs.helpmanual.io/usage/schema
 __ https://github.com/robotframework/robotframework/blob/master/atest/README.rst#schema-validation

doc/schema/libdoc_json_schema.py

@@ -1,5 +1,13 @@
 #!/usr/bin/env python3
 
+"""Libdoc JSON schema model definition.
+
+The schema is modeled using pydantic in this file. After updating the model,
+execute this file to regenerate the actual schema file in libdoc.json.
+
+https://pydantic-docs.helpmanual.io/usage/schema/
+"""
+
 from datetime import datetime
 from enum import Enum
 from pathlib import Path