Skip to content

Item Property Reference

Jump to bottom Edit New page
Bryan Housel edited this page Mar 19, 2021 · 25 revisions

Each category file contains an Array of items that belong to that catetory.

Items can either be normal items or template items.

Normal items

"items": [
  …
  {
    "displayName": "McDonald's",
    "id": "mcdonalds-658eea",
    "locationSet": {"include": ["001"]},
    "tags": {
      "amenity": "fast_food",
      "brand": "McDonald's",
      "brand:wikidata": "Q38076",
      "brand:wikipedia": "en:McDonald's",
      "cuisine": "burger",
      "name": "McDonald's"
    }
  },
  …

"Normal" item properties:

displayName

Required yes
Type String
Example "McDonald's"

The displayName can contain anything, but it should be a short text appropriate for display in lists or as preset names in editor software. This is different from the OpenStreetMap name tag.

The displayName should be written in the local language of the item.

displayName must be unique within a category.

By convention, if you need to disambiguate between multiple brands with the same name, we add text in parenthesis. Here there are 2 items named "Target", but they have been assigned different display names to tell them apart.

In brands/shop/department_store.json:

"items": [
  …
  {
    "displayName": "Target (Australia)",
    "id": "target-c93bbd",
    "locationSet": {"include": ["au"]},
    "tags": {
      "brand": "Target",
      "brand:wikidata": "Q7685854",
      "brand:wikipedia": "en:Target Australia",
      "name": "Target",
      "shop": "department_store"
    }
  },
  {
    "displayName": "Target (USA)",
    "id": "target-592fe0",
    "locationSet": {"include": ["us"]},
    "tags": {
      "brand": "Target",
      "brand:wikidata": "Q1046951",
      "brand:wikipedia": "en:Target Corporation",
      "name": "Target",
      "shop": "department_store"
    }
  },
  …

id

Required no (generated automatically)
Type String
Example "mcdonalds-658eea"

Each item has a unique id generated for it. When adding a new item, you don't need to add an id. The next time npm run build is run, the id will be generated automatically.

The identifiers are stable unless the name, key, value, or locationSet change.

locationSet

Required yes
Type Object {}

Each item requires a locationSet to define where the item is available. You can define the locationSet as an Object with include and exclude properties:

"locationSet": {
  "include": [ Array of locations ],
  "exclude": [ Array of locations ]
}

The "locations" can be any of the following:

👉 locationSet Tips:

matchNames, matchTags

Required no
Type Array[Strings]

Brands are often tagged inconsistently in OpenStreetMap. For example, some mappers write "International House of Pancakes" and others write "IHOP".

This project includes a "fuzzy" matcher that can match alternate names and tags to a single entry in the name-suggestion-index. The matcher keeps duplicate items out of the index and is used in the iD editor to help suggest tag improvements.

matchNames and matchTags properties can be used to list the less-preferred alternatives.

"properties": {
  "path": "brands/amenity/fast_food"      // all items in this file will match the tag `amenity=fast_food`
  …
},
"items": [
  …
  {
    "displayName": "Honey Baked Ham",
    "id": "honeybakedham-4d2ff4",
    "locationSet": { "include": ["us"] },
    "matchNames": ["honey baked ham company"],    // also match these less-preferred names
    "matchTags": ["shop/butcher", "shop/deli"],   // also match these less-preferred tags
    "tags": {
      "alt_name": "HoneyBaked Ham",                    // match `alt_name`
      "amenity": "fast_food",
      "brand": "Honey Baked Ham",                      // match `brand`
      "brand:wikidata": "Q5893363",
      "brand:wikipedia": "en:The Honey Baked Ham Company",
      "cuisine": "american",
      "name": "Honey Baked Ham",                       // match `name`
      "official_name": "The Honey Baked Ham Company"   // match `official_name`
    }
  },
  …

The matcher code also has some useful automatic behaviors…

You don't need to add matchNames for:

  • variations in capitalization, punctuation, spacing (the middots common in Japanese names count as punctuation, so "V・ドラッグ" already matches "vドラッグ")
  • variations that already appear in the name, brand, operator, network.
  • variations that already appear in an alternate name tag (e.g. alt_name, short_name, official_name, etc.)
  • variations that already appear in any international version of those tags (e.g. name:en, official_name:ja, etc.)
  • variations in diacritic marks (e.g. "Häagen-Dazs" already matches "Haagen-Dazs")
  • variations in & vs. and

You don't need to add matchTags for:

  • Tags assigned to match groups (defined in config/matchGroups.json). For example, you don't need add matchTags: ["shop/doityourself"] to every "shop/hardware" and vice versa. Tags in a match group will automatically match any other tags in the same match group.

👉 Bonus: The build script will automatically remove extra matchNames and matchTags that are unnecessary.

preserveTags

Required no
Type Array[Regex Strings]
Example ["^name"]

For tags matching these regular expressions, values in NSI should not replace an existing value in OSM.

By default, all of the tags as they appear in NSI are how they should appear on an OSM feature. Validator software (such as built into iD) can suggest updates to OSM by comparing an OSM feature's tags against NSI's tags.

In some situations, we want to leave an existing OSM tag value alone. preserveTags contains an Array of regular expressions to match OSM keys where we want to preserve any existing tag value and never suggest a replacement.


The preserveTags property can be set per-category (applying to all items in a category) or per-item.

preserveTags is useful for tags such as "^name" (key starts with "name"), on items where the name tag is expected to be unique:

  • Apple Store ("Apple Bridgewater")

See also issue #4906

note

Required no
Type String

You can optionally add a note property to any item. The note can contain any text useful for maintaining the index - for example, information about the brand's status, or a link to a GitHub issue.

The notes just stay with the name-suggestion-index; they aren't OpenStreetMap tags or used by other software.

{
  "displayName": "United Bank (Connecticut)",
  "id": "unitedbank-28419b",
  "locationSet": { "include": ["peoples_united_bank_ct.geojson"] },
  "note": "Merged into People's United Bank (Q7165802) in 2019, see https://en.wikipedia.org/wiki/United_Financial_Bancorp",
  "tags": { … }
}

tags

Required yes
Type Object {}

Each item requires a tags value. This is just an Object containing all the OpenStreetMap tags that should be set on the feature.

Add a custom footer

Home

For Contributors

Contributing to the index

Advanced Topics

For Developers

Information for developers using the name-suggestion-index in another project.

For Maintainers

Information for maintainers, including how to clone and build the project.

 

Clone this wiki locally