Sharebar?

Question on the syntax for RESTful API filtering by userIds

Question on the syntax for RESTful API filtering by userIds

I am trying to work out the correct syntax to filter student results by a state identifier returned within the userIds array of objects.

For example, if the user record contains the following:

      "userIds": [
        {
          "type": "stateID",
          "identifier": "000000000"
        }
      ],

 

What would the proper filter syntax be to find a student with the stateID of 000000000?

I have worked with a provider that returned data within metadata and the syntax for that is mentioned in the v1.1 specification:

filter=metadata.propertyName='123'

This will not work with an array of objects, however.

 

 

I'm in the process of

I'm in the process of implementing a provider and I have exactly the same question because the spec simply doesn't cover that scenario. What I think would make sense would be one of the following:
* Use the CSV specified format for the value: e.g. userIds~'stateID:000000000'
* Make it behave as if it were structured like metadata, e.g. userIds.stateId='000000000'

There are also several other deficiencies in the filter specification:
* description of array semantics gives a handful of (incorrectly formatted (missing single quotes)) examples for operators = and ~ and then proceeds to say "This means filtering using the '=' has 'AND' semantics and for '~" has 'OR' semantics" which doesn't jive at all with the examples.
* no description of array semantics for operators other than = and ~
* no description of whether order matters for arrays
* no description of semantics of ~ for scalar fields - one would think it would have substring type semantics, but how is that then reconciled with the array semantics (e.g. match a substring within an array element)
* no escaping mechanism for single-quote or comma within a value

Matthew Richards's picture

Gap in the spec

You folks are right.  This is a gap in the spec.  I don't think there is any way that the current filtering syntax in the specification can support a complex query of a collection like that.  We will be discussing this in the OneRoster Work Group meeting this upcoming Monday.  At this point I don't think we will be able to fix the gap for OneRoster 1.2, which has its scope frozen, but we could talk about ways to alleviate the use case with best practices.  We can also start brainstorming what the fix could look like and add it to the backlog for the next version of OneRoster.

 

Matt

Gap in the spec, redux

Here's a good filter I'd like: classes or courses with non-empty resources. The 'resources' property is always an array, even if empty, I believe.

We are experiencing the same

We are experiencing the same limitation with filtering. Not having the ability to filter on a nested object should be a requirement. What I am finding is that for any endpoint where properties are nested, no filtering option is available. Ex: you can no longer filter on "Role" from the GetUsers endpoint.
This will force us to use a combination of CSV and OneRoster v1.1 from the provider.