Skip to content

Latest commit

 

History

History
409 lines (357 loc) · 11.2 KB

0.1.md

File metadata and controls

409 lines (357 loc) · 11.2 KB

h2geo-presets specification

version: 0.1.1

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

$.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.
Example:

image: 'http://static.directmatin.fr/sites/default/files/velib_frein_arriere.jpg'

$.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. Must be pointing to a valid image url. This field is optional. Example:

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

$.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
      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.$.item.$.url

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

$.groups.$.item.$.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
   value: # This field is optional
   values: # This field is optional
   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

$.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
  • 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.$.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: 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.$.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.$.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)
  • 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