Network Working Group L. Lhotka Internet-Draft CESNET Intended status: Informational June 14, 2007 Expires: December 16, 2007 Converting Annotated RELAX NG Schemas for Use in I-Ds or RFCs draft-lhotka-relaxng-to-rfc-00 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on December 16, 2007. Copyright Notice Copyright (C) The IETF Trust (2007). Lhotka Expires December 16, 2007 [Page 1] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 Abstract This memo presents a method for annotating XML schemas expressed in the RELAX NG language and transforming them to a form suitable for direct inclusion in an XML source of an I-D or RFC. The XSLT (Extensible Stylesheet Language Transformations) stylesheet performing the transformation also automatically generates cross- references between RELAX NG pattern definitions and their references. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Adding Annotations . . . . . . . . . . . . . . . . . . . . . . 4 3. Transformations . . . . . . . . . . . . . . . . . . . . . . . 7 4. Formatted Example Schema . . . . . . . . . . . . . . . . . . . 10 4.1. start . . . . . . . . . . . . . . . . . . . . . . . . . . 10 4.2. player-content . . . . . . . . . . . . . . . . . . . . . . 10 5. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 12 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Appendix A. The rng2rfc.xsl stylesheet . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 Intellectual Property and Copyright Statements . . . . . . . . . . 21 Lhotka Expires December 16, 2007 [Page 2] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 1. Introduction XML schemas typically serve two complementary purposes. First, they are used by validating programs for deciding whether an XML document conforms to the schema. On the other hand, schemas are often perused by authors who use the XML language defined in the schema for preparing documents, or programmers who write utilities processing such documents. For the latter purpose, it is highly advisable to augment the schema with annotations that explain the schema in more detail and provide semantic information. Modern schema languages offer means for adding structured annotations to a schema rather than just embedding them in XML comments, which has been the only option for the original Document Type Definition (DTD). W3C XML Schema [3] offers a special "annotation" element for this purpose, while in RELAX NG [1] all foreign elements and attributes (in namespaces other than "http://relaxng.org/ns/structure/1.0") must be ignored by a validating program and thus can serve as annotations. In the context of IETF activities, the most natural way of publishing and/or standardizing an XML schema is to make it a part of an Internet Draft or RFC that describes the application the schema is used for. However, including an annotated schema directly in an I-D or RFC is not optimal since the annotations wrapped in XML elements are clumsy and hard to read. XML comments are better in this respect, but still the best option for rendering the annotations is to convert them into standard paragraphs of the I-D or RFC. This memo presents a simple method for annotating RELAX NG schemas, and an XSLT stylesheet that transforms such annotated schemas into a form suitable for a direct inclusion in an XML source of I-D or RFC prepared according to [4]. In addition, the stylesheet automatically generates cross references that further aid navigation through the schema. This method is an adaptation of my previous work [2] that used reStructuredText [6] for the annotations. Lhotka Expires December 16, 2007 [Page 3] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 2. Adding Annotations The annotation system introduces just a single new XML element: "rfc". Its namespace is "http://lhotka.name/ns/rng2rfc-annotations/1.0". In other words, annotations are written as follows: ... where the namespace prefix "a" must be properly defined as an abbreviation of the above URI, typically in the "grammar" element (the root of the schema). The "rfc" elements can be included as children of the following RELAX NG elements: "grammar", "start" and "define". As a matter of fact, they may appear in other places, too, but in that case they are ignored by the stylesheet. Any combination of text and XML markup described in [4] is allowed inside the "rfc" elements, although in order to obtain sensible results only paragraph-level elements such as "t" or "figure" should be used. Each annotation may contain multiple paragraphs, figures etc. However, if the contents is just one paragraph, it needn't be enclosed in the "t" element. Here is a simple example of an annotated schema: This RELAX NG schema defines a simple data model for a football team. The annotations use the markup defined in . The root element is "<football-team>". It contains any number of <player> elements. See for their content. Lhotka Expires December 16, 2007 [Page 4] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 Each player has the attribute "role" with one of the four choices given below, and element "<name>" which is supposed to contain the full name of the player. goalkeeper defender midfielder striker Several details in this example are worth pointing out: 1. The XML language for I-Ds and RFCs [4] does not use a namespace, which makes it generally difficult to mix with other XML languages - RELAX NG in this case. As a consequence, the "t", "eref" and "xref" elements in the example formally belong to the default RELAX NG namespace. In practice, this shouldn't cause any problems since they are enclosed in the "rfc" element with a different namespace, and RELAX NG specification [1] requires that such elements together with their contents be ignored by validating programs. To avoid this minor flaw, at the expense of slightly increased verbosity, one could use a non-default namespace for the RELAX NG elements and write, for example, "". The XSLT stylesheet is designed to handle both cases. 2. Inside the annotations, the usual XML rules apply. In particular, the contents must be well-formed and the characters "<", ">" and "&" written via entities. Lhotka Expires December 16, 2007 [Page 5] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 3. The cross reference "" points to a target section that are automatically created by the XSLT stylesheet for each defined pattern. 4. The other cross-reference, "" will not have the corresponding anchor even after the XSLT transformation. It is assumed that the bibliographic reference will be added by other means, for example manually. Missing targets are probably tolerable only in cases like this - as references to well-known works such as RFCs. Lhotka Expires December 16, 2007 [Page 6] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 3. Transformations A RELAX NG schema annotated as described in the previous section can be converted to an XML fragment suitable for including in an I-D or RFC by means of any XSLT-1.0 processor and the stylesheet _rng2rfc.xsl_ shown in Appendix A. For instance, the following command line can be used for transforming our football schema with the xsltproc [7] tool: xsltproc --output football.xml rng2rfc.xsl football.rng The result of the transformation is as follows: This RELAX NG schema defines a simple data model for a football team. The annotations use the markup defined in .
<grammar ns="http://lhotka.name/ns/football/1.0" xmlns:a="http://lhotka.name/ns/rng2rfc-annotations/1.0" xmlns="http://relaxng.org/ns/structure/1.0">
The root element is "<football-team>". It contains any number of <player> elements. See for their content.
<start> <element name="football-team"> <zeroOrMore> <element name="player"> <ref name="player-content"/> </element> </zeroOrMore> </element> </start>
Each player has the attribute "role" with one of the four choices given below, and element "<name>" which is supposed to contain the full name of the player. Lhotka Expires December 16, 2007 [Page 7] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 The pattern is referenced by: start
<define name="player-content"> <attribute name="role"> <choice> <value>goalkeeper</value> <value>defender</value> <value>midfielder</value> <value>striker</value> </choice> </attribute> <element name="name"> <text/> </element> </define>
Comparing it to the original annotated schema, we see the annotation of the grammar element became the introductory part of the XML fragment, all RELAX NG pattern definitions elements caused a section to be generated with the name of the pattern as its title, and the annotation inside each "define" element was moved just after the section title. In addition, cross references showing other patterns in the schema (including the "start" element) that use the pattern definition were automatically generated. The stylesheet doesn't attempt to create a full-fledged I-D or RFC conforming to [4]. Provisions for doing so would necessarily make the schema annotations rather unwieldy and, moreover, in many cases the I-D or RFC document will also cover other topics besides the schema description. The root element in the output fragment is "middle" so that the output can be made into an I-D or RFC just by adding the "front" and optionally "back" elements and wrapping everything in the "rfc" element. However, it is by no means necessary to keep the result of the _rng2rfc.xsl_ stylesheet untouched. For example, one can manually divide the pattern definitions into higher-level sections, add more text and so on. The following section shows the rendering of the football schema produced by the xml2rfc [8] tool. For this purpose, I just enclosed Lhotka Expires December 16, 2007 [Page 8] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 the above fragment in a "section" element (so that the auto-generated pattern sections effectively became subsections) and removed the start and end tags of the "middle" element. Lhotka Expires December 16, 2007 [Page 9] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 4. Formatted Example Schema This RELAX NG schema defines a simple data model for a football [9] team. The annotations use the markup defined in [4]. 4.1. start The root element is "". It contains any number of elements. See Section 4.2 for their content. 4.2. player-content Each player has the attribute "role" with one of the four choices given below, and element "" which is supposed to contain the full name of the player. The pattern is referenced by: o start (Section 4.1) Lhotka Expires December 16, 2007 [Page 10] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 goalkeeper defender midfielder striker Lhotka Expires December 16, 2007 [Page 11] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 5. Conclusions The method presented in this memo is similar in spirit to "literate programming in XML" [5], which may be applied to arbitrary XML documents, for example XSLT stylesheets. However, its main benefit, namely that it allows for arbitrary modularization and reordering of the original document, just duplicates the intrinsic functionality of RELAX NG based on the "define" and "ref" elements. Therefore, the specialized XSLT stylesheet rng2rfc.xsl is considerably simpler and yet achieves better results. A similar stylesheet could be developed for W3C XML Schema, although its modularization possibilities are less flexible than the "define-ref" mechanism of RELAX NG. Comments, suggestions and patches are solicited and should be sent to author's address. Lhotka Expires December 16, 2007 [Page 12] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 6. References [1] Clark, J., Ed. and MURATA. Makoto, Ed., "RELAX NG Specification", OASIS Committee Specification, December 2001, . [2] Lhotka, L., "Annotating XML Schemas with reStructuredText", Technical report 3/2006, Praha: CESNET, June 2006, . [3] Thompson, H., Ed., Beech, D., Ed., Maloney, M., Ed., and N. Mendelsohn, Ed., "XML Schema Part 1: Structures Second Edition", W3C Recommendation, October 2004, . [4] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, June 1999, . [5] Walsh, N., "Literate Programming in XML", XML Conference 2002, October 2002, . [6] [7] [8] [9] Lhotka Expires December 16, 2007 [Page 13] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 Appendix A. The rng2rfc.xsl stylesheet Lhotka Expires December 16, 2007 [Page 14] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 < =" " Lhotka Expires December 16, 2007 [Page 15] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 xmlns : =" " > start < > </ > Lhotka Expires December 16, 2007 [Page 16] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 The pattern is referenced by: symbols start < > Lhotka Expires December 16, 2007 [Page 17] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 </ > < / > </ > </ > =" " =" " Lhotka Expires December 16, 2007 [Page 19] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 Author's Address Ladislav Lhotka CESNET, z.s.p.o. Zikova 4 Praha 6 160 00 CZ Email: lhotka@cesnet.cz Lhotka Expires December 16, 2007 [Page 20] Internet-Draft Converting RELAX NG to I-Ds or RFCs June 2007 Full Copyright Statement Copyright (C) The IETF Trust (2007). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Lhotka Expires December 16, 2007 [Page 21]