Next / Previous / Contents / Shipman's homepage


This publication describes an XML schema for representing a birdwatcher's field notes, along with instructions for using an accompanying module written in the Python programming language.

This publication is available in Web form and also as a PDF document. Please forward any comments to

Table of Contents

1. Requirements
2. Why XML?
3. Design considerations
3.1. The time dimension
3.2. The spatial dimension
3.3. The taxonomic dimension: what kind of bird?
3.4. Other dimensions of the data
4. Entity-relationship diagram
5. The schema
5.1. The preamble
5.2. note-set: the root element
5.3. The day-notes element
5.4. The day-summary element: information about the field day
5.5. The loc element: Defining location codes
5.6. The gps element: defining a waypoint
5.7. The day-annotation elements
5.8. The form element: records for one kind of bird
5.9. The taxon-group pattern: biological classification of the birds seen
5.10. The age-sex-group attributes
5.11. The loc-group pattern: locality attributes and content
5.12. The sighting-notes elements
5.13. The photo element
5.14. The floc element: Multiple sightings of a given form
5.15. The narrative elements
6. Directory structure for data files
7. A Python interface
8. class BirdNoteSet: Container for notes
8.1. BirdNoteSet(): Constructor
8.2. BirdNoteSet.genDays(): Generate contained daily sets
8.3. BirdNoteSet.addDay(): Add a daily note set
8.4. BirdNoteSet.readFile(): Read an XML file
8.5. BirdNoteSet.writeFile(): Save as XML
9. class DayNotes: Notes for one day
9.1. DayNotes.title(): General title string
9.2. DayNotes.defaultLoc(): What is the default location?
9.3. DayNotes.lookupLoc(): Look up a location code
9.4. DayNotes.addForm(): Add a new form record
9.5. DayNotes.genForms(): Retrieve stored sightings
9.6. DayNotes.genFormsSeq(): Retrieve sightings in addition order
10. class DaySummary: Daily context
10.1. DaySummary.defaultLoc(): What is the default location?
10.2. DaySummary.addLoc(): Add a new locality code definition
10.3. DaySummary.lookupLoc(): Look up a location code
10.4. DaySummary.genLocs(): Retrieve all locality definitions
11. class Loc: Locality code definition
11.1. Loc.addGps(): Add a waypoint
11.2. Loc.genGps(): Generate waypoints
12. class Gps: GPS waypoint
13. class BirdForm: Records for one kind of bird
13.1. BirdForm.addSighting()
13.2. BirdForm.__len__(): Return the number of sightings
13.3. BirdForm.__getitem__(): Retrieve a child sighting
13.4. BirdForm.nSightings(): Number of sightings
13.5. BirdForm.getLocGroup(): Get the effective locality
14. class LocGroup: Inheritable locality data
15. class SightNotes: Sighting notes
15.1. SightNotes.addPara(): Add general notes
15.2. SightNotes.addPhoto(): Add a photo link
15.3. SightNotes.genPhotos(): Retrieve photo links
16. class Sighting: Single sighting
16.1. Sighting.getLocGroup()
17. class AgeSexGroup: Age and sex details
18. class Photo: Photograph link
19. class Narrative: General container for narrative
19.1. Narrative.addPara(): Add a paragraph
19.2. Narrative.__len__(): How many paragraphs?
19.3. Narrative.__getitem__(): Get one paragraph
19.4. Narrative.genParas(): Generate the contained paragraphs
20. class Paragraph: General container for a paragraph of narrative
20.1. Paragraph.addContent(): Add content
20.2. Paragraph.genContent(): Generate the phrase list
21. class BirdNoteTree: A complete set of notes
21.1. BirdNoteTree(): Constructor
21.2. BirdNoteTree.genMonths(): Generate monthly record sets
22. class FlatSighting: Complete sighting record

1. Requirements

Formal field notes taken while birdwatching have some value to the scientific community. The system described here is primarily intended to archive such notes and make them accessible for study.

A secondary purpose is to serve the needs of recreational birdwatchers who want to know what others have seen so they can plan their own field trips.

This system does not address the needs of a system for storing the notes from multiple observers. The identity of the primary observer is not represented internally, although that observer can mention other observers who were present for some or all of the sightings.

At this writing, the primary thrust of the design effort is to produce an internal representation of bird notes that is accurate yet flexible and reasonably easy to use. The external rendering of the encoded notes is an open-ended challenge. At a minimum, the notes ought to be available on the Web in chronological order.

Future renderings will include an archival print form, and assorted facilities for querying records through the Web. Such queries will allow users to limit records by time period, locality, type of bird, and type of data. For example, a user might ask, what are all this observer's records for Vermilion Flycatcher? What records are there of the vocalizations of Verdin? What are the observer's American Birding Association totals for countable species for the state of New Mexico?

This document includes:

  • A discussion of why XML was the chosen representation, and an XML schema that defines the document type used to represent the bird records.

  • A programmatic interface in the Python language that can be used to access records in that XML document type.

The actual implementation of the Python interface is discussed in a companion publication, Objects to represent bird note files.