search

reconciliation-api / specs

Specifications of the reconciliation API
https://reconciliation-api.github.io/specs/draft/
30 stars 9 forks source link

Add `type` parameter to suggest property queries #104

Open wetneb opened 1 year ago

wetneb commented 1 year ago

OpenRefine includes a type= query parameter to its auto-completion HTTP calls for properties, letting the reconciliation service to suggest properties which are relevant for the given type.

This parameter is not currently mentioned in the specs: I would propose to add it.

OpenRefine also includes other unspecified parameters in its queries: https://wikidata.reconci.link/en/suggest/property?prefix=test&spell=always&exact=false&scoring=schema&prefixed=true&type=Q223393

I would remove the spell=always, exact=false, scoring=schema and prefixed=true from those calls unless someone can find a meaning for them, which would make them useful for a broad range of services.

See also: https://forum.openrefine.org/t/suggest-property-request-always-includes-a-type/264 OpenRefine issue: https://github.com/OpenRefine/OpenRefine/issues/5523

thadguidry commented 1 year ago

OpenRefine includes a type= query parameter to its auto-completion HTTP calls for properties, letting the reconciliation service to suggest properties which are relevant for the given type.

Sorry, the wording there seems confusing to me. You say:

QUERY "includes a type= query parameter to its auto-completion HTTP calls for properties,"

RESPONSE "reconciliation service to suggest properties which are relevant for the given type."

So, in QUERY and RESPONSE which are truly OPTIONAL and which are MUST INCLUDE?

QUERY

RESPONSE - @wetneb should it return suggesting "properties of the Type of the Property" that was specified in the previous query?

ostephens commented 1 year ago

I feel like something is missing from @thadguidry's response?

tfmorris commented 1 year ago

re "unspecified parameters" The "spec" for OpenRefine is the current implementation. There isn't a separate specification, although in this particular case, the relevant documentation for the parameters that OpenRefine is sending is part of the Freebase Suggest API which, in turn, refers to the Freebase Search API.

I'll quote the docs here in case Google removes them in the future:

All parameters below are optional but you must have one of either query or filter

Parameter name Value Description

Optional parameters as_of_time | string | A MQL as_of_time value to use with mql_output queries. callback | string | JS method name for JSONP callbacks. cursor | integer | The cursor parameter along with the limit parameter allows you to page through a defined number of results at a time. For example, to present 3 pages of successive 10 results, use  limit=10 and cursor=0, then cursor=10, and cursor=20. domain | string | Restrict to topics with this Freebase domain ID. encode | string | The encoding of the response. You can use this parameter to enable HTML encoding.Acceptable values are:"html": Encode certain characters in the response (such as tags and ampersands) using HTML encoding."off": No encoding of the response. You should not print the results directly on a web page without HTML-escaping the content first. (default) exact | boolean | Query on exact name and keys only. filter | string | The filter parameter allows you to create more complex rules and constraints to apply to your query.The filter value is a simple language that supports the following symbols:the all, any, should and not operatorsthe type, domain, name, alias, with and without operandsthe ( and ) parenthesis for grouping and precedenceTo learn how to use the filter property see the Search Cookbook. format | string | Structural format of the JSON response.Acceptable values are:"entity": Basic information about the entities. (default)"ids": Ordered list of Freebase ids."mids": Ordered list of Freebase mids. indent | boolean | Whether to indent the JSON results or not. lang | string | The code of the language with which to run the query. Default is 'en'. limit | integer | Maximum number of results to return. By default, 20 matches in decreasing order of relevance are returned, if that many exist. Fewer or more matches may be requested by using the limit parameter with a different value. (Example.) mql_output | string | The MQL query to run againist the results to extract more data. After the query is run, the matching documents' IDs are passed to the mql_output MQL query to retrieve actual data about the matches. The MQL results are sorted by decreasing relevance score. prefixed | boolean | Prefix match against names and aliases. query | string | Query term to search for. scoring | string | Relevance scoring algorithm to use.Acceptable values are:"entity": Use Freebase and popularity entity ranking. (default)"freebase": Use Freebase entity ranking."schema": Use schema ranking for properties and types. spell | string | Request 'did you mean' suggestionsAcceptable values are:"always": Request spelling suggestions for any query at least three characters long."no_results": Request spelling suggestions if no results were found."no_spelling": Don't request spelling suggestions. (default) stemmed | boolean | Query on stemmed names and aliases. May not be used with prefixed. type | string | Restrict to topics with this Freebase type id. with | string | A filter rule to match against. without | string | A filter rule to not match against.

All parameters below are optional but you must have one of either query or filter.

Parameter name Value Description Optional parameters as_of_time string A MQL as_of_time value to use with mql_output queries. callback string JS method name for JSONP callbacks. cursor integer The cursor parameter along with the limit parameter allows you to page through a defined number of results at a time. For example, to present 3 pages of successive 10 results, use limit=10 and cursor=0, then cursor=10, and cursor=20. domain string Restrict to topics with this Freebase domain ID. encode string The encoding of the response. You can use this parameter to enable HTML encoding.

Acceptable values are: "html": Encode certain characters in the response (such as tags and ampersands) using HTML encoding. "off": No encoding of the response. You should not print the results directly on a web page without HTML-escaping the content first. (default) exact boolean Query on exact name and keys only. filter string
The filter parameter allows you to create more complex rules and constraints to apply to your query.

The filter value is a simple language that supports the following symbols:

the all, any, should and not operators the type, domain, name, alias, with and without operands the ( and ) parenthesis for grouping and precedence To learn how to use the filter property see the Search Cookbook.

format string Structural format of the JSON response.

Acceptable values are: "entity": Basic information about the entities. (default) "ids": Ordered list of Freebase ids. "mids": Ordered list of Freebase mids. indent boolean Whether to indent the JSON results or not. lang string The code of the language with which to run the query. Default is 'en'. limit integer Maximum number of results to return. By default, 20 matches in decreasing order of relevance are returned, if that many exist. Fewer or more matches may be requested by using the limit parameter with a different value. (Example.) mql_output string The MQL query to run againist the results to extract more data. After the query is run, the matching documents' IDs are passed to the mql_output MQL query to retrieve actual data about the matches. The MQL results are sorted by decreasing relevance score. prefixed boolean Prefix match against names and aliases. query string Query term to search for. scoring string Relevance scoring algorithm to use.

Acceptable values are: "entity": Use Freebase and popularity entity ranking. (default) "freebase": Use Freebase entity ranking. "schema": Use schema ranking for properties and types. spell string Request 'did you mean' suggestions

Acceptable values are: "always": Request spelling suggestions for any query at least three characters long. "no_results": Request spelling suggestions if no results were found. "no_spelling": Don't request spelling suggestions. (default) stemmed boolean Query on stemmed names and aliases. May not be used with prefixed. type string Restrict to topics with this Freebase type id. with string A filter rule to match against. without string A filter rule to not match against.

thadguidry commented 1 year ago

I feel like something is missing from @thadguidry's response?

clarified by adding my question to @wetneb directly on the RESPONSE

wetneb commented 1 year ago

The "spec" for OpenRefine is the current implementation.

I clearly disagree. Given that OpenRefine itself has basically no documentation of its own implementation, this would amount to saying that service implementers are expected to reverse-engineer OpenRefine to figure out the protocol. I did that 5 years ago for the Wikidata service and I do not want this to be what we wish other service implementers.

My expectation (and the whole point of founding this W3C group) is that OpenRefine aligns to the W3C spec, and follows it as it evolves. That has been happening for some years already and I see no reason to stop this move.

thadguidry commented 1 year ago

The quotes around "spec" that @tfmorris used is a way Americans sometimes say softly or loosely or unreal. So, soft "spec" or loose "spec". He wasn't saying real spec. Which we do need and he knows, and also was helpful giving the doc links to improve the real spec we're drafting in W3C.