Default values for facets and resetting all facets

[HadrienGardeur]

With the move to OPDS 2.0, we've cleaned up our approach for representing facets with three core concepts:

• a facet collection which contains metadata (title of the group) plus links (list of values available)
• each value is represented using a Link Object with an optional number of items expected to be available
• and we can also indicate which value is currently in-use using the self value in the rel of a Link Object

Here's what we have in our current draft for it:

{
  "facets": [
    {
      "metadata": {
        "title": "Language"
      },
      "links": [
        {
          "href": "/fr", 
          "type": "application/opds+json", 
          "title": "French", 
          "properties": { "numberOfItems": 10 }
        },
        {
          "href": "/en", 
          "type": "application/opds+json", 
          "title": "English", 
          "properties": { "numberOfItems": 40 }
        },
        {
          "href": "/de", 
          "type": "application/opds+json", 
          "title": "German", 
          "properties": { "numberOfItems": 6 }
        }
      ]
    }
  ]
}

Once a facet is selected by the user, the client follows the URI indicated in href. If I select French, this could result in a feed with the following facet for example:

{
  "facets": [
    {
      "metadata": {
        "title": "Language"
      },
      "links": [
        {
          "href": "/fr", 
          "rel": "self",
          "type": "application/opds+json", 
          "title": "French", 
          "properties": { "numberOfItems": 10 }
        },
        {
          "href": "/en", 
          "type": "application/opds+json", 
          "title": "English", 
          "properties": { "numberOfItems": 40 }
        },
        {
          "href": "/de", 
          "type": "application/opds+json", 
          "title": "German", 
          "properties": { "numberOfItems": 6 }
        }
      ]
    }
  ]
}

As you can see in this example, there's nothing here that allows to me reset the value of the current facet, this would need to be added by the catalog, for example with a value pointing to "All" :

{
  "facets": [
    {
      "metadata": {
        "title": "Language"
      },
      "links": [
        {
          "href": "/", 
          "type": "application/opds+json", 
          "title": "All", 
          "properties": { "numberOfItems": 56 }
        },
        {
          "href": "/fr", 
          "rel": "self",
          "type": "application/opds+json", 
          "title": "French", 
          "properties": { "numberOfItems": 10 }
        },
        {
          "href": "/en", 
          "type": "application/opds+json", 
          "title": "English", 
          "properties": { "numberOfItems": 40 }
        },
        {
          "href": "/de", 
          "type": "application/opds+json", 
          "title": "German", 
          "properties": { "numberOfItems": 6 }
        }
      ]
    }
  ]
}

Even with this addition, there's nothing that indicates to the client which value is actually the default one. This lack of information about default values for facets has a negative impact on the kind of UX/UI that OPDS clients can provide, since it limits what we can do with them.

For example, it has become fairly common to use what Google calls an input chip in Material Design 3 for such use cases where:

• a facet with an active option is displayed as a chip
• a dismiss icon (X) is available on the right of the chip to reset the facet to the default value
• tapping on the rest of the chip displays the other options available for that facet

Some mobile apps go even beyond that by allowing the user to dismiss all facets/filters that are currently active, for example by showing a dismiss action next to all active facets.

Example in Spotify

Example in Google Play Books

This concept has been explored in OPDS 1.x before by one of the oldest OPDS app out there called eBook Search where the default value for each facet is identified by a rel value, and a new link is also added to a catalog in order to reset all facets.

I think that there's some value in exploring that concept, either through a rel value or a new addition to properties.

[gotson]

It would be nice if facets could handle multiple selection. For example to select multiple languages in the above example, or to use multiple criterias at the same time.

This is an example of the filter panel in Komga:

Each section will show the available values, and allows for multiple selection within the section, or with other criterias.

[HadrienGardeur]

I see this as a separate need than knowing default values and being able to reset a facet or all facets.

The main issue with multi-select is the representation of the data: with links, we tend to follow a link after each facet is selected. This results in a feed where the facet groups or the list of link for a given facet group can change based on the value that you've selected.

Following the same approach for multi-value facets would be quite disruptive IMO and the ideal approach would be to express facets as a templated URI where each facet is a value that can be sent as a query parameter rather than a link.

I'm a bit wary of going down that road because it's a completely new approach for facets compared to what we have in OPDS 1.1+ and OPDS 2.0.
We could find a middle ground by simply telling the client that a given facet allows multiple values. This could look like this:

{
  "facets": [
    {
      "metadata": {
        "title": "Language",
        "type": "http://opds-spec.org/facet/multi-select"
      },
      "links": [
        {
          "href": "/", 
          "type": "application/opds+json", 
          "rel": "http://opds-spec.org/facet/default"
          "title": "All", 
          "properties": { "numberOfItems": 56 }
        },
        {
          "href": "/fr+en", 
          "rel": "self",
          "type": "application/opds+json", 
          "title": "French", 
          "properties": { "numberOfItems": 10 }
        },
        {
          "href": "/fr+en", 
          "rel": "self",
          "type": "application/opds+json", 
          "title": "English", 
          "properties": { "numberOfItems": 40 }
        },
        {
          "href": "/de", 
          "type": "application/opds+json", 
          "title": "German", 
          "properties": { "numberOfItems": 6 }
        }
      ]
    }
  ]
}

As you can see in this example:

• the facet clearly indicates that it allows multi-select through a well-known value for type in its metadata
• the default value is set to "All" for languages
• the values for "French" and "English" are both selected

There are a few things that bother me though:

• we end up with two active facets where the Link Objects have the same href
• when selecting a value (let's say "German") there's no guarantee that "German" will be selected at all in the resulting feed or that you'll receive any facet for "Language" at all
• deselecting a value is even more confusing in this use case, we would need to shake things up significantly to say that Link Objects marked as "active" with the self value for rel provide a href to deselect the current value
• and if we go down that path, using self to identified the current active facet becomes very confusing IMO

We would end up with something like that:

{
  "links": [
    {
      "rel": "self",
      "type": "application/opds+json"
      "href": "https://example.com/fr+en"
    }
  ],
  "facets": [
    {
      "metadata": {
        "title": "Language",
        "type": "http://opds-spec.org/facet/multi-select"
      },
      "links": [
        {
          "href": "/", 
          "type": "application/opds+json", 
          "rel": "http://opds-spec.org/facet/default"
          "title": "All", 
          "properties": { "numberOfItems": 56 }
        },
        {
          "href": "/en", 
          "rel": "http://opds-spec.org/facet/active",
          "type": "application/opds+json", 
          "title": "French", 
          "properties": { "numberOfItems": 10 }
        },
        {
          "href": "/fr", 
          "rel": "http://opds-spec.org/facet/active",
          "type": "application/opds+json", 
          "title": "English", 
          "properties": { "numberOfItems": 40 }
        },
        {
          "href": "/de", 
          "type": "application/opds+json", 
          "title": "German", 
          "properties": { "numberOfItems": 6 }
        }
      ]
    }
  ]
}

[HadrienGardeur]

Here's my proposal for handling both default values in a facet group and resetting everything: we introduce a single new rel value that we use for the default value in a facet group or for resetting all facets in a feed.

Since we already had http://opds-spec.org/facet in OPDS 1.x, I suggest using http://opds-spec.org/facet/default.

Here's an example of the way this could be used in a feed:

{
  "links": [
    {
      "href": "/",
      "rel": "http://opds-spec.org/facet/default", 
      "type": "application/opds+json"
    }
  ],
  "facets": [
    {
      "metadata": {
        "title": "Sort",
        "type": "http://opds-spec.org/facet/sort"
      },
      "links": [
        {
          "href": "/fr",
          "rel": "http://opds-spec.org/facet/default", 
          "type": "application/opds+json", 
          "title": "Most popular"
        },
        {
          "href": "/new/fr", 
          "rel": "self",
          "type": "application/opds+json", 
          "title": "New releases"
        }
      ]
    },
    {
      "metadata": {
        "title": "Language"
      },
      "links": [
        {
          "href": "/new",
          "rel": "http://opds-spec.org/facet/default", 
          "type": "application/opds+json", 
          "title": "All", 
          "properties": { "numberOfItems": 56 }
        },
        {
          "href": "/new/fr", 
          "rel": "self",
          "type": "application/opds+json", 
          "title": "French", 
          "properties": { "numberOfItems": 10 }
        },
        {
          "href": "/new/en", 
          "type": "application/opds+json", 
          "title": "English", 
          "properties": { "numberOfItems": 40 }
        },
        {
          "href": "/new/de", 
          "type": "application/opds+json", 
          "title": "German", 
          "properties": { "numberOfItems": 6 }
        }
      ]
    }
  ]
}

In this example:

• we have two facets: one for sorting results and another one for filtering by language
• the default values for these facets are: most popular and all languages
• the current values for these facets are: new releases and French
• with the new rel value I could reset the sort facet to its default value: most popular
• I can also reset the language facet to its default value: all languages
• or I can reset both facets to their default values