HGrant

From Grantsfire

hGrant is a way of publishing grants information on a web page so that it may be read and understood by both people and software. This allows grants information to be automatically collected and aggregated into a searchable database.

hGrant is a series of semantic HTML patterns influenced by the microformats concept. That's a high-falutin' way of saying that you can express and publish metadata using basic web technologies -- HTML and CSS -- nothing else. You don't need to learn XML, RDF, RSS, or any of the many other technologies you may have read about.

If you're already publishing grants information on the web, you can use hGrant by making very minor changes to the page.

To get started:

1. Read the specification below.
2. Start with our tutorial, then read the Frequently Asked Questions.
3. Join the gf_working mailing list, a discussion forum for foundations and other participants using hGrant.
4. When you're ready to start publishing your information, read the specification and study other people's experiences in Acquired Wisdom.

If you know what RSS is and want to publish your grants information in a feed as opposed to a regular HTML page, read Using RSS. If you don't know what RSS is, don't worry too much about it. It's not necessary to get started using hGrant.

Ask questions and make suggestions on the gf_working mailing list or on the hGrant Discussion page. And please feel free to edit this Wiki any way you see fit!

Contents 1 Resources 2 Grants Data 3 Specification 3.1 Root Class Name 3.2 Properties and Sub-properties 3.3 Property List 3.4 Tagging 3.5 Human vs. Machine readable 4 Examples 4.1 Minimum Required hGrant 4.2 title and url 4.3 period 4.4 grantee and grantor 4.5 geo-focus 4.6 Tagging 5 Examples in the wild 6 Property Validation 7 Implementations 8 Acknowledgements 9 See Also

Resources

• GIFTS Export
• Comparison of data fields for hGrant, eGrant Reporting Standard, GIFTS Foundation Center export

Grants Data

• hGrant Feeds
• Funder Websites with Grants Data
• Grants Databases

Specification

The format of hGrant is a series of nested HTML elements with a class attribute which identifies an element as an hGrant property.

Root Class Name

The root class name is "hgrant". An element with a class name of "hgrant" is itself called an hGrant.

Properties and Sub-properties

The properties list of an hGrant are represented by elements inside the hGrant. Elements with class names matching the listed properties represent the values of those properties. Some properties have sub-properties and those are represented by elements inside the elements for properties.

Property List

hGrant properties (sub-properties use nested list elements to show hierarchy).

Required properties are in bold like this.'

• title
• description
• amount
  • currency
  • amount
• url
• period
  • dtstart
  • dtend
• grantee (hCard)
  • adr
    • post_office_box
    • extended_address
    • street_address
    • locality
    • region
    • postal_code
    • country_name
  • tel
  • email
  • url
  • org
  • fn
• grantor (hCard)
  • adr
    • post_office_box
    • extended_address
    • street_address
    • locality
    • region
    • postal_code
    • country_name
  • tel
  • email
  • url
  • org
  • fn
• geo-focus
  • locality
  • region
  • postal_code
  • country
  • tel
  • email
  • url
  • org
  • fn

Tagging

An hGrant can be tagged using the rel-tag method. This doesn't use class names to determine properties. Instead it uses the rel attribute of an anchor (a) element.

• rel-tag

Human vs. Machine readable

The human visible text contents of an element for a property represents the value of that property, with a few exceptions:

if an <abbr> element is used for a property then the title attribute, if present, of the <abbr> element will be used as the value of that property. The more human readable version of the value will be displayed to the user and the machine can interpret a more appropriate representation. Here's an example:

<div class="amount">
  <abbr class="currency" title="USD">$</abbr>
  <abbr class="amount" title="30000">30,000.00</abbr>
</div>

This will be rendered to the user as:

$ 30,000.00

And the machine interpreting your hGrant will see this:

amount: {
  currency: 'USD',
  amount: 30000
}

Examples

Below are examples of marking up hGrant properties.

Minimum Required hGrant

<div class="hgrant">
  <p class="description">Grant to study the mating habits of corn.</p>

  <div class="amount">
    <abbr class="currency" title="GBP">£</abbr>
    <abbr class="amount" title="300000">300.000,00</abbr>
  </div>

  <div class="grantee vcard">
    <span class="org fn">Farming Foundation</span>
  </div>

  <div class="grantor vcard">
    <span class="org fn">Corn Co-op</span>
  </div>
</div>

title and url

Here's a simple way to combine the title and url of an hGrant.

<div class="hgrant">
  <h2 class="title"><a class="url" href="http://farmfound.org/corn.html">Corn Study</a></h2>
</div>

An hGrant parser will see this structure:

hgrant: {
  title: 'Corn Study',
  url: 'http://farmfound.org/corn.html'
}

period

The period consists of two dates, the start and end dates of this grant. The machine readable and human readable formats of a date can be different using the <abbr> HTML element.

<div class="hgrant">
  <p class="period">
    This grant is in effect from
    <abbr class="dtstart" title="20080101T0000-0700">January 1, 2008</abbr>
    to
    <abbr class="dtend" title="20091231T0000-0700">December 31, 2009</abbr>.
  </p>
</div>

An hGrant parser will see this structure:

hgrant: {
  period: {
    dtstart: '20080101T0000-0700',
    dtend: '20091231T0000-0700'
  }
}

You can learn more about machine readable date formats in RFC 3339.

grantee and grantor

These are hCards. Here is an example:

<div class="hgrant">
  <div class="grantee vcard">
    <h3>Grant Recipient</h3>

    <p class="fn org"><a class="url" href="http://corncoop.org">Corn Co-op</a></p>

    <p class="adr">
      <span class="street_address">250 W Coop St</span>
      <span class="extended_address">Suite 3</span> <br />
      <span class="locality">Pittsburgh</span>
      <abbr class="region" title="Pennsylvania">PA</abbr>,
      <span class="postal_code">15222</span>
      <abbr class="country_name" title="United States">USA</abbr>
    </p>

     <p>Contact Details</p>
     <ul>
       <li><abbr class="tel" title="14126810000">+1.412.681.0000</abbr></li>
       <li><a href="mailto:info@corncoop.org" class="emial">info@corncoop.org</a></li>
  </div>
</div>

An hGrant parser will see this structure:

hgrant: {
  grantee: {
    org: 'Corn Co-op',
    fn: 'Corn Co-op',
    adr: {
      street_address: '250 W Coop St',
      extended_address: 'Suite 3',
      locality: 'Pittsburgh',
      region: 'Pennsylvania',
      postal_code: 15222,
      country_name: 'United States'
    },
    tel: 14126810000,
    email: 'info@corncoop.org'
  }
}

You can use the same format for grantor by switching the class name associated with the hCard from grantee to grantor.

geo-focus

geo-focus provides information about the area an hGrant represents. Here is an example:

<div class="hgrant">
  <div class="geo-focus">
    <span class="locality">Waukesha</span>
    <abbr class="region" title="Wisconsin">WI</abbr>,
    <span class="postal_code">53186</span>
    <abbr class="country" title="United States">USA</abbr>
  </div>
</div>

An hGrant parser will see this structure:

hgrant: {
  'geo-focus': {
    locality: 'Waukesha',
    region: 'Wisconsin',
    postal_code: 53186,
    country: 'United States'
  }
}

Tagging

Tagging is simple, here are some examples:

<div class="hgrant">
  <p>Tags:
    <a rel="tag" href="http://technorati.com/tag/corn">corn</a>,
    <a rel="tag" href="http://technorati.com/tag/farming">farming</a>,
    <a rel="tag" href="http://technorati.com/tag/midwest">midwest</a>.
  </p>
</div>

An hGrant parser will see this structure:

hgrant: {
  'tags': [
    {
      title: 'corn',
      url: 'http://technorati.com/tag/corn'
    },
    {
      title: 'farming',
      url: 'http://technorati.com/tag/farming'
    },
    {
      title: 'midwest',
      url: 'http://technorati.com/tag/midwest'
    }
  ]
}

Examples in the wild

• Grantsfire

Property Validation

The feed validation tool requires information about property types and the intensity by which they're required. For example, a URL is important but not required. It's helpful to link an entry on Grantsfire to its originating source for more details, submissions, etc. Therefore, a missing URL is a warning but not an error. Using classic street-light terminology, it's a yellow light but not a red light.

I need to know the critical nature of each property. Here's a list to get started accompanied by my best guess. Please fix my poor assumptions:

title warning

URL warning

description error

amount (currency) error

period warning

dtstart ([ datetime])

dtend ([ datetime])

grantee (hCard) error

grantor (hCard) error

rel-tag warning

This feedback is required before the feed validator can be completed.

Implementations

Acknowledgements

Portions of this content and structure happily copied from the hCard specification. Thanks!

See Also

• Tutorial
• Mapping GIFTS tables and columns to hGrant properties