DEV Community: 中村覚

Implementation Guide for TEI XML Schema Combining RELAX NG and Schematron

中村覚 — Fri, 01 Aug 2025 21:03:12 +0000

:::message
After manual verification, this article was written by AI.
:::

Introduction

When editing TEI (Text Encoding Initiative) XML, validation of not only element and attribute structures but also more complex business rules becomes necessary. This article explains how to combine RELAX NG (RNG) and Schematron to achieve both structural and content validation, using real project challenges as examples.

Challenges to Solve

When editing classical Japanese literary texts in TEI XML, we had the following requirements:

Dynamic validation of ID references: Validate that IDs referenced in corresp attributes actually exist in witness elements within the document
Auto-completion in Oxygen XML Editor: Automatically display ID candidates during editing
Support for multiple ID references: Allow multiple IDs to be specified separated by spaces
Restrict references to specific elements: Allow only witness element IDs to be referenced, and generate an error if person element IDs are included

Why RNG + Schematron?

RELAX NG Strengths

Element and attribute structure definition
Data type specification
Basic content model definition

Schematron Strengths

XPath-based complex validation rules
Cross-reference checking within documents
Custom error message provision

By combining these two, we can achieve strict validation from both structural and content perspectives.

Implementation Example

1. Basic RNG Schema Structure

<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
         xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
         xmlns:sch="http://purl.oclc.org/dsdl/schematron"
         datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
         ns="http://www.tei-c.org/ns/1.0">

  <!-- Schematron namespace declaration -->
  <sch:ns prefix="tei" uri="http://www.tei-c.org/ns/1.0"/>

  <!-- Embed Schematron rules here -->

  <start>
    <ref name="TEI"/>
  </start>

  <!-- RNG structural definitions -->
</grammar>

2. ID Definition and anyURI Type Usage

To achieve auto-completion in Oxygen XML Editor, we use the anyURI type:

<!-- Witness list -->
<define name="listWit">
  <element name="listWit">
    <oneOrMore>
      <element name="witness">
        <attribute name="xml:id">
          <data type="ID"/>
        </attribute>
        <text/>
      </element>
    </oneOrMore>
  </element>
</define>

<!-- Base text reading -->
<define name="lem">
  <element name="lem">
    <attribute name="corresp">
      <a:documentation>
        Reference to witness
        Internal reference in IDREF format with #
        Oxygen displays a list of xml:ids with #
      </a:documentation>
      <list>
        <oneOrMore>
          <data type="anyURI"/>
        </oneOrMore>
      </list>
    </attribute>
    <text/>
  </element>
</define>

Key points:

data type="ID" ensures uniqueness
data type="anyURI" allows internal references with #
list element allows multiple space-separated values

3. Advanced Validation with Schematron

<sch:pattern id="witness-references">
  <sch:title>Witness ID Reference Validation</sch:title>

  <sch:rule context="tei:lem[@corresp]">
    <sch:let name="listWitIds" value="//tei:listWit/tei:witness/@xml:id"/>
    <sch:let name="listPersonIds" value="//tei:listPerson/tei:person/@xml:id"/>
    <sch:let name="correspTokens" value="tokenize(normalize-space(@corresp), '\s+')"/>

    <!-- Should reference only witnesses -->
    <sch:assert test="every $token in $correspTokens 
                      satisfies (
                        starts-with($token, '#') and 
                        substring($token, 2) = $listWitIds
                      )" role="error">
      The corresp attribute should only reference witness IDs.
      Available witness IDs: #<sch:value-of select="string-join($listWitIds, ', #')"/>
    </sch:assert>

    <!-- Error when person IDs are included -->
    <sch:report test="some $token in $correspTokens 
                      satisfies (
                        starts-with($token, '#') and 
                        substring($token, 2) = $listPersonIds
                      )" role="error">
      The corresp attribute contains person IDs.
      Detected person IDs: <sch:value-of select="
        string-join(
          for $token in $correspTokens
          return if (starts-with($token, '#') and substring($token, 2) = $listPersonIds) 
                 then $token 
                 else (),
          ', '
        )
      "/>
    </sch:report>
  </sch:rule>
</sch:pattern>

Key points:

Define variables with sch:let and dynamically retrieve values with XPath
Parse multiple ID references with tokenize()
Error when condition is not met with sch:assert
Error when condition is met with sch:report
Specify error level with role="error" (warning, info also available)

4. Practical Usage Example

<!-- Usage in XML document -->
<?xml-model href="schema.rng" type="application/xml" 
    schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="schema.rng" type="application/xml" 
    schematypens="http://purl.oclc.org/dsdl/schematron"?>

<TEI xmlns="http://www.tei-c.org/ns/1.0">
    <teiHeader>
        <listWit>
            <witness xml:id="aaa">Witness A</witness>
            <witness xml:id="iii">Witness I</witness>
        </listWit>
        <listPerson>
            <person xml:id="abc">
                <persName>Person ABC</persName>
            </person>
        </listPerson>
    </teiHeader>
    <text>
        <body>
            <app>
                <!-- Correct example: referencing only witnesses -->
                <lem corresp="#aaa #iii">Main text</lem>
                <rdg corresp="#aaa">Alternative reading</rdg>
            </app>
            <app>
                <!-- Error example: includes person -->
                <lem corresp="#aaa #abc">Main text</lem>
                <rdg>Alternative reading</rdg>
            </app>
        </body>
    </text>
</TEI>

Implementation Considerations

1. XPath 2.0 Syntax

Pay attention to the syntax of for expressions in XPath within Schematron:

<!-- Correct -->
let $invalid := (
  for $token in $correspTokens
  return 
    let $id := substring($token, 2)
    return if ($id = $validIds) then () else $token
)

<!-- Will cause error -->
let $invalid := for $token in $correspTokens
                let $id := substring($token, 2)
                return if ($id = $validIds) then () else $token

2. IDREF vs anyURI

IDREF type: Cannot include #, limiting completion in Oxygen
anyURI type: Allows values with #, Oxygen automatically provides ID completion

3. Schematron role Attribute

role="error": Red error marker
role="warning": Yellow warning marker
role="info": Blue information marker

Advanced Examples

Complex Cross-Reference Validation

<sch:pattern id="cross-references">
  <!-- app element must have exactly one lem element -->
  <sch:rule context="tei:app">
    <sch:assert test="count(tei:lem) = 1">
      The app element must have exactly one lem element
    </sch:assert>
  </sch:rule>

  <!-- rdg element's corresp cannot duplicate lem element's -->
  <sch:rule context="tei:rdg[@corresp]">
    <sch:let name="lemCorresp" value="../tei:lem/@corresp"/>
    <sch:assert test="not(@corresp = $lemCorresp)">
      The rdg element's corresp must have a different value from the lem element
    </sch:assert>
  </sch:rule>
</sch:pattern>

Conditional Required Attributes

<sch:pattern id="conditional-attributes">
  <sch:rule context="tei:date[@when]">
    <!-- If when attribute exists, it must be in ISO format -->
    <sch:assert test="matches(@when, '^\d{4}-\d{2}-\d{2}$')">
      The when attribute must be specified in YYYY-MM-DD format
    </sch:assert>
  </sch:rule>
</sch:pattern>

Summary

By combining RELAX NG and Schematron:

Separation of structural and content validation: Design that leverages each technology's strengths
Dynamic validation rules: Flexible validation based on document content
Editor support: Advanced editing support in Oxygen XML Editor and others
Clear error messages: Custom messages in your native language

Especially when editing documents with complex structures like TEI XML, this combination becomes an extremely powerful tool.

References

The complete schema code introduced in this article is actually used in production projects. I hope it will be helpful for those facing similar challenges.

RELAX NGとSchematronを組み合わせたTEI XMLスキーマの実装ガイド

中村覚 — Fri, 01 Aug 2025 20:59:52 +0000

:::message
人手で検証を行った後、AIが記事を執筆しました。
:::

はじめに

TEI（Text Encoding Initiative）XMLを編集する際、要素や属性の構造検証だけでなく、より複雑なビジネスルールの検証が必要になることがあります。本記事では、RELAX NG（RNG）とSchematronを組み合わせて、構造検証と内容検証の両方を実現する方法を、実際のプロジェクトで直面した課題を例に解説します。

解決したい課題

日本の古典文学テキストをTEI XMLで校訂する際、以下のような要求がありました：

ID参照の動的検証: corresp属性で参照するIDが、実際に文書内のwitness要素に存在することを検証したい
Oxygen XML Editorでの補完機能: 編集時にIDの候補を自動表示したい
複数ID参照のサポート: スペース区切りで複数のIDを指定可能にしたい
特定要素のみ参照を許可: witness要素のIDのみを参照可能とし、person要素のIDが含まれる場合はエラーにしたい

なぜRNG + Schematronなのか？

RELAX NGの得意分野

要素・属性の構造定義
データ型の指定
基本的な内容モデルの定義

Schematronの得意分野

XPathベースの複雑な検証ルール
文書内の相互参照チェック
カスタムエラーメッセージの提供

この2つを組み合わせることで、構造と内容の両面から厳密な検証が可能になります。

実装例

1. 基本的なRNGスキーマ構造

<?xml version="1.0" encoding="UTF-8"?>
<grammar xmlns="http://relaxng.org/ns/structure/1.0"
         xmlns:a="http://relaxng.org/ns/compatibility/annotations/1.0"
         xmlns:sch="http://purl.oclc.org/dsdl/schematron"
         datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes"
         ns="http://www.tei-c.org/ns/1.0">

  <!-- Schematron名前空間宣言 -->
  <sch:ns prefix="tei" uri="http://www.tei-c.org/ns/1.0"/>

  <!-- ここにSchematronルールを埋め込む -->

  <start>
    <ref name="TEI"/>
  </start>

  <!-- RNGによる構造定義 -->
</grammar>

2. ID定義とanyURI型の活用

Oxygen XML Editorで自動補完を実現するために、anyURI型を使用します：

<!-- 証本リスト -->
<define name="listWit">
  <element name="listWit">
    <oneOrMore>
      <element name="witness">
        <attribute name="xml:id">
          <data type="ID"/>
        </attribute>
        <text/>
      </element>
    </oneOrMore>
  </element>
</define>

<!-- 底本読み -->
<define name="lem">
  <element name="lem">
    <attribute name="corresp">
      <a:documentation>
        証本への参照
        #付きのIDREF形式で内部参照
        Oxygenでは#付きのxml:id一覧が表示されます
      </a:documentation>
      <list>
        <oneOrMore>
          <data type="anyURI"/>
        </oneOrMore>
      </list>
    </attribute>
    <text/>
  </element>
</define>

ポイント:

data type="ID"で一意性を保証
data type="anyURI"で#付きの内部参照を許可
list要素でスペース区切りの複数値を許可

3. Schematronによる高度な検証

<sch:pattern id="witness-references">
  <sch:title>Witness ID参照の検証</sch:title>

  <sch:rule context="tei:lem[@corresp]">
    <sch:let name="listWitIds" value="//tei:listWit/tei:witness/@xml:id"/>
    <sch:let name="listPersonIds" value="//tei:listPerson/tei:person/@xml:id"/>
    <sch:let name="correspTokens" value="tokenize(normalize-space(@corresp), '\s+')"/>

    <!-- witnessのみを参照すべき -->
    <sch:assert test="every $token in $correspTokens 
                      satisfies (
                        starts-with($token, '#') and 
                        substring($token, 2) = $listWitIds
                      )" role="error">
      corresp属性は証本（witness）のIDのみを参照すべきです。
      利用可能なwitness ID: #<sch:value-of select="string-join($listWitIds, ', #')"/>
    </sch:assert>

    <!-- person IDが含まれている場合のエラー -->
    <sch:report test="some $token in $correspTokens 
                      satisfies (
                        starts-with($token, '#') and 
                        substring($token, 2) = $listPersonIds
                      )" role="error">
      corresp属性に人物（person）のIDが含まれています。
      検出されたperson ID: <sch:value-of select="
        string-join(
          for $token in $correspTokens
          return if (starts-with($token, '#') and substring($token, 2) = $listPersonIds) 
                 then $token 
                 else (),
          ', '
        )
      "/>
    </sch:report>
  </sch:rule>
</sch:pattern>

ポイント:

sch:letで変数を定義し、XPathで動的に値を取得
tokenize()で複数ID参照をパース
sch:assertで条件を満たさない場合にエラー
sch:reportで条件を満たす場合にエラー
role="error"でエラーレベルを指定（warning、info も可能）

4. 実際の使用例

<!-- XML文書での使用 -->
<?xml-model href="schema.rng" type="application/xml" 
    schematypens="http://relaxng.org/ns/structure/1.0"?>
<?xml-model href="schema.rng" type="application/xml" 
    schematypens="http://purl.oclc.org/dsdl/schematron"?>

<TEI xmlns="http://www.tei-c.org/ns/1.0">
    <teiHeader>
        <listWit>
            <witness xml:id="aaa">証本A</witness>
            <witness xml:id="iii">証本I</witness>
        </listWit>
        <listPerson>
            <person xml:id="abc">
                <persName>人物ABC</persName>
            </person>
        </listPerson>
    </teiHeader>
    <text>
        <body>
            <app>
                <!-- 正しい例：witnessのみ参照 -->
                <lem corresp="#aaa #iii">本文</lem>
                <rdg corresp="#aaa">別の読み</rdg>
            </app>
            <app>
                <!-- エラー例：personを含む -->
                <lem corresp="#aaa #abc">本文</lem>
                <rdg>別の読み</rdg>
            </app>
        </body>
    </text>
</TEI>

実装時の注意点

1. XPath 2.0の構文

Schematron内のXPath式では、for式の構文に注意が必要です：

<!-- 正しい -->
let $invalid := (
  for $token in $correspTokens
  return 
    let $id := substring($token, 2)
    return if ($id = $validIds) then () else $token
)

<!-- エラーになる -->
let $invalid := for $token in $correspTokens
                let $id := substring($token, 2)
                return if ($id = $validIds) then () else $token

2. IDREF vs anyURI

IDREF型: #を含めることができず、Oxygenでの補完が制限される
anyURI型: #付きの値を許可し、Oxygenが自動的にID補完を提供

3. Schematronのrole属性

role="error": 赤色のエラーマーカー
role="warning": 黄色の警告マーカー
role="info": 青色の情報マーカー

応用例

複雑な相互参照の検証

<sch:pattern id="cross-references">
  <!-- app要素には必ずlem要素が1つ必要 -->
  <sch:rule context="tei:app">
    <sch:assert test="count(tei:lem) = 1">
      app要素には必ず1つのlem要素が必要です
    </sch:assert>
  </sch:rule>

  <!-- rdg要素のcorrespはlem要素と重複不可 -->
  <sch:rule context="tei:rdg[@corresp]">
    <sch:let name="lemCorresp" value="../tei:lem/@corresp"/>
    <sch:assert test="not(@corresp = $lemCorresp)">
      rdg要素のcorrespはlem要素と異なる値にしてください
    </sch:assert>
  </sch:rule>
</sch:pattern>

条件付き必須属性

<sch:pattern id="conditional-attributes">
  <sch:rule context="tei:date[@when]">
    <!-- when属性がある場合、ISO形式でなければならない -->
    <sch:assert test="matches(@when, '^\d{4}-\d{2}-\d{2}$')">
      when属性はYYYY-MM-DD形式で指定してください
    </sch:assert>
  </sch:rule>
</sch:pattern>

まとめ

RELAX NGとSchematronを組み合わせることで：

構造検証と内容検証の分離: それぞれの得意分野を活かした設計が可能
動的な検証ルール: 文書の内容に基づいた柔軟な検証
エディタ支援: Oxygen XML Editorなどでの高度な編集支援
わかりやすいエラーメッセージ: 日本語でのカスタムメッセージ

特にTEI XMLのような複雑な構造を持つ文書の編集において、この組み合わせは非常に強力なツールとなります。

参考資料

この記事で紹介したスキーマの完全なコードは、実際のプロジェクトで使用されているものです。同様の課題を抱えている方の参考になれば幸いです。