Clarification around and/or logic for filters (and taxonomies)

Technical
1

Hey all,

I’m looking for some clarification around and/or logic for filtering services (and taxonomies)

The examples I’ve found in the documentation say “and/or” but does that mean:

Its and/or depending on your implementation

or

and/or is whats returned, so the results for a query where I request value1 and value2 in my params, if a service has value1 and value2 return it plus if a service has value1 or value2 return it?

1 Like
2

Hello Hannah

I do think we should clarify. @davidraznick may be able to point us to something.

My understanding is that query parameters should be combined with a Boolean AND - so all filter conditions should be valid for all results.

So if you want to do an OR, you need to do two (or more) queries and combine the responses.

2 Likes
3

Has this been resolved in the documentation? I can’t find an answer there.

4

Sorry, I completely missed this.

Mike is correct that it is boolean AND.

/services?taxonomy_id=XXX&organization_id=YYY

So this is searching for taxonomy_id XXX AND organization_id YYY

This should be made clearer in the docs.

5

Thanks for replying @davidraznick.

Just to clarify using just taxonomies as an example

/services?taxonomy_id=1&taxonomy_id=2
returns all services with 1 AND 2 and not services with 1 OR 2?

Service A - is returned
- taxonomy_id: 1
- taxonomy_id: 2

Service B - is returned
- taxonomy_id: 1
- taxonomy_id: 2

Service C - is not returned
- taxonomy_id: 1

Service D - is not returned
- taxonomy_id: 2

So to return all four of those services I would need to do

/services?taxonomy_id=1
/services?taxonomy_id=2

and combine the results?

theres no scope for something like /services?taxonomy_id=1,2 as valid OR alternative?

6

Hi @hntpx Hannah,

We updated the docs to make this clearer. Hopefully this helps clarify your more recent query also - API Reference — Open Referral Data Specifications 3.0.1 documentation

If you have any further queries let me know. Feel free to @me

Dan

1 Like
7

Wondering if a graphQL API would help with this or something along the lines of JQL for Jira. Just brain dumping

8

Hi @HannahN, @rgparkins,

JTLYK - We are looking into/discussing this our end and will get back to you as soon as possible.

Dan

9

Hey @hntpx

Sincere apologies for the delayed response – this came in just as I rushed off to the mountains on leave!

In short: you raise a very valid point and I think this is good behaviour which we should clarify is desirable or at least permitted to implementors. Certainly the logic around AND for different query parameters doesn’t preclude this, and if everyone is in agreement that this is what we want then we can get onto clarifying this in the docs as a matter of priority.

I think the desired behaviour is that AND is used for different parameters e.g. taxonomy_id = 1 AND organization_id = XYZ, while OR is used for requesting values matching values within a specific parameter e.g. taxonomy_id = 1 OR taxonomy_id = 2. As far as I’m aware, this is fairly standard practice which I would endorse supporting in the HSDS API specification.

Therefore this request:

/services?taxonomy_id=1&taxonomy_id=2

would return all services with a taxonomy_id of 1 OR of 2, allowing you to get all four services you list.

When querying across different parameters, each new parameter is basically an AND clause in the logic. So this request:

/services?taxonomy_id=1&taxonomy_id=2&organization_id=XYZ

would return all services that have an organization_id of XYZ AND a taxonomy_id of 1 OR 2.

This request:

/services?taxonomy_id=1&taxonomy_id=2&organization_id=XYZ&organization_id=ABC

would return all services with an organization_id of XYZ OR ABC, AND have a taxonomy_id of 1 or 2. This can also be represented as:

(organization_id == 'XYZ' OR organization_id == 'ABC') AND (taxonomy_id == 1 OR taxonomy_id == 2)

Would this logic work for you?

There are also some unsupported edge-cases here, but I’d need to know more about your concerns as a developer to determine whether they’re pertinent or not. The functionality outlined above would basically be the limits of the logic in this syntax, and it’d be difficult or impossible to construct more complex boolean requirements e.g.

(organization_id == 'XYZ' AND taxonomy_id == 1) OR (organization_id == 'ABC' AND taxonomy_id = 2)

I believe it’s at this point we’d need to discuss how reasonable it is to ask implementors to support query parameters in more complex formats such as a JSON payload representing the query, such as what occurs in Elastic. I’m not deeply familiar with GraphQL or JQL myself, so they might be appropriate (@rgparkins might know more about this?). In any case, the concern from the standard’s perspective would be how to represent these capabilities using the Open API specification file; as long as we have a shared way of doing that, then it should be reasonable as an approach.

There is also certainly nothing stopping any HSDS developer from also providing additional functionality, they just also need to comply with the expected behaviour outlined in the API Specification; which we’ve now got more clarity on thanks to this engagement :slight_smile:

1 Like
10

Hey @mrshll

For some more context this issue has come up on our directory application Scout which is using the Outpost API.

Theres more information in this ticket but the short version is that currently selecting two taxonomies and calling /services?taxonomy_id=1&taxonomy_id=2 it isn’t clear enough to the user that the results you receive don’t always contain both of those taxonomies you’re filtering by so we wanted to amend the API to allow for results to be returned where both contain that taxonomy.

I’ve put some suggestions and thoughts in that ticket but it doesn’t account for other options its only looking at taxonomies for now. Different kinds of taxonomies or other filters and organisations etc might make it very messy and complicated suddenly running two queries and filtering some results doesn’t seem too difficult :joy:!