Table of Contents
Overview
RELAX-NG is an emerging alternative to W3C XML Schema, which is said to be very complex and hard learn/use/maintain.
This plugin implements an IntelliJ IDEA feature request (IDEA-13734) to add full support for RELAX-NG to IntelliJ IDEA 7.0. It supports both the authoring of RELAX-NG schemas with many kinds of features IntelliJ IDEA is known for, and also improves the editing of XML documents that conform to a certain RELAX-NG schema.
The following sections list some of the main features, like on-the-fly error highlighting, code completion and refactoring. For a quick start, please see the section |#Configuration.
Features
Error Highlighting for RELAX-NG Files
Error highlighting exists for various aspects of editing RELAX-NG documents. Unless otherwise stated, all of those are available in both the XML syntax as well as the Compact Syntax for RELAX-NG.
Reference Validation
First, there is the validation of references to named patterns ("define") in RELAX-NG schemas. Unresolved references are highlighted and a Quick Fix is offered to create the missing declaration.
Namespace Prefix Validation
Namespace prefixes that are used in element- or attribute-declarations are checked whether they are bound to an actual namespace declaration, either by an xmlns:XXX="..."
attribute in the XML syntax or an equivalent namespace XXX = "..."
declaration in the compact syntax.
In both cases a QuickFix is offered to create an appropriate declaration for an unbound prefix.
Model Validation
The validation for the complete RELAX-NG model is performed by parsing and validating the currently opened RELAX-NG schema to report any violations about the model, such as invalid recursive usage of named patterns, missing start-elements (unless the file is included anywhere), and a lot more. This validation is performed by an external library (RNGOM) and is invoked by IDEA only when no other problems are present in the current file.
Unused Define Inspection
Not quite an error, but just like IDEA highlights other unused symbols, the plugin provides an inspection that looks for named patterns that aren't used anywhere and can be removed. This helps to create and maintain schemas that don't contain any unnecessary overhead.
Completion
The completion feature is split into two parts: Completion for references when editing RELAX-NG schemas and element- and attribute names while editing XML documents that are associated with a RELAX-NG schema.
RELAX-NG Completion
In RELAX-NG files there is code completion for named patterns which offers all the named patterns that are visible inside the current scope. Of course, this also works both for the XML syntax as well as the Compact Syntax. In fact, in the compact syntax there's also the possibility to complete keywords, like "grammar" or "namespace".
XML Completion
When editing XML documents that are associated with a RELAX-NG schema, there will be completion for element- and attribute names at the current editing location. The completion offers are as precise as possible, but are not based on a full check of the underlying RELAX-NG model. That's similar to the completion IDEA offers for DTD or W3C XML schemas, which is basically a list of "what's theoretically possible". Although that bears some risk of completing something that's not correct, it enables the user to start making modifications that are not - yet - valid.
The plugin also provides an own RELAX-NG schema for RELAX-NG in XML syntax, which automatically supports the completion of RELAX-NG element names, such as "grammar", "define", etc. which are comparable with keywords in the Compact Syntax.
Refactoring and Navigation
Rename & Find Usages
References to named patterns can be renamed just like any other identifier in IDEA. The plugin will rename the declaration and all of its usages inside the visible scope. Navigation-features like "Find Usages", "Highlight Usages in File", "Goto Declaration (Ctrl-B)", etc. are available as well to navigate between named patterns and their references.
Overrides/Is Overridden Markers
For any pattern-definition that overrides a definition from an included file, an "overrides" marker will be displayed. For the overridden definition, an "is overridden" marker is displayed, both with the possibility to navigate to the respective target when clicking the gutter-icon.
Goto Symbol
Named pattern definitions can be searched for with the "Goto Symbol" feature, without having to know in which file exactly they are located.
XML Validation
When editing an XML document that is associated with a RELAX-NG schema, a complete validation will performed. The validation is split into two parts: An internal validation that checks whether an element, an attribute or attribute value is completely unknown and incorrect, and an external validation based on Jing that performs the full validation once no other problems are encountered.
Documentation Lookup
It's possible to display documentation and comments for RELAX-NG constructs while editing XML documents using IDEA's standard "Quick Documentation Lookup" action. While editing RELAX-NG documents this can e.g. display comments about referenced define-patterns.
Schema Conversion
To convert schemas between different formats, there's a frontend to the conversion utility Trang which can do the following conversions:
- Convert RELAX-NG between XML- and Compact syntax
- Convert XML- and Compact Syntax RELAX-NG schemas into W3C XML Schema syntax
- Convert RELAX-NG schemas to and from XML 1.0 DTD syntax
- Create RELAX-NG schemas from XML instance documents
For the output type "XSD" as well as the input type "DTD", it is possible to tweak some conversion options in the "Advanced..." dialog. The options are explained in detail in the Trang manual.
Errors and warnings from the conversion process will be displayed in the "Messages" toolwindow.
External Validation
With the action "Tools -> Validate" from the Main Menu it is possible to perform a manual validation of XML documents with the bundled RELAX-NG validator Jing. Messages from the validation process are displayed in the "Messages" toolwindow and can also be exported to a text file.
Configuration
There's really not much to configure to make use of the plugin's support for working with RELAX-NG. Schemas in XML syntax are automatically recognized in any XML file by their namespace URI. Additionally, the extension "rng" is, if not already done, automatically registered with the XML file type. Compact Syntax files are recognized in files with the extension "rnc" by default, but this can be customized via Settings | File Types
by mapping any other extension to the "RELAX NG Compact Syntax" file type.
To get the full support when editing XML documents, the document's root tag namespace should be mapped to a RELAX-NG schema that describes the document. This can be done either by using IDEA's automatic download (the "Fetch External Resource" Quick Fix) in case the namespace URI directly references a RELAX-NG file or by manually setting up such a mapping via Settings | External Resources
.
For non-namespace documents this works a bit differently though. For such documents, it is possible to configure a RELAX-NG schema together with other per-file highlighting settings by clicking the little "Hector"-icon in the status bar. For non-namespace files, this popup will allow to select the path of the RELAX-NG schema to use for editing the file.
Background: Why RELAX-NG?
RELAX-NG is a lot simpler to read and write than W3C XML Schema, but can actually describe more complex structures. It also doesn't suffer from various inconsistencies in XML Schema, such as the different treatment of elements and attributes.
Currently RELAX-NG is gaining more and more momentum as it is being adopted by popular technologies like DocBook 5, XHTML 2.0, OpenOffice, etc. There's no doubt that, unless someone is a real expert in XML Schema, a RELAX-NG to model for a custom XML schema should be considerably easier to create, and would require less effort to document and maintain. Give it a try!
Some References about RELAX-NG
- Elliotte Rusty Harold, http://cafe.elharo.com/xml/relax-wins/
- James Clark, http://www.imc.org/ietf-xml-use/mail-archive/msg00217.html
- Griffin Brown, http://www.griffinbrown.co.uk/blog/PermaLink,guid,9aebb083-a961-42b1-9748-a57e06a0f19a.aspx
Availability
The plugin is available for IntelliJ IDEA 7.0 via the built-in plugin manager and at the IntelliJ Plugin Repository.
Version History
Version 0.9 (2007-11-13)
- Initial version
Version 1.0 (2007-11-21)
- Added conversion of RELAX-NG schemas with Trang (Tools -> Convert Schema...) as well as the possibility to create RELAX-NG schemas from XML instance documents (Tools -> Generate Schema from XML file...)
- Added ability to validate XML documents with RELAX-NG schemas via Tools -> Validate
- Added better support for Quick Documentation Lookup when authoring RNG files
Version 1.1 (2007-11-26)
- Improved handling of included files
- Inspection "UnusedDefine" works in Compact Syntax files and can be suppressed
- Added the possibility to associate non-namespace documents with a RELAX-NG schema. This can be done in the "Hector Popup" in the statusbar that also configures other per-file highlighting settings.
- Bugfixes & internal cleanup
Version 1.2 (2007-12-10)
- Display overridden/overrides markers for named patterns
- Initialize output path for schema conversion, ask to overwrite existing files
- Bugfixes
Version 1.2.1 (2007-12-13)
- Fixed some caching issues (changes in schema were not picked up)
- Suppress duplicate errors from Tools | Validate
Version 1.2.2 (2008-01-22)
- Fixed path issue in JARs on non-Windows systems
Version 1.5
- Support for IDEA 8.x
Version 1.5.3 (2009-03-16)
- Correct attribute value validation for token datatype
Version 1.5.4 (2010-04-13)
- Support for IDEA 9.x
11 Comments
Anonymous
Will this plugin be available for Idea 9?
Anonymous
I would also like to ask if it will be available for IDEA 9 (currently it doesn't show up in the beta plugin picker)
Anonymous
This plugin is great.
Please please please can we have it in IntelliJ 9?
Anonymous
What about Schematron support?
Anonymous
Is it possible to install and use this plugin in PhpStorm?
Steve Ebersole
Anyone successfully used this with Docbook 5 in Intellij 9?
Per the DocBook guide, I map the http://docbook.org/ns/docook to its relax-ng schema at http://docbook.org/xml/5.0/rng/docbook.rng (at least I think thats per the guide as they never say exactly what the corresponding schemaLocation for http://docbook.org/ns/docook ought to be).
This works and the editor is able to properly validate and suggest completions. Until I came to a link. In DocBook 4 (I am converting a document) the element was <ulink/>, but its now <link/> with its attributes defined by XLink.
The editor does not like the xlink namespace at all. Adding a xmlns:xlink="http://www.w3.org/1999/xlink" to <book/> fixed that but i had no idea what to map that namespace to. Plus the fact that it is already defined in the docbook relax-ng schema; why should it have to be defined again?
And then I tried using some XIncludes, and things totally broke down. There I needed to explicitly prefix all the docbook elements with db: (the prefix defined in the relax-ng schema) for the editor to understand.
Switching to XSD fixed the XInclude prefixing problem.
What am I doing wrong?
Sascha Weinreuter
I haven't actually tried it, but you may be successful by using the xsd from here: http://www.w3.org/TR/xml-i18n-bp/xmlspec/xlink.xsd (or even converting the XSD to RNG). Simply telling IDEA to ignore the namespace may work just as well.
A namespace prefix must always be declared in the XML instance document because this is required even without access to any schema. The prefixes used in the schema and the instance document can actually be totally different, they just have to map to the same namespace URI.
Please be more specific about this. Can you provide a complete example of what you tried and what didn't work as expected?
Sascha
Steve Ebersole
Hey Sascha,
First I apologize as I really do not know the terminology to describe this very well. But thank you much for your reply and time.
Basically I am try to convert some documentation written in DocBook v4 to v5. For v5, DocBook recommends using the Relax NG schema as it is more complete or accurate. So in my editor, I took:
and changed that to:
In IntelliJ settings (File > Settings > Resources) I mapped the http://docbook.org/ns/docook (URI) to http://docbook.org/xml/5.0/rng/docbook.rng (Location). As far as I understand, that should be the same as explicitly adding xsi:schemaLocation="http://docbook.org/ns/docbook http://docbook.org/xml/5.0/rng/docbook.rng" to the <book/> element.
That worked in this file except for the <link/> tag. Specifically the editor complained about the xlink:href attribute saying that it is "not allowed here". For whatever reason (noob here), adding xmlns:xlink="http://www.w3.org/1999/xlink" to <book/> allowed the editor to understand the xlink:href attribute (or at least to not complain about it). The editor does complain about http://www.w3.org/1999/xlink not being a registered URI.
Next I went on to one of the XInclude files, Book_Info.xml here:
And tried converting it to v5:
The editor here does not like any of the elements saying they "must be declared". Prefixing each with db: (I found that by perusing the docbook.rng file) worked, meaning the IntelliJ editor showed the following as valid:
I was just not sure why I needed to prefix the docbook elements here, but not in the main document file.
Steve Ebersole
Hmm, I went ahead and tried converting another XIncluded file, this time a chapter and it worked. In fact all the other XIncluded files I tried worked. So it is just something different with how DocBook defined <info> in the schema. Probably they do not intend it to be separate. Personally I never understood separating out <bookinfo/> myself.
Dominic Chambers
This is a really great piece of software, but there is just one thing that stops it from Just Working(TM), and being truly awesome. Would you consider adding a quick-fix to automatically locate the schema for an XML instance document? Given that you are able to automatically determine which files are RelaxNG schemas, and since you have Trang around to convert the rnc files to rng first, you would merely need to inspect the root node of each rng schema to determine the default namespace each grammar provides, then:
David Tiselius
Hmm… this plugin craches on startup, giving threaddump:
using version 1.5.5 on Idea 13.1.2