<source>

[SJagodzinski]

Source

• remove child element <sourceEntry> and add optional child element <reference>

• add new optional child element <citedRange>

• add attributes:
  @audience
@scriptOfElement
@valueURI
@vocabularySource
@vocabularySourceURI

• keep name and scope

Creator of issue

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

Related issues / documents

EAD3 Reconciliation

Additional EAD 3 attributes
@altrender - Optional
@audience - Optional (values limited to: external, internal)
@encodinganalog - Optional
@lang - Optional
@localtype - Optional
@script - Optional

Additional child elements in EAC-CPF
<objectBinWrap>

Context

A source used for the establishement of the description of the CPF entity in the EAC-CPF instance.

May contain: <descriptiveNote> , <objectBinWrap> , <objectXMLWrap> , <sourceEntry>
May occur within: <sources>
Attributes: @lastDateTimeVerified, @xlink:actuate, @xlink:arcrole, @xlink:href, @xlink:role, @xlink:show, @xlink:title, @xml:id - all optional
@xlink:type - Required (if any XLINK attributes used)
Availability: Mandatory, Repeatable

Solution documentation

Rephrasing Summary, Description and Usage and Attribute usage needed?

May contain: <citedRange> (0..n), <descriptiveNote> (0..1), <objectXMLWrap> (0..1), <reference> (1..n)
May occur within: <sources>
Attributes:
@audience - optional (values limited to: external, internal)
@id - optional
@href - optional
@languageOfElement - optional
@lastDateTimeVerified - optional
@linkRole - optional
@linkTitle - optional
@scriptOfElement - optional
@valueURI - optional
@vocabularySource - optional
@vocabularySourceURI - optional
Availability: Required, repeatable

• New or other example needed
• Topic for Best Practise Guide

Encoding example

<control>
 <recordId>records identifier</recordId>
 <maintenanceAgency> [...] </maintenanceAgency>
  <maintenanceHistory> [...] </maintenanceHistory>
 <sources>
  <source audience="external" id="source1" href="link to source" languageOfElement="eng" lastDateTimeVerified="2020" linkRole="linkrole" linkTitle="linktext" scriptOfElement="lat" valueURI="sourceURI" vocabularySource="vocabularyName" vocabularySourceURI="vocabularyNameURI">
  <reference>internal or external reference to a source</reference>
  <citedRange>p. 1</citedRange>
  <objectXMLWrap> 
   <anyelementofanynamespace/>
  </objectXMLWrap>
  <descriptiveNote>
   <p>descriptive note for a source</p>
  </descriptiveNote>
  </source>
 </sources>
</control>

[ailie-s]

Tag Library Text:

Summary: A required child element of <sources> used to identify a particular source of evidence used for the establishment of the description of the CPF entity in the EAC-CPF instance.
May contain: citedRange (0..n), descriptiveNote (0..1), objectXMLWrap (0..1), reference (1..n)
May occur within: sources
Attributes:
@audience - optional (values limited to: external, internal)
@id - optional
@href - optional
@languageOfElement - optional
@lastDateTimeVerified - optional
@linkRole - optional
@linkTitle - optional
@scriptOfElement - optional
@valueURI - optional
@vocabularySource - optional
@vocabularySourceURI - optional
Description and Usage:
Use <source> to cite a published resource used in describing the CPF entity. Though not required, a reference for the source should be included as a textual description in the child <reference>.
Use the optional <descriptiveNote> for any additional notes about the source. Use the optional <objectXMLWrap> to embed XML documenting the source from any namespace other than EAC-CPF.
Availability: Required, repeatable

[kerstarno]

Schema test feedback, tested for both XSD and RNG, variation with <sourceEntry>:

• <source> is required and can be repeated
• <source> requires the sub-element <sourceEntry> (which cannot be repeated)
• <source> allows for the optional attributes @audience, @id, @languageOfElement, @scriptOfElement, @href, @linkRole, @linkTitle, @lastDateTimeVerified as well as for the inclusion of several attributes from another namespace (tried with "show" and "actuate" from XLink)
• <source> does NOT allow for the optional attributes @valueURI, @vocabularySource, and @vocabularySourceURI
  • Updated the control.rng for the "development" branch to allow for these attributes with <source>
  • Retested with the updated schemas (both XSD and RNG): <source> does now also allow for the optional attributes @valueURI, @vocabularySource, and @vocabularySourceURI
• <source> allows for the optional sub-elements <citedRange>, <objectXMLWrap> and <descriptiveNote>, the first of which is repeatable, while the last two are not repeatable

Schema test feedback, tested for both XDS and RNG, variation with <reference> (https://github.com/SAA-SDT/eac-cpf-schema/tree/issue/107/xml-schemas/eac-cpf):

• <source> is required and can be repeated
• <source> does NOT require any sub-elements, i.e. can be left empty and would still validate
  • Updated the control.rng for the "issue 107" branch to require <reference> and to make it not repeatable
  • Retested with the updated schemas (both XSD and RNG): <source> does now require <reference> (which cannot be repeated)
• <source> allows for the optional attributes @audience, @id, @languageOfElement, @scriptOfElement, @href, @linkRole, @linkTitle, @lastDateTimeVerified as well as for the inclusion of several attributes from another namespace (tried with "show" and "actuate" from XLink)
• <source> does NOT allow for the optional attributes @valueURI, @vocabularySource, and @vocabularySourceURI
  • Updated the control.rng for the "issue 107" branch to allow for these attributes with <source>
  • Retested with the updated schemas (both XSD and RNG): <source> does now also allow for the optional attributes @valueURI, @vocabularySource, and @vocabularySourceURI
• <source> allows for the optional sub-elements <citedRange>, <objectXMLWrap> and <descriptiveNote>, the first of which is repeatable, while the last two are not repeatable

Test successful after the corrections in the schemas as described.

[fordmadox]

@kerstarno Just an FYI that I just updated the development branch to switch out sourceEntry with reference. Can you test this one again and make sure that I've got everything still right?

[kerstarno]

Retested with both, RNG and XSD, in the development branch, which is now including <reference> instead of <sourceEntry>:

• <source> is required and can be repeated
• <source> requires the sub-element <reference> (which cannot be repeated)
• <source> allows for the optional attributes @audience, @id, @languageOfElement, @scriptOfElement, @href, @linkRole, @linkTitle, @lastDateTimeVerified, @valueURI, @vocabularySource, and @vocabularySourceURI as well as for the inclusion of several attributes from another namespace (tried with "show" and "actuate" from XLink)
• <source> allows for the optional sub-elements <citedRange>, <objectXMLWrap> and <descriptiveNote>, the first of which is repeatable, while the last two are not repeatable

Test successful.

Note 1: With <reference> in this context, but also in others the attributes @conventionDeclarationReference, @maintenanceEventReference, and @sourceReference will also be available in the <control> section.

Note 2: Both, RNG and XSD, currently prescribe the sequence of <citedRange>, <objectXMLWrap>, <descriptiveNote> with regard to the optional sub-elements of <source>. Given the scope and purpose of these elements, I'd say this is ok, so mainly noting for documentation.

[fordmadox]

Thanks, @kerstarno !

Regarding note 1, this is also true for span now in the control section. We could have different models for those same elements when used in control, or we could make sure that they cannot be used in control at all, etc. Not sure what would be best.

Regarding note 2, I've kept the prescribed order mostly the same from what we have now in EAC, but I would still prefer the option of not enforcing order. I'd definitely want more community feedback about that, though, since some folks might really like that, say, descriptiveNote is always forced to be the last element in a group when it's used.

All that said, if we are removing the option of biogHist/reference, and if reference will only be available (I think) in paragraph elements elsewhere, I'd be in favor of going back to source/sourceEntry rather than source/reference 😃

[kerstarno]

@fordmadox - I think, we should actually be fine with having the @...Reference attributes in some <control> elements, as long as these are elements that are available not only in <control>. I mean, this could be our line of explanation. Mainly wanted to flag it; didn't mean to say that it should be removed or changed.

As for <reference> - even if we removed it as direct sub-element of <biogHist>, there's still the point of <reference@target>, which will make it available in quite a few places. So, I'd stick with the decision to get rid of <sourceEntry>.

[fordmadox]

@SJagodzinski : I haven't followed the modeling too closely around "reference", but just a note that we are reversing the decision from EAC 1.1 where sourceEntry was made repeatable (see #13). Is that right? Just wanted to be clear. If so, what is your preference for the EAC 1.1 to 2.0 migration? Should that process:

• Create one source element for every sourceEntry element (which will have a little data loss, at least in the case if both sourceEntry / source elements had xml:id attributes, etc.);
• Turn any sourceEntry elements with a position greater than 1 into a comment (or something else);
• Something else?

[SJagodzinski]

* Create one source element for every sourceEntry element (which will have a little data loss, at least in the case if both sourceEntry / source elements had xml:id attributes, etc.);

Create one <source> element for every <source> element. Move each <sourceEntry> data to <reference> .

@fordmadox , @ailie-s : We need to make <reference> repeatable in <source>.

<sourceEntry> was optional, but <reference> is mandatory now. So if there is a <source> without <sourceEntry> we need a text or content for <reference>.

Turn <objectBinWrap> in a comment.

Everything else should work.

[fordmadox]

Got it, I think. @SJagodzinski and @kerstarno: I just updated the development branch to allow reference to repeat in source. And, based on our new ordering rule, everything still stays in the same order (1..n reference comes before 0..n citedRange, that is). See c7b2f6f

[fordmadox]

And this makes the transformation process from EAC 1.1 to 2.0 much easier 😄

[kerstarno]

Re-tested and can confirm, that <reference> is now required and repeatable within <source>. This applies to both schemas, RNG and XSD.