Properties, In-Depth: Part 1 - Goals and Basic Design

 

In a previous blog post,  I discussed a bit about properties for flights, but I think there's actually a lot to talk about here so this is the first in a series of posts about properties in a bit more depth.

I should also start by apologizing for the name "properties"; it's a holdover from the software world where "objects" have "properties"; you can think of it as synonymous to an attribute, or a field of data.  It's really simply a chunk of data that you can attach to a flight: every flight has a set of core fields (total time, PIC time, date, etc.), and zero or more properties that may or may not be present on any given flight. 

Basic Goals

There are really three goals for properties.

One is to enable extensibility of the system without having to make code changes.  Since properties are defined in the database itself, it's a simple update to the database to create new properties.  This helps a lot for the very frequent scenario of a pilot who requests a custom field for one purpose or another.   

But there are problems with custom fields.  One of the very basic is that the semantics of a user-defined field are generally unknown to the system, so it is hard to avoid mistakes or to enforce good data practices; after all, we're all pilots and should be focusing on flying; only I should need to worry about the data.  But another problem is that the odds are really good that if one pilot needs to track something, that another pilot also needs to track the same thing, or something very similar.  Why reinvent the wheel? 

So the second goal of properties is to help keep things orderly and broadly useful across the MyFlightbook community.

The third goal of properties is to enable customization of the logbook to match different flying needs.  A GA pilot typically records different (but overlapping!) data with what a military pilot records, which is different from what an airline pilot needs to track, and so forth.  I discuss this in a bit more depth here and here.

How do they work?

At its core, a property is simply a piece of data attached to a flight that is linked to a property-type.  The property itself is a simple essentially naked piece of data; it is the property type with which it is associated that determines how it is entered, displayed, and otherwise behaves.

The property-type defines the abstract property; this is what you see in the list of properties that are available for a flight, and as of this writing there are nearly 700 of them in the system.  Many properties can be associated with a single property-type.  For example, if you log Solo Time on a dozen flights, that's 12 different values that are each associated with a single shared "Solo Time" property-type definition.

A property-type encapsulates the following:

• The Title for the property (what you see in the list of available property types).  An example might be "Solo Time"
• The formatting for how to display the property's data.  E.g., if you have 90 minutes of solo time on a flight, it might display "Solo Time: 1.5", "Solo Time: 1,5", or "Solo Time: 1:30", depending on your locale, or whether you use decimal or HH:MM notation for times
• A description for the property (this is shown in the little pop-up help tip for the property)
• Any sort order rules.  E.g., "Block Out" sorts after "Block In", but since you log Block Out first, it makes sense to show that first.
• The data type for the property (discussed below)
• Any semantic flags for the property (discussed below).

The data type and flags provide a first level of semantics for the property - how should the property be treated?  For the most part, the system is ignorant of the true meaning of a given property; out of the nearly 700 property types, there are only about 120 or so that are even known by the code, and probably half of those are simply mappings for importing fields from other logbook programs.  But the data type and flags allow the system to work intelligently with all of these properties even without knowing anything about what they mean.

A property-type can be one of 7 data types:

• Integer.  This is a whole number, and is typically used for things you count like landings or approaches.  With exceptions noted below, these are also summed and displayed in totals by default.
• Decimal.  These are positive real numbers, typically used for time.  E.g., Solo Time.  Like integers, these are also summed and displayed in totals, and are shown using the formatting appropriate for your settings, including HH:MM.  Any of these properties that is a time (see below) can be cross-filled from the "Total Time" field by pressing-and-holding it (on the mobile apps) or by clicking the little arrow next to it (on the website).
  
• Currency.  This is just like decimal except that it is assumed to be a monetary amount.  An example is Fuel Cost.  Note that the specific currency (dollars, euros, yen, etc.) is NOT specified, so it's up to you to use consistent units.  This is formatted using your locale's currency conventions, so "3.1" will show as $3.10 in the US or £3.10 if you use UK settings.
• True/False.  This is something that is true for the whole flight or not.  An example is a Flight Review or a Checkride.
• Date. A date, without a corresponding time.  Interestingly, at the moment I don't have any date property-types, but I'm ready if the need ever arises.
• Date+Time.  A date with a corresponding time, assumed to be Zulu.  An example is Block Out.  These are formatted using your locale's date conventions and are adjusted from UTC to your timezone if you've specified a preferred timezone (website) or have checked the "Use Local Time" option in the mobile apps, but they are always stored as UTC.  As a result, the displayed value can change if your time zone changes.
  
• Text. This is free-form text, such as the name of the PIC or the name of the instructor.

The semantic flags identify additional semantics for the property so that the system can be more intelligent in handling it without having to know anything really about what it is and how it works.  Any given flag can be set or not set independently from any other flag.  

Broadly speaking, a given flag either identifies some aspects of how the property behaves but without any particular interpretation/meaning, or it indicate that the property belongs to a group of properties that do have some specific semantic meaning, but where it is not important for the system to know which exact property type it is.

The flags in the first group (identifying how the property behaves) are the following:

• Exclude from totals.  By default, numerical types (integers, decimals, and currency) are summed and shown in totals, but this doesn't always make sense.  For example, it makes sense to see the total amount  you spent on fuel to track your total spend, but it makes no sense to add the price of a unit of fuel in one flight to the price of a unit of fuel on another flight.
• Not a time.  By default, numerical types are assumed to be times and hence respect your preference for decimal vs. HH:MM display.  But not all decimals are time.  For example, fuel consumed or distance flown are straight up numerical values.  This flag suppresses HH:MM for such properties.
  
• No Autocomplete.  Text properties remember values you've used previously to make it easier to re-enter frequently used values like your student's name or the name of the PIC.  But autocomplete doesn't make sense for properties where re-use is unlikely or rare, such as "first time to airport" or "approach name(s)".
• All Capitals.  Some text properties, by convention, should be all in uppercase.  "First time to airport" and  "Runways Used" are examples.  These properties display their text in all uppercase letters. 
• Exclude from Previously Used.  By default, when you use a property, it shows up for subsequent flights on the assumption that you're likely to use it again.  For example, most of us never get to experience the thrill of a carrier landing, but if you record one, there's a really good likelihood you'll be recording more.  But many properties - particularly those indicating (many) checkrides or sign-offs - are ones you'll never use again, so those have this flag and are excluded from the previously-used property list by default.  They're still available to you, you just have to find them in the list.
  

A note on units: we obviously all use the same measure of time (hours and  minutes) around the world, so a time is always in hours, although it may be displayed in decimal or HH:MM format (e.g., an hour and a half is either 1.5 or 1:30, but those are just two expressions of the same time value).  But decimals that are not times and currencies can have different units: a per diem might be in dollars/day or euros per day, a speed might be knots or mph or km/h, and so forth.  These properties are effectively unitless in MyFlightbook.  Pick a unit to use for it and stick with it.

The remainder of the flags actually identify that a given property has some sort of meaning to the system, so I'll discuss those in my next post.

Hopefully, that explains how I can add new properties to the system with a trivial amount of effort, and without having to change code, and how nearly 700 property types can play nicely together in a system that is truly oblivious to what most of them mean.