Add `type` parameter to suggest property queries

[wetneb]

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: OpenRefine/OpenRefine#5523

[thadguidry]

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,"

• a Property
  • has a Type #parameter
  • has a Type #parameter
  • has a Type #parameter

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

• a Type
  • has a Property #suggested
  • has a Property #suggested
  • has a Property #suggested
• a Type
  • has a Property #suggested
  • has a Property #suggested
  • has a Property #suggested
• a Type
  • has a Property #suggested
  • has a Property #suggested
  • has a Property #suggested

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

QUERY

• a Property
  • has a Type (OPTIONAL parameter)

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

• a Property
  • a Type
    • has a Property (OPTIONAL suggested property returned from reconciliation service)
    • has a Property (OPTIONAL suggested property returned from reconciliation service)

[ostephens]

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

[tfmorris]

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](https://developers.google.com/freebase/v1/search#query) or [filter](https://developers.google.com/freebase/v1/search#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]

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

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

[wetneb]

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]

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.