Matching/Filtering for Tin Can Statements

| Comments

Tin Can API statements flexibly describe learning-related events. Like many event-focused systems, use cases frequently involve ‘watching’, ‘filtering’, and generally reacting to events having certain characteristics. While there are many extremely capable systems and libraries for performing those operations, there’s still a need for a portable, flexible way of defining filters that match or don’t match individual statements, for use as part of those larger systems.

After hearing from several people about scenarios where I saw such filters providing part of the solution, I started brainstorming. The results are below.

Generally speaking, a statement is of interest if a particular part of the statement has a value meeting certain criteria, or if combination of parts-meeting-criteria using and, or, or not apply. Other important considerations for the solution are ease of implementation, readability, and concision.

The solution I’ve come up with looks like this:

    "or": {
        "$.result.success": true,
        "$.result.score.scaled": {
            ">": 0.5
    "$": ""

That filter would match any statement with the ‘completed’ verb and either a successful result or a scaled score over 0.5.

The keys that start with a $ are JSONPath expressions. JSONPath is a standard, similar to XPath, for selectively extracting data from JSON documents.

The result of the JSONPath expression is compared to the value. If the value is not an object, that part of the filter matches if and only if the result of the JSONPath expression exactly matches the value. If the value is an object, the key(s) in that object define how the value must match, such as “>” above (in addition to the obvious mathematical operators, options will probably include intersection, set membership, subset, nonexistence, and so forth).

Inside value objects and in the filter as a whole, multiple filters are “anded” together, and combined/derived filters may be created by nesting filters inside “and”, “or”, and “not”.

Note: to ensure portability and security, no ‘script expressions’ are allowed in JSONPath in a filter.

If you like what you’re reading, comment or otherwise get in touch. I hope to see this work eventually lead to a community standard that can be applied in many scenarios and across many platforms where statements flow.