How to Contribute

The two central parts of the tagging schema are: The presets which essentially describes OpenStreetMap's primary tags, and the fields which represent additional property tags an individual features can have. In this repository, these are found in the respective sub-directories of the data directory.

A simple preset looks like this:

{
    // Display name for this feature type in American English
    "name": "Produce Stand",
    // Aliases are synonyms of the preset's name - this is for alternative
    // names a preset might also be known as
    "aliases": [
        "Farm Shop",
        "Farm Stand"
    ]
    // Terms are additional search terms for the preset - these are added to
    // fuel the search functionality. searching for 'vegetables' will bring
    // up this 'farm shop' preset
    "terms": [
        "fresh food",
        "fruits",
        "greengrocer",
        "orchard",
        "organics",
        "vegetables"
    ],
    // Tags that are added to the feature when selecting the preset,
    // and also used to match the preset against existing features.
    "tags": {
        "shop": "farm"
    },
    // The geometry types for which this preset is valid.
    // options are point, area, line, and vertex.
    // vertices are points that are parts of lines, like the nodes in a road
    // lines are unclosed ways, and areas are closed ways
    "geometry": [
        "point", "area"
    ]
    // The icon in iD which represents this feature.
    "icon": "maki-shop",
    // The names of fields that will appear by default in the editor sidebar.
    "fields": [
        "{shop}",
        "organic"
    ],
    // The names of fields that the user can add manually. These will also
    // appear if the corresponding tags are present.
    "moreFields": [
        "produce"
    ]
}

And a field can be as simple as:

{
    // The label of the attribute field.
    "label": "Produce",
    // The type of the field. There are many different field types
    // available. e.g. "text", "check", "radio", "combo", etc.
    "type": "semiCombo",
    // The key of the tag this field is representing 
    "key": "produce",
}

All available parameters and options are documented on the schema-builder readme page.

Creating new Presets or Fields

To create a new preset or field, just create a new JSON file (or files) in the respective sub-directory of the data directory. The file name should match the tag the field or preset. Sub-directories are used to sort the presets: They should be placed in a directory matching the primary tag key (e.g. the preset for highway=service should be the service.json file in a directory called highway), and presets which are further refining a generic preset by using additional tags, these should be nested by one additional layer of directories (e.g. the preset for highway=service + service=driveway should be created as highway/service/driveway.json). Similarly, fields for tag which contain a : should use sub-directories to group them together (e.g. the field for the roof:colour tag should be placed as colour.json inside the directory roof).

Most of the time it is easiest to start by copying a preset or field which is similar to the new preset or field you want to create, and just amend the tag, name/label and other properties accordingly.

Creating Regional Presets and Fields

{
    "key": "expressway",
    "type": "check",
    "label": "Expressway",
    "locationSet": {
        "include": [
            "US"
        ]
    }
}

Regional presets use the locationSet property to specify in which region a specific preset or field should be available. The possible values for the location options can be explored on the web page ideditor.codes. Regional presets and fields should use a suffix in their file name to distinguish them from regular presets/fields: e.g. a regional field for the crossing:markings tag for Bulgaria (country code BG) should be created as crossing/markings-BG.json.

When creating a regional variant of a preset or field, the newly introduced regions should be excluded from the global version of the respective preset or field, because otherwise both the generic/global and the regional versions of the presets would be offered for the same tag. The same is also the case for new regional fields, which need also to be included as an additional value in the list of fields (or moreFields) of all presets which are using this field.

If possible, regional presets and fields should make use of the possibility to cross-reference strings from the generic preset they are based on. That way, the regional presets don't needlessly introduce new text which need to be re-translated into all languages. Similarly, regional presets can use the possibility to cross-reference fields from their base preset to reduce duplication of information.