EAS Codelists & Validation Suite

This repository provides controlled vocabulary management and Schematron validation for the EAD4, EAC-CPF 3.0, and EAF 1.0 archival standards.

Core Components

• The Codelist Builder: scripts/build-registry.py harvests data from the SAA-SDT "Best Practices" Markdown and global ISO standards.
• The Codelist Artifact: web/eas-registry.xml is the unified "Source of Truth" generated by the Codelist Builder for EAS Value Lists and ISO standards.
• The Schematron Driver: src/eas-driver.sch orchestrates namespaces and imports the eas-registry file.

Ultimate Deliverable

• Standalone Schematron files: schematron/ holds the three Schematron deliverables, one for each EAS Standard.

Getting Started

1. Configure Python Virtual Environment

To ensure all dependencies (like requests) are handled cleanly, use a virtual environment:

# Create the environment
python -m venv venv

# Activate it (macOS/Linux)
source venv/bin/activate

# Activate it (Windows)
.\venv\Scripts\activate

# Install dependencies
pip install requests

2. Build the Registry

Once your environment is active, run the build script to generate the latest XML registry:

python scripts/build-registry.py

Project Structure

• .github/
  • workflows/
    • registry-and-validation.yml
• scripts/
  • build-registry.py: The Python engine that generates the web/eas-registry.xml file.
  • flatten.xsl: The XSLT file used to flatten the Schematron for each EAS deliverable, which pulls in the web/eas-registry.xml file
• src/
  • ead.sch, eac.sch, eaf.sch: Standard-specific entry points for validation.
  • eas-driver.sch: The core orchestrator managing namespaces and registry imports.
  • functions/date-functions.xsl: XSLT 3.0/4.0 engine for EDTF validation.
  • modules/: Shared business logic for codes and dates.
• web/
  • index.html: The user interface for the drag-and-drop web validator.
  • eas-rules.sef.json: The compiled version of the validation logic.
  • eas-registry.xml: The generated XML source of truth.
  • validator.js: The JavaScript glue code that runs the Saxon-JS engine.

3. Validating Locally

This project uses Saxon-JS and NPM (Node Package Manager) to compile the Schematron files into executable XSLT and SEF files.

Prerequisites

To build the rules locally, you will need to have Node.js installed on your machine.

Setup

The first time you clone this repository, you need to install the build tools. Open your terminal, navigate to this project folder, and run:

npm install

Compiling the Schematron Rules

Whenever you make changes to the .sch files in the /src directory, you must recompile them if you want to test locally (these steps are handled automatically on any merge to the 'main' branch). To clean the old builds and generate the new validation files for EAD, EAC, and EAF, run:

npm run build

What this does

1. Empties the old /build and /schematron directories.
2. Flattens the source Schematron files.
3. Transpiles them into XSLT using SchXslt.
4. Exports the final rules as compiled .sef.json files in the /web directory.

These same steps are run whenever a branch is merged into the main branch of this GitHub repository.

Testing the Website locally

Next, if you would like to test out the RNG+Schematron Web Validation tool locally, you can run the following command to start up a local, cache-disabled web server:

npm run serve

Then, visit http://127.0.0.1:8080/ to interact with the web/index.html Validation webpage.

Summary of Tests Provided

The TS-EAS Schematron files currently specify the following tests:

• When an encoding list is set to EASList in then control section, then the corresponding values for that list specified at https://saa-sdt.github.io/EAS-Best-Practices/docs/control/value-lists will be checked.

• When a language encoding of iso639-1, iso639-2, iso639-2b, iso639-2t, iso639-3, or ietf-bcp-47 is set in the control section, then every languageOfElement and languageCode attribute in the document will be tested against a regular expression pattern that adheres to that specific standard.

  • For example, if either iso639-1 or ietf-bcp-47 is set in the control section, then a value of "fr" will validate because those two characters are found in the associated regular expression pattern.

• The countryCode attribute will be validated against ISO 3166-1, unless eac:control/@contryEncoding is set to "otherCountryEncoding".

• All scriptCode and scriptOfElement attributes will be validated against ISO 15924, unless eac:control/@scriptEncoding is set to "otherScriptEncoding".

• The text value of the agencyCode element will be validated against a expression value that adheres to the ISO 15511 standard, unless eac:control/@repostioryEncoding is set to "otherRepositoryEncoding". The regular expression requires a prefix, a hyphen ("-"), and an identifier.

  • The prefix must either match a country code from ISO 3166-1, or it must include three to four characters in the A to Z range, regardless of case (e.g. "oclc", "EUR", and "SzB" are all valid prefixes).
  • The identifier that follows the hyphen can be 1 to 11 characters long and include a mix of A-Z characters (regardless of case), numeric characters from 0-9, as well as any of the additional three characters: ":", "/", and "-".

• Every '@id' attribute will be tested in the document to ensure that each id only occurs once. This test is already carried out by the XSD version of the schema, but it is not enforced by the RNG version due to how RNG treats the xsd:ID datatype.

• Every reference-related (e.g. '@sourceReference') and target attribute present will be tested to ensure that the attribute is linked elsewhere in the current file.

  • @conventionDeclarationReference: must be linked to an @id found in a conventionDeclaration element.
  • @localTypeDeclarationReference: must be linked to an @id found in a localTypeDeclaration element.
  • @maintenanceEventReference: must be linked to an @id found in a maintenanceEvent element.
  • @sourceReference: must be linked either to an @id found in a source element or a citedRange element.
  • @target: must be linked to an @id found somewhere within the current document.

• The maintanceAgency element within the control section must include either a non-empty agencyCode element or a non-empty agencyName element. It can also have both, but it needs one of the two at a minimum.

• The eventDateTime element must include either a @standardDateTime attribute or text.

• Any use of the @era attribute should be restricted to either 'ce' or 'bce'.

• Unless the dateEncoding within the control section is set to "otherDateEncoding", then a sub-profile of dates allowable by ISO 8601:2019, parts 1 and 2 (which includes EDTF dates), will be enforced. The Schematron file includes the following restrictions on the @notAfter, @notBefore, @standardDate attributes:

  1. Valid dates within all three attributes may be composed of the following:
     • a Year
       • which may optionally start with a "+" or "-".
       • contain no less than 4 characters (e.g. year 100 must be encoded as 0100), and no more than 10 characters.
       • contains numeric characters, or an X to indicate an unknown value, according to the new EDTF features provided in ISO 8601:2019. e.g. "192X" is valid.
     • a Year, a hyphen separtor (intended to not be optional in our subprofile of ISO 8601), and a Season, which must have a value of 21 to 41, according to ISO 8601:2019
     • a Year, a hyphen separator, and a Month, which must include a value from 01 (for January) to 12 (for December). Unknown values can optionally be indicated with an "X".
     • a Year, a hyphen separator, a Month, a hyphen seprator, and a Day, which must be include two characters in the range of 01 to 31, with an optional X to indicate an unknown value. If the month is February, then 30 and 31 will be invalid values, and 29 should only be valid for leap years.
     • a Year, a hyphen seprator, a Month, a hyphen seprator, a Day, and a Time, which can either start with a "T" or a " ".
     • a qualifier that precedes or follows any of those parts. The valid qualifiers are "?" (i.e. uncertain), "~" (i.e. approximate), and "%" (i.e. uncertain and approximate).
  2. @notAfter and @notBefore must not contain any date ranges, which may be specified with ".." and "/". If date ranges are required, then those should only be encoded within a @standardDate attribute that is present on a date element (not a fromDate or toDate element).
  3. Further, though date ranges may start and end with "..", they should not start or end with a "/".
  4. Last, regarding date ranges, only one range can be specified in our profile. In other words: 1800/1820 is valid, but 1800/1820..1830 would not be. Similarly, a single attribute that encodes a date set and range (e.g. 1800,1802,1807,1810..1820) would also not be valid. For that case, the dateSet element should be utlized instead.

• When XHTML is used within the formattingExtension element, then a subset of HTML elements and attributes will be asserted as valid within the context of the EAS schemas. See

  eas-schematron-validator/scripts/build-registry.py

  Lines 19 to 58 in 75c901d

  	"xhtml_matrix": {
  	"global_attributes": [
  	"id", "class", "title", "lang", "xml:lang", "dir"
  	],
  	"elements": {
  	# Headings and Blocks
  	"h1": [], "h2": [], "h3": [], "h4": [], "h5": [], "h6": [],
  	"div": [], "p": [], "br": [], "hr": [],
  	# Lists
  	"ul": [],
  	"ol": ["start", "type", "reversed"],
  	"li": ["value"],
  	"dl": [], "dt": [], "dd": [],
  	# Tables
  	"table": [], "caption": [],
  	"thead": [], "tbody": [], "tfoot": [], "tr": [],
  	"th": ["abbr", "axis", "headers", "colspan", "rowspan", "scope"],
  	"td": ["abbr", "axis", "headers", "colspan", "rowspan", "scope"],
  	# Inline Text
  	"em": [], "strong": [], "dfn": [], "code": [],
  	"sub": [], "sup": [], "span": [], "abbr": [], "cite": [],
  	"b": [], "i": [], "small": [],
  	# Quotes and Edits
  	"blockquote": ["cite"],
  	"q": ["cite"],
  	"ins": ["cite", "datetime"],
  	"del": ["cite", "datetime"],
  	# Links and Media
  	"a": ["href", "rel", "target", "type", "name", "hreflang"],
  	"img": ["src", "alt", "width", "height", "longdesc"],
  	# Ruby Annotations
  	"ruby": [], "rt": [], "rp": []
  	}
  	},

  for the current subset.