This file lines out the rules and reasoning behind the layout of the currently generated Repository.
The current specification is considered the Version 0.1.0 and is separately specified from the YAML file versions.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.
---
title: Folder relationships
---
erDiagram
LAT_LON ||--o{ RELATION : contains
LAT_LON ||--o{ WAY : contains
LAT_LON ||--o{ NODE : contains
NODE {
OptionalString file_generator "The tool which has generated the file originally"
string file_version "The version of the file format of this file"
OptionalString legacy_object_version "The object revision from the old system"
f64 lat "Latitude of the node"
f64 lon "Longitude of the node"
MapStringString tags "A key-value pair of tags for the way itself"
}
RELATION ||--o{ WAY : contains
RELATION ||--o{ NODE : contains
RELATION {
OptionalString file_generator "The tool which has generated the file originally"
string file_version "The version of the file format of this file"
OptionalString legacy_object_version "The object revision from the old system"
object[] members "The members of the relation"
MapStringString tags "A key-value pair of tags for the relation itself"
}
WAY ||--o{ NODE : contains
WAY {
OptionalString file_generator "The tool which has generated the file originally"
string file_version "The version of the file format of this file"
OptionalString legacy_object_version "The object revision from the old system"
object[] nodes "The nodes of the way"
MapStringString tags "A key-value pair of tags for the way itself"
}
Please note that the YAML definition is not documented in this document. It only contains loose references to the YAML files for understanding. It is not checked for validity of the YAML examples given.
As visible in the diagram above, the entry point MUST be a folder defined by the Lat and Lon. This LatLon pair is defined to be a folder structure over all of the possible LatLon combinations and SHOULD chunk the world into folders of relatively even size.
The LatLong SHOULD be defined to be the digits before the dot. Since we deal however with folders, we MUST be keeping them in positive numbers at any given time. Therefore, the coordinates MUST be in WGS84 format shifted upwards by 180 and 90 respectively. This means that the coordinate Longitudes go from 0-360 and Latitudes go from 0-180. This way they can easily be converted back by other tools and they are valid folder names.
Additionally, the coordinates MUST be separated by an underscore for readability.
As an example, the LatLon folder for -180 and -90 would be "000_000" and the folder for -179 and -89 shall be "001_001".
The coordinates in the folder name MUST be 3 digit wide at all times.
Relations MUST always be within the LAT_LON folder they are part in.
If a relation is in multiple of said chunks, the original files SHOULD be within the chunk with the smallest number and MUST be symlinked to all others affected chunks.
A Relation folder MUST contain only the member nodes or ways.
If a Node is within a Relation it MUST NOT be in the chunks directly but only within the Relation.
A Relation MUST NOT be part of a way or node itself.
For metadata, a relation MUST have a metadata.yaml file containing its metadata
within the folder. Node IDs within the YAML are OPTIONAL.
If a Relation references a Node previously already being part of another way or relation the new relation is RECOMMENDED to contain only a symlink and not a new file.
Ways MUST only be part of a relation or a LAT_LON Chunk. They MUST NOT be part of a way or a node.
If a Way is part of a relation, the relation MUST NOT contain a symlink to the way's nodes unless there is a direct reference to that node.
Ways in turn of the first definition MUST only contain nodes and MUST additionally
contain a metadata.yaml used for defining the additional metadata of said way.
Nodes MAY be part of any of the above 3 folder types. They MUST however follow all the prior rules.
A Node MUST be a YAML file of the format <Node ID>.yaml which MUST follow the
current YAML metadata file specification. However, it MAY only be updated when a
given node was updated by a user. This means as an implication that a node MAY
not have the most recent format when reading. This is meant to reduce the amount
of needed commits on a version update of the YAML file. A software MAY however
choose to update them gradually over time. This is allowed so that necessary format
updates can be updated quickly. However, this MUST be used with caution since it will
increase the repository size dramatically if done careless.