Search Categories & Databases XML

XML Format

Search categories and databases are defined in a standard XML format. We commonly refer to this XML file as "categories.xml".

Notes:

A category can contain either databases or sub-categories, not both.
There can be only one top-level default category. This category cannot contain any sub-categories and must contain at least one database.
To test categories and databases with the sample authorization service (org.sakaiproject.citation.impl.SampleSiteOsidConfiguration), be sure to add the "all" database group for each database:
```
<database_group>all</database_group>
```
Using the sample authorization service can be a permanent solution if all Citations Helper users have access to the same search categories and databases.

A note for Ex Libris Metalib sites: Metalib supports three types of databases, shown below.

Type	Description
"Search and Retrieve"	Returns search results
"Search and Link"	Returns a count of hits available and a vendor link
"Link To"	Returns a link to the database (cannot be searched)

Only "Search and Retrieve" databases work well with the Citations Helper, so only these should be added to the XML configuration file.

View a complete sample XML file

Sample XML

<config>
  <categories>
    <category name="name" id="id" default="default">  <!-- top level default (auto-selected) category -->
      <category_description>Optional category description</category_description>
      <category_databases>
        <category_database recommended="recommended">  <!-- auto-selected -->
          <id>database_id</id>
          <alt_name>Optional alternate database name for only this category</alt_name>
          <alt_description>Optional alternate database description for only this category</alt_description>
        </category_database>
        <category_database recommended="recommended">  <!-- auto-selected -->
          <id>database_id</id>
          <alt_name>Optional alternate database name for only this category</alt_name>
          <alt_description>Optional alternate database description for only this category</alt_description>
        </category_database>
        <category_database>
          <id>database_id</id>
          <alt_name>Optional alternate database name for only this category</alt_name>
          <alt_description>Optional alternate database description for only this category</alt_description>
        </category_database>
      </category_databases>
    </category>
    <category name="name" id="id">  <!-- top-level, non-default -->
      <category_description>Optional category description</category_description>
      <category name="name" id="id">  <!-- sub-category -->
        <category_description>Optional category description</category_description>
        <category_databases>  <!-- sub-category databases -->
          <category_database recommended="recommended"> <!-- auto-selected -->
             <id>database_id</id>
             <alt_name>Optional alternate database name for only this category</alt_name>
             <alt_description>Optional alternate database description for only this category</alt_description>
          </category_database>
          <category_database>
             <id>database_id</id>
             <alt_name>Optional alternate database name for only this category</alt_name>
             <alt_description>Optional alternate database description for only this category</alt_description>
          </category_database>
          <category_database recommended="recommended"> <!-- auto-selected -->
             <id>database_id</id>
             <alt_name>Optional alternate database name for only this category</alt_name>
             <alt_description>Optional alternate database description for only this category</alt_description>
          </category_database>
        </category_databases>
      </category>
    </category>
  </categories>

  <databases>
    <database name="name" id="id">
      <database_description>description</database_description>
      <database_group>UMICH-AnnArbor</database_group>  <!-- institution-specific groups -->
      <database_group>UMICH-Dearborn</database_group>
    </database>
    <database name="name" id="id">
      <database_description>description</database_description>
      <database_group>UMICH-Law</database_group>
      <database_group>UMICH-Business</database_group>
    </database>
    <!-- More databases here... -->
  </databases>
</config>

Schemas

The following schemas are out of date.

The following XML schemas have been inferred programatically from the above document using Trang. Corrections are welcome.

RELAX NG (compact syntax)

default namespace = ""

start =
  element config {
    element categories { category+ },
    element databases {
      element database {
        attribute id { xsd:NCName },
        attribute name { text },
        element database_description { text },
        element database_group { xsd:NCName }
      }+
    }
  }
category =
  element category {
    attribute default { xsd:NCName }?,
    attribute id { xsd:integer },
    attribute name { text },
    ((category
      | element category_description { text })+,
     element category_databases {
       element category_database {
         attribute recommended { xsd:NCName }?,
         element id { xsd:NCName }
       }+
     })?
  }

RELAX NG (full syntax)

<?xml version="1.0" encoding="UTF-8"?>
<grammar ns="" xmlns="http://relaxng.org/ns/structure/1.0" datatypeLibrary="http://www.w3.org/2001/XMLSchema-datatypes">
  <start>
    <element name="config">
      <element name="categories">
        <oneOrMore>
          <ref name="category"/>
        </oneOrMore>
      </element>
      <element name="databases">
        <oneOrMore>
          <element name="database">
            <attribute name="id">
              <data type="NCName"/>
            </attribute>
            <attribute name="name"/>
            <element name="database_description">
              <text/>
            </element>
            <element name="database_group">
              <data type="NCName"/>
            </element>
          </element>
        </oneOrMore>
      </element>
    </element>
  </start>
  <define name="category">
    <element name="category">
      <optional>
        <attribute name="default">
          <data type="NCName"/>
        </attribute>
      </optional>
      <attribute name="id">
        <data type="integer"/>
      </attribute>
      <attribute name="name"/>
      <optional>
        <oneOrMore>
          <choice>
            <ref name="category"/>
            <element name="category_description">
              <text/>
            </element>
          </choice>
        </oneOrMore>
        <element name="category_databases">
          <oneOrMore>
            <element name="category_database">
              <optional>
                <attribute name="recommended">
                  <data type="NCName"/>
                </attribute>
              </optional>
              <element name="id">
                <data type="NCName"/>
              </element>
            </element>
          </oneOrMore>
        </element>
      </optional>
    </element>
  </define>
</grammar>

W3C XML Schema

<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="config">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="categories"/>
        <xs:element ref="databases"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="categories">
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" ref="category"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="databases">
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" ref="database"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="database">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="database_description"/>
        <xs:element ref="database_group"/>
      </xs:sequence>
      <xs:attribute name="id" use="required" type="xs:NCName"/>
      <xs:attribute name="name" use="required"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="database_description" type="xs:string"/>
  <xs:element name="database_group" type="xs:NCName"/>
  <xs:element name="category">
    <xs:complexType>
      <xs:sequence minOccurs="0">
        <xs:choice maxOccurs="unbounded">
          <xs:element ref="category"/>
          <xs:element ref="category_description"/>
        </xs:choice>
        <xs:element ref="category_databases"/>
      </xs:sequence>
      <xs:attribute name="default" type="xs:NCName"/>
      <xs:attribute name="id" use="required" type="xs:integer"/>
      <xs:attribute name="name" use="required"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="category_description" type="xs:string"/>
  <xs:element name="category_databases">
    <xs:complexType>
      <xs:sequence>
        <xs:element maxOccurs="unbounded" ref="category_database"/>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
  <xs:element name="category_database">
    <xs:complexType>
      <xs:sequence>
        <xs:element ref="id"/>
      </xs:sequence>
      <xs:attribute name="recommended" type="xs:NCName"/>
    </xs:complexType>
  </xs:element>
  <xs:element name="id" type="xs:NCName"/>
</xs:schema>

DTD

<?xml encoding="UTF-8"?>

<!ELEMENT config (categories,databases)>
<!ATTLIST config
  xmlns CDATA #FIXED ''>

<!ELEMENT categories (category)+>
<!ATTLIST categories
  xmlns CDATA #FIXED ''>

<!ELEMENT databases (database)+>
<!ATTLIST databases
  xmlns CDATA #FIXED ''>

<!ELEMENT database (database_description,database_group)>
<!ATTLIST database
  xmlns CDATA #FIXED ''
  id  #REQUIRED
  name CDATA #REQUIRED>

<!ELEMENT database_description (#PCDATA)>
<!ATTLIST database_description
  xmlns CDATA #FIXED ''>

<!ELEMENT database_group (#PCDATA)>
<!ATTLIST database_group
  xmlns CDATA #FIXED ''>

<!ELEMENT category ((category|category_description)+,
                    category_databases)?>
<!ATTLIST category
  xmlns CDATA #FIXED ''
  default  #IMPLIED
  id  #REQUIRED
  name CDATA #REQUIRED>

<!ELEMENT category_description (#PCDATA)>
<!ATTLIST category_description
  xmlns CDATA #FIXED ''>

<!ELEMENT category_databases (category_database)+>
<!ATTLIST category_databases
  xmlns CDATA #FIXED ''>

<!ELEMENT category_database (id)>
<!ATTLIST category_database
  xmlns CDATA #FIXED ''
  recommended  #IMPLIED>

<!ELEMENT id (#PCDATA)>
<!ATTLIST id
  xmlns CDATA #FIXED ''>