DTS（Distributed Text Services）を使ってみる

概要

DTS（Distributed Text Services）の使用方法を学ぶ機会があり、その備忘録です。

使用するAPI

以下で紹介されているAlpheiosを使用します。

https://github.com/distributed-text-services/specifications/?tab=readme-ov-file#known-corpora-accessible-via-the-dts-api

トップ

https://texts.alpheios.net/api/dts

collections, documents, navigationが使えることがわかります。

{
	"navigation": "/api/dts/navigation",
	"@id": "/api/dts",
	"@type": "EntryPoint",
	"collections": "/api/dts/collections",
	"@context": "dts/EntryPoint.jsonld",
	"documents": "/api/dts/document"
}

Collection Endpoint

collections

https://texts.alpheios.net/api/dts/collections

2つの下位コレクションが含まれることがわかります。

{
	"totalItems": 2,
	"member": [
		{
			"@id": "urn:alpheios:latinLit",
			"@type": "Collection",
			"totalItems": 3,
			"title": "Classical Latin"
		},
		{
			"@id": "urn:alpheios:greekLit",
			"@type": "Collection",
			"totalItems": 4,
			"title": "Ancient Greek"
		}
	],
	"title": "None",
	"@id": "default",
	"@type": "Collection",
	"@context": {
		"dts": "https://w3id.org/dts/api#",
		"@vocab": "https://www.w3.org/ns/hydra/core#"
	}
}

Classical Latin

idurn:alpheios:latinLitを指定して、コレクションをClassical Latinに限定します。

https://texts.alpheios.net/api/dts/collections?id=urn:alpheios:latinLit

3つの下位コレクションが含まれることがわかります。

{
	"totalItems": 3,
	"member": [
		{
			"@id": "urn:cts:latinLit:phi0472",
			"@type": "Collection",
			"totalItems": 1,
			"title": "Catullus"
		},
		{
			"@id": "urn:cts:latinLit:phi0620",
			"@type": "Collection",
			"totalItems": 1,
			"title": "Propertius, Sextus"
		},
		{
			"@id": "urn:cts:latinLit:phi0959",
			"@type": "Collection",
			"totalItems": 1,
			"title": "Ovid"
		}
	],
	"title": "Classical Latin",
	"@id": "urn:alpheios:latinLit",
	"@type": "Collection",
	"@context": {
		"dts": "https://w3id.org/dts/api#",
		"@vocab": "https://www.w3.org/ns/hydra/core#",
		"ns1": "http://www.w3.org/2004/02/skos/core#"
	},
	"dts:extensions": {
		"ns1:prefLabel": [
			{
				"@value": "Classical Latin",
				"@language": "eng"
			}
		]
	}
}

Catullus

idurn:cts:latinLit:phi0472を指定して、コレクションをCatullusに限定します。

https://texts.alpheios.net/api/dts/collections?id=urn:cts:latinLit:phi0472

1つの下位コレクションが含まれることがわかります。

{
	"totalItems": 1,
	"member": [
		{
			"@id": "urn:cts:latinLit:phi0472.phi001",
			"@type": "Collection",
			"totalItems": 1,
			"title": "Carmina"
		}
	],
	"title": "Catullus",
	"@id": "urn:cts:latinLit:phi0472",
	"@type": "Collection",
	"@context": {
		"dts": "https://w3id.org/dts/api#",
		"cts": "http://chs.harvard.edu/xmlns/cts/",
		"ns1": "http://www.w3.org/2004/02/skos/core#",
		"@vocab": "https://www.w3.org/ns/hydra/core#"
	},
	"dts:extensions": {
		"cts:groupname": [
			{
				"@value": "Catullus",
				"@language": "eng"
			}
		],
		"ns1:prefLabel": [
			{
				"@value": "Catullus",
				"@language": "eng"
			}
		]
	}
}

Carmina

idurn:cts:latinLit:phi0472.phi001を指定して、コレクションをCarminaに限定します。

https://texts.alpheios.net/api/dts/collections?id=urn:cts:latinLit:phi0472.phi001

これまでとは結果が異なり、memberにResourceタイプのデータが含まれることがわかります。

{
	"totalItems": 1,
	"member": [
		{
			"totalItems": 0,
			"dts:citeStructure": {
				"dts:citeType": "poem",
				"dts:citeStructure": [
					{
						"dts:citeType": "line"
					}
				]
			},
			"dts:extensions": {
				"cts:label": [
					{
						"@value": "Carmina",
						"@language": "lat"
					}
				],
				"ns2:language": "lat",
				"ns1:prefLabel": [
					{
						"@value": "Carmina",
						"@language": "lat"
					}
				],
				"cts:description": [
					{
						"@value": "Catullus, Gaius Valerius, creator; Merrill, Elmer Truesdell, 1860-1936, editor",
						"@language": "eng"
					}
				]
			},
			"dts:passage": "/api/dts/document?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1",
			"title": "Carmina",
			"@id": "urn:cts:latinLit:phi0472.phi001.alpheios-text-lat1",
			"@type": "Resource",
			"dts:references": "/api/dts/navigation?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1",
			"dts:citeDepth": 2
		}
	],
	"title": "Carmina",
	"@id": "urn:cts:latinLit:phi0472.phi001",
	"@type": "Collection",
	"@context": {
		"dts": "https://w3id.org/dts/api#",
		"cts": "http://chs.harvard.edu/xmlns/cts/",
		"ns1": "http://www.w3.org/2004/02/skos/core#",
		"@vocab": "https://www.w3.org/ns/hydra/core#",
		"ns2": "http://purl.org/dc/elements/1.1/"
	},
	"dts:extensions": {
		"cts:title": [
			{
				"@value": "Carmina",
				"@language": "lat"
			}
		],
		"ns2:language": "lat",
		"ns1:prefLabel": [
			{
				"@value": "Carmina",
				"@language": "lat"
			}
		]
	}
}

また、dts:passageでDocument EndpointへのURL、dts:referencesでNavigation EndpointへのURLが確認できます。

Navigation Endpoint

トップ

先に取得した以下のNavigation EndpointのURLにアクセスします。

https://texts.alpheios.net/api/dts/navigation?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1

{
	"passage": "/api/dts/document?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1{&ref}{&start}{&end}",
	"level": 1,
	"citeType": "poem",
	"@id": "/api/dts/navigation?level=1&id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1&groupBy=1",
	"citeDepth": 2,
	"@context": {
		"hydra": "https://www.w3.org/ns/hydra/core#",
		"@vocab": "https://w3id.org/dts/api#"
	},
	"hydra:member": [
		{
			"ref": "1"
		},
		{
			"ref": "2"
		},
		{
			"ref": "3"
		},
		{
			"ref": "4"
		},
		{
			"ref": "5"
		},
		{
			"ref": "6"
		},
		{
			"ref": "7"
		},
		{
			"ref": "8"
		},
		{
			"ref": "9"
		},
		{
			"ref": "10"
		},
		{
			"ref": "11"
		},
		{
			"ref": "12"
		},
		{
			"ref": "13"
		},
		{
			"ref": "14"
		},
		{
			"ref": "14b"
		},
		{
			"ref": "15"
		},
		{
			"ref": "16"
		},
		{
			"ref": "17"
		},
		{
			"ref": "21"
		},
		{
			"ref": "22"
		},
		{
			"ref": "23"
		},
		{
			"ref": "24"
		},
		{
			"ref": "25"
		},
		{
			"ref": "26"
		},
		{
			"ref": "27"
		},
		{
			"ref": "28"
		},
		{
			"ref": "29"
		},
		{
			"ref": "30"
		},
		{
			"ref": "31"
		},
		{
			"ref": "32"
		},
		{
			"ref": "33"
		},
		{
			"ref": "34"
		},
		{
			"ref": "35"
		},
		{
			"ref": "36"
		},
		{
			"ref": "37"
		},
		{
			"ref": "38"
		},
		{
			"ref": "39"
		},
		{
			"ref": "40"
		},
		{
			"ref": "41"
		},
		{
			"ref": "42"
		},
		{
			"ref": "43"
		},
		{
			"ref": "44"
		},
		{
			"ref": "45"
		},
		{
			"ref": "46"
		},
		{
			"ref": "47"
		},
		{
			"ref": "48"
		},
		{
			"ref": "49"
		},
		{
			"ref": "50"
		},
		{
			"ref": "51"
		},
		{
			"ref": "52"
		},
		{
			"ref": "53"
		},
		{
			"ref": "54"
		},
		{
			"ref": "55"
		},
		{
			"ref": "56"
		},
		{
			"ref": "57"
		},
		{
			"ref": "58"
		},
		{
			"ref": "58b"
		},
		{
			"ref": "59"
		},
		{
			"ref": "60"
		},
		{
			"ref": "61"
		},
		{
			"ref": "62"
		},
		{
			"ref": "63"
		},
		{
			"ref": "64"
		},
		{
			"ref": "65"
		},
		{
			"ref": "66"
		},
		{
			"ref": "67"
		},
		{
			"ref": "68a"
		},
		{
			"ref": "68b"
		},
		{
			"ref": "69"
		},
		{
			"ref": "70"
		},
		{
			"ref": "71"
		},
		{
			"ref": "72"
		},
		{
			"ref": "73"
		},
		{
			"ref": "74"
		},
		{
			"ref": "75"
		},
		{
			"ref": "76"
		},
		{
			"ref": "77"
		},
		{
			"ref": "78"
		},
		{
			"ref": "78b"
		},
		{
			"ref": "79"
		},
		{
			"ref": "80"
		},
		{
			"ref": "81"
		},
		{
			"ref": "82"
		},
		{
			"ref": "83"
		},
		{
			"ref": "84"
		},
		{
			"ref": "85"
		},
		{
			"ref": "86"
		},
		{
			"ref": "87"
		},
		{
			"ref": "88"
		},
		{
			"ref": "89"
		},
		{
			"ref": "90"
		},
		{
			"ref": "91"
		},
		{
			"ref": "92"
		},
		{
			"ref": "93"
		},
		{
			"ref": "94"
		},
		{
			"ref": "95"
		},
		{
			"ref": "96"
		},
		{
			"ref": "97"
		},
		{
			"ref": "98"
		},
		{
			"ref": "99"
		},
		{
			"ref": "100"
		},
		{
			"ref": "101"
		},
		{
			"ref": "102"
		},
		{
			"ref": "103"
		},
		{
			"ref": "104"
		},
		{
			"ref": "105"
		},
		{
			"ref": "106"
		},
		{
			"ref": "107"
		},
		{
			"ref": "108"
		},
		{
			"ref": "109"
		},
		{
			"ref": "110"
		},
		{
			"ref": "111"
		},
		{
			"ref": "112"
		},
		{
			"ref": "113"
		},
		{
			"ref": "114"
		},
		{
			"ref": "115"
		},
		{
			"ref": "116"
		}
	]
}

refパラメータの指定

得られた結果に基づき、以下のように&ref=1を追加してみます。

https://texts.alpheios.net/api/dts/navigation?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1&ref=1

以下の結果が得られました。

{
	"passage": "/api/dts/document?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1{&ref}{&start}{&end}",
	"level": 2,
	"citeType": "line",
	"@id": "/api/dts/navigation?ref=1&level=1&id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1&groupBy=1",
	"citeDepth": 2,
	"@context": {
		"hydra": "https://www.w3.org/ns/hydra/core#",
		"@vocab": "https://w3id.org/dts/api#"
	},
	"hydra:member": [
		{
			"ref": "1.1"
		},
		{
			"ref": "1.2"
		},
		{
			"ref": "1.3"
		},
		{
			"ref": "1.4"
		},
		{
			"ref": "1.5"
		},
		{
			"ref": "1.6"
		},
		{
			"ref": "1.7"
		},
		{
			"ref": "1.8"
		},
		{
			"ref": "1.9"
		},
		{
			"ref": "1.10"
		}
	]
}

InvalidLevel

citeDepthが2になっているため、これ以上下の階層を探索することはできないはずです。

確認のため、以下にアクセスしてみます。

https://texts.alpheios.net/api/dts/navigation?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1&ref=1.1

結果、以下のようにエラーが返却されました。

{
	"statusCode": 404,
	"@type": "Status",
	"@context": "http://www.w3.org/ns/hydra/context.jsonld",
	"description": " Invalid value for level parameter in Navigation Endpoint request ",
	"title": "InvalidLevel"
}

Document Endpoint

トップ

Collection Endpointで得られた以下にアクセスしてみます。

https://texts.alpheios.net/api/dts/document?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1

結果、以下のTEI/XMLの全体が取得できました。

<TEI xmlns="http://www.tei-c.org/ns/1.0">
  <script />
  <teiHeader>
    <fileDesc>
      <titleStmt>
        <title>Carmina</title>
        <title type="sub">Machine readable text</title>
        <author>C. Valerius Catullus</author>
        <editor role="editor">E. T. Merrill</editor>
        <sponsor>Perseus Project, Tufts University</sponsor>
        <principal>Gregory Crane</principal>
        <respStmt>
          <resp>Prepared under the supervision of</resp>
          <name>Bridget Almas</name>
          <name>Lisa Cerrato</name>
          <name>William Merrill</name>
          <name>David Smith</name>
        </respStmt>
        <funder n="org:NEH">The National Endowment for the Humanities</funder>
      </titleStmt>
      <extent>about 112Kb</extent>
      <publicationStmt>
        <publisher>Trustees of Tufts University</publisher>
        <pubPlace>Medford, MA</pubPlace>
        <authority>Perseus Project</authority>
        <date type="release">1997-10-28</date>
      </publicationStmt>
      <sourceDesc>
        <biblStruct>
          <monogr>
            <author>Catullus</author>
            <title>Catullus</title>
            <editor role="editor">Elmer Truesdell Merrill</editor>
            <imprint>
              <pubPlace>Boston</pubPlace>
              <publisher>Ginn and Company</publisher>
              <date>1893</date>
            </imprint>
          </monogr>
        </biblStruct>
      </sourceDesc>
    </fileDesc>
    <encodingDesc>
      <refsDecl n="TEI.2">
        <refState unit="poem" />
        <refState unit="line" />
      </refsDecl>
      <refsDecl n="CTS">
        <cRefPattern n="line" matchPattern="(\w+).(\w+)" replacementPattern="#xpath(/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='$1']//tei:l[@n='$2'])">
          <p>This pointer pattern extracts poem and line</p>
        </cRefPattern>
        <cRefPattern n="poem" matchPattern="(\w+)" replacementPattern="#xpath(/tei:TEI/tei:text/tei:body/tei:div/tei:div/tei:div[@n='$1'])">
          <p>This pointer pattern extracts poem</p>
        </cRefPattern>
      </refsDecl>
    </encodingDesc>
    <profileDesc>
      <langUsage>
        <language ident="lat">Latin </language>
        <language ident="eng">English </language>
      </langUsage>
    </profileDesc>
    <revisionDesc>
      <change when="2018-04-04" who="Thibault Clerice">Removing duplicates</change>
      <change when="2014-11-06" who="Thibault Clerice">Moving to Epidoc with new URN</change>
      <change when="2013-09-13" who="balmas01">moving Greg's work-in-progress on CTS-izing greco-roman collection texts to a Work directory</change>
        ...
    </revisionDesc>
  </teiHeader>
  <text>
    <body>
      <div type="edition" xml:lang="lat" n="urn:cts:latinLit:phi0472.phi001.perseus-lat2">
        <div type="textpart" subtype="Lyrics">
          <div type="textpart" subtype="poem" n="1">
            <milestone unit="meter" n="Phalaecean" />
            <head xml:lang="eng" rend="newlevel">1</head>
            <l n="1">Cui dono lepidum novum libellum</l>
            <l n="2">arido modo pumice expolitum?</l>
            <l n="3">Corneli, tibi; namque tu solebas</l>
            <l n="4">meas esse aliquid putare nugas,</l>
            <l n="5">iam tum cum ausus es unus Italorum</l>
            <l n="6">omne aevum tribus explicare chartis,</l>
            <l n="7">doctis, Iuppiter, et laboriosis!</l>
            <l n="8">quare habe tibi quidquid hoc libelli</l>
            <l n="9">qualecumque, quod, o patrona virgo,</l>
            <l n="10">plus uno maneat perenne saeclo.</l>
          </div>
          <div type="textpart" subtype="poem" n="2">
            <milestone unit="meter" n="Phalaecean" />
            <head xml:lang="eng" rend="newlevel">2</head>
            <l n="1">Passer, deliciae meae puellae,</l>
            <l n="2">quicum ludere, quem in sinu tenere,</l>
            <l n="3">cui primum digitum dare adpetenti</l>
            <l n="4">et acris solet incitare morsus,</l>
            ...
          </div>
        </div>
      </div>
    </body>
  </text>
</TEI>

refパラメータの指定

Navigation Endpointで得られたref1を使用して、以下にアクセスしてみます。

https://texts.alpheios.net/api/dts/document?id=urn%3Acts%3AlatinLit%3Aphi0472.phi001.alpheios-text-lat1&ref=1

結果、以下が得られました。subtypepoem、n1の部分テキストが得られました。部分テキストの場合、<dts:fragment xmlns:dts="https://w3id.org/dts/api#">が使用されるようでした。

<TEI xmlns="http://www.tei-c.org/ns/1.0" xmlns:py="http://codespeak.net/lxml/objectify/pytype" py:pytype="TREE">
  <dts:fragment xmlns:dts="https://w3id.org/dts/api#">
    <text>
      <body>
        <div type="edition" xml:lang="lat" n="urn:cts:latinLit:phi0472.phi001.perseus-lat2">
          <div type="textpart" subtype="Lyrics">
            <div type="textpart" subtype="poem" n="1">
              <milestone unit="meter" n="Phalaecean" />
              <head xml:lang="eng" rend="newlevel">1</head>
              <l n="1">Cui dono lepidum novum libellum</l>
              <l n="2">arido modo pumice expolitum?</l>
              <l n="3">Corneli, tibi; namque tu solebas</l>
              <l n="4">meas esse aliquid putare nugas,</l>
              <l n="5">iam tum cum ausus es unus Italorum</l>
              <l n="6">omne aevum tribus explicare chartis,</l>
              <l n="7">doctis, Iuppiter, et laboriosis!</l>
              <l n="8">quare habe tibi quidquid hoc libelli</l>
              <l n="9">qualecumque, quod, o patrona virgo,</l>
              <l n="10">plus uno maneat perenne saeclo.</l>
            </div>
          </div>
        </div>
      </body>
    </text>
  </dts:fragment>
</TEI>

まとめ

DTSの各種エンドポイントの使い方の一例を確認しました。DTSの理解にあたり、参考になりましたら幸いです。