😽
校異源氏物語テキストDBのDTS（Distributed Text Services） APIの更新

2025/05/24に公開
 概要校異源氏物語テキストDBのDTS（Distributed Text Services） APIを更新したので、備忘録です。

 背景DTS（Distributed Text Services） APIは以下で説明されています。
https://distributed-text-services.github.io/specifications/
以下の記事で、DTS APIの作成について紹介しました。
https://zenn.dev/nakamura196/articles/6cb1c7e6a6a6ea
一方、以下を課題としていました。
今回開発したDTS APIも上記のガイドラインに非対応の箇所がある可能性がある点にご注意ください。
そこで、前回作成したAPIをv1とし、今回はdtsVersionの1-alphaに従ったv2のAPIを作成します。

 API以下がEntry Endpointです。v1とv2の違いは以下です。
v1
https://dts-typescript.vercel.app/api/v1/dts
{
    "navigation": "/api/v1/dts/navigation",
    "@id": "/api/v1/dts",
    "@type": "EntryPoint",
    "collections": "/api/v1/dts/collections",
    "@context": "dts/EntryPoint.jsonld",
    "documents": "/api/v1/dts/document"
}
v2
https://dts-typescript.vercel.app/api/v2/dts
{
    "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json",
    "dtsVersion": "1-alpha",
    "@id": "/api/v2/dts",
    "@type": "EntryPoint",
    "collection": "/api/v2/dts/collection{?id}",
    "navigation": "/api/v2/dts/navigation{?resource,ref,down}",
    "document": "/api/v2/dts/document{?resource,ref}"
}
同様に、各種Endpointの記述を変更しています。

 ビューアの改修以下の記事で、DTSのビューア開発について紹介しました。
https://zenn.dev/nakamura196/articles/2075123655d57b
そして、以下を課題としていましたが、この点に対応できるように改修しました。
Navigation Endpointを使用していますが、現時点で複数階層には非対応です。
例えば、Navigation Endpointは以下のように記述します。
https://dts-typescript.vercel.app/api/v2/dts/navigation?resource=urn:kouigenjimonogatari.1&down=1
{
  "@context": "https://distributed-text-services.github.io/specifications/context/1-alpha1.json",
  "dtsVersion": "1-alpha",
  "@type": "Navigation",
  "@id": "/api/v2/dts/navigation?resource=urn:kouigenjimonogatari.1&down=1",
  "resource": {
    "@id": "urn:kouigenjimonogatari.1",
    "@type": "Resource",
    "document": "/api/v2/dts/document?resource=urn:kouigenjimonogatari.1{&ref}",
    "collection": "/api/v2/dts/collection?id=urn:kouigenjimonogatari.1",
    "navigation": "/api/v2/dts/navigation?resource=urn:kouigenjimonogatari.1{&ref}",
    "citationTrees": [
      {
        "@type": "CitationTree",
        "citeStructure": [
          {
            "@type": "CiteStructure",
            "citeType": "page",
            "citeStructure": [
              {
                "@type": "CiteStructure",
                "citeType": "line"
              }
            ]
          }
        ]
      }
    ]
  },
  "member": [
    {
      "identifier": "5",
      "@type": "CitableUnit",
      "level": 1,
      "parent": null,
      "citeType": "page"
    },
    {
      "identifier": "6",
      "@type": "CitableUnit",
      "level": 1,
      "parent": null,
      "citeType": "page"
    },
    {
      "identifier": "7",
      "@type": "CitableUnit",
      "level": 1,
      "parent": null,
      "citeType": "page"
    },
    {
      "identifier": "8",
      "@type": "CitableUnit",
      "level": 1,
      "parent": null,
      "citeType": "page"
    },
...
  ]
}
特に、CitationTreeを使って、階層を記述します。ビューアがこの情報を処理するように修正することで、以下のように、レベルごとのナビゲーションボタンが表示されるようにしました。
例えば、「桐壺」のナビゲーションレベル1・引用タイプがpageを選択すると、以下のようにページ毎のテキストがダウンロードできるページに遷移します。
実際に1つ目の5ページ目をダウンロードした結果が以下です。
https://dts-typescript.vercel.app/api/v2/dts/document?resource=urn:kouigenjimonogatari.1&ref=5
スタイルシートを除外したXMLの例は以下です。dts:wrapperを用いて、部分テキストから構成されるTEI/XMLを返却します。
<text>
    <body>
      <dts:wrapper xmlns:dts="https://w3id.org/api/dts#">
        <p>
          <pb corresp="#zone_0005" facs="https://dl.ndl.go.jp/api/iiif/3437686/R0000022/0,0,3445,4706/full/0/default.jpg" n="5"/>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-01.json">いつれの御時にか女御更衣あまたさふらひ給けるなかにいとやむことなきゝは</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-02.json">にはあらぬかすくれて時めき給ありけりはしめより我はと思あかり給へる御方</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-03.json">〱めさましきものにおとしめそねみ給おなしほとそれより下らうの更衣たち</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-04.json">はましてやすからすあさゆふの宮つかへにつけても人の心をのみうこかしうら</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-05.json">みをおふつもりにやありけむいとあつしくなりゆきもの心ほそけにさとかちな</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-06.json">るをいよ〱あかすあはれなる物におもほして人のそしりをもえはゝからせ給</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-07.json">はす世のためしにもなりぬへき御もてなし也かんたちめうへ人なともあいなく</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-08.json">めをそはめつゝいとまはゆき人の御おほえなりもろこしにもかゝることのおこ</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-09.json">りにこそ世もみたれあしかりけれとやう〱あめのしたにもあちきなう人のも</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-10.json">てなやみくさになりて楊貴妃のためしもひきいてつへくなりゆくにいとはした</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-11.json">なきことおほかれとかたしけなき御心はへのたくひなきをたのみにてましらひ</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-12.json">給ちゝの大納言はなくなりてはゝ北の方なんいにしへの人のよしあるにておや</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-13.json">うちくしさしあたりて世のおほえはなやかなる御方〱にもいたうおとらすな</seg>
          <lb/>
          <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-14.json">にことのきしきをももてなしたまひけれととりたてゝはか〱しきうしろみし</seg>
          <lb/>
        </p>
      </dts:wrapper>
    </body>
  </text>
同様に、ナビゲーションレベル2・引用タイプがlineのダウンロード例が以下です。
https://dts-typescript.vercel.app/api/v2/dts/document?resource=urn:kouigenjimonogatari.1&ref=https://w3id.org/kouigenjimonogatari/api/items/0005-01.json
スタイルシートを除外したXMLの例は以下です。dts:wrapperを用いて、部分テキストから構成されるTEI/XMLを返却します。
<TEI xmlns="http://www.tei-c.org/ns/1.0" xmlns:dts="https://w3id.org/api/dts#">
...
  <text>
    <body>
      <dts:wrapper xmlns:dts="https://w3id.org/api/dts#">
        <seg corresp="https://w3id.org/kouigenjimonogatari/api/items/0005-01.json">いつれの御時にか女御更衣あまたさふらひ給けるなかにいとやむことなきゝは</seg>
      </dts:wrapper>
    </body>
  </text>
</TEI>

 参考
 xml-formatterNode.jsを用いてXMLを整形する際、以下のライブラリが便利でした。
https://www.npmjs.com/package/xml-formatter

 DeepWikiDeepWikiを使って、ドキュメントの自動生成を行いました。
https://deepwiki.com/nakamura196/dts-typescript
以下、最新のものではありませんが、エンドポイントの一覧などが作成されていました。

 まとめ誤った理解をしている点もあるかもしれませんが、参考になりましたら幸いです。
なお、Collection Endpointのnav変数や、Navigation/Document Endpointのstart/end変数など、まだ対応できていない点があるので、いずれ対応したいと思います。
概要

背景

API

ビューアの改修

参考

xml-formatter

DeepWiki

まとめ

Discussion
