Document geojson-format to create a challenge from

[pietervdvn]

Is your feature request related to a problem? Please describe.

I'm documenting how to setup a guided import with MapRoulette and MapComplete. For this, the source data to import should be converted into a geojson that can be understood by MapRoulette and which is uploaded during the 'Create a new challenge flow'.

It is clear that, when supplying points, every point will be shown as task.

However, it is not clear to me which properties are allowed in the geojson. @rlin did a great job figuring out some of the allowed properties (e.g. tags and blurb) but the precise semantixs are unclear.

Some questions I have, for example, are:

• I think that tags is a string of ;-separated values. Is this correct? What if a tag should have ; as value?
• What other properties exist?
• What happens if I set a field in the form? E.g. if I upload a file where some entries have a tags-property and I fill out the tags-field in the form, will it ignore the properties in the file or rather work as fallback value if they are not set?
• what is a blurb exactly?

Describe the solution you'd like

Ideally, learn.maproulette.org would have a page listing the possible properties and their precise semantics.

I didn't find a relevant page, despite searching around for a bit.

[pietervdvn]

Also see #1737

[mvexel]

I agree this really needs attention...

@ljdelight @jschwarz2030 do you know if it's possible to generate better swagger documentation with inline comments or should we go the route of adding a manually written page on learn.maproulette.org?

[jschwarz2030]

I believe a new page on learn.maproulette.org would be better, since swagger has been difficult to scale to our documentation needs, especially when providing details on nested data objects and data types and sufficient context for our users with a range of engineering skills.

Perhaps a good starting point would be a living document on hackmd. @pietervdvn since you're already creating a document, I can assist you if you're open to starting/managing this endeavor.

to answer a few of your initial questions,

• Tags are separated by commas and tags can contain semicolons
• other properties

checkinComment: "#maproulette"
dataOriginDate: ""
defaultBasemap: -1
defaultBasemapId: ""
defaultPriority: 0
defaultZoom: 18
description: "asdf"
difficulty: 2
enabled: true
featured: false
highPriorityRule: "{}"
instruction: "asdf"
limitReviewTags: false
limitTags: false
localGeoJSON: 
lowPriorityRule: "{}"
maxZoom: 19
mediumPriorityRule: "{}"
minZoom: 3
name: ""
overpassTargetType: null
parent: 4
presets: []
requiresLocal: false
tags: "foo,bar"
taskStyles: []

• What happens if I set a field in the form? E.g. if I upload a file where some entries have a tags-property and I fill out the tags-field in the form, will it ignore the properties in the file or rather work as fallback value if they are not set?
  I searched for a bit on this in the code and i don't see tags getting set on tasks during challenge/task creation. only when a task is mapped or reviewed. I could be wrong though.

• what is a blurb?
  It appears a blurb is just a secondary description field

You can contact me on OSM slack as well #Jimmy

[jschwarz2030]

There's a testChallenge object here https://github.com/osmlab/maproulette-java-client/blob/dev/src/test/resources/challenges/testChallenge.json but it isn't exhaustive

[yans80]

Here is the list of challenge properties with their semantics if you are interested:
https://hackmd.io/@RGqHG6yhT3SGgsiGwQ0zPA/r18m6Z7Gh

Pls note that if may not work as expected if you try to add these properties via geojson, as they will get overridden by fields in create challenge form.

[matkoniecz]

Would it be possible to move it into some docs kept in repository? Not on some third party site where it may become deleted at any time?

[pietervdvn]

@matkoniecz Yeah, agreed.

But as the list is relatively small, I'll copy-paste it below:

List of challenge properties with their default values and semantics

{
  blurb: "",                    // shorter description of the challenge
  checkinComment: "",           // changeset description
  checkinSource: "",            // changeset source
  completionPercentage: 0,      // percentage of tasks completed on the challenge
  cooperativeType: 0,           // none = 0, tag fix = 1, cooperative = 2
  created: "",                  // date the challenge is created
  customBasemap: "",            // custom base map URL
  dataOriginDate: "",           // age of the data in iso date string. The date the data was downloaded, generated, etc
  defaultBasemap: -1,           // the default basemap to use for the challenge, -1 = user default. 4 = Bing or EsriWorldImagery or EsriWorldImageryClarity or Mapbox or Open Street Map(standard) or thunderforest open cycle map, 3 = custom base map. customBasemap must be supplied if default base map is 3
  defaultBasemapId: "",         // default base map id when default base map = 4, possible values are Bing, EsriWorldImagery, EsriWorldImageryClarity, Mapbox, MAPNIK = open street map standard, tf-cycle = thunderforest open cycle map                  
  defaultPriority: 0,           // high = 0, medium = 1, low = 2
  defaultZoom: 13,              // default Zoom Level
  deleted: false,               // sets whether a challenge is deleted or not
  description: "",              // description of challenge
  difficulty: 2,                // difficulty of challenge, 1 = easy, 2 = normal, 3 = expert
  enabled: true,                // sets whether the challenge is publicly discoverable or not    
  exportableProperties: "",     // comma-separated task properties to be exported in csv
  featured: false,              // sets whehter a challenge is featured or not
  highPriorityRule: {},         // please visit https://learn.maproulette.org/documentation/task-priority-rules/ for details
  id: number,                   // id of challenge, required when updating a challenge
  infoLink: "",                 // an information file that will be used to display information about the challenge, when creating challenge from github
  instruction: "",              // instruction of challenge
  isArchived: false,            // sets whether to archive a challenge or not
  lastTaskRefresh: "",          // timestamp on last time tasks were built or added to the challenge
  limitReviewTags: false,       // only preferred review tags will be used when set to true
  limitTags: false,             // only preferred tags will be used when set to true
  lowPriorityRule: {},          // please visit https://learn.maproulette.org/documentation/task-priority-rules/ for details
  maxZoom: 19,                  // maximum allowed zoom levels, see https://wiki.openstreetmap.org/wiki/Zoom_levels
  mediumPriorityRule: {},       // please visit https://learn.maproulette.org/documentation/task-priority-rules/ for details
  minZoom: 1,                   // minimum allowed zoom levels, see https://wiki.openstreetmap.org/wiki/Zoom_levels
  modified: "",                 // timestamp the challenge last modified
  name: "",                     // name of the challenge
  osmIdProperty: "",            // osm id property
  overpassQL: "",               // overpass query when data source is set to overpass
  overpassTargetType: "",       // "none" = any, "way", "node"
  owner: integer,               // owner osm id
  parent: integer,              // id of the project the challenge belongs to
  preferredTags: "",            // list of comma separated preferred tags that you want the user to use when completing a task
  preferredReviewTags: "",      // list of comma separated preferred tags that you want the reviewer to use when reviewing a task
  presets: [],                  // array of enabled preset strings, this is used to limit the types of OSM features presented to mappers in iD by default when working on your tasks
  remoteGeoJson: "",            // remote geojson url when data source is set to remote geojson
  requiresLocal: false,         // sets whether tasks require local or on-the-ground knowledge to complete, challenge will not show on discoverable page if set to true
  reviewSetting: 0,             // 0 = review is not required, 1 = review is required
  status: 3,                    // none = 0, building = 1, failed = 2, ready = 3, partially loaded = 4, finished = 5, deleting tasks = 6
  statusMessage: "",            // message displayed in case challenge failed to build
  tags: [],                     // comma-separated categories types the challenge belong to, possible values are "landuse","boundary", "highway", "natural","water", "amenity","leisure", "railway","public_transport", "building" etc
  taskBundleIdProperty: "",     // task bundle id property
  taskStyles: [],               // list of task property styles, please visit https://learn.maproulette.org/documentation/styling-task-features/ for details
  updateTasks: false,           // periodically delete old, stale (not updated in ~30 days) tasks still in Created or Skipped state, when set to true
}