Documenting the MusicXML schema
|Dec 8, 2020||Community Group update|
The latest MusicXML version is 3.1. However, the official MusicXML documentation stops at version 3.0, and the Music Notation Community Group’s plan to keep the documentation updated is unclear.
So I decided to spend some time researching existing tools to convert MusicXML’s schema definition (XSD) to HTML, and hit upon
xs3p, which has a venerable lineage going back several years and multiple incarnations. Since XSD is itself expressed as XML, the simplest approach (and the one adopted by
xs3p) is to produce an XSLT script that transforms the schema definition into HTML.
Using the standard
xsltproc console tool, I simply ran:
xsltproc /path/to/xs3p/xs3p.xsl /path/to/musicxml-3.1/schema/musicxml.xsd > musicxml.html
and obtained an HTML version of the full MusicXML schema definition in no time flat!
- One-line transformation process means easy automation
- Single HTML file means no search engine needed - browser page search is enough
- Single HTML file means easy packaging and hosting
- HTML5 / UTF-8 / Markdown / Bootstrap support means better documentation output
- Large HTML file means slower browser response
- Not responsive on smaller form factors
- Left-side navigation pane scrolling is tied to main content scrolling
If there’s interest from the W3C Music Notation Community Group, I will consider working on some fixes to enhance the HTML output
Update Dec 8, 2020
The W3C MusicXML Community Group is ready to move ahead with a new documentation site! The discussion is happening here - they were gracious enough to mention my modest experiment