Road Model Schema

Feedback schema definition

The Map Feedback API has its own schema. This schema includes a set of fields that apply to all feedback types. This part can be called an envelope. One of these fields, data, contains feedback-type-specific information. Because this field can follow multiple schemas, it effectively serves as an extension point. More details about the Map Feedback API schema can be found in Create feedback.

Road model feedback is modelled as a change request against the map data. The schema supports reporting a missing feature (add), a feature that exists in the data but not in reality (remove), and a change to an existing feature including its geometry (modify). Each feature type has its own set of mandatory and optional attributes per change type (see the Feature type definitions section below).

Envelope

The Map Feedback API envelope is reused as-is. Only the kind value is specific to this schema.

Schema of the data

The data field is a JSON object with a set of common fields plus a feature-specific attributes object. The attributes allowed (and mandatory) for each feature type are defined in the Feature type definitions section below.

Common fields

Value conventions

These conventions apply to attribute values across all feature types:

• Geometry — WKT with coordinates in longitude-latitude order (POINT(lon lat), LINESTRING(lon lat, lon lat, …)), consistent with the envelope.
• Time domains (opening_hours, conditional_hours, conditions) — yes or no followed by @ and a day/time span in the form <days> <from>-<to>, e.g. no @ Mo-Fr 10:00-17:00 (no access Monday–Friday 10:00–17:00), yes @ Mo-Fr 07:00-17:00 (applies Monday–Friday 07:00–17:00).
• Localized values — to give an attribute value in a specific language, use LC-SC = <value>, where LC is the language code, SC the script code, e.g. nl-Latn = Amsterdamsestraatweg.
• Multi-valued attributes (e.g. conditional, vehicle_access) — multiple values in one string, delimited by ;.
• Units — metric is the default (weights in kg, dimensions in metres, speed per unit attribute where applicable). If specifying imperial, state it explicitly in the value, e.g. 9000 lbs, 6' 7''.
• Direction — forward, backward (relative to the digitization direction of the way) or both_ways.

Feature type definitions

This section defines each value the feature field can take. For every feature type: the Add / Modify / Remove columns list the attributes that are mandatory for that change type; Optional attributes lists what else may be supplied, with constrained values where applicable. details is always mandatory (see common fields) and is not repeated below.

poi

road

speed_limit

address

Localized values follow the LC-SC = <value> convention.

street_name

Localized values follow the LC-SC = <value> convention.

barrier

oneway

truck_restriction

turn_restriction

Providing from and to featureIds is strongly recommended — it helps resolve the feedback more efficiently and accurately.

land_use

bridge_or_tunnel

administrative_area

other

Escape hatch for feature types not (yet) defined in this schema. attributes is free-form key: value; details must describe the feature and the requested change unambiguously.

Examples

1. Missing POI (add)

1
{
2
  "changeType": "add",
3
  "feature": "poi",
4
  "geometry": "POINT(-3.693252 40.399412)",
5
  "attributes": {
6
    "name": "Shell",
7
    "category": "fuel_station",
8
    "email": "shellbookham@shell.com"
9
  },
10
  "details": "Fuel station present on-site but missing from the map.",
11
  "mapVersion": "57595/1",
12
  "source": "manual-feedback",
13
  "sourceDetails": "Field survey 2026-06"
14
}

2. Missing truck restrictions (add)

1
{
2
  "changeType": "add",
3
  "feature": "truck_restriction",
4
  "geometry": "LINESTRING(-0.4335233 51.3566726, -0.4342779 51.3535401)",
5
  "attributes": {
6
    "maxlength": "15",
7
    "maxheight": "4",
8
    "maxweight": "15000",
9
    "conditional_hours": "yes @ Mo-Fr 07:00-17:00"
10
  },
11
  "details": "Missing truck restrictions along this stretch of road.",
12
  "mapVersion": "57666/1",
13
  "source": "manual-feedback",
14
  "sourceDetails": "Weybridge town web site: https://www.discoverweybridge.co.uk/"
15
}

3. Superfluous POI (remove)

1
{
2
  "changeType": "remove",
3
  "feature": "poi",
4
  "featureId": "POI:1234567",
5
  "details": "POI no longer exists in reality; business closed.",
6
  "mapVersion": "57595/1",
7
  "source": "1234",
8
  "sourceDetails": "Superfluous POI check"
9
}

4. Incorrect house number (modify)

1
{
2
  "changeType": "modify",
3
  "feature": "address",
4
  "geometry": "POINT(-0.4404627 51.3459953)",
5
  "attributes": {
6
    "housenumber": "37"
7
  },
8
  "details": "Address information incorrect at this location. Should be number 37 not 15.",
9
  "sourceDetails": "Local knowledge"
10
}

5. Add housing estate (missing)

1
{
2
  "changeType": "add",
3
  "feature": "address",
4
  "geometry": "POINT(4.899431 52.379189)",
5
  "attributes": {
6
    "housing_estate": "Riverside Gardens",
7
    "street": "Parklaan",
8
    "city": "Utrecht"
9
  },
10
  "details": "Housing estate 'Riverside Gardens' is missing from the map.",
11
  "mapVersion": "57595/1",
12
  "source": "manual-feedback"
13
}

Complete feedback (envelope + base64 data)

The data JSON is base64-encoded into the envelope, e.g. for example 1:

1
{
2
  "geometry": "POINT(-3.693252 40.399412)",
3
  "kind": "road_model_feedback",
4
  "data": "<base64 of the data JSON>",
5
  "severity": 1,
6
  "labels": ["example"],
7
  "referenceId": "12345"
8
}