Filtering

OneRoster collection endpoints accept a server-side filter query parameter that follows the 1EdTech OneRoster v1.2 filter syntax. This page is a practical reference for what you can put in it.

Operators

Operator	Meaning	Applies to
=	equals	strings, numbers, dates, booleans
!=	not equals	strings, numbers, dates, booleans
>	greater than	numbers, dates
>=	greater or equal	numbers, dates
<	less than	numbers, dates
<=	less or equal	numbers, dates
~	substring contains	strings

Combine predicates with AND (uppercase). The spec also defines OR; verify support per endpoint before relying on it.

Field paths

Filters reference fields by dotted path, traversing into nested objects and GUIDRef references:

• sourcedId — top-level field
• student.sourcedId — sourcedId of the referenced student
• roles.org.sourcedId — sourcedId of the org inside any of the user's roles
• class.sourcedId — sourcedId of the referenced class
• dateLastModified — top-level timestamp

Literal values

Type	Format	Example
String	single-quoted	'user-441'
Number	bare	42, 3.14
Boolean	true / false	true
Date-time	ISO 8601, single-quoted	'2026-04-20T00:00:00Z'

Examples

Single equality:

filter=student.sourcedId='user-441'

Combined with AND:

filter=roles.org.sourcedId='org-12' AND roles.role='teacher'

Date comparison (intra-day delta — see the integration guide on dateLastModified semantics before relying on this for incremental sync):

filter=dateLastModified>'2026-04-26T12:00:00Z'

Substring contains:

filter=familyName~'Sjov'

URL encoding

The whole filter expression goes in a query string, so reserved characters need percent-encoding when sent over HTTP. Most clients do this automatically. If you're hand-crafting a URL:

• = → %3D
• ' → %27
• space → %20

So filter=student.sourcedId='user-441' becomes filter=student.sourcedId%3D%27user-441%27 on the wire.

What filter is not

• It does not select fields (no projection — use the fields parameter where supported, see the per-API page).
• It does not aggregate.
• It does not paginate (use limit/offset).
• It does not sort (results are sorted by id by default; see the per-API page).