Coding Conventions

CAO has a few simple required coding conventions for the EAD finding aids that it searches.  The four requirements below ensure that CAO functions as intended. None of these four coding conventions runs contrary to best practices for EAD.

  1. EADs that are indexed in CAO must be “well-formed” and valid (either against the 2002 schema or the v.1 DTD)
    • In general, your EADs should be clean of unnecessary spaces and line breaks, especially within tags. This is not an issue if you are using a tool like ArchivesSpace to generate your EAD. If you are encoding by hand with a text editor, HTML Tidy [] can help to clean-up files.  If you use CAO’s template, you should not have an issue with unnecessary spaces and line breaks.  
  2. File names must be the same as the <eadid> value.  (This enables the “show containers” fuction. The “show containers” button on CAO search results will show keyword hits in the <unittitle>s of a finding aid’s inventory or <dsc> directly in the search result list).
    • The content of the <eadid> (that is, what’s between the <eadid> and </eadid>) must be the same as the prefix of the EAD document’s file name.  An EAD file named: “findingAid.xml”, must have an <eadid> value of “findingAid”.  See the example <eadid> below for a file named: “findingAid.xml”:
<eadid mainagencycode="US-ctdabn"
      • Filenames and <eadid>s ARE case sensitive.  FindingAid is not the same as Findingaid and will be seen as different in CAO’s indexer.
      • Filenames and <eadid>s should be alpha-numeric.  Therefore, you should not use spaces,  hyphens, quatation marks, dollar signs, periods (except before the file extension), ampersands, etc.).  This helps in reducing errors that can occur in the indexer when file names look like a coding syntax.

3. There must be a URL attribute in the <eadid> 

      • The value of the url attribute in the <eadid> tag must contain the link back to the ead document on your server OR a link to where that finding is published.
      • See the url attribute below points to where the repository’s finding aid lives:
<eadid mainagencycode="US-ctanycol" url="">academicPrograms</eadid>

With the URL attribute encoded correctly, a search in CAO will drive users to YOUR site.

4. There must be a mainagency code in the <eadid>

      • You must have a mainagency code as an attribute in the <eadid> tag.  You will either have a code already or we can assign you one, but CAO’s search knows what repository a particular finding aid is from by the mainagencycode attribute in the eadid. If you are using ArchivesSpace, the bucket for the mainagency code is in the repository record and will be exported with every EAD file in that repostory from your system.
      • Notice in the one of the examples above that the mainagencycode=”US-ctdabn“;  that’s for Western Connecticut State University and we found that code at:  You can then append to the beginning of that code the following (uppercase): “US-“.  Users of ArchivesSpace, will see that it automatically appends the country code to the mainagency code when the country code is added to the repository record.

That’s it!  Again, these four conventions required above are all in line with EAD best practice. 


There is one optional “requirement” which is not EAD code-based.  EADs with no top-level <abstract>, <unittitle> or <controlaccess> elements may be valid but will be difficult to identify when among a group of search results in CAO.  Arguably, a finding aid without those elements is not superior to one with them, so, why not add them?