OpenAPI add OR logical operator doc and examples

[rduyme]

Doc and examples

OpenAPI add :

• OR logical operator

Proposition : alignment with OpenAlex simple operators ( see https://docs.openalex.org/how-to-use-the-api/get-lists-of-entities/filter-entity-lists ) using :

• in filter value : | means OR
• coma between filters means AND
• in filter value : + means AND

Examples :

• UC_1 : title contains ocean => filter=cf.search.title:ocean
• UC_2 : product type is publication OR dataset OR software => filter=product_type:publication|dataset|software
• UC_3 : title contains pacific OR title contains atlantic => filter=cf.search.title:pacific|atlantic
• UC_3 : title contains sweden OR title contains swedish => filter=cf.search.title:sweden|swedish
• UC_4 : title contains ocean AND title contains atlantic => filter=cf.search.title:ocean,cf.search.title:atlantic ( and we also support : filter=cf.search.title:ocean+atlantic )
• UC_5 : title contains ocean AND product type is publication => filter=cf.search.title:ocean,product_type:publication
• UC_6 : title contains ocean AND title contains atlantic AND product type is publication => filter=cf.search.title:ocean,cf.search.title:atlantic,product_type:publication ( and we also support : filter=cf.search.title:ocean+atlantic,product_type:publication )

Note the following query can be sent. but it will not return any record. (it is not possible to have 2 different product_type )

• product type is publication AND dataset => filter=product_type:publication,product_type:dataset

[menzowindhouwer]

Do we have enough use cases to warrent the implementation burden for all implementers? Do you need it for your use case?

---

The proposal isn't complete, i.e. it doesn't allow ORs between filters:

• title contains ocean OR abstract contains ocean => isn't possible

So if we need it for our use cases we (c|sh)ould look around for filter specifications with full coverage of logical expressions, so our implementation effort will be more complete!

---

I think we already get a long way with the following default interpretation, i.e. without the need for logical expression support:

• AND between multiple filters
• OR between filter values

which is an interpretation that works for both fields that have a single values and fields that have multiple values.

NOTE: this clashes with the final example above that between filter values its an OR not an AND:

• filter=product_type:publication,product_type:dataset => product_type is publication OR product_type is dataset

where the default interpretation can never clash with the data model

[rduyme]

Hi Menzo,
Thanks for the feedback

Impossible to anticipate all the use cases. Idea was just to answer UC_2 (Question from OpenAire) and at the same time UC_3.
I suggested to reuse OpenAlex simple approach ( they have a large user base and needs )

yes. "it doesn't allow ORs between filters". But I think when you start doing this you need to switch to a complex grammar (Elastic like query, SQL etc... or use logic parenthesis etc... ). I have the feeling a default AND between filters is more clear than OR.

Let's vote/decide in SKG-IF meeting :-)

( Note : For OSTrails, my personal need is only "autocomplete"/query from a client with a single search term, this means : UC_1. No need for any OR logic )

[menzowindhouwer]

Discussed at the OST SKG IF API of 20250917, we agreed (as AND is the most natural interpretation) to go for the following default interpretation:

• AND between multiple filters
• AND between filter values

It's optional to throw an error if more filter values are requested for a field that has only a single value.

• UC_1 : title contains ocean => filter=cf.search.title:ocean
• UC_2 : product type is publication OR dataset OR software => not supported in single query filter
• UC_3 : title contains pacific OR title contains atlantic => not supported in single query filter
• UC_3 : title contains sweden OR title contains swedish => not supported in single query filter
• UC_4 : title contains ocean AND title contains atlantic => filter=cf.search.title:ocean,cf.search.title:atlantic
• UC_5 : title contains ocean AND product type is publication => filter=cf.search.title:ocean,product_type:publication
• UC_6 : title contains ocean AND title contains atlantic AND product type is publication => filter=cf.search.title:ocean,cf.search.title:atlantic,product_type:publication

Clarifications :

• To do a OR you'll have to send a multiple queries and process them client side.
• the following chars : "+" "|" (mentioned in previous comments) do not have any specific semantic.

[aisimeon349e6]

Discussed at the OST SKG IF API of 20250917, we agreed (as AND is the most natural interpretation) to go for the following default interpretation:

• AND between multiple filters
• AND between filter values

It's optional to throw an error if more filter values are requested for a field that has only a single value.

• UC_1 : title contains ocean => filter=cf.search.title:ocean
• UC_2 : product type is publication OR dataset OR software => not supported in single query filter
• UC_3 : title contains pacific OR title contains atlantic => not supported in single query filter
• UC_3 : title contains sweden OR title contains swedish => not supported in single query filter
• UC_4 : title contains ocean AND title contains atlantic => filter=cf.search.title:ocean,cf.search.title:atlantic
• UC_5 : title contains ocean AND product type is publication => filter=cf.search.title:ocean,product_type:publication
• UC_6 : title contains ocean AND title contains atlantic AND product type is publication => filter=cf.search.title:ocean,cf.search.title:atlantic,product_type:publication

Clarifications :

• To do a OR you'll have to send a multiple queries and process them client side.
• the following chars : "+" "|" (mentioned in previous comments) do not have any specific semantic.

I suggest we don't repeat the field in the filter, no need for that and the whole url will be shorter and more readable (think of a case where someone wants to send it by email).

A field could accept multiple values like this:
filter=cf.search.title:ocean,atlantic - internally, comma will be interpreted as AND. So, the final query to the search engine will be: query (ocean AND atlantic).

pros of this approach:

1. the url with all request params will be shorter
2. shorter means more readable
3. it's much easier for me to implement
4. less code, less parsing of the filter, better performance

[rduyme]

Hi Alexios, @aisimeon349e6
regarding your last proposition how would you write UC_6 ?
UC_6 : title contains ocean AND title contains atlantic AND product type is publication => filer=?

[aisimeon349e6]

@rduyme
"title contains ocean AND title contains atlantic AND product type is publication"
would be like this:
filter=cf.search.title:ocean atlantic,product_type:publication