<citation>

[SJagodzinski]

Citation

• rename to <reference>
• use <reference> external linking only; internal linking will be done via the attribute @target which will be made available for all elements with the exception of <eac>
• add attributes
  @audience
@conventationDeclarationReference
@id
@languageOfElement
@maintenanceEventReference
@scriptofElement
@sourceReference
@target
• change availability from optional, not repeatable to optional, repeatable
• add <reference> to elements with descriptive content and to elements containing the former element <citation> (see solution documentation below for detailed list)
• remove attribute @lastDateTimeVerified
• remove xlink namespace

Creator of issue

1. Silke Jagodzinski
2. TS-EAS: EAC-CPF subgroup
3. [email protected]

Related issues / documents

Suggestion to add <title> to EAC-CPF #60

EAD3 Reconciliation

A required child element of <conventiondeclaration>, <localtypedeclaration>, and <rightsdeclaration> for identifying any rules and conventions applied in the compilation of the description.

Additional EAD 3 attributes
@actuate - Optional (values limited to: none, onload, onrequest, other)
@altrender - Optional
@arcrole - Optional
@entityref - Optional
@show - Optional (values limited to: embed, new, none, other, replace)
@xpointer - Optional

May contain: [text], <abbr>, <emph>, <expan>, <foreign>, <lb>, <ptr>, <ref>
Availability: Required, not repeatable

Additional partent elements in EAC-CPF
<biogHist> , <function> , <functions> , <legalStatus> , <legalStatuses> , <localDescription> , <localDescriptions> , <mandate> , <mandates> , <occupation> , <occupations> , <place> , <places>

Context

An element that cites an external resource.

May contain: [text], <span>

May occur within: <biogHist> , <conventionDeclaration> , <function> , <functions> , <legalStatus> , <legalStatuses> , <localDescription> , <localDescriptions> , <localTypeDeclaration> , <mandate> , <mandates> , <occupation> , <occupations> , <place> , <places> , <rightsDeclaration>

Attributes:
@lastDateTimeVerified, @xlink:actuate, @xlink:arcrole, @xlink:href, @xlink:role, @xlink:show, @xlink:title, @xml:id, @xml:lang - all optional
@xlink:type - Required (if any XLINK attributes used)

Availability:
Within <conventionDeclaration> , <localTypeDeclaration> and <rightsDeclaration> : Mandatory, Non-repeatable
Within <function> , <legalStatus> , <localDescription> , <mandate> , <occupation> , <place> : Optional, Non-repeatable
Within <functions> , <legalStatuses> , <localDescriptions> , <mandates> , <occupations> , <places> : Optional, Repeatable

Solution documentation:

May contain: [text], <span>
May occur within: <abstract>, <chronItem>, <chronItemSet>, <conventionDeclaration>, <event>, <eventDescription>, <item>, <localTypeDeclaration>, <p>, <rightsDeclaration>, <source>

Attributes:
@audience - optional (values limited to: external, internal)
@conventationDeclarationReference - optional
@href - optional
@id - optional
@languageOfElement - optional
@linktitle - optional
@linkrole - optional
@maintenanceEventReference - optional
@scriptofElement - optional
@sourceReference - optional
@target - optional

Availability: optional, repeatable

Example encoding

<conventionDeclaration>
 <shortCode>acronym, abbreviation or short code of the convention</shortCode>
 <reference audience="external" conventionDeclarationReference="conventiondeclaration1" href="externallink" id="reference1" languageOfElement="en" linkTitle="linktext" linkRole="application/pdf" maintenanceEventReference="maintenancevent1" scriptOfElement="lat" sourceReference="source1" target="address1">external reference to the convention</reference>
 <descriptiveNote>
  <p>descriptive note for convention declaration</p>
 </descriptiveNote>
</conventionDeclaration>

[SJagodzinski]

TS EAS meeting 6 August 2020:

The element <reference> is placed in <p> elements in all places.

[kerstarno]

Tested as part of Schema Team's schema testing:

• <citation> is not available anymore in the draft RNG and XSD schemas
• <reference> is a required sub-element of <conventionDeclaration>, <localTypeDeclaration>, <rightsDeclaration>, and <source>; in these contexts, <reference> cannot be repeated
• <reference> is an optional sub-element of <abstract>, <event>, <eventDescription>, <item>, <p>; in these contexts, <reference> can be repeated
• <reference> is currently missing as optional sub-element of <chronItem> and <chronItemSet>
  • I've updated models-and-shared-elements.rng to include <reference>as optional and repeatable sub-element of <chronItem> and <chronItemSet>
  • I've retested and can now confirm that <reference> is available for <chronItem> and <chronItemSet> and can be repeated in these contexts
    • @SJagodzinski - I've used the "optional, repeatable" approach here as generally laid out for <reference>; in case, <reference> should not be repeatable with <chronItem> and <chronItemSet>, please let the Schema Team know
• <reference> itself can have text
• <reference> allows for <span> as an optional and repeatable sub-element
• <reference> allows for the optional attributes @audience, @id, @target, @languageOfElement, @scriptOfElement, @conventionDeclarationReference, @maintenanceEventReference, @sourceReference, @href, @linkTitle, @linkRole, and @lastDateTimeVerified
• <reference> also allows for optional attributes from other namespaces (tested with XLink)
• apart from the elements specified above, <reference> is currently still available as optional sub-element of <place>
  • I've updated models-and-shared-elements.rng to remove <reference> from <place>
  • I've retested and can now confirm that <reference> is only available in the elements specified above

The above applies for RNG and XSD schemas.

The element is ready.

[fordmadox]

And whatever is decided, if reference is added as a floating element to chronItem / chronItemSet, then there should be something in the Best Practices to distinguish how that is used versus @sourceReference + source.

[kerstarno]

Setting this back to "in progress" following the change in cardinality of <reference> in the context of <source> (see #107). Will re-test once this change is in the development schema.

[kerstarno]

And whatever is decided, if reference is added as a floating element to chronItem / chronItemSet, then there should be something in the Best Practices to distinguish how that is used versus @sourceReference + source.

I'd think, this is one of the general questions referring to all options of linking to some other resource outside of the EAS instance, not necessarily bound to the specific use cases of <chronItem> and <chronItemSet>:

• @sourceReference with <source> for a resource that has been used specifically to create the content of the EAS instance, i.e. information used within the EAS instance is either literally or generally cited from that source
• <reference@href> respectively just <reference> (in other contexts than <source>) for a resource that provides additionally useful, contextual information, e.g. a chronicle of a certain period in time when the entity described was influential for this era
• <relation><targetEntity targetType="resource"> or <relation><targetEntity targetType="resource" valueURI="[...]"> for a resource that either has been created, used, or maintained by the entity described or is about the entity described; note: it might be the case that a resource about an entity (or maybe even one that was created, used, or maintained by the entity) was also used as a source to create the EAS instance about that entity; such resource then could be mentioned in both contexts; maybe we could recommend putting it in the context that's most pertinent?
• slightly different from the above cases, but still a link to some resource outside of the EAS instance - @valueURI in combination with @vocabularySource and/or @vocabularySourceURI for a resource that is part of a vocabulary, ontology, thesaurus, etc. defining terms and other pieces of information used within the EAS instance

[kerstarno]

Re-tested for cardinality in the contexts of <source> along with <conventionDeclaration>, <localTypeDeclaration>, and <rightsDeclaration>. Can confirm that

• <reference> is a required sub-element of <source>, in which context it can be repeated now
• <reference> is a required sub-element of <conventionDeclaration>, <localTypeDeclaration>, and <rightsDeclaration>, in which contexts it remains non-repeatable

This applies to both schemas, RNG and XSD.

[ailie-s]

Tag Library Text

<reference> Reference
Summary: An element that cites an external resource.
May contain: [text], span (0..n)
May occur within: abstract, chronItem, chronItemSet, conventionDeclaration, event, eventDescription, item, localTypeDeclaration, p, rightsDeclaration, source
Attributes:
@audience - optional (values limited to: external, internal)
@conventationDeclarationReference - optional
@href - optional
@id - optional
@languageOfElement - optional
@lastDateTimeVerified - optional
@linkRole - optional
@linkTitle - optional
@maintenanceEventReference - optional
@scriptOfElement - optional
@sourceReference - optional
@target - optional
Description and Usage:
An element used for referencing external resources that have been used to compile the EAC-CPF instance, or that identify rules or conventions that have been applied.
<reference> is a required child element of <conventionDeclaration>, <localTypeDeclaration>, and <rightsDeclaration> for identifying any rules and conventions applied in the compilation of the description. It is also a required child element of <source>, used to identify any sources used in compiling the description. <source> may include multiple child <reference> elements.
<reference> is an optional child element of <abstract>, <chronItem>, <chronItemSet>, <event>, <eventDescription>, <item>, and <p> where it is used to reference any external resources that have been used in compiling the content of that element.
Attribute Usage: Use @href to link to the cited resource.
See also: <reference> is used for external linking only. If any internal linking is required within the EAC-CPF instance, use the @target attribute.
Availability:
Within <conventionDeclaration>, <localTypeDeclaration>, <rightsDeclaration>: required, not repeatable
Within <source>: required, repeatable
Within <abstract>, <chronItem>, <chronItemSet>, <event>, <eventDescription>, <item>, <p>: optional, repeatable