Skip to content

Latest commit

 

History

History
531 lines (450 loc) · 15 KB

1.0.md

File metadata and controls

531 lines (450 loc) · 15 KB

H2Geo Specification

H2Geo is the standard meant to represent OSM data models

version: 1.0

Structure

The base yml structure of a preset is the following:

name: # Mandatory field, internationalized
version: # Mandatory field
author: # Mandatory field
lastUpdate: # Mandatory field, set automatically
description: # Mandatory field, internationalized
offlineArea: # Optional field: a set of bounding boxes (for implementations compatible with offline areas)
image: # Optional field: an image which represents your preset
groups: # Mandatory field: a set of group of data types inside your preset
schema: "1.0" # Current schema version. Mandatory

$.name

The name of your preset. Must be a set of key/value entries, key being the language, value being the name in the specified language. Warning: the preset must have an entry with the key 'default' Example:

name:
 default: "My preset" # This 'default' entry is mandatory
 fr: "Mon preset"
 en: "My preset"
 es: "Mi preset"

$.version

The version of your preset. Can be any string value. Example:

version: 1.0.0-RC1

$.author

The author of your preset. Can be any string value. Example:

author: Loïc Ortola

$.description

The description of your preset. Must be a set of key/value entries, key being the language, value being the name in the specified language. Warning: the preset must have an entry with the key 'default' Example:

description:
 default: "This preset is awesome" # This 'default' entry is mandatory
 fr: "Ce preset est trop cool"
 en: "This preset is awesome"
 es: "Este preset es impresionante"

$.offlineArea

The offlineArea represents a set of bounding boxes which may be fetched automatically by a client. This is useful for presets made for specific regions (Velib Stations of Paris for instance). NB: this entry is optional. Warning: the syntax of a bounding box is an array of latitude / longitude values in the following order: [west, south, east, north] Example:

offlineArea:
 - [2.318866,48.854833,2.349637,48.866211] # tuileries / louvre
 - [2.225740,48.884614,2.256510,48.895985] # la defense
 - [2.305884,48.832803,2.336655,48.844186] # montparnasse

$.image

An image representing your preset. This field is optional. It should look like a banner image.

N.B.: All images and icons will be using the same data model as specified below:

Supported image formats are: svg, png, jpg.

Icons can be declared in three different ways:

1. Using a valid remote URL

Example:

 image: https://image.freepik.com/free-icon/pharmacy--emergency_318-33252.jpg

2. Using an icon from one of the available standard OSM icon repositories: OpenStreetMap Carto (official), Osmic, OSM Icons

Those three will be declared using the 3 following URIs: carto://, osmic://, osm-icons://

3. Using a provided icon

All provided icons should be provided in a resources/name_of_your_preset directory and use the res:// URI prefix.

Example: For an icon named my-preset-background.png, you would type

 image: res://my-preset-background.png

The preset tree would look like this: |- mypreset.json |- resources/ | | | - mypreset/ | | | - my-preset-background.png

4. i18n

Sometimes, you may have different icons for different languages. In that case, you can internationalize the icon field like you would for regular strings.

Example:

 image:
   default: res://my-model-icon_en.svg
   fr: res://my-model-icon_fr.svg
   en: res://my-model-icon_en.svg

$.groups

The main field where all your preset structure will be detailed. This field is mandatory. The data field is a set of groups. Example:

groups:
 - name: # This will be your first group of items
   icon:
   url:
   items:
 - name: # This will be your second group of items
   icon:
   url:
   items:
 #...

$.groups.$

A group represents a set of items <=> data types. For instance, imagine a group named "Emergencies" containing the following items: Police Station, Defibrillator, Fire Station, Hospital, etc... Every preset requires to have at least one group.

The structure of a group is the following:

- name: # This field is mandatory and internationalized
  icon: # This field is optional
  url: # This field is optional
  items: # This field is mandatory

$.groups.$.name

The name of your group. Must be a set of key/value entries, key being the language, value being the group name in the specified language. This field is mandatory. Warning: the group name must have an entry with the key 'default' Example:

 groups:
  - name:
   default: "Emergencies" # This 'default' entry is mandatory
   fr: "Urgences"
   en: "Emergencies"
   es: "Emergencia"

$.groups.$.icon

The icon representing your group. This field is optional. The same image specification model is applied as in $.image

Example : Using the OpenStreetMap Carto icon advertising/column.svg

 - icon: carto://advertising/column

Example : Using the OSMic icon barrier/gate-14.svg

 image: osmic://barrier/gate-14

Example : Using the OSM Icons icon 29001

 image: osm-icons://29001

$.groups.$.url

A url pointing to the specification of the current group. This field is optional.

$.groups.$.items

A set of items, each representing a specific data type. This field is mandatory.

The structure of an item is the following:

    - name: # This field is mandatory
      url: # This field is optional
      icon: # This field is optional
      query: # This field is optional
      label: # This field is mandatory and internationalized
      description: # This field is mandatory and internationalized
      keywords: # This field is mandatory and internationalized
      tags: # This field is mandatory
      constraints: # This field is optional

$.groups.$.items.$.name

The name of your item. This field is mandatory. Warning: the item name must have an entry with the key 'default' Example:

 items:
  - name: amenity=Police station

$.groups.$.items.$.url

A url pointing to the specification of the current item. This field is optional.

$.groups.$.items.$.icon

The icon representing your item. This field is optional. The same image specification model is applied as in $.groups.$.icon

$.groups.$.items.$.query

The overpass query allowing to fetch the current item. This field is optional.

$.groups.$.items.$.label

The label of your item. Must be a set of key/value entries, key being the language, value being the group name in the specified language. This field is mandatory. The label is usally displayed in place of the name. Warning: the item label must have an entry with the key 'default' Example:

 items:
  - label:
   default: "Police station"" # This 'default' entry is mandatory
   fr: "Poste de police"
   en: "Police station"
   es: "Estación de policía"

$.groups.$.items.$.description

The description of your item. Must be a set of key/value entries, key being the language, value being the name in the specified language. Warning: the item descripton must have an entry with the key 'default' Example:

items:
  - description:
   default: "This item is awesome" # This 'default' entry is mandatory
   fr: "Cet item est trop cool"
   en: "This item is awesome"
   es: "Este item es impresionante"

$.groups.$.items.$.keywords

A list a words in association with the item but not necessarily directly linked to the name or to the label. Example:

items:
  - name:
    default: "Police station"
    fr: "Poste de police"
    en: "Police station"
  - keywords:
    default:
      - traffic ticket
      - lawsuit
    en:
      - traffic ticket
      - lawsuit
    fr:
      - contravention
      - plainte

$.groups.$.items.$.tags

This field represents the set of tags necessary to identify the item (data type).

The structure of a tag is the following:

 - key: # This field is mandatory
   type: # This field is mandatory
   description: # This field is optional and internationalized
   statement: # This field is optional and internationalized
   value: # This field is optional and internationalized
   values: # This field is optional and internationalized
   images: # This field is optional and internationalized
   required: # This field is optional, defaults to true
   show: # This field is optional, defaults to true
   editable: # This field is optional, defaults to true
   validation: # This field is optional
   persist: # This field is optional, defaults to true

$.groups.$.items.$.tags.$.key

This field represents the OpenStreetMap key of the entry. Example:

 - key: amenity

$.groups.$.items.$.tags.$.type

This field represents the type of data represented by the tag. The value of the type is one of the following:

  • CONSTANT: a fixed known value
  • TEXT: a textual content
  • NUMBER: a number content
  • COLOR: a color. Can either be a CSS-color, a 6-hex-digit or a 3-hex-digit as specified here
  • SINGLE_CHOICE: one value among a set of options (provided). Equivalent to radio buttons
  • MULTI_CHOICE: 0, 1, or many values among a set of options (provided). Equivalent to an array of checkboxes
  • OPENING_HOURS: A set of opening hours

$.groups.$.items.$.tags.$.description

This field represents the description of the tag.

$.groups.$.items.$.tags.$.statement

This field represents the question one may ask when requesting for the tag value.

Example: For a preset named Shop and the tag amenity, we might have the following statement:

statement: What type of shop is this?

As usual, this field is also internationalizable:

statement:
  default: What type of shop is this?
  fr: Quel est le type de magasin que vous voyez ici?
  en: What type of shop is this?

$.groups.$.items.$.tags.$.value

This field should only be used when tag type is CONSTANT. This will ensure that the tag value is set.

$.groups.$.items.$.tags.$.values

This field represents either:

  • a finite set of values in case tag type is among the following: SINGLE_CHOICE or MULTI_CHOICE;
  • a set of possible most-common values in case tag type is among the following: COLOR, TEXT or NUMBER or OPENING_HOURS.

Example:

 values:
  - stands
  - wall_loops
  - rack

N.B.: Those values can also be internationalized like the following:

 values:
  - stands: Stands
  - wall_loops:
      default: Wall Loops
      fr: Cercles
      en: Wall loops
  - rack: Rack

$.groups.$.items.$.tags.$.images

This field represents a finite set of images to be used as symbological representation in complement of the previously set values. In that case, tag type is among the following: SINGLE_CHOICE or MULTI_CHOICE.

The first level keys have to be named after the values entries.

Example:

 images:
  - informal: res://bus_stop_no_sign.svg
  - pole: res://bus_stop_pole_sign.svg
  - shelter: res://bus_stop_shelter.svg

N.B.: Those values can also be internationalized like the following:

 images:
  - informal:
      default: res://bus_stop_no_sign_en.svg
      fr: res://bus_stop_no_sign_fr.svg
      en: res://bus_stop_no_sign_en.svg
  - pole:
      default: res://bus_stop_pole_sign_en.svg
      fr: res://bus_stop_pole_sign_fr.svg
      en: res://bus_stop_pole_sign_en.svg
  - shelter:
      default: res://bus_stop_shelter_en.svg
      fr: res://bus_stop_shelter_fr.svg
      en: res://bus_stop_shelter_en.svg

$.groups.$.items.$.tags.$.required

This field represents whether a tag is required or not. This field is optional, and is semantically default to true.

$.groups.$.items.$.tags.$.show

This field represents whether a tag should be shown or not in a client ui. This field is optional, and is semantically default to true.

$.groups.$.items.$.tags.$.editable

This field represents whether a tag should be editable or not in a client ui. This field is optional, and is semantically default to true.

$.groups.$.items.$.tags.$.persist

This field represents whether a tag should be persisted in the OpenStreetMap database or not. This field is optional, and is semantically default to true. When having specific tags which should not be shared with OpenStreetMap, use persist: false.

$.groups.$.items.$.tags.$.validation

This field represents a way to validate a tag. The following fields can be used:

  • regex: custom regular expression (ex: [a-zA-Z0-9] for alphanumeric)
  • format: supports two values: EMAIL or URL
  • length: fixed char length
  • minLength: minimum char length
  • maxLength: maximum char length
  • minValue: minimum number value (for NUMBER tag types only)
  • maxValue: maximum number value (for NUMBER tag types only)
  • minChoices: minimum choices selected (for MULTI_CHOICE and LEVEL tag types only)
  • maxChoices: maximum choices selected (for MULTI_CHOICE and LEVEL tag types only)

$.groups.$.items.$.constraints

This field allows to declare a set of constraints applied on an item. A constraint is aware of the item tags.

A constraint has the following structure:

- source: # This field is mandatory
  condition: # This field is mandatory
  action: # This field is mandatory

$.groups.$.items.$.constraints.$.source

This field defines the source where constraint should be operating, depending on constraint type. Today, the only available constraint type is TAG

TYPE

constraints:
 - source:
    type: TAG
    key: mytagsource

For type TAG: Constraint source is the source tag.

$.groups.$.items.$.constraints.$.condition

This field defines the conditional operation to perform on the constraint source. Two conditions are specified in this version: EXISTS, EQUALS

EXISTS

condition:
   type: EXISTS
   value: true

EQUALS

condition:
   type: EQUALS
   value: thevalueofmysource

$.groups.$.items.$.constraints.$.action

This field defines the action to perform once condition has been met. Two implementations have been specified in this version: SET_TAG_VALUE, REMOVE_TAG

SET_TAG_VALUE

action:
  type: SET_TAG_VALUE
  key: mytargettag
  value: mytargettagvalue

REMOVE_TAG

action:
  type: REMOVE_TAG
  key: mytargettag

Examples

This constraint will change 'myothertag' when 'myoptionaltag' is present

 constraints:
  - source:
      type: TAG
      key: myoptionaltag
    condition:
      type: EXISTS
      value: true
    action:
      type: SET_TAG_VALUE
      key: myothertag
      value: mytargettagvalue

This constraint will change 'myothertag' when 'mytag' value equals to 'helloworld'

 constraints:
  - source:
     -type: TAG
      key: myoptionaltag
    condition:
     - type: EQUALS
       value: helloworld
    action:
    - TYPE: SET_TAG_VALUE
      key: myothertag
      value: mytargettagvalue

This constraint will remove 'myothertag' when 'mytag' value is present

 constraints:
  - source:
      type: TAG
      key: myoptionaltag
    condition:
      type: EXISTS
      value: true
    action:
      type: REMOVE_TAG
      key: myothertag