Extend "mode" and "preferences" with description

[thanchevici]

Hi, currently mode and preferences are strings only. This may create confusion on user side. I suggest changing them to include a description that can be used by clients

"properties": {
"http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/core": {
"preferences": [
           {"name" : "fastest", "description": "Computes fastest route"},
          {"name" : "shortest", "description": "Computes shortest route"},
   ]
  },
"http://www.opengis.net/spec/ogcapi-routes-1/1.0.0-draft.1/conf/mode": {
"modes": [
         {"name" : "motor-vehicle", "description": "Computes route for a car"},
         {"name" : "bicycle", "description": "Computes route for a bicycle"},
         {"name" : "pedestrian", "description": "Computes a pedestrian route"}
     ]
   }
}

Best regards, Teodor

[cportele]

The proposal makes sense to.

What should be discussed are the keys of the members. Typically we use in OGC API schemas "id" for something that is a local identifier (like in this case), "title" for a human-readable label or title (usually a few words) and "description" for a longer explanation. I think, we should require "id" and allow "title" and "description" with a recommendation to provide a "title".

[cportele]

Meeting 2022-11-22: Include in v1.0, but with a slightly different encoding:

"preferences": { 
  "fastest": { "title": "Computes fastest route" },
  "shortest": { "title": "Computes shortest route" }
}

Also include "description" for now.

[thanchevici]

@cportele these two should be combined. The server will report a mode, with what preferences or options are available. Each mode on the server might have options. "fastest" and "shortest" are not the only one, and not all modes will have this. The goal again is to provide extensibility

Something like this:

{
    "modes" : [
        {
            "motor-vehicle" :
            {
                "title": "Computes route for a car",
                "options" : {
                    "type" : "array",
                    "items" : {
                        "type" : "object",
                        "enum": [
                            {"fastest": { "title": "Computes fastest route" }},
                            {"shortest": { "title": "Computes shortest route" }}]
                    }
                }
            },
            "uav-survey" :
            {
                "title": "Generate a lawn mower pattern",
                "options" : {
                    "type" : "object",
                    "properties":{
                        "forward-overlap": { "title": "forward overlap percentage", "type" : "integer", "minimum":10, "maximum":50 },
                        "lateral-overlap": { "title": "lateral overlap percentage", "type" : "integer", "minimum":10, "maximum":50 }
                    }
                }
            }
        }
    ]
}

[cportele]

Meeting 2022-12-13:

• "mode" is currently a separate conformance class to make it simple for APIs that only support a single mode.
• "preference" (the routing cost function) is the only required parameter/option at the moment
• We want to keep the API simple for the simpler use cases, but also support the more complex use cases that require richer information and multiple modes with different parameters. How to do it is not yet clear. We will continue the discussion in the next meeting on January 3rd, 2023.
• If the parameters of the conformance classes become complex, adding them to the Conformance Declaration may no longer be the right approach.

[thanchevici]

@cportele @jeffharrison maybe we can do this:

make preferences optional. add an advanced option in the server that is an object. Servers not supporting advanced options will return an empty object

A server reporting with advanced options and "uav-survey" and "uav-inspection" modes will report the following schema for advancedOptions

"advancedOptions" :{
   "uav-survey":{
      "title":"Generate a lawn mower pattern",
      "forward-overlap":{
         "title":"forward overlap percentage",
         "type":"integer",
         "minimum":10,
         "maximum":50
      },
      "lateral-overlap":{
         "title":"lateral overlap percentage",
         "type":"integer",
         "minimum":10,
         "maximum":50
      },
      "AGL":{
         "title":"Above ground level flight altitude",
         "type":"integer",
         "minimum":100,
         "maximum":500,
         "unit":"feet"
      }
   },
   "uav-inspection":{
      "title":"generates an inspection pattern",
      "distance":{
         "title":"distance from point of interest",
         "type":"integer",
         "minimum":10,
         "maximum":50,
         "unit":"meter"
      },
      "vertical-step":{
         "title":"Step in vertical movement",
         "type":"integer",
         "minimum":10,
         "maximum":50,
         "unit":"meter"
      }
   }
}

This will keep the API simple, will not require changes to mode or preferences. To me this looks like a simple solution.

[cportele]

Meeting 2023-01-03:

• Move "preference" out of the Core requirements class into the Modes requirements class.
• If the Modes requirements class is supported, a new operation is added that lists all available modes (resource path to be determined). A mode will specify the preferences for optimizing the route that are available for that mode. Information about the preferences and modes will be removed from the Conformance Declaration.
• The "preference" query parameter will be moved to the Modes requirements class
• The mode description can be extended with additional properties of the mode. For example, the UxS group can specify mode parameters that are specific to UxS vehicles.