Additional Documentation ★★★

A cited resource may have any number of related documents such as articles, publications, user guides, data dictionaries that are useful in applying the resource to desired purposes. Often these are difficult to discover and manage. Capturing these in the metadata is recommended.


Element Name	additionalDocumentation
Parent	MD_Metadata.identificationInfo>MD_Identification
Class/Type	CI_Citation
Governance	Domain, Agency
Purpose	Data Management, Resource Use
Audience	machine resource - ⭑
	general - ⭑ ⭑ ⭑
	resource manager - ⭑ ⭑ ⭑ ⭑ ⭑
	specialist - ⭑ ⭑ ⭑ ⭑ ⭑
Metadata type	descriptive
ICSM Level of Agreement	⭑ ⭑ ⭑

Definition

Citation of other documentation associated with the resource, e.g. related articles, publications, user guides, data dictionaries

ISO Obligation

There may be zero to many [0..*] additionalDocumentation packages for the cited resource in the MD_DataIdentification package of class CI_Citation in the metadata record.

Discussion

To make the best use of a given resource, additional documentation may be useful or required. Providing instructions for accessing these documents can greatly enhance the value of a resource to its users and providers. Capturing these additional documents in the metadata is also helpful to resource managers who need to properly track the linkages between a resource and its documentation. The resource may be data or service, MD_DataIdentification* or *SV_ServiceIdentification

ICSM Best Practice Recommendations

Therefore - to make the best use of a given resource capturing the links to additional documentation related to this resource is highly recommended. Capture those documents of the highest value to your most likely community of users. If possible, include some reference to documentation or its metadata that can be easily understood by laypeople and label this accordingly.

This element should be populated in all metadata records with a minimum of title, identifier, date and citedResponsibleParty. If possible, use the link to the metadata for the cited additional documentation as the resource landing page.

Recommended Sub-Elements

title - (type - charStr) [1..1] mandatory for citations, the name by which the cited resource is known
date - (class - CI_Date) recommended, the reference date for the cited resource In addition, some direction should be given about how to access the cited additional resource
onlineResource - (class CI_OnlineResource) [0..*] a description of how to access the cited additional resource online
citedResponsibleParty - (class CI_Responsibility) [0..*] contact information for someone who can give guidance about accessing the cited additional resource

Also Consider

MD_DataIdentification.supplementalInformation - is defined as “any other descriptive information about the resource”
MD_AssociatedResource - contains information about resources of which this resource is a piece. Association types are taken from the DS_AssociationTypeCode

Outstanding Issues

DCAT Previously captured DCAT related documentation on these elements calls what is considered the equivalent “A free-text account of the catalog.” Mapping seems incorrect.

Crosswalk considerations

DCAT

Maps to dct.description free-text

RIF-CS

Maps to Description 'notes'

Examples

XML

<mdb:MD_Metadata>
....
  <mdb:identificationInfo>
   <mri:MD_DataIdentification>
   ....
     <mri:additionalDocumentation>
      <cit:CI_Citation>
        <cit:title>
         <gco:CharacterString>Usage guide</gco:CharacterString>
        </cit:title>
        <cit:date>
         <cit:CI_Date>
           <cit:date>
            <gco:Date>2019-07-01</gco:Date>
           </cit:date>
           <cit:dateType>
            <cit:CI_DateTypeCode 
            codeList="https://schemas.isotc211.org/19115/resources/Codelist/
            cat/codelists.xml#CI_DateTypeCode"
                       codeListValue="creation"/>
           </cit:dateType>
         </cit:CI_Date>
        </cit:date>
        <cit:citedResponsibleParty>
         <cit:CI_Responsibility>
           <cit:role>
            <cit:CI_RoleCode 
            codeList="https://schemas.isotc211.org/19115/resources
            /Codelist/cat/codelists.xml#CI_RoleCode"
            codeListValue="custodian"/>
           </cit:role>
           <cit:party>
            <cit:CI_Organisation>
              <cit:name>
               <gco:CharacterString>OpenWork Ltd</gco:CharacterString>
              </cit:name>
              <cit:contactInfo>
               <cit:CI_Contact>
                 <cit:address>
                  <cit:CI_Address>
                    <cit:electronicMailAddress>
                    <gco:CharacterString>info@openwork.nz
                    </gco:CharacterString>
                    </cit:electronicMailAddress>
                  </cit:CI_Address>
                 </cit:address>
               </cit:CI_Contact>
              </cit:contactInfo>
              <cit:individual>
               <cit:CI_Individual>
                 <cit:name>
                  <gco:CharacterString>Byron Cochrane
                  </gco:CharacterString>
                 </cit:name>
               </cit:CI_Individual>
              </cit:individual>
            </cit:CI_Organisation>
           </cit:party>
         </cit:CI_Responsibility>
        </cit:citedResponsibleParty>
        <cit:onlineResource>
         <cit:CI_OnlineResource>
           <cit:linkage>
            <gco:CharacterString>https://openwork-nz.github.io
            /Resources/2019/04/25/gn-plugins.html
            </gco:CharacterString>
           </cit:linkage>
           <cit:protocol gco:nilReason="missing">
            <gco:CharacterString/>
           </cit:protocol>
           <cit:name gco:nilReason="missing">
            <gco:CharacterString/>
           </cit:name>
           <cit:description gco:nilReason="missing">
            <gco:CharacterString/>
           </cit:description>
           <cit:function>
            <cit:CI_OnLineFunctionCode codeList=
            "https://schemas.isotc211.org/19115/resources/Codelist
            /cat/codelists.xml#CI_OnLineFunctionCode"
            codeListValue=""/>
           </cit:function>
         </cit:CI_OnlineResource>
        </cit:onlineResource>
      </cit:CI_Citation>
     </mri:additionalDocumentation>
   ....
   </mri:MD_DataIdentification>
  </mdb:identificationInfo>
....
</mdb:MD_Metadata>

\pagebreak

UML diagrams

Recommended elements highlighted in yellow

additionalDoc

\pagebreak