Technical Information

LinkOut DTD

The LinkOut Document Type Definition (DTD) specifies the XML elements used in LinkOut files. The LinkOut DTD is available at LinkOut.DTD.

The URL for the DTD must be included in the prolog of a LinkOut file.

In the identity file, use:

<!DOCTYPE Provider "-//NLM//DTD LinkOut 1.0//EN" "https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">

In a resource file, use:

<!DOCTYPE LinkSet "-//NLM//DTD LinkOut 1.0//EN" "https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">

<!-- Typical usage:

        <!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut//EN" "LinkOut.dtd">
        <LinkSet>
        ...
         </LinkSet>
            
         or:

         <!DOCTYPE Provider PUBLIC "-//NLM//DTD LinkOut//EN" "LinkOut.dtd">
         <Provider>
         ...
         </Provider>
    -->
<!--

   Rule based URL generation. In general, to build the
   URL both base and rule are required, where base is the
   HTTP base address, for example:
   
   http://www.sciencemag.org/cgi/content/full/

   and rule is in the following format:
&lo.vol;/&lo.iss;/&lo.page;

   LinkOut will replace the keywords in rule with the actual 
   value for a retrieved citation. Therefore, rule will be 
   translated into: 281/5384/1863
   
   The program will concatenate base with rule:

   http://www.sciencemag.org/cgi/content/full/281/5384/1863

The following keywords are supported for any database:

lo.id - Unique identifier (PMID, TaxID, etc.)

For PubMed only 

lo.pii   - Publisher Item Identifier.  Must be submitted by the publisher. For example, 6847, in the PubMed DTD this ID is an attribute of the ArticleId element. 
lo.doi   - Article DOI 
lo.issn  - Journal ISSN code 
lo.essn  - Journal Electronic ISSN code
lo.issnl - Journal ISSN code without the dash 
lo.jtit  - Journal title (MEDLINE abbreviation) 
lo.vol   - Volume 
lo.iss   - Issue 
lo.page  - First page 
lo.year  - Four digit year. For example, 1998 
lo.yr    - Last two digit of year. For example, 98; 00 
lo.yl    - Last digit of year. For example, for 1999 use 9; for 1990 use 0.
lo.eyear - Four digit year of electronic publication date. For example, 1998 
lo.eyr   - Last two digits of year of electronic publication date. For example, 98; 00 
lo.eyl   - Last digit of year of electronic publication date. For example, for 1999 
use 9; for 1990 use 0 
lo.month - The month. For example, September
lo.mon   - The 3 letter month abbreviation. For example, Sep 
lo.mo    - Two digit month. For example, 01; 12 
lo.emonth- The month of electronic publication date.  For example, September
lo.emon  - The 3 letter month abbreviation of electronic publication date. For 
example, Sep
lo.emo   - Two digit month of electronic publication date.
For example, 01;12 
lo.day   - Two digit day. For example, 01; 31 
lo.eday  - Two digit day of electronic publication date.  For example, 01; 31 
lo.auth  - First author 
lo.authln- Last name of the first author
lo.nlmid - NLM unique Identifier
lo.bookacc- Book accession number of a record
lo.bookname- Internal id for a book record
lo.elocationid – Electronic location Identifier of a record

For Sequence databases (Nucleotide, Protein, Structure, Genome):

lo.pacc  - Primary accession for sequences

For Taxonomy only:

lo.scientificname - Full scientific name.For example: "Homo sapiens neanderthalensis"
lo.genus – genus name
lo.species – species name
lo.subsp – subspecies name
For Gene only:

lo.genename – Gene name
lo.orgname – binomial, and strain when appropriate, from NCBI Taxonomy database
lo.taxid – unique identifier from NCBI Taxonomy database
lo.mimid – identifier(s) from Online Mendelian Inheritance in Man (OMIM)
-->
<!ENTITY lo.id                   "lo.id">
<!ENTITY lo.pii                  "lo.pii">
<!ENTITY lo.doi                  "lo.doi">
<!ENTITY lo.issn                 "lo.issn">
<!ENTITY lo.essn                 "lo.essn">
<!ENTITY lo.issnl                "lo.issnl">
<!ENTITY lo.jtit                 "lo.jtitle">
<!ENTITY lo.vol                  "lo.vol">
<!ENTITY lo.iss                  "lo.iss">
<!ENTITY lo.page                 "lo.page">
<!ENTITY lo.year                 "lo.year">
<!ENTITY lo.yr                   "lo.yr">
<!ENTITY lo.yl                   "lo.yl">
<!ENTITY lo.eyear                "lo.eyear">
<!ENTITY lo.eyr                  "lo.eyr">
<!ENTITY lo.eyl                  "lo.eyl">
<!ENTITY lo.month                "lo.month">
<!ENTITY lo.mon                  "lo.mon">
<!ENTITY lo.mo                   "lo.mo">
<!ENTITY lo.emonth               "lo.emonth">
<!ENTITY lo.emon                 "lo.emon">
<!ENTITY lo.emo                  "lo.emo">
<!ENTITY lo.day                  "lo.day">
<!ENTITY lo.eday                 "lo.eday">
<!ENTITY lo.auth                 "lo.auth">
<!ENTITY lo.authln               "lo.authln">
<!ENTITY lo.nlmid                "lo.nlmid">
<!ENTITY lo.bookacc              "lo.bookacc">
<!ENTITY lo.bookname             "lo.bookname">
<!ENTITY lo.elocationid          "lo.elocationid">
<!ENTITY lo.pacc                 "lo.pacc">
<!ENTITY lo.scientificname       "lo.scientificname">
<!ENTITY lo.genus                "lo.genus">
<!ENTITY lo.species              "lo.species">
<!ENTITY lo.subsp                "lo.subsp">
<!ENTITY lo.genename             "lo.genename">
<!ENTITY lo.orgname              "lo.orgname">
<!ENTITY lo.taxid                "lo.taxid">
<!ENTITY lo.mimid                "lo.mimid">

<!-- Entities for special characters -->

<!ENTITY reg        "&#174;" >
<!ENTITY copy       "&#169;">
<!ENTITY trade      "&#8482;">

<!-- internal DTD entities -->

<!ENTITY % url.data          "#PCDATA">
<!ENTITY % rule.data         "%url.data; | pad | apad | subs
                             | toupper | tolower | strip | normalize">
<!ENTITY % iso.lang.codes    "(DA|DE|EN|EL|ES|FR|IT|IW|JA|NL|NO|RU|SV|ZH)">
<!ELEMENT SubjectType        (#PCDATA)>

<!-- can be one of the following; see LinkOut SubjectTypes and Attributes at
https://www.ncbi.nlm.nih.gov/books/NBK3807/#files.Special_Elements_SubjectType 
for a description of these elements:

//CHEMICAL INFORMATION
        Biological Properties
        Chemical Libraries
        Imaging Agents
        Metabolism
        Molecular Interactions
        Physical Properties
        Reactions
        Theoretical Properties
        Toxicology
        Vendors

//EDUCATION
        conferences/meetings/workshops
        glossaries/dictionaries
        online tutorials/courses

//FUNDING SOURCES
        funding sources

//LITERATURE
        abstracts/indexes/summaries
        aggregators
        books
        images
        individual online article
        institutional repository
        libraries
        patent databases
        publishers/providers
        supplemental materials
        systematic reviews

//MEDICAL
        clinical trials
        consumer health
        diagnostics
        disease organizations
        medical equipment and devices
        pharmacology
        treatment guidelines

//MOLECULAR BIOLOGY DATABASES
        DNA/protein sequence
        gene/protein/disease-specific
        gene expression
        locus-specific
        mapping
        organism-specific
        population/variation
        protein interactions/pathways
        structure
        taxonomy/phylogenetic

//RESEARCH MATERIALS
        clones/clone libraries
        culture/stock collections
        laboratory equipment
        oligonucleotides
        other reagents

//RESEARCHERS
        colleges/universities
        companies/research institutes
        directories
        individuals
        societies/associations

//TOOLS
        3D structure prediction/functional modeling
        primer design
        protein identification/characterization
        restriction mapping
        sequence screening/similarity/alignment
        sequence viewer
        translation
-->

<!ELEMENT Attribute   (#PCDATA)>
<!-- can be one of the following; see LinkOut SubjectTypes and Attributes at 
https://www.ncbi.nlm.nih.gov/books/NBK3807/#files.Special_Elements_Attribute

for a description of these elements:
//BARRIERS
        registration required
        subscription/membership/fee required

//OWNERSHIP
        author of URL
        publisher of information in URL

//Resource Form
        author manuscript
        electronic full-text
        full-text online
        full-text PDF
        full-text PostScript
        order form
        print collection       

//Administrative
        preference
-->
<!-- This is the top level element for Provider -->
<!ELEMENT Provider               (ProviderId, Name, NameAbbr, SubjectType?,
 Attribute*, Url*, IconUrl*, Brief?, ExclFileName*)>
<!ELEMENT ProviderId              (#PCDATA)>
<!ELEMENT Name                    (#PCDATA)>
<!ELEMENT NameAbbr                (#PCDATA)>
<!ELEMENT Url                     (%url.data;)>
<!ATTLIST Url              LNG    %iso.lang.codes;  "EN"  >
<!ELEMENT IconUrl                 (%url.data;)>
<!ATTLIST IconUrl          LNG    %iso.lang.codes;  "EN"  >
<!ELEMENT Brief                   (#PCDATA)>
<!ELEMENT ExclFileName                          (#PCDATA)>
<!ATTLIST ExclFileName          
                fieldname       (uid|query)             "uid"
                database        CDATA           #REQUIRED>

<!-- End of Provider group -->

<!ELEMENT LinkSet                 (Link+)>
<!ELEMENT Link                    (LinkId, ProviderId, IconUrl*,
(ObjectSelector|SubObjectSelector),(ObjectUrl+)>
<!ELEMENT LinkId                  (#PCDATA)>
<!ELEMENT ObjectSelector          (Database, ObjectList)>
<!ELEMENT Database                (#PCDATA)>
<!-- All NCBI databases may be configured to include LinkOut. Please write to
 [email protected] for the current list of databases available for LinkOut -->
    
<!ELEMENT ObjectList              (FileName|(Query,ExclQuery*,ExclObjId*,ExclFileName*)|ObjId)+>
<!ELEMENT FileName                (#PCDATA)>
<!ATTLIST FileName                 fieldname   CDATA   #REQUIRED> 

<!ELEMENT Query                   (#PCDATA)>
<!ELEMENT ObjId                   (#PCDATA)>
<!ELEMENT ExclObjId               (#PCDATA)>

<!-- End of ObjectList group -->
<!-- End of ObjectSelector group -->

<!-- Libraries must use SubObjectSelector to refer to the sub providers -->
<!ELEMENT SubObjectSelector       (Database, SubProvider)>
<!ELEMENT SubProvider             (NameAbbr, (InclQuery|ExclQuery)*)>
<!ELEMENT InclQuery               (#PCDATA)>
<!ELEMENT ExclQuery               (#PCDATA)>
<!-- End of SubObjectSelector group -->

<!ELEMENT ObjectUrl              (((Base, (Rule|RuleToMany)?) | (Rule|RuleToMany)),
UrlName?, SubjectType?, Attribute*)>

<!ATTLIST ObjectUrl        LNG    %iso.lang.codes;  "EN" >

<!ELEMENT Base                    (%url.data;)>
<!ELEMENT pad                     (%rule.data;)*>
<!-- used to mark up strings that require padding to create
     fixed-length string attributes. --> 

<!ATTLIST pad   
        with                CDATA                  #REQUIRED
        width               CDATA                  #REQUIRED
        align               (left|right)            "right"> 
<!-- with a character to pad with (required)
     width result string size (required) (integer)
align the text should align to (left|right) (default:right)
     -->
     
<!ELEMENT apad                     (%rule.data;)*>
<!-- used to mark up strings that require padding to create 
     fixed-length string attributes. It skips all preceding 
     alpha characters before padding --> 

<!ATTLIST apad   
        with                CDATA                  #REQUIRED
        width               CDATA                  #REQUIRED
        align               (left|right)            "right"> 
<!-- with a character to pad with (required)width result string size (required) 
(integer)align the text should align to (left|right) (default:right)
     Examples:
      <apad with = "0" width = "6">E32</apad>  => "E00032"
      <apad with = "0" width = "6">640</apad>  => "000640"
     -->
<!ELEMENT subs                 (%rule.data;)*>
<!-- substitute one string for another in the element's content -->
<!ATTLIST subs  
        for                 CDATA                  #REQUIRED
        with                CDATA                 #REQUIRED>
<!-- for the string to replace with the string to substitute -->
     
<!ELEMENT toupper              (%rule.data;)*>
<!-- convert element content into upper case -->
<!ELEMENT tolower              (%rule.data;)*>
<!-- convert element content into lower case -->
<!ELEMENT strip                (%rule.data;)*>
<!-- strip off spaces/letters/digits in the element's content -->

<!ATTLIST strip  
 what   (spaces|letters|nondigits|digits)     #REQUIRED>

<!ELEMENT normalize            (%rule.data;)*>
<!-- are used for normalization of &lo.vol, &lo.iss; elements. Examples:
            "Pt 5"                  ==> "5"
            "3 Suppl"               ==> "3"
            "2A Pt 3"               ==> "2A"
            "10 Suppl 2 Pt 1"       ==> "10"
            "2/3"                   ==> "2"
      -->

<!ELEMENT Rule                    (%rule.data;)*>
<!ELEMENT UrlName                 (#PCDATA)>
<!ELEMENT RuleToMany              (Rule, Separator)>
<!ELEMENT Separator               (#PCDATA)>

<!-- End of ObjectUrl group -->
<!-- End of Link group -->
<!-- End of LinkSet group -->

Databases Available for Linking

Links can be made from the following NCBI databases to outside resources. When entering the database in the <Database> element, use the Db abbreviation, rather than the database name.

If you are interested in providing LinkOut links to other NCBI databases not listed in the above table, please write to vog.hin.mln.ibcn@ofni to express your interest to the relevant groups at NCBI. Note that LinkOut is able to link only to 5% of the total database records (depending on database size).

Icons

Icons should:

• Be 120 pixels wide x 30 pixels high or smaller.
• Be in one of the following image formats: GIF, JPEG, or PNG
• The icon URL for an icon file should not include XML escape characters such as &, “, <, >, '
• Identify the resource being linked. For libraries, this could be the library name. For resource providers, this could be the name of the resource and/or the format or language in which the resource is being delivered.
• If a journal or database resource is freely available, or free with a registration, the icon should have the text “Free.”
• Look like an actionable button. The icon should have a border and a colored background. Icons and text should be easy to read and should not blend in to the PubMed display.
• Not be animated.

The icon file name should use only letters from the English alphabet and numbers. Do not use special characters or spaces. Examples of file names are: libft.gif, libprint.gif, freeft.jpg, notfree.jpg.

Examples of icons are shown below.

Library icons

Other provider icons

Identity File

The identity file contains the information about a provider that NCBI needs to list the provider in LinkOut. This file must be named providerinfo.xml; the file name is case sensitive.

Section Contents

• Format
• Prolog
• Elements

<?xml version="1.0"?>
<!DOCTYPE Provider PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">
<Provider>
<ProviderId>ProviderId assigned by NCBI(required)</ProviderId>
   <Name>Name of Resource Provider or Library(required)</Name>
   <NameAbbr>NameAbbr assigned by NCBI(required)</NameAbbr>
   <SubjectType>SubjectType (optional)</SubjectType>
   <Attribute>Attribute (optional, repeatable)</Attribute>
   <Url>URL of provider’s website(optional, repeatable)</Url>
   <Brief>Short description of resource provider(optional)</Brief>
</Provider>

Resource File

The resource file describes the records the provider will link from and contains the information that LinkOut needs to generate links. Links described in the resource file should link directly to the resource; users should not have to perform any additional searching to access the resource after clicking the provider’s link.

Resource files, links to online full text and other database content, may be submitted as an XML file, CSV file, or as a simple text file.

<?xml version="1.0" ?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">
<LinkSet>
 <Link>
   <LinkId>Identifier assigned to link by provider(required)</LinkId>
   <ProviderId>ProviderId assigned by NCBI(required)</ProviderId>
   <IconUrl>URL of icon to be displayed on database records(required)</IconUrl>
   <ObjectSelector>
     <Database>NCBI database in which links will appear(required)</Database>
     <ObjectList>
        <Query>Search retrieving records to be linked(repeatable,
        required unless <ObjId> is specified</Query>
     </ObjectList>
   </ObjectSelector>
   <ObjectUrl>
     <Base>Stable portion of URL for provider’s resource(required)</Base>
     <Rule>Variable portion of URL for resource (required)</Rule>
     <SubjectType>SubjectType (optional)</SubjectType>
     <Attribute>Attribute (optional, repeatable)</Attribute>
     <UrlName>Short text string describing resource (optional)</UrlName>
   </ObjectUrl>
 </Link>
</LinkSet>

<?xml version="1.0" ?>
<!DOCTYPE LinkSet PUBLIC "-//NLM//DTD LinkOut 1.0//EN"
"https://www.ncbi.nlm.nih.gov/projects/linkout/doc/LinkOut.dtd">
<LinkSet>
 <Link>
   <LinkId>Identifier assigned to link by provider(required)</LinkId>
   <ProviderId>ProviderId assigned by NCBI(required)</ProviderId>
   <ObjectSelector>
     <Database>NCBI database in which links will appear(required)</Database>
     <ObjectList>
        <FileName fieldname="uid">filename.uid (file with Entrez database uids)</FileName>   
     </ObjectList>
   </ObjectSelector>
   <ObjectUrl>
     <Base>Stable portion of URL for provider’s resource(required)</Base>
     <Rule>Variable portion of URL for resource (required)</Rule>
     <SubjectType>SubjectType</SubjectType>
     <Attribute>Attribute (optional, repeatable)</Attribute>
     <UrlName>Short text string describing resource (optional)</UrlName>
   </ObjectUrl>
 </Link>
</LinkSet>

------ lines starting with "-" are comments -----
------ information in the first block is global-----
prid:   [required] 
dbase:  [required] 
stype:  [optional] 
attr:   [optional]
!base:  [optional] 

------ 
linkid: [required - LinkOut will add a suffix to make sure it is unique] 
uids:   [required if query is not present] 
query:  [required if uids is not present] 
base:   [required] 
rule:   [required] 
icon:   [optional] 
name:   [optional] 
stype:  [optional] 
attr:   [optional] 
------ 

----- 
query: <species1> [name] 
rule:  <http://...my_species1_page.html> 
----- 
query: <species2> [name] 
rule:  <http://...my_species2_page.html> 
-----  

-----
query: <species1> [name] OR <species2> [name] 
rule:  <http://...my_species1or2_page.html> 
----- 

----- 
query: <species1> [name] 
query: <species2> [name] 
rule:  <http://...my_species1or2_page.html> 
----- 

--- separate unique identifiers (UIDs) with a blank space.---
---Each new line of UIDs should start have the “uids” label---
uids: 123456 123469 3847559 
uids: 4755983 2197866
rule:  <http://...my_species1or2_page.html> 
----- 

Special Elements: SubjectType

The <SubjectType>, <Attribute>, and <UrlName> elements are used to organize and describe resources in the database displays and to facilitate access to these resources by defining them as groups.

SubjectType is used to group resources in the LinkOut Display, making it easier to browse through available LinkOut resources. In most cases, resources are grouped by Subject Category.

Only one SubjectType should be applied to each Link. If no SubjectType is specified for a Link, it will be displayed under the heading "Miscellaneous".

SubjectTypes are also used in My NCBI, allowing users to display records with links to resources from a specific SubjectType or Subject Category as a filter, and to activate icons for these links.

SubjectType can be used in searches to retrieve records with links to resources from a specific SubjectType.

To do this, enter the following in the search box.

losubjtSubjectTypeName [sb]
Replace SubjectTypeName with the SubjectType name from the list below.

This filter can be used as a part of any NCBI database search.

Special Elements: Attribute

The <SubjectType>, <Attribute>, and <UrlName> elements are used to organize and describe resources in the NCBI database displays and to facilitate access to these resources by defining them as groups.

The Attribute element is used to provide information about the resource itself, independent of content. It describes the format, barriers to access, and the ownership (if any) of the resources being linked. Based on the information provided by Attribute, users can make an informed choice from a list of LinkOut resources available. For example, they will know if a resource is free before clicking the link.

Attributes can be used in database searches to retrieve records with links to resources with a specific Attribute.

To do this, enter the following in the search box.

loattrAttributeName [sb]
Replace AttributeName with the Attribute name from the list below.

This filter can be used as a part of any NCBI database search.

Special aliases are also available for these searches:

Full text [sb]

Free full text [sb]

For each resource, the provider should select all Attribute values from the list below that apply and include them in the appropriate LinkOut files.

Special Elements: UrlName

UrlName is a short text string used to describe a resource. If possible, <SubjectType> and <Attribute> should be used, rather than UrlName. UrlName should be used only when the allowed terms in the SubjectType and Attribute lists do not suffice to describe the resource. UrlName is not searchable.

When UrlName is used, it will appear in the LinkOut Display. In the example below from the Gene database LinkOut display, the two providers Kyoto Encyclopedia of Genes and Genomes and TaqMan have used UrlName to provide additional information about the resource being linked. The link appears as the description given in UrlName. The first provider has not used UrlName, so the link appears as the resource name.

Allowable Rule Keywords

As in all XML files, entities can be defined and used in LinkOut files to facilitate file construction.

There are several pre-defined Linkout entities (Allowable Rule Keywords) in the LinkOut DTD. When an entity is used in the <Rule> element, the NCBI system will replace the entity with the corresponding value from each NCBI database record when constructing the URL specified in your <Rule>. Note that LinkOut entities cannot be used in the <Base> element or other elements in a LinkOut file.

The following is a list of entities and the values with which they will be substituted:

For PubMed only:

For Sequence databases (Nucleotide, Protein, Structure, Genome):

For Taxonomy only:

For UniGene only:

Special Characters

XML requires certain special characters to be encoded in the files. When using the following characters in LinkOut files, except in LinkOut entities, please encode them as shown.

Do not use ASCII encoding in LinkOut files.

Transferring Files via FTP

Providers must write to vog.hin.mln.ibcn@tuoknil to apply for inclusion in LinkOut before submitting files.

LinkOut files are submitted to NCBI via FTP. The following file name conventions apply:

• File names may include alpha and numeric characters only. Spaces and special characters such as hyphens are not allowed.
• Identity and Resource files must have the file extension “.xml”. The exception is resource files submitted as a simple text file.
• Identity files must be named “providerinfo.xml”.