search

ArchivesPortalEuropeFoundation / EAG2012

Maintenance of EAG2012, the Encoded Archival Guide for describing institutions with archival holdings
5 stars 1 forks source link

[Major revision] Adapt approach to referencing sources, editors, and rules involved in the creation and update of the EAG file #148

Open kerstarno opened 1 year ago

kerstarno commented 1 year ago

Provide a general summary of the issue in the Title above. Delete the part of the issue template that does not apply depending on whether you describe a change to an existing element / attribute or the addition of a new one.

Creator of issue

State your name, organisation and ways to reach you. Name: Kerstin Arnold Organisation: Archives Portal Europe Foundation, Working Group on Standards Email: standards@archivesportaleurope.net GitHub username (if applicable): @kerstarno

Changes to existing element / attribute

Give the current name of the element / attribute. Include the tag name and the full name. Name: @source

Change in name

Indicate any changes in name. New name: @sourceReference

Change in context

List all parent elements to which the element / attribute should be added. Furthermore, list all parent elements from which the element / attribute should be removed.

Change in data type (attributes)

Indicate any changes in an attribute's data type including the mention of specific default values (if applicable). New data type (with default values): While @source was of data type anyURI, @sourceReference is of data type IDREFS

New element / attribute

Give the name of the new element / attribute. Include the tag name and the full name. Name: @conventionDeclarationReference, @maintenanceEventReference

Context and availability

List all parent elements to which the element / attribute should be added. For elements, give an indication of their availability within each parent element ("1..1" for required but not repeatable, "1 (or another number)..n" for required and repeatable, "0..1" for optional but not repeatable", "0..n" for optional and repeatable). For attributes, indicate their availability with "1" for required or "0" for optional within each parent element. Parent element(s): Both of these attributes will be optionally available alongside @sourceReference, i.e. in all sub-elements of <repository> (as well as <repository> itself), with the exception of <repositoryType> (which uses predefined content) and <objectXMLWrap> (which is taken from another namespace).

Data type (attributes)

Indicate the new attribute's data type including the mention of specific default values (if applicable). New data type (with default values): IDREFS

Example of XML code

Provide a sample encoding in XML of the new / changed element (with potential attributes). Write your text after the "Example:" below. Example:

Here is how the encoding would look like when "Someone" made an update to a <nameEntry> based on a "Source" and following a new convention or "Rule".

<control>
  [...]
  <maintenanceHistory>
    <maintenanceEvent id="mainEv1" maintenanceEventType="udpated">
      <agent agentType="human">Someone</agent>
      <eventDateTime standardDateTime="2023-01-26">26 January 2023</eventDateTime>
      <eventDescription>Update the name entry for the institution following a new agreement of its stakeholders 
      </eventDescription>
    </maintenanceEvent>
  </maintenanceHistory>
  <sources>
    <source id="source1">
      <reference>Minutes of the Stakeholder Meeting on 25 January 2023</reference>
    </source>
  </sources>
  <conventionDeclaration id="conDec1">
    <reference>Vocabulary of "Entity Names for Organisations"</reference>
  </conventionDeclaration>
</control>
<repository>
  <identity>
    <nameEntry sourceReference="#source1" conventionDeclarationReference="#conDec1" maintenanceEventReference="#mainEv1">
      <part>Organisation, Ltd. (ORG)</part>
    </nameEntry>
    [...]
  </identity>
  [...]
</repository>
kerstarno commented 1 year ago

For conversion, the @source attribute gets removed from any element that uses it in EAG 2012. Instead, the value of the attribute is included in a <source><reference> element within <control><sources>. This <source> element then gets a concurrent @id assigned (like @id="source1", @id="source2", @id="source3", etc.), which is referenced from a new @sourceReference attribute that is added to the descriptive element that initially had the @source attribute.

In the case of <recordId>, <otherRecordId>, <eventDateTime>, <agent>, <shortCode>, <agencyCode>, <agencyName>, and <otherAgencyCode>, a new @target attribute would be used for the same purpose.

E.g. the current encoding:

<control>
  <recordId source="[source of recordId]">recordId</recordId>
  [...]
</control>
[...]
  <desc>
    [...]
    <holdings source="[source of holdings]">
      [...]
    </holdings>
  </desc>

becomes

<control>
  <recordId target="#source1">recordId</recordId>
  [...]
  <sources>
    <source id="source1">
      <reference>source of recordId</reference>
    </source>
    <source id="source2">
      <reference>source of holdings</reference>
    </source>
  </sources>
</control>
[...]
  <description>
    [...]
    <holdings sourceReference="#source2">
      [...]
    </holdings>
  </description>

As the same source can be referenced from different elements, it would be good to have a (spell)check built into the conversion that would create one source that is used in various places throughout the EAG 2012 document only once within <control>. I.e. the current encoding:

<control>
  <recordId source="[source of recordId and holdings]">recordId</recordId>
  [...]
</control>
[...]
  <desc>
    [...]
    <holdings source="[source of recordId and holdings]">
      [...]
    </holdings>
  </desc>

becomes

<control>
  <recordId target="#source1">recordId</recordId>
  [...]
  <sources>
    <source id="source1">
      <reference>source of recordId and holdings</reference>
    </source>
  </sources>
</control>
[...]
  <description>
    [...]
    <holdings sourceReference="#source1">
      [...]
    </holdings>
  </description>