diff --git a/data/presets/README.md b/data/presets/README.md
index 98bd7240b..6896848b9 100644
--- a/data/presets/README.md
+++ b/data/presets/README.md
@@ -1,15 +1,15 @@
## Presets
-iD uses a simple presets system based on [JSON](http://en.wikipedia.org/wiki/JSON)
-preset definitions and simple structure.
+iD editor preset and field types are defined in [JSON](http://en.wikipedia.org/wiki/JSON)
+files located under the `data/presets` folder of the iD repository.
-## Individual Presets
+#### Preset Files
-Specific presets are located under `data/presets/presets`. They're organized in a
-directory hierarchy based on OSM key/value pairs. For example, the preset that matches
+Presets are defined in JSON files located under `data/presets/presets`. They're organized in a
+directory hierarchy based on OSM key/value pairs. For example, the preset that matches
the tag `leisure=park` is in the file `data/presets/presets/leisure/park.json`.
-## Preset Format
+#### Preset Schema
A basic preset is of the form:
@@ -23,8 +23,7 @@ A basic preset is of the form:
],
// The geometry types for which this preset is valid.
// options are point, area, line, and vertex.
- // vertexes are points that are parts of lines, like the nodes
- // in a road
+ // vertexes 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"
@@ -47,8 +46,12 @@ A basic preset is of the form:
"name": "Park"
}
```
+The complete JSON schema for presets can be found in [`data/presets/schema/preset.json`](data/presets/schema/preset.json)
-#### Searchable
+
+#### Preset Properties
+
+##### searchable
Deprecated or generic presets can include the property `"searchable": false`.
This means that they will be recognized by iD when editing existing data,
@@ -60,40 +63,158 @@ By convention, unsearchable presets have filenames that begin with an underscore
## Fields
-Fields are, like presets, defined in JSON structures. A typical field is
+Fields are reusable form elements that can be associated with presets.
+
+#### Field Files
+
+Fields are defined in JSON files located under `data/presets/fields`.
+
+The field files are typically named according to their associated OSM key.
+For example, the field for the tag `access=*` is stored in the file
+`data/presets/fields/access.json`. Note that there are exceptions to this rule
+for fields that might work differently depending on which preset is active
+(`access_simple.json`, `access_toilets.json`).
+
+Some keys in OSM are namespaced using colons (':'). Namespaced fields
+are nested in folders according to their tag.
+For example, the field for the tag `piste:difficulty=*` is stored in the file
+`data/presets/fields/piste/difficulty.json`.
+
+
+#### Field Schema
```js
{
- "key": "access",
- "type": "combo"
+ "key": "cuisine",
+ "type": "combo",
+ "label": "Cuisine"
+}
+```
+The complete JSON schema for fields can be found in [`data/presets/schema/field.json`](data/presets/schema/field.json)
+
+
+#### Field Types
+
+**Text fields**
+* `text` - Basic single line text field
+* `number` - Text field with up/down buttons for entering numbers (e.g. `width=*`)
+* `localized` - Text field with localization abilities (e.g. `name=*`, `name:es=*`, etc.)
+* `tel` - Text field for entering phone numbers (localized for editing location)
+* `email` - Text field for entering email addresses
+* `url` - Text field for entering URLs
+* `textarea` - Multi-line text area (e.g. `description=*`)
+
+**Combo/Dropdown fields**
+* `combo` - Dropdown field for picking one option out of many (e.g. `surface=*`)
+* `typeCombo` - Dropdown field picking a specific type from a generic category key
+(e.g. `waterway=*`. If unset, tag will be `waterway=yes`, but dropdown contains options like `stream`, `ditch`, `river`)
+* `multiCombo` - Dropdown field for adding `yes` values to a common multikey
+(e.g. `recycling:*` -> `recycling:glass=yes`, `recycling:paper=yes`, etc.)
+* `networkCombo` - Dropdown field that helps users pick a route `network` tag (localized for editing location)
+
+**Checkboxes**
+* `check` - 3-state checkbox: `yes`, `no`, unknown (no tag)
+* `defaultcheck` - 2-state checkbox where checked produces `yes` and unchecked produces no tag
+
+**Radio Buttons**
+* `radio` - Multiple choice radio button field
+
+**Special**
+* `access` - Block of dropdowns for defining the `access=*` tags on a highway
+* `address` - Block of text and dropdown fields for entering address information (localized for editing location)
+* `cycleway` - Block of dropdowns for adding `cycleway:left` and `cycleway:right` tags on a highway
+* `maxspeed` - Numeric text field for speed and dropdown for "mph/kph"
+* `restrictions` - Graphical field for editing turn restrictions
+* `wikipedia` - Block of fields for selecting a wiki language and wikipedia page
+
+
+#### Field Properties
+
+##### `key`/`keys`
+
+The `key` property names the OSM key that the field will edit.
+Compound fields like `address` expect an array of keys in the `keys` property.
+
+##### `universal`
+
+If a field definition contains the property `"universal": true`, this field will
+appear in the "Add Field" list for all presets
+
+##### `geometry`
+
+If specified, only show the field for this kind of geometry. Should contain
+one of `point`, `vertex`, `line`, `area`.
+
+##### `default`
+
+The default value for the field. For exmaple, the `building_area.json` field
+will automatically add the tag `building=yes` to certain presets that are
+associated with building features (but only if drawn as a closed area).
+
+```js
+{
+ "key": "building",
+ "type": "combo",
+ "default": "yes",
+ "geometry": "area",
+ "label": "Building"
}
```
-In which `type` is the fields's type. Valid field types are
+##### `options`
-* textarea
-* radio
-* combo
-* address
-* check - a tri-state checkbox: yes, no, or unknown (no tag)
-* defaultcheck - a boolean checkbox where checked produces a `*=yes` tag and
- unchecked produces no tag
+Combo field types can provide dropdown values in an `options` array.
+The user can pick from any of the options, or type their own value.
-The `key` property names the OSM key that the field will edit. Alternatively, for
-compound fields like `address`, you can specify an array of keys in the `keys`
-property.
+```js
+{
+ "key": "diaper",
+ "type": "combo",
+ "label": "Diaper Changing Available",
+ "options": ["yes", "no", "room", "1", "2", "3", "4", "5"]
+}
+```
+
+##### `strings`
+
+Combo field types can accept name-value pairs in the `strings` property.
+This is helpful when the field has a fixed number of options and you want to be
+able to provide a translateable description of each option. When using `strings`,
+the user can not type their own value, they must choose one of the given values.
+```js
+{
+ "key": "smoothness",
+ "type": "combo",
+ "label": "Smoothness",
+ "placeholder": "Thin Rollers, Wheels, Off-Road...",
+ "strings": {
+ "options": {
+ "excellent": "Thin Rollers: rollerblade, skateboard",
+ "good": "Thin Wheels: racing bike",
+ "intermediate": "Wheels: city bike, wheelchair, scooter",
+ "bad": "Robust Wheels: trekking bike, car, rickshaw",
+ "very_bad": "High Clearance: light duty off-road vehicle",
+ "horrible": "Off-Road: heavy duty off-road vehicle",
+ "very_horrible": "Specialized off-road: tractor, ATV",
+ "impassable": "Impassable / No wheeled vehicle"
+ }
+ }
+}
+```
+
+If a combo field does not specify `options` or `strings`, the field will fetch
+common tag values from the Taginfo service to use as dropdown values.
-Each field definition lives in a separate file in `data/presets/fields`. The field
-name (used in the preset `fields` property) is the name of the file (minus the `.json`
-extension).
## Icons
Preset icons in iD are pulled from the open source map icon set,
[Maki](http://www.mapbox.com/maki/).
-The icons are identified in iD by the same name as they are on the Maki home. Use those
+
+The icons are identified in iD by the same name as they are on the Maki home. Use those
names when identifying the icon to be used for a given preset.
+
## Building
To build presets, all you need to do is run `make`.
@@ -101,6 +222,7 @@ To build presets, all you need to do is run `make`.
This command will take care of running the build script, which packages all presets
into one file: `dist/presets.js`, which is included in the packaged iD.js file.
+
## Custom Presets
iD supports deployments which use a custom set of presets. You can supply presets via
diff --git a/data/presets/schema/field.json b/data/presets/schema/field.json
index 660fec199..4d04b714f 100644
--- a/data/presets/schema/field.json
+++ b/data/presets/schema/field.json
@@ -54,20 +54,21 @@
"combo",
"cycleway",
"defaultcheck",
- "text",
+ "email",
+ "lanes",
+ "localized",
"maxspeed",
"multiCombo",
+ "networkCombo",
"number",
- "tel",
- "email",
- "url",
"radio",
- "textarea",
- "localized",
- "wikipedia",
- "typeCombo",
"restrictions",
- "lanes"
+ "tel",
+ "textarea",
+ "text",
+ "typeCombo",
+ "url",
+ "wikipedia"
],
"required": true
},