glam/schemas/20251121/linkml/modules/classes/EADDownload.yaml

id: https://nde.nl/ontology/hc/class/EADDownload
name: ead_download
title: EADDownload Class
prefixes:
  linkml: https://w3id.org/linkml/
  hc: https://nde.nl/ontology/hc/
  dcat: http://www.w3.org/ns/dcat#
  dcterms: http://purl.org/dc/terms/
  schema: http://schema.org/
  xsd: http://www.w3.org/2001/XMLSchema#
imports:
- linkml:types
- ../metadata
- ./DataServiceEndpoint
- ../slots/protocol
- ../slots/response_format
- ../slots/specificity_annotation
- ../slots/template_specificity
- ./SpecificityAnnotation
- ./TemplateSpecificityScores
classes:
  EADDownload:
    is_a: DataServiceEndpoint
    class_uri: hc:EADDownload
    description: |
      EAD (Encoded Archival Description) finding aid download endpoint.

      **Purpose:**

      Models endpoints that provide EAD XML downloads for archival finding aids.
      EAD is the international standard for encoding archival descriptive information.

      **EAD Versions:**

      - **EAD3** (2015): Current standard, aligned with ISAD(G), RiC-CM
      - **EAD 2002**: Previous version, still widely used
      - **EAD 1.0** (1998): Original version, legacy

      **EAD Structure:**

      An EAD document contains:
      - **<eadheader>** / **<control>**: Finding aid metadata
      - **<archdesc>**: Archival description
        - **<did>**: Descriptive identification (title, dates, extent)
        - **<bioghist>**: Biographical/historical note
        - **<scopecontent>**: Scope and content
        - **<arrangement>**: Arrangement
        - **<accessrestrict>**: Access restrictions
        - **<userestrict>**: Use restrictions
        - **<dsc>**: Description of subordinate components (hierarchy)

      **Example - Nationaal Archief EAD Download:**

      ```yaml
      ead_download:
        endpoint_name: "Nationaal Archief EAD Download"
        base_url: "https://www.nationaalarchief.nl/onderzoeken/archief/"
        url_pattern: "{base_url}{archive_code}/download/ead"
        ead_version: EAD_2002
        archive_code_format: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
        includes_dao_links: true
        includes_index: true
        compression: none
        example_url: "https://www.nationaalarchief.nl/onderzoeken/archief/2.04.87/download/ead"
      ```

      **Use Cases:**

      1. **Finding aid harvesting**: Aggregate archival descriptions
      2. **Data migration**: Move descriptions between systems
      3. **Preservation**: Archive finding aids as XML
      4. **Integration**: Import into archival management systems

      **See Also:**

      - EAD3: https://www.loc.gov/ead/
      - ISAD(G): https://www.ica.org/en/isadg-general-international-standard-archival-description-second-edition      
    attributes:
      base_url:
        slot_uri: dcat:endpointURL
        description: |
          Base URL for EAD downloads.

          Individual finding aids accessed by appending archive code.

          Example: "https://www.nationaalarchief.nl/onderzoeken/archief/"          
        range: uri
        required: true
      url_pattern:
        slot_uri: hydra:template
        description: |
          URL pattern for constructing EAD download requests.

          Use {placeholders} for dynamic parts:
          - {archive_code}: Archive/fonds identifier
          - {format}: Output format (ead, xml)

          Example: "{base_url}{archive_code}/download/ead"          
        range: string
      ead_version:
        slot_uri: dcterms:conformsTo
        description: |
          EAD version used in downloaded files.

          Values:
          - EAD3: Current standard (2015)
          - EAD_2002: Previous version, widely used
          - EAD_1_0: Original version (legacy)          
        range: EADVersionEnum
        required: true
      ead_schema_url:
        slot_uri: schema:schemaVersion
        description: |
          URL to EAD schema (XSD or RNG) used for validation.

          Example: "https://www.loc.gov/ead/ead3.xsd"          
        range: uri
      archive_code_format:
        slot_uri: dcterms:identifier
        description: |
          Regex pattern for archive/fonds codes used in URLs.

          Dutch Nationaal Archief uses: "^[0-9]+\\.[0-9]+\\.[0-9]+$" (e.g., 2.04.87)

          Example: "^[0-9]+\\.[0-9]+\\.[0-9]+$"          
        range: string
      archive_code_examples:
        slot_uri: schema:workExample
        description: |
          Example archive codes for reference.

          Example: ["2.04.87", "2.21.281.02", "4.MST"]          
        range: string
        multivalued: true
      isad_g_compliant:
        slot_uri: dcterms:conformsTo
        description: |
          Whether EAD output follows ISAD(G) description standard.

          ISAD(G) = General International Standard Archival Description          
        range: boolean
      includes_dao_links:
        slot_uri: schema:associatedMedia
        description: |
          Whether EAD includes <dao> (digital archival object) links.

          <dao> elements link to digitized content (images, documents).
          Essential for integration with digital content delivery.          
        range: boolean
      includes_index:
        slot_uri: schema:hasPart
        description: |
          Whether EAD includes <index> elements.

          Index provides structured access points (names, subjects, places).          
        range: boolean
      includes_controlaccess:
        slot_uri: schema:hasPart
        description: |
          Whether EAD includes <controlaccess> elements.

          Controlled access terms (subjects, names, genres, functions).          
        range: boolean
      multilevel_description:
        slot_uri: schema:hasPart
        description: |
          Whether EAD supports multi-level hierarchical description.

          Uses <dsc> (description of subordinate components) with nested
          <c> (component) elements for series, files, items.          
        range: boolean
      max_hierarchy_depth:
        slot_uri: schema:maxValue
        description: |
          Maximum depth of component hierarchy in downloaded EADs.

          Some systems limit depth for performance.

          Example: 12          
        range: integer
      encoding:
        slot_uri: schema:encodingType
        description: |
          Character encoding of EAD output.

          Should be UTF-8 for modern systems.

          Example: "UTF-8"          
        range: string
      compression:
        slot_uri: schema:encodingFormat
        description: |
          Compression applied to downloads.

          Values:
          - NONE: Plain XML
          - GZIP: Gzip compressed
          - ZIP: ZIP archive          
        range: CompressionTypeEnum
      includes_dtd_declaration:
        slot_uri: schema:additionalProperty
        description: |
          Whether XML includes DOCTYPE declaration referencing DTD.

          Legacy EAD often includes DTD reference.
          Modern practice uses XSD validation.          
        range: boolean
      namespace_aware:
        slot_uri: schema:additionalProperty
        description: |
          Whether EAD uses XML namespaces.

          EAD3 uses namespace: urn:isbn:1-931666-22-9 (changed to LOC namespace)
          EAD 2002 may be namespace-aware or not.          
        range: boolean
      default_namespace:
        slot_uri: schema:additionalProperty
        description: |
          Default XML namespace for EAD elements.

          EAD3: "http://ead3.archivists.org/schema/"
          EAD 2002: "urn:isbn:1-931666-22-9"          
        range: uri
      language_of_description:
        slot_uri: dcterms:language
        description: |
          Primary language of finding aid descriptions.

          ISO 639-1 code.

          Example: "nl" (Dutch)          
        range: string
      supports_partial_download:
        slot_uri: schema:additionalProperty
        description: |
          Whether partial EAD download is supported.

          Some systems allow downloading specific components rather
          than entire finding aid.          
        range: boolean
      batch_download_available:
        slot_uri: schema:additionalProperty
        description: |
          Whether batch download of multiple finding aids is available.

          May provide ZIP archive or OAI-PMH harvesting.          
        range: boolean
      transform_options:
        slot_uri: schema:additionalProperty
        description: |
          Output transformation options available.

          Some systems offer XSLT-transformed output (HTML, PDF).

          Example: ["EAD", "HTML", "PDF"]          
        range: string
        multivalued: true
      example_url:
        slot_uri: schema:workExample
        description: |
          Example URL for EAD download.

          Example: "https://www.nationaalarchief.nl/onderzoeken/archief/2.04.87/download/ead"          
        range: uri
    slot_usage:
      protocol:
        description: EAD downloads use HTTP GET (REST-like). Uses DataServiceProtocolEnum.REST.
      response_format:
        description: |
          EAD is always XML.          
        ifabsent: string(application/xml)
      specificity_annotation:
        range: SpecificityAnnotation
        inlined: true
      template_specificity:
        range: TemplateSpecificityScores
        inlined: true
    comments:
    - EAD is the standard for archival finding aids
    - Check for <dao> links to connect descriptions with digitized content
    - EAD3 is current standard but EAD 2002 still widely used
    see_also:
    - https://www.loc.gov/ead/
    - https://eadiva.com/
    - https://www.ica.org/en/isadg-general-international-standard-archival-description-second-edition
    slots:
    - specificity_annotation
    - template_specificity
enums:
  EADVersionEnum:
    description: |
      Versions of the EAD (Encoded Archival Description) standard.      
    permissible_values:
      EAD3:
        description: |
          EAD3 (2015) - Current standard.

          Major revision aligned with:
          - ISAD(G) and ISAAR(CPF)
          - RiC-CM (Records in Contexts)
          - Schema-first design (XSD, RNG)

          Namespace: http://ead3.archivists.org/schema/          
      EAD_2002:
        description: |
          EAD 2002 - Previous version.

          Most widely deployed version.
          DTD and XSD schemas available.

          Namespace: urn:isbn:1-931666-22-9          
      EAD_1_0:
        description: |
          EAD 1.0 (1998) - Original version.

          Legacy, rarely used for new content.
          DTD-based validation.          
      UNKNOWN:
        description: |
          EAD version not specified or unknown.

          May require inspection of downloaded file.          
  CompressionTypeEnum:
    description: |
      Compression types for file downloads.      
    permissible_values:
      NONE:
        description: |
          No compression - plain file.

          MIME type unchanged from content type.          
      GZIP:
        description: |
          Gzip compression.

          Single compressed file.
          Content-Encoding: gzip          
      ZIP:
        description: |
          ZIP archive.

          May contain multiple files.
          application/zip          
      BZIP2:
        description: |
          Bzip2 compression.

          Higher compression ratio than gzip.          
      XZ:
        description: |
          XZ/LZMA compression.

          Very high compression ratio.