Field types (Leo's) by LeoFrachet · Pull Request #2 · MobilityData/transit

LeoFrachet · 2018-09-13T14:55:15Z

I've removed the definition which weren't about data type for now (required, optional...)

As explained in https://github.com/MobilityData/Tasks/issues/3, I've focused on factorizing the definition appearing multiple times in the existing spec.

This reverts commit 21bc280.

barbeau · 2018-09-13T15:12:13Z

+- **ID** - The field contains an identifier which uniquely identifies an entity (therefore  is dataset unique). Its value is not aimed to be displayed to the user, and is a sequence of any UTF-8 characters, but using only printable ASCII characters is recommended.
+- **Positive Integer** - The field contains a non-negative whole number (which includes 0).
+- **Language Code** - The field contains a IETF BCP 47 language code. For an introduction to IETF BCP 47, please refer to http://www.rfc-editor.org/rfc/bcp/bcp47.txt and http://www.w3.org/International/articles/language-tags/. E.g. "en" for English, "en-US" for American English or "de" for German.
+- **Latitude** - The field contains the WGS84 latitude as a float number (it includes decimals). The value must be higher and -90.0 and smaller than 90.0.


For lat and long, I would change this to a floating point (i.e., decimal) number

I would change to `The value must be greater than or equal to -90.0 and less than or equal to 90.0."

Done. But I removed the (i.e.,decimal) which was cutting the definition in half and I got stuck at "what is a floating point?"

I'm adding an example at the end.

So technically this should actually read The field contains the WGS84 latitude in decimal degrees.

"decimal degrees" is the way the numeric decimal format is usually described (as opposed to degrees/minutes/seconds).

barbeau · 2018-09-13T15:14:30Z

+- **Positive Integer** - The field contains a non-negative whole number (which includes 0).
+- **Language Code** - The field contains a IETF BCP 47 language code. For an introduction to IETF BCP 47, please refer to http://www.rfc-editor.org/rfc/bcp/bcp47.txt and http://www.w3.org/International/articles/language-tags/. E.g. "en" for English, "en-US" for American English or "de" for German.
+- **Latitude** - The field contains the WGS84 latitude as a float number (it includes decimals). The value must be higher and -90.0 and smaller than 90.0.
+- **Longitude** - The field contains the WGS84 longitude as a float number (it includes decimals). The value must be higher and -180.0 and smaller than 180.0.


I would change to `The value must be greater than or equal to -180.0 and less than or equal to 180.0."

barbeau · 2018-09-13T15:15:48Z

+- **Language Code** - The field contains a IETF BCP 47 language code. For an introduction to IETF BCP 47, please refer to http://www.rfc-editor.org/rfc/bcp/bcp47.txt and http://www.w3.org/International/articles/language-tags/. E.g. "en" for English, "en-US" for American English or "de" for German.
+- **Latitude** - The field contains the WGS84 latitude as a float number (it includes decimals). The value must be higher and -90.0 and smaller than 90.0.
+- **Longitude** - The field contains the WGS84 longitude as a float number (it includes decimals). The value must be higher and -180.0 and smaller than 180.0.
+- **Service Date** - The field contains the service date in the YYYYMMDD format. Since service time within a service date can be above 24:00:00, a service date often contains information for the subsequent day(s). E.g "20180913" for Septembre 13th, 2018.


I would use the U.S. English spelling for Septembre instead - September

Grrrrrr.

I totally agree, but my fingers are so confused. I've spent the last 13 days fighting when I'm writing "septembre" in French, that I'm writing "Septembre", and I see that now I have it back in French, I'm mixing it in English.

barbeau · 2018-09-13T15:17:15Z

+- **Longitude** - The field contains the WGS84 longitude as a float number (it includes decimals). The value must be higher and -180.0 and smaller than 180.0.
+- **Service Date** - The field contains the service date in the YYYYMMDD format. Since service time within a service date can be above 24:00:00, a service date often contains information for the subsequent day(s). E.g "20180913" for Septembre 13th, 2018.
+- **Service Time** - The field contains the service time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. E.g. "14:30:00" for 2:30PM or "25:35:00" for 1:35AM on the next date.
+- **Text string** - The field contains a string of UTF-8 caracters, which is aimed to be displayed to the rider and which must therefore be readable.


caracters -> characters

readable -> human readable.

barbeau · 2018-09-13T15:18:07Z

+- **Service Date** - The field contains the service date in the YYYYMMDD format. Since service time within a service date can be above 24:00:00, a service date often contains information for the subsequent day(s). E.g "20180913" for Septembre 13th, 2018.
+- **Service Time** - The field contains the service time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. E.g. "14:30:00" for 2:30PM or "25:35:00" for 1:35AM on the next date.
+- **Text string** - The field contains a string of UTF-8 caracters, which is aimed to be displayed to the rider and which must therefore be readable.
+- **Timezone** - The field contains a TZ timezone from the TZ database. Timezone names never contain the space character but may contain an underscore. Refer to http://en.wikipedia.org/wiki/List_of_tz_zones for a list of valid values. E.g. "Asia/Tokyo", "America/Los_Angeles" or "Africa/Cairo".


I'd hyperlink the TZ database.

barbeau · 2018-09-13T15:19:50Z


+## Field Types
+
+- **Ad-hoc** - Please see the detail column of the field for the definition of the field type.


Which fields would this describe? Without knowing that, I think Misc is probably a better value.

I've mainly done it for currency_type(ISO 4217) and agency_phone (which should be E123 but currently isn't specified as such).

But to answer your question I've checked every field and it could also be used for:

agency_email, feed_contact_email (but I can add a type for that now that I see there are two of them)

shape_dist_traveled (positive float)

price (positive float)

feed_version (not an ID, not really a Text string)

I must confess I don't like "Misc", it sounds as "what we haven't sorted". Ad-hoc is distinct, it is saying that the format is distinct.

But if another anglo endorse the "Misc", I'll go for it. @antrim?

I must confess I don't like "Misc", it sounds as "what we haven't sorted".

Isn't that what it is :)?

I'm not married to "Misc", but "Ad-Hoc" definitely doesn't sound right. To me in English "Ad-Hoc" implies something that's a "one-off" or something done once for a particular purpose without organization. To me it almost implies that you could put whatever you want in that field.

Thinking more, I'd actually vote to remove this type entirely and just list all types here, even if they only occur once in the spec.

I'm adding the Non-negative float type (roll eyes) and the email type.

Regarding ad-hoc, I'm just gonna remove it.

barbeau · 2018-09-13T15:20:10Z

+## Field Types
+
+- **Ad-hoc** - Please see the detail column of the field for the definition of the field type.
+- **Color** - The field contains a color encoded as a six-character hexadecimal number. Refer to https://htmlcolorcodes.com/ to generate a valid value. E.g. "FFFFFF" for white, "000000" for black or "0039A6" for the A,C,E lines in NYMTA.


six-character -> six-digit

I would add ...hexadecimal number. A leading "#" is not included.

I'm adding the # comment after the "valid value". Because when you read the definition as "a six-character hexadecimal number", you don't see why we speak about not including the #. There is no hash in a six-character hexadecimal number.

barbeau · 2018-09-13T15:23:48Z

+
+- **Ad-hoc** - Please see the detail column of the field for the definition of the field type.
+- **Color** - The field contains a color encoded as a six-character hexadecimal number. Refer to https://htmlcolorcodes.com/ to generate a valid value. E.g. "FFFFFF" for white, "000000" for black or "0039A6" for the A,C,E lines in NYMTA.
+- **Enum** - The field contains a value among a set of ad-hoc predefined constants defined in the "Details" column. E.g. the route_type field contains a "0" for tram, a "1" for subway...


I would say The field contains a value from...

I would remove ad-hoc.

We might want to consider replacing all E.g. with For example, to be clearer.

Done, done and done.

barbeau · 2018-09-13T15:26:40Z

+- **Color** - The field contains a color encoded as a six-character hexadecimal number. Refer to https://htmlcolorcodes.com/ to generate a valid value. E.g. "FFFFFF" for white, "000000" for black or "0039A6" for the A,C,E lines in NYMTA.
+- **Enum** - The field contains a value among a set of ad-hoc predefined constants defined in the "Details" column. E.g. the route_type field contains a "0" for tram, a "1" for subway...
+- **ID** - The field contains an identifier which uniquely identifies an entity (therefore  is dataset unique). Its value is not aimed to be displayed to the user, and is a sequence of any UTF-8 characters, but using only printable ASCII characters is recommended.
+- **Positive Integer** - The field contains a non-negative whole number (which includes 0).


As ugly as it is, I think this type must be named Non-negative Integer - "positive" by definition excludes 0.

And, I'd change the definition to The field contains a the value 0 or a positive whole number.

"positive" by definition excludes 0.

Haha. Oh God. Not in French Math (aka not in real Math). But yeah, I've heard that's how you do Math. It is so confusing. Zero is obviously positive and negative. This is why we have N* and Z*. Anyway... #DontStartMeOnThat #ThisIsWhyWeHave12FieldsMedals #LongLiveNAndZStar

Anyway. I'll replace "Positiv" by "Non-negative".

barbeau · 2018-09-13T15:31:00Z

@LeoFrachet I've left a few comments in-line.

LeoFrachet · 2018-09-13T15:56:42Z

@barbeau: I've answered to most of your comments, accepting most of them (sometime reluctantly).

LeoFrachet · 2018-09-13T18:19:02Z

@barbeau: updated using your second reviewing.

barbeau · 2018-09-13T18:45:21Z

 File: **Required**

-|  Field Name | Required | Details |
+|  Field Name | Required & Type | Details |


I would separate "Type" into it's own column. GTFS-realtime has:

Field Name Type Required Cardinality Description

For example:
https://github.com/google/transit/blob/master/gtfs-realtime/spec/en/reference.md#message-feedmessage

But we don't need "Cardinality" here

antrim

LGTM. I left a few suggestions and comments.

antrim · 2018-09-13T16:22:41Z

+- **Longitude** - The field contains the WGS84 longitude as a a floating point number. The value must be geater than or equal to -180.0 and less than or equal to 180.0. For example: "12.492269" for the Colloseum in Roma.
+- **Service Date** - The field contains the service date in the YYYYMMDD format. Since service time within a service date can be above 24:00:00, a service date often contains information for the subsequent day(s). E.g "20180913" for September 13th, 2018.
+- **Service Time** - The field contains the service time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. For example: "14:30:00" for 2:30PM or "25:35:00" for 1:35AM on the next date.
+- **Text string** - The field contains a string of UTF-8 characters, which is aimed to be displayed to the rider and which must therefore be human readable.


…which is aimed to be displayed to the rider and which must therefore be human readable.

Should we remove that last clause?
stop_desc, route_desc, and feed_version would all be text fields (I think) but are not necessarily intended to be displayed to the rider. Well, actually stop_desc, route_desc have an ambiguous purpose.

feed_version is a stretch I agree. I can remove it.

But description field are often used to be shown to the rider.

antrim · 2018-09-13T18:56:48Z

+- **Non-negative Float** - The field contains a non-negative floating point number (which includes 0).
+- **Non-negative Integer** - The field contains a non-negative whole number (which includes 0).
+- **Phone number** - The field contains a phone number.
+- **Service Date** - The field contains the service date in the YYYYMMDD format. Since service time within a service date can be above 24:00:00, a service date often contains information for the subsequent day(s). E.g "20180913" for September 13th, 2018.


I suggest changing the order of these sentences and a few other language times.

The field contains the service date in the YYYYMMDD format. E.g "20180913" for September 13th, 2018. Because service times can be past 24:00:00, a service date may include transit operations on the subsequent real calendar day(s).

Yeah... I agree.

antrim · 2018-09-13T18:59:03Z

+- **Non-negative Integer** - The field contains a non-negative whole number (which includes 0).
+- **Phone number** - The field contains a phone number.
+- **Service Date** - The field contains the service date in the YYYYMMDD format. Since service time within a service date can be above 24:00:00, a service date often contains information for the subsequent day(s). E.g "20180913" for September 13th, 2018.
+- **Service Time** - The field contains the service time in the HH:MM:SS format (H:MM:SS is also accepted). The time is measured from "noon minus 12h" of the service day (effectively midnight except for days on which daylight savings time changes occur). For times occurring after midnight, enter the time as a value greater than 24:00:00 in HH:MM:SS local time for the day on which the trip schedule begins. For example: "14:30:00" for 2:30PM or "25:35:00" for 1:35AM on the next date.


This introduces a new term -- "Service Time". I just want to check that everyone is good with this. I think I'd rather just use "Time", because I think that all time fields in GTFS match this definition. I understand what "Service Time" means, but I think it is possible that adding "Service" might add potential for confusion rather than add clarity.

Oh ok. But I'm using it with service date, to show that those are not usual date & time. So if you think we should remove it there, then I would advocate to also remove it in service date.

antrim · 2018-09-13T19:04:27Z

+- **Language Code** - The field contains a IETF BCP 47 language code. For an introduction to IETF BCP 47, please refer to http://www.rfc-editor.org/rfc/bcp/bcp47.txt and http://www.w3.org/International/articles/language-tags/. For example: "en" for English, "en-US" for American English or "de" for German.
+- **Latitude** - The field contains the WGS84 latitude in decimal degrees. The value must be greater than or equal to -90.0 and less than or equal to 90.0. For example: "41.890169" for the Colloseum in Roma.
+- **Longitude** - The field contains the WGS84 longitude in decimal degrees. The value must be geater than or equal to -180.0 and less than or equal to 180.0. For example: "12.492269" for the Colloseum in Roma.
+- **Non-negative Float** - The field contains a non-negative floating point number (which includes 0).


How about adding "decimal" for people who don't immediately know what "floating point" means.

"The field contains a non-negative floating point number (i.e. allowing decimals), which includes 0."

I also do not find "floating point number" obvious. But I don't know how to be clear on this one.

I think this works - The field contains a non-negative floating point (i.e., decimal) number, which includes 0.

antrim · 2018-09-13T19:05:46Z

+- **Latitude** - The field contains the WGS84 latitude in decimal degrees. The value must be greater than or equal to -90.0 and less than or equal to 90.0. For example: "41.890169" for the Colloseum in Roma.
+- **Longitude** - The field contains the WGS84 longitude in decimal degrees. The value must be geater than or equal to -180.0 and less than or equal to 180.0. For example: "12.492269" for the Colloseum in Roma.
+- **Non-negative Float** - The field contains a non-negative floating point number (which includes 0).
+- **Non-negative Integer** - The field contains a non-negative whole number (which includes 0).


If the previous change is accepted, then I suggest replacing the parens with a comma for consistency.

Non-negative Integer - The field contains a non-negative whole number, which includes 0.

LeoFrachet · 2018-09-13T19:39:40Z

The definition of float is still under discussion, but I would advocate to still open this PR on the official repo. the discussion can continue there.

LeoFrachet · 2018-09-13T19:53:41Z

Move to google#104

# This is the 1st commit message: add tripupdate clarification # This is the commit message #2: fixed formatting # This is the commit message #3: Clarify detour description in service alerts Updated detour description for clarity. # This is the commit message #4: Clarify DETOUR effect description in reference.md Updated the description of the DETOUR effect to clarify that it refers to stops not being served. # This is the commit message #5: better detour definition

Evan Howington and others added 7 commits September 7, 2018 10:13

Added field designations, data types

21bc280

same as previous, removed sample addition of "primary key" to agency_id

c5bf81c

Revert "Added field designations, data types"

6db7096

This reverts commit 21bc280.

added language data type

4472829

Updated text string, enum, time, hexadecimal number, and language

aaf3c32

Update field types definitions

5fb42c3

Fix typo

c3cf788

LeoFrachet requested review from antrim, barbeau and ehowington September 13, 2018 14:55

barbeau reviewed Sep 13, 2018

View reviewed changes

Comment thread gtfs/spec/en/reference.md

antrim mentioned this pull request Sep 13, 2018

Add definitions of field types #1

Closed

Update as per @barbeau review

fbaa669

Léo Frachet added 2 commits September 13, 2018 14:18

Improving field type as per @barbeau review (2)

d2ddd86

Add email and non-negative float types

70d1eae

Add phone number and use types for agency, stops and routes

977365c

barbeau reviewed Sep 13, 2018

View reviewed changes

Add type for all the field and improve formatting

93cd79f

Léo Frachet added 5 commits September 13, 2018 14:52

Fix formatting

c58b3a7

ditto

9f592df

ditto

ab6644a

Revert collumn

984750f

Reduce the number of column in stops

d631678

antrim suggested changes Sep 13, 2018

View reviewed changes

Léo Frachet added 11 commits September 13, 2018 15:08

Remove the two extra column in stops

3cf1eb6

Replace starts by dots

ad78556

Update type formatting for stops

7223cae

Add type column for trips

8c309d7

Update stop times and fix issues

318ad85

Fix typo

0853c51

Update calendar and calendar dates

e1ce7a5

Add type column for fares_*

90fd3f0

Add column type for frequency and shapes

246aa6d

Add type column for transfer and feed info

dad473b

fix typos

445a575

Fix bold on required

c55ac24

barbeau reviewed Sep 13, 2018

View reviewed changes

Comment thread gtfs/spec/en/reference.md Outdated

Rome not Roma

c9e7bc8

LeoFrachet closed this Sep 13, 2018


		## Field Types

		- Ad-hoc - Please see the detail column of the field for the definition of the field type.

Uh oh!

Conversation

LeoFrachet commented Sep 13, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

barbeau Sep 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

barbeau Sep 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeoFrachet Sep 13, 2018 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

barbeau commented Sep 13, 2018

Uh oh!

LeoFrachet commented Sep 13, 2018

Uh oh!

LeoFrachet commented Sep 13, 2018

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

barbeau Sep 13, 2018 •

edited

Loading

barbeau Sep 13, 2018 •

edited

Loading

LeoFrachet Sep 13, 2018 •

edited

Loading