Correspondence Metadata Interchange format

Documentation

Overview

The web service correspSearch aggregates and interprets digital indexes of letters from scholarly editions or repositories, which are provided online as TEI-XML files in the Correspondence Metadata Interchange (CMI) format. The CMI format was developed by the TEI Correspondence SIG and is a highly reduced and restricted subset of the TEI Guidelines which is based mainly on the TEI element correspDesc.

The Basis of a digital index of letters according to the CMI format is a TEI-XML file. You can download a template with short descriptions here.

Correspondence Metadata

The TEI-XML file contains as many correspDesc elements as you have letters, postcards, etc. in your scholarly edition. A particular correspDesc element in CMI format is more restrictive and reduced with regard to its vocabulary than the TEI Guidlines generally allow. This enables interchange between the respective TEI documents.

The image shows schematically the different parts of a correspDesc element in the CMI format. The addressee and sender are documented the same way. The example originates from an example provided by the TEI Correspondence SIG.

Please note, that the web service searches persons and places using authority controlled IDs. Therefore, you should provide authority controlled IDs for as many persons and places as possible (for more information see below).

The following table offers detailed information about the particular parts of a correspDesc element in the CMI format:

XPath (relative to correspDesc) Description Value(s) and Notes
/correspAction Includes the data related to the sending/receiving process of a letter, postcard etc. Only child elements, no text allowed
/correspAction/@type Type of the correspondence action Allowed: "sent", "received"
/correspAction/persName Personal name of sender or addressee Mandatory; if the sender or addressee is unknown please indicate this by the string "Unknown"
/correspAction/persName/@ref Authority controlled ID of sender or addressee If available. The following authority controlled files are supported: VIAF, GND, LC, BNF and NDL. Please note that the web service searches for persons and places using authority controlled IDs. For further information see the FAQ section
/correspAction/orgName Name of institution, company etc. Optional, if persName is not applicable
/correspAction/placeName Name of the place a letter was sent from or where it is being sent to If available
/correspAction/placeName/@ref Authority controlled ID of the place a letter was sent from or where it is being sent to If available. The following authority controlled files are supported: GeoNames
/correspAction/date Machine-readable date of when the letter was sent or received If available. The web service supports the attributes @when, @from, @to, @notBefore and @notAfter. Unlike the TEI Guidelines the web service supports only the following date formats:
  • YYYY-MM-DD, e.g. 1804-03-01
  • YYYY-MM, e.g. 1804-03
  • YYYY, e.g. 1808
All other formats will not be processed.

The correspDesc elements are noted inside teiHeader/profileDesc.

Information about the digital index of letters

Besides the letter's bibliographic metadata, you have to include some information about the index of letters itself in the teiHeader/fileDesc element. All elements there are mandatory if not stated otherwise.

XPath Description Value(s) and Notes
//titleStmt/title Title of the digital index of letters Free text field
//titleStmt/editor Contact person concerning the digital index of letters If available with an e-mail address in editor/email
//publicationStmt/publisher Author of the letter metadata as defined in the Creative Commons Licence CC-BY 4.0 Free text field
//publicationStmt/availability/licence Licence statement Mandatory: "This file is licensed under the terms of the Creative Commons License CC-BY 4.0"
//publicationStmt/availability/licence/@target URL of the licence Mandatory: "https://creativecommons.org/licenses/by/4.0/"
//publicationStmt/date/@when Timestamp of the last update of this file Format: xsd:dateTime
//publicationStmt/idno URL of this digital index of letters The URL serves as a unique identifier
//publicationStmt/idno/@type Type of the above mentioned identifier Mandatory: "URL"
//sourceDesc/bibl Bibliographic information about the scholarly edition from which the correspondence metadata is derived from. No specifications.
//sourceDesc/bibl/@type Type of scholarly edition The following values are allowed: "print", "online"

Validation and registration

Once the file is available online, it may be tested for technical correctness by using correspSearch's validation service. This validation service only needs the URL of the correspBeacon file as input. If there are any errors, the validation service returns explanatory error messages.

´╗┐

Any further questions?

For more information see the FAQ section.

Further information

You can find further examples of the CMI format on the GitHub repository of the TEI Correspondence SIG.

Future of the CMI format

A blog article on digiversity discusses the further development of the CMI format.