Page MenuHomePhabricator

Improve rendering of event schema for browsing and documentation
Open, LowPublic


Previously, schema were rendered using the Schema: namespace and served as both the de facto repository of schema, the documentation of the schema, and a discussion place (using the Talk pages). It also ensured easy reference from within other on-wiki documentation.

The new system stores event schema as a mixture of .json and .yaml files in git repositories. These files contain some documentation in the form of description fields, etc., and maintaining separate documentation on-wiki will introduce a maintenance burden and prevent a single source of truth.

We should explore ways that we can make the schema files themselves the source of truth, as was the case in the prior system. At the same time, we should explore ways to make that documentation more approachable.

Options to think about

  • Re-purpose the JSON renderer used for Schema: pages to parse and render JSONSchema on-wiki. This could be done as an automated step on schema merge. The wiki pages would not be editable and would not be used by EventGate to obtain the schema, but would serve as documentation, be able to be linked easily by other wiki pages, would have a talk page, etc.
  • Improve the rendering of JSON and YAML files provided by the default browser, so that navigating to is a more pleasant experience.