Add a new operation GetDomain

[glegal]

New optional GetDomain operation for discovering the parameters dependencies

NB : This subject has been discussed during the ninth december 2024 technical meeting.
State of fact :
In some cases, authorised values for a parameter depends on the value of another parameter,
Currently, it is only possible to trial and error on the API by using the Execute for discovering these dependencies.

New operation proposal :
A solution could be an additional GetDomain operation that delivers a description of authorized value for the remaining parameters depending the value tested for a parameter.

An example of request and reponse is provided below :

Lets say we have process that takes 4 parameters :
– A city name
– A country name
– A district number
– A bounding box

We have a data sample with 3 cities :
– Paris in France with 4 district
– Barcelone in Spain with any district
– Gognies-Chaussée a city that is on the border of France and Belgium

The initial « DescribeProcess » operation display all the possible values :
GET : http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency

{
    "id": "urn:exa:wps:examind::test.param.dependency",
    "title": "Examind : Test.param.dependency",
    "version": "1.0.0",
    "jobControlOptions": [
        "sync-execute",
        "async-execute",
        "dismiss"
    ],
    "outputTransmission": [
        "reference",
        "value"
    ],
    "inputs": [
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:country",
            "title": "Country",
            "description": "Country.",
            "minOccurs": "1",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "France",
                                "Espagne",
                                "Belgique"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:city",
            "title": "City",
            "description": "City.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "Barcelone",
                                "Gognies-Chaussée",
                                "Paris"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:district",
            "title": "District",
            "description": "District.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "1",
                                "2",
                                "3",
                                "4"
                            ]
                        },
                        "dataType": {
                            "name": "Integer",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#integer"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:boundary",
            "title": "Boundary",
            "description": "Boundary.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "supportedCRS": [
                    {
                        "crs": "EPSG:4326",
                        "default": true
                    },
                    {
                        "crs": "CRS:84",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3395",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3857",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27571",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27572",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27573",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27574",
                        "default": false
                    }
                ]
            }
        }
    ],
    "outputs": [],
    "executeEndpoint": "http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/jobs",
    "abstract": "Param used to test parameter value dependencies."
} 

We now use the new GetDomain operation to get the possibilities by adding the parameter Country = France

POST http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/domain
Body :

{
    "inputs": [{
            "id": "urn:exa:wps:examind::test.param.dependency:input:country",
            "input": {
                "dataType": {
                    "name": "String"
                },
                "value": "France"
            }
        }]
}

The response returns only the matching parameters :

{
    "id": "urn:exa:wps:examind::test.param.dependency",
    "title": "Examind : Test.param.dependency",
    "version": "1.0.0",
    "jobControlOptions": [
        "sync-execute",
        "async-execute",
        "dismiss"
    ],
    "outputTransmission": [
        "reference",
        "value"
    ],
    "inputs": [
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:country",
            "title": "Country",
            "description": "Country.",
            "minOccurs": "1",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "France"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:city",
            "title": "City",
            "description": "City.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "Gognies-Chaussée",
                                "Paris"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:district",
            "title": "District",
            "description": "District.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "1",
                                "2",
                                "3",
                                "4"
                            ]
                        },
                        "dataType": {
                            "name": "Integer",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#integer"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:boundary",
            "title": "Boundary",
            "description": "Boundary.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "supportedCRS": [
                    {
                        "crs": "EPSG:4326",
                        "default": true
                    },
                    {
                        "crs": "CRS:84",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3395",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3857",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27571",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27572",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27573",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27574",
                        "default": false
                    }
                ]
            }
        }
    ],
    "outputs": [],
    "executeEndpoint": "http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/jobs",
    "abstract": "Param used to test parameter value dependencies."
}

If we supply the country Belgium and city Gognies-Chaussée, we do no longer have district in the reponse.

POST http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/domain
Body :

{
    "inputs": [{
            "id": "urn:exa:wps:examind::test.param.dependency:input:country",
            "input": {
                "dataType": {
                    "name": "String"
                },
                "value": "Belgique"
            }
        },{
            "id": "urn:exa:wps:examind::test.param.dependency:input:city",
            "input": {
                "dataType": {
                    "name": "String"
                },
                "value": "Gognies-Chaussée"
            }
        }]
}

Response :

{
    "id": "urn:exa:wps:examind::test.param.dependency",
    "title": "Examind : Test.param.dependency",
    "version": "1.0.0",
    "jobControlOptions": [
        "sync-execute",
        "async-execute",
        "dismiss"
    ],
    "outputTransmission": [
        "reference",
        "value"
    ],
    "inputs": [
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:country",
            "title": "Country",
            "description": "Country.",
            "minOccurs": "1",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "Belgique"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:city",
            "title": "City",
            "description": "City.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "Gognies-Chaussée"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:district",
            "title": "District",
            "description": "District.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "dataType": {
                            "name": "Integer",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#integer"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:boundary",
            "title": "Boundary",
            "description": "Boundary.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "supportedCRS": [
                    {
                        "crs": "EPSG:4326",
                        "default": true
                    },
                    {
                        "crs": "CRS:84",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3395",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3857",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27571",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27572",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27573",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27574",
                        "default": false
                    }
                ]
            }
        }
    ],
    "outputs": [],
    "executeEndpoint": "http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/jobs",
    "abstract": "Param used to test parameter value dependencies."
}

If we then filter on the country Spain, as the city Barcelone is configured with « Any » district,
All the available districts will be returned 

POST http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/domain
Body :

{
    "inputs": [{
            "id": "urn:exa:wps:examind::test.param.dependency:input:country",
            "input": {
                "dataType": {
                    "name": "String"
                },
                "value": "Espagne"
            }
        }]
}

Response :

{
    "id": "urn:exa:wps:examind::test.param.dependency",
    "title": "Examind : Test.param.dependency",
    "version": "1.0.0",
    "jobControlOptions": [
        "sync-execute",
        "async-execute",
        "dismiss"
    ],
    "outputTransmission": [
        "reference",
        "value"
    ],
    "inputs": [
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:country",
            "title": "Country",
            "description": "Country.",
            "minOccurs": "1",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "Espagne"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:city",
            "title": "City",
            "description": "City.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "Barcelone"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:district",
            "title": "District",
            "description": "District.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "1",
                                "2",
                                "3",
                                "4"
                            ]
                        },
                        "dataType": {
                            "name": "Integer",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#integer"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:boundary",
            "title": "Boundary",
            "description": "Boundary.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "supportedCRS": [
                    {
                        "crs": "EPSG:4326",
                        "default": true
                    },
                    {
                        "crs": "CRS:84",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3395",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3857",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27571",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27572",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27573",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27574",
                        "default": false
                    }
                ]
            }
        }
    ],
    "outputs": [],
    "executeEndpoint": "http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/jobs",
    "abstract": "Param used to test parameter value dependencies."
}

If we use the bbox parameter with a envelope englobing Paris and Barcelone we get all the paramters from both cities :

POST http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/domain
Body :

{
    "inputs": [{
            "id": "urn:exa:wps:examind::test.param.dependency:input:boundary",
            "input": {
                "bbox": [1.5, 41.1, 3.4, 49.2],
                "crs": "EPSG:4326"
            }
        }]
}

Response :

{
    "id": "urn:exa:wps:examind::test.param.dependency",
    "title": "Examind : Test.param.dependency",
    "version": "1.0.0",
    "jobControlOptions": [
        "sync-execute",
        "async-execute",
        "dismiss"
    ],
    "outputTransmission": [
        "reference",
        "value"
    ],
    "inputs": [
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:country",
            "title": "Country",
            "description": "Country.",
            "minOccurs": "1",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "France",
                                "Espagne"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:city",
            "title": "City",
            "description": "City.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "Barcelone",
                                "Paris"
                            ]
                        },
                        "dataType": {
                            "name": "String",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#string"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:district",
            "title": "District",
            "description": "District.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "literalDataDomains": [
                    {
                        "allowedValues": {
                            "allowedValues": [
                                "1",
                                "2",
                                "3",
                                "4"
                            ]
                        },
                        "dataType": {
                            "name": "Integer",
                            "reference": "http://www.w3.org/TR/xmlschema-2/#integer"
                        }
                    }
                ]
            }
        },
        {
            "id": "urn:exa:wps:examind::test.param.dependency:input:boundary",
            "title": "Boundary",
            "description": "Boundary.",
            "minOccurs": "0",
            "maxOccurs": "1",
            "input": {
                "supportedCRS": [
                    {
                        "crs": "EPSG:4326",
                        "default": true
                    },
                    {
                        "crs": "CRS:84",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3395",
                        "default": false
                    },
                    {
                        "crs": "EPSG:3857",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27571",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27572",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27573",
                        "default": false
                    },
                    {
                        "crs": "EPSG:27574",
                        "default": false
                    }
                ]
            }
        }
    ],
    "outputs": [],
    "executeEndpoint": "http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency/jobs",
    "abstract": "Param used to test parameter value dependencies."
}

[francescoingv]

@glegal the issue is interesting for me, however I am confused with the details of the example provided.
As far as I understand, according to OGC API - PROCESSES - PART 1: CORE Version 1.0.0,
Example — Example OGC Process Description., starting at page 71

in the description of your example, the inputs should start with:

    "inputs":
        {
            "urn:exa:wps:examind::test.param.dependency:input:country": {
                "title": "Country",
                "description": "Country.",
                "minOccurs": "1",
                "maxOccurs": "1",
                "schema": {
                    "type": "string",
                    "enum": [
                        "France",
                        "Espagne",
                        "Belgique"
                    ]
                }

[glegal]

@francescoingv Yes you are right. I used a JSON version of a WPS 2 server developed during an OGC testbed.
This was before the official release of the Processes API.
I will update the examples (and my server also, but it will take more time).

[fmigneault]

Can we get more details about what is the requested feature?

As I understand it, there is a very complex set of cross-dependencies between input values, for which a specific "GetDomain" process was defined to resolve them. It seems to me like defining such a process is a valid strategy to handle these complex resolutions. So, what is the expectation from the OGC API - Processes standard definition? The standard doesn't need any update to define this "GetDomain" process. It can already be defined as proposed.

[pvretano]

I like the idea. GetDomain was defined initially in CSW here and work is being done in Features and Records here to add GetDomain to the OGC APIs.

The ideas are identical and I would not want to see two divergent proposals for GetDomain capabilities.

The Features & Records proposal does not use POST. It works purely on GET.

It uses a "profile" parameter to request the possible values versus the actual values. The "profile" parameter takes the values "valid-domain" (all possible values) and "actual-domain" (all actual or filtered values). The default is "valid-domain".

The original CSW definition of GetDomain included a Filter. In the Features and Records proposal we are proposing to not define filtering capabilities because there wasn't a compelling use case.

Well, I guess Processes now provides a nice use case so maybe we can put filter back on the table!

If I translate the examples @glegal presented above the requests would look like this:

• GET : http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency
• GET : http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency?profile=actual-domain&filter=urn:exa:wps:examind::test.param.dependency:input:country='France'
• GET : http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency?profile=actual-domain&filter=urn:exa:wps:examind::test.param.dependency:input:country='Belgique' AND urn:exa:wps:examind::test.param.dependency:input:city='Gognies-Chaussée'
• GET : http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency?profile=actual-domain&filter=urn:exa:wps:examind::test.param.dependency:input:country='Espagne'
• GET : http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency?profile=actual-domain&filter=S_INTERSECTS("urn:exa:wps:examind::test.param.dependency:input:boundary", BBOX(1.5, 41.1, 3.4, 49.2))&filter-crs=EPSG:4326

NOTE: I have not escaped anything for the sake of clarity.

So we would use the "profile" parameter and the standard "filter", "filter-lang" and "filter-crs" parameters and CQL2 to add GetDomain capabilties to the DescribeProcess operation.

I am not opposed to moving forward with this capability but I would be opposed to propsing something different than what is defined in CSW and what is being proposed in Features and Records.

Thoughts?

[fmigneault]

Thanks @pvretano
Much clearer now.

Would it make sense, also for the sake of alignment, to use /processes/{processId}/queryables or /processes/{processId}/schema rather than overloading /processes/{processId} directly? Using the same endpoint for ProcessDescription and GetDomain will most probably end up into conflicting parameters. For example, profile could be considered for returning the ProcessDescription with different representations (e.g.: providing an openEO process graph or a CWL), which would not be possible anymore.

[pvretano]

@fmigneault not sure that /queryables or /schema would be a suitables endpoints in processes. These are defined in Part 5 of features with specific semantics for features and records.

I have two thoughts in mind ...

Thought 1:
For the sake of processes, I would propose that we disscociate the list of process inputs and outputs from the specific process description language/representation and define two new endpoints, /processes/{processId}/inputs and /processes/{processId}/outputs, for getting the schemas of just the inputs or the outputs of a process ... always in a well known schema language like JSON-Schema. We could then apply profile, properties, filter, etc. to those endpoints to get the desired variations.

Through 2:
On the other hand, the profile parameter is an array (i.e. list of values) and so you could request a process description in OpenEO or CWL ...AND... also request just the "actual" values rather than the "possible" values. Something like:

GET : http://localhost:8080/examind/WS/wps/default/processes/urn:exa:wps:examind::test.param.dependency?profile=actual-domain,openEO-schema&filter=urn:exa:wps:examind::test.param.dependency:input:country='France'

Although "Thought 1" seems nice and clean I think "Thought 2" would result in a better client-side expereince since it would require fewer calls to get the necessary information to compose a request.

But I could be convinced either way ...

[fmigneault]

I agree "Thought 2" seems like a nicer client experience.

[bpross-52n]

SWG meeting from 2025-04-14: This will not be added to version 2.0. We would like to see a few code sprints that test the GetDomain operation in other API standards.