ISO-8601 date strings and JSON-LD context tweaks

[hdelva]

Some small changes:

• ISO-8601 date strings where applicable
• Gave the stops endpoint its own JSON-LD context
• Added a trip identifier. Although it's not mandatory according to the LC spec, it's something route planning applications will need.

I have noticed that sometimes the arrivalTime defaults to 1970-01-01, but couldn't really track down what's causing it. Might be something to keep an eye on.

The data is now usable with the dev branch of plannerjs, if you're interested. For example:

const planner = new FlexibleTransitPlanner();
planner.addConnectionSource("http://localhost:3000/connections");
planner.addStopSource("http://localhost:3000/stops");

EventBus
    .on(EventType.Query, (Query) => {
        console.log("Query", Query);
    })
    .on(EventType.LDFetchGet, (url, duration) => {
        console.log(`[GET] ${url} (${duration}ms)`);
    })
    .on(EventType.Warning, (e) => {
        console.warn(e);
    });

planner
    .query({
        from: "http://localhost:3000/stops/900000100513",
        to: "http://localhost:3000/stops/900000100018",
        minimumDepartureTime: new Date("2019-12-19T17:12:24.217Z"),
    })
    .on("data", (path) => {
        console.log(JSON.stringify(path, null, " "));
    });

[derhuerst]

ISO-8601 date strings where applicable

What's the rationale for using ISO 8601 for e.g. the t parameter in /connections?t=…? t describes a globally unique point in time here (an instant), so why use a more complex format?

ISO 8601 strings for e.g. departure times make sense to me, because they exist in a local context.

Added a trip identifier. Although it's not mandatory according to the LC spec, it's something route planning applications will need.

Keep in mind that /trips/:id is not implemented yet by hafas-linked-connections-server.

[hdelva]

A unix timestamp (like the t parameter) could also work, but the range of lc:departureTimeQuery is defined to be an xsd:dateTime, which is consistent with ISO-8601. A client interpreting the hydra template will expect to be able to fill in the template with a dateTime string. You're right that these xsd:dateTime values are more complex than timestamps though, and technically they contain some characters that ideally should be percent-encoded. But I'm not sure if there even is a datatype for timestamps, and defining a new datatype wouldn't be great for the usability of the data.

Keep in mind that /trips/:id is not implemented yet by hafas-linked-connections-server.

That's ok, nobody's implemented that part yet.

[derhuerst]

A unix timestamp (like the t parameter) could also work, but the range of lc:departureTimeQuery is defined to be an xsd:dateTime, which is consistent with ISO-8601.

Fair enough!

Keep in mind that /trips/:id is not implemented yet by hafas-linked-connections-server.

That's ok, nobody's implemented that part yet.

HAFAS trip IDs are unstable and impractical, but are probably sufficient as long as they don't need to match the trip IDs of other endpoints. We could quickly implement /trips/:id with them via hafas.trip(tripId).

[derhuerst]

@hdelva Friendly ping, this is almost done! 🙂

[hdelva]

I promise I'll finish this next week! It's been a busy couple of weeks, and I also didn't realize this was blocked because of me, my bad.

The good news is that we should have a more flexible demo of plannerjs now, so I can also make sure everything works now.

[hdelva]

There's one other thing you should check though, the Linked Connections spec implies that departure/arrival times should include any delays already, and the arrivalDelay/departureDelay fields are there to infer the scheduled time. Does the data source model it this way as well?

[derhuerst]

There's one other thing you should check though, the Linked Connections spec implies that departure/arrival times should include any delays already [...]. Does the data source model it this way as well?

hafas-linked-connections-server currently needs a hafas-client@4 client, which works this way.

[derhuerst]

Merged as 49f3c0c and published as hafas-linked-connections-server@1.0.1. Thanks!