missing introduction to the format

[matkoniecz]

https://github.com/public-transport/friendly-public-transport-format/blob/master/README.md describes the vision, without any examples of the format itself

it links to https://github.com/public-transport/friendly-public-transport-format/blob/master/spec/readme.md that has no introduction or basic examples. It immediately starts from "In order to be able to use this format in both static data and API responses, you may chose wether to reference an item by its id or inline the item as an object." what is a minor, not so important detail.

Maybe it would be better to start from a straightforward example of a simplest possible route?

In my case I am looking for a simple format for representing train/bus/plane routes and I prefer to avoid inventing my own from scratch. But I am also uninterested in looking through entire spec to implement simple things following it.

[matkoniecz]

Now I started reading rest of documentation and it is less problematic than expected as it is quite short and uncomplicated.

But I will leave it open as first impression is quite poor (feel free to close is that is not a problem or not worth fixing).

[matkoniecz]

I just found https://github.com/public-transport/friendly-public-transport-format/blob/master/examples/valid-simple-journey.json

I think it should be more accessible (I can make a PR, ping me after processing ones that I already created)

[derhuerst]

Agree, the first impression is bad. Let's add a really basic example, e.g. the one from

friendly-public-transport-format/examples/valid-simple-journey.json

Lines 1 to 25 in a262d28

	{
	"type": "journey",
	"id": "12345",
	"legs": [{
	"origin": "10001",
	"destination": "10003",
	"departure": "2017-03-16T20:00:00+01:00",
	"departurePlatform": "4-1",
	"departureDelay": null,
	"arrival": "2017-03-17T15:00:00+02:00",
	"arrivalPlatform": "9",
	"arrivalDelay": 30,
	"schedule": "1234",
	"public": true,
	"operator": "2",
	"price": {
	"amount": 19.95,
	"currency": "EUR"
	}
	}],
	"price": {
	"amount": 19.95,
	"currency": "EUR"
	}
	}

[matkoniecz]

valid-simple-journey.json may be further simplified. departureDelay and arrivalDelay are both optional and something that may be safely dropped from simplest possible example.

I am considering further simplification, I created #55 and #56 to check is it something possible.

I will continue after resolving #55 and #56.

[derhuerst]

I think the duplicated price can be left out from the introduction. departureDelay/arrivalDelay are IMO quite important, and therefore one of them should be included.