idnits 2.17.1 draft-lhotka-relaxng-to-rfc-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 15. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 721. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 732. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 739. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 745. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a Security Considerations section. ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 14, 2007) is 6160 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2629 (ref. '4') (Obsoleted by RFC 7749) Summary: 5 errors (**), 0 flaws (~~), 1 warning (==), 7 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group L. Lhotka 3 Internet-Draft CESNET 4 Intended status: Informational June 14, 2007 5 Expires: December 16, 2007 7 Converting Annotated RELAX NG Schemas for Use in I-Ds or RFCs 8 draft-lhotka-relaxng-to-rfc-00 10 Status of this Memo 12 By submitting this Internet-Draft, each author represents that any 13 applicable patent or other IPR claims of which he or she is aware 14 have been or will be disclosed, and any of which he or she becomes 15 aware will be disclosed, in accordance with Section 6 of BCP 79. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that 19 other groups may also distribute working documents as Internet- 20 Drafts. 22 Internet-Drafts are draft documents valid for a maximum of six months 23 and may be updated, replaced, or obsoleted by other documents at any 24 time. It is inappropriate to use Internet-Drafts as reference 25 material or to cite them other than as "work in progress." 27 The list of current Internet-Drafts can be accessed at 28 http://www.ietf.org/ietf/1id-abstracts.txt. 30 The list of Internet-Draft Shadow Directories can be accessed at 31 http://www.ietf.org/shadow.html. 33 This Internet-Draft will expire on December 16, 2007. 35 Copyright Notice 37 Copyright (C) The IETF Trust (2007). 39 Abstract 41 This memo presents a method for annotating XML schemas expressed in 42 the RELAX NG language and transforming them to a form suitable for 43 direct inclusion in an XML source of an I-D or RFC. The XSLT 44 (Extensible Stylesheet Language Transformations) stylesheet 45 performing the transformation also automatically generates cross- 46 references between RELAX NG pattern definitions and their references. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 51 2. Adding Annotations . . . . . . . . . . . . . . . . . . . . . . 4 52 3. Transformations . . . . . . . . . . . . . . . . . . . . . . . 7 53 4. Formatted Example Schema . . . . . . . . . . . . . . . . . . . 10 54 4.1. start . . . . . . . . . . . . . . . . . . . . . . . . . . 10 55 4.2. player-content . . . . . . . . . . . . . . . . . . . . . . 10 56 5. Conclusions . . . . . . . . . . . . . . . . . . . . . . . . . 12 57 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 13 58 Appendix A. The rng2rfc.xsl stylesheet . . . . . . . . . . . . . 14 59 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 20 60 Intellectual Property and Copyright Statements . . . . . . . . . . 21 62 1. Introduction 64 XML schemas typically serve two complementary purposes. First, they 65 are used by validating programs for deciding whether an XML document 66 conforms to the schema. On the other hand, schemas are often perused 67 by authors who use the XML language defined in the schema for 68 preparing documents, or programmers who write utilities processing 69 such documents. For the latter purpose, it is highly advisable to 70 augment the schema with annotations that explain the schema in more 71 detail and provide semantic information. 73 Modern schema languages offer means for adding structured annotations 74 to a schema rather than just embedding them in XML comments, which 75 has been the only option for the original Document Type Definition 76 (DTD). W3C XML Schema [3] offers a special "annotation" element for 77 this purpose, while in RELAX NG [1] all foreign elements and 78 attributes (in namespaces other than 79 "http://relaxng.org/ns/structure/1.0") must be ignored by a 80 validating program and thus can serve as annotations. 82 In the context of IETF activities, the most natural way of publishing 83 and/or standardizing an XML schema is to make it a part of an 84 Internet Draft or RFC that describes the application the schema is 85 used for. However, including an annotated schema directly in an I-D 86 or RFC is not optimal since the annotations wrapped in XML elements 87 are clumsy and hard to read. XML comments are better in this 88 respect, but still the best option for rendering the annotations is 89 to convert them into standard paragraphs of the I-D or RFC. 91 This memo presents a simple method for annotating RELAX NG schemas, 92 and an XSLT stylesheet that transforms such annotated schemas into a 93 form suitable for a direct inclusion in an XML source of I-D or RFC 94 prepared according to [4]. In addition, the stylesheet automatically 95 generates cross references that further aid navigation through the 96 schema. 98 This method is an adaptation of my previous work [2] that used 99 reStructuredText [6] for the annotations. 101 2. Adding Annotations 103 The annotation system introduces just a single new XML element: 104 "rfc". Its namespace is 105 "http://lhotka.name/ns/rng2rfc-annotations/1.0". In other words, 106 annotations are written as follows: 108 ... 110 where the namespace prefix "a" must be properly defined as an 111 abbreviation of the above URI, typically in the "grammar" element 112 (the root of the schema). 114 The "rfc" elements can be included as children of the following RELAX 115 NG elements: "grammar", "start" and "define". As a matter of fact, 116 they may appear in other places, too, but in that case they are 117 ignored by the stylesheet. 119 Any combination of text and XML markup described in [4] is allowed 120 inside the "rfc" elements, although in order to obtain sensible 121 results only paragraph-level elements such as "t" or "figure" should 122 be used. Each annotation may contain multiple paragraphs, figures 123 etc. However, if the contents is just one paragraph, it needn't be 124 enclosed in the "t" element. 126 Here is a simple example of an annotated schema: 128 130 134 135 This RELAX NG schema defines a simple data model for a football 137 team. 138 The annotations use the markup defined in . 140 142 143 144 The root element is "<football-team>". It contains any 145 number of <player> elements. See for their content. 147 148 149 150 151 152 153 154 155 157 158 159 Each player has the attribute "role" with one of the four 160 choices given below, and element "<name>" which is 161 supposed to contain the full name of the player. 162 163 164 165 goalkeeper 166 defender 167 midfielder 168 striker 169 170 171 172 173 174 176 178 Several details in this example are worth pointing out: 180 1. The XML language for I-Ds and RFCs [4] does not use a namespace, 181 which makes it generally difficult to mix with other XML 182 languages - RELAX NG in this case. As a consequence, the "t", 183 "eref" and "xref" elements in the example formally belong to the 184 default RELAX NG namespace. In practice, this shouldn't cause 185 any problems since they are enclosed in the "rfc" element with a 186 different namespace, and RELAX NG specification [1] requires that 187 such elements together with their contents be ignored by 188 validating programs. To avoid this minor flaw, at the expense of 189 slightly increased verbosity, one could use a non-default 190 namespace for the RELAX NG elements and write, for example, 191 "". The XSLT stylesheet is designed to handle both 192 cases. 194 2. Inside the annotations, the usual XML rules apply. In 195 particular, the contents must be well-formed and the characters 196 "<", ">" and "&" written via entities. 198 3. The cross reference "" points to a 199 target section that are automatically created by the XSLT 200 stylesheet for each defined pattern. 202 4. The other cross-reference, "" will not 203 have the corresponding anchor even after the XSLT transformation. 204 It is assumed that the bibliographic reference will be added by 205 other means, for example manually. Missing targets are probably 206 tolerable only in cases like this - as references to well-known 207 works such as RFCs. 209 3. Transformations 211 A RELAX NG schema annotated as described in the previous section can 212 be converted to an XML fragment suitable for including in an I-D or 213 RFC by means of any XSLT-1.0 processor and the stylesheet 214 _rng2rfc.xsl_ shown in Appendix A. For instance, the following 215 command line can be used for transforming our football schema with 216 the xsltproc [7] tool: 218 xsltproc --output football.xml rng2rfc.xsl football.rng 220 The result of the transformation is as follows: 222 223 This RELAX NG schema defines a simple data model for a football 225 team. 226 The annotations use the markup defined in . 228
229 <grammar 230 ns="http://lhotka.name/ns/football/1.0" 231 xmlns:a="http://lhotka.name/ns/rng2rfc-annotations/1.0" 232 xmlns="http://relaxng.org/ns/structure/1.0"> 233
235
236 The root element is "<football-team>". It contains any 237 number of <player> elements. See for their content. 239
240 <start> 241 <element name="football-team"> 242 <zeroOrMore> 243 <element name="player"> 244 <ref name="player-content"/> 245 </element> 246 </zeroOrMore> 247 </element> 248 </start> 249 250
251
253
254 Each player has the attribute "role" with one of the four 255 choices given below, and element "<name>" which is supposed 256 to contain the full name of the player. 257 The pattern is referenced by: 258 259 start 260 261
262 <define name="player-content"> 263 <attribute name="role"> 264 <choice> 265 <value>goalkeeper</value> 266 <value>defender</value> 267 <value>midfielder</value> 268 <value>striker</value> 269 </choice> 270 </attribute> 271 <element name="name"> 272 <text/> 273 </element> 274 </define> 275
276
278 280 Comparing it to the original annotated schema, we see the annotation 281 of the grammar element became the introductory part of the XML 282 fragment, all RELAX NG pattern definitions elements caused a section 283 to be generated with the name of the pattern as its title, and the 284 annotation inside each "define" element was moved just after the 285 section title. In addition, cross references showing other patterns 286 in the schema (including the "start" element) that use the pattern 287 definition were automatically generated. 289 The stylesheet doesn't attempt to create a full-fledged I-D or RFC 290 conforming to [4]. Provisions for doing so would necessarily make 291 the schema annotations rather unwieldy and, moreover, in many cases 292 the I-D or RFC document will also cover other topics besides the 293 schema description. 295 The root element in the output fragment is "middle" so that the 296 output can be made into an I-D or RFC just by adding the "front" and 297 optionally "back" elements and wrapping everything in the "rfc" 298 element. However, it is by no means necessary to keep the result of 299 the _rng2rfc.xsl_ stylesheet untouched. For example, one can 300 manually divide the pattern definitions into higher-level sections, 301 add more text and so on. 303 The following section shows the rendering of the football schema 304 produced by the xml2rfc [8] tool. For this purpose, I just enclosed 305 the above fragment in a "section" element (so that the auto-generated 306 pattern sections effectively became subsections) and removed the 307 start and end tags of the "middle" element. 309 4. Formatted Example Schema 311 This RELAX NG schema defines a simple data model for a football [9] 312 team. 314 The annotations use the markup defined in [4]. 316 321 4.1. start 323 The root element is "". It contains any number of 324 elements. See Section 4.2 for their content. 326 327 328 329 330 331 332 333 334 336 4.2. player-content 338 Each player has the attribute "role" with one of the four choices 339 given below, and element "" which is supposed to contain the 340 full name of the player. 342 The pattern is referenced by: 344 o start (Section 4.1) 345 346 347 348 goalkeeper 349 defender 350 midfielder 351 striker 352 353 354 355 356 357 359 5. Conclusions 361 The method presented in this memo is similar in spirit to "literate 362 programming in XML" [5], which may be applied to arbitrary XML 363 documents, for example XSLT stylesheets. However, its main benefit, 364 namely that it allows for arbitrary modularization and reordering of 365 the original document, just duplicates the intrinsic functionality of 366 RELAX NG based on the "define" and "ref" elements. Therefore, the 367 specialized XSLT stylesheet rng2rfc.xsl is considerably simpler and 368 yet achieves better results. 370 A similar stylesheet could be developed for W3C XML Schema, although 371 its modularization possibilities are less flexible than the 372 "define-ref" mechanism of RELAX NG. 374 Comments, suggestions and patches are solicited and should be sent to 375 author's address. 377 6. References 379 [1] Clark, J., Ed. and MURATA. Makoto, Ed., "RELAX NG 380 Specification", OASIS Committee Specification, December 2001, 381 . 383 [2] Lhotka, L., "Annotating XML Schemas with reStructuredText", 384 Technical report 3/2006, Praha: CESNET, June 2006, 385 . 387 [3] Thompson, H., Ed., Beech, D., Ed., Maloney, M., Ed., and N. 388 Mendelsohn, Ed., "XML Schema Part 1: Structures Second Edition", 389 W3C Recommendation, October 2004, 390 . 392 [4] Rose, M., "Writing I-Ds and RFCs using XML", RFC 2629, 393 June 1999, . 395 [5] Walsh, N., "Literate Programming in XML", XML Conference 2002, 396 October 2002, 397 . 399 [6] 401 [7] 403 [8] 405 [9] 407 Appendix A. The rng2rfc.xsl stylesheet 409 411 436 441 442 444 445 446 447 449 450 451 452 454 455 456 458 459 460 462 463 464 465 466 467 468 469 470 472 473 474 475 476 477 478 479 480 481 482 483 485 487 488 489 490 491 492 493 494 < 495 496 497 498 499 500 =" 501 502 " 504 505 506 507 508 xmlns 509 510 : 511 512 513 =" 514 515 " 516 517 518 > 519 520 521 522 523 524 525 527 528 529 530 531 start 532 533 534 535 536 537 538 539 < 540 541 542 > 543 544 545 </ 546 547 > 548 549 550 551 552 553 554 555 557 558 559 560 561 562 563 564 565 568 570 571 The pattern is referenced by: 572 573 574 575 symbols 576 577 578 579 580 start 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 < 596 597 598 > 599 600 601 </ 602 603 > 604 605 606 607 608 609 610 612 613 614 615 616 < 617 618 619 620 621 622 623 / 624 625 626 > 627 628 </ 629 630 631 632 633 634 > 635 636 </ 637 638 639 640 > 641 643 644 645 646 649 650 651 652 655 656 657 658 660 661 662 665 666 668 670 671 674 675 677 679 680 681 682 =" 683 684 " 685 687 688 689 690 =" 691 692 " 693 695 697 Author's Address 699 Ladislav Lhotka 700 CESNET, z.s.p.o. 701 Zikova 4 702 Praha 6 160 00 703 CZ 705 Email: lhotka@cesnet.cz 707 Full Copyright Statement 709 Copyright (C) The IETF Trust (2007). 711 This document is subject to the rights, licenses and restrictions 712 contained in BCP 78, and except as set forth therein, the authors 713 retain all their rights. 715 This document and the information contained herein are provided on an 716 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 717 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 718 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 719 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 720 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 721 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 723 Intellectual Property 725 The IETF takes no position regarding the validity or scope of any 726 Intellectual Property Rights or other rights that might be claimed to 727 pertain to the implementation or use of the technology described in 728 this document or the extent to which any license under such rights 729 might or might not be available; nor does it represent that it has 730 made any independent effort to identify any such rights. Information 731 on the procedures with respect to rights in RFC documents can be 732 found in BCP 78 and BCP 79. 734 Copies of IPR disclosures made to the IETF Secretariat and any 735 assurances of licenses to be made available, or the result of an 736 attempt made to obtain a general license or permission for the use of 737 such proprietary rights by implementers or users of this 738 specification can be obtained from the IETF on-line IPR repository at 739 http://www.ietf.org/ipr. 741 The IETF invites any interested party to bring to its attention any 742 copyrights, patents or patent applications, or other proprietary 743 rights that may cover technology that may be required to implement 744 this standard. Please address the information to the IETF at 745 ietf-ipr@ietf.org. 747 Acknowledgment 749 Funding for the RFC Editor function is provided by the IETF 750 Administrative Support Activity (IASA).