Contest
Child pages
  • RELAX-NG Support
ConfigureSpace tools
Skip to end of metadata
Go to start of metadata

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.

Icon

The Unused Define Inspection is not enabled by default. It can be enabled in Settings | Errors | RELAX-NG

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.

Icon

This is currently still in an experimental stage. The marker sometimes have their own opinion when to appear (smile)

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.

Icon

IDEA doesn't accept symbols that contain a dot, i.e. entering a name like "attlist.foo" would not work, however when entering just "attlist", also "attlist.foo" is displayed and can be selected.

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.

Icon

The line and column numbers that are displayed in the messages toolwindow are off by one. This is an open IDEA bug: IDEADEV-23382. This is said to be fixed in IDEA 7.0.3.

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.

Icon

To ensure the association between the XML and the RELAX-NG schema works correctly, one of the target namespace URI(s) of the schema must match the URI it is registered for.

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.

Icon

After choosing a schema, it may be required to make a change to the file to tell IDEA to drop its cached information and load the new schema.

Icon

Currently this requires an explicit xmlns="" declaration to make IDEA recognize the association with the empty namespace. See IDEADEV-23808.

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

  1. Elliotte Rusty Harold, http://cafe.elharo.com/xml/relax-wins/
  2. James Clark, http://www.imc.org/ietf-xml-use/mail-archive/msg00217.html
  3. 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
  • No labels

11 Comments

  1. Anonymous

    Will this plugin be available for Idea 9?

  2. 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)

  3. Anonymous

    This plugin is great.

    Please please please can we have it in IntelliJ 9?

  4. Anonymous

    What about Schematron support?

  5. Anonymous

    Is it possible to install and use this plugin in PhpStorm?

  6. 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?


    1. Sascha Weinreuter

      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

      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.

      Plus the fact that it is already defined in the docbook relax-ng schema; why should it have to be defined again?

      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.

      And then I tried using some XIncludes, and things totally broke down.

      Please be more specific about this. Can you provide a complete example of what you tried and what didn't work as expected?

      Sascha

  7. 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.

    1. 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. 

  8. 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:

    1. if there are no schemas that match you can't help.
    2. if exactly one schema matches you can add a mapping for it.
    3. if multiple schemas match then you can either fail, or have the user elect which of the schemas to use (personally, I'm fine with the former).

  9. David Tiselius

    Hmm… this plugin craches on startup, giving threaddump:

    using version 1.5.5 on Idea 13.1.2