Opal Categories API

## Overview Categories are in a tree: a given category has zero or more ancestors and zero or more descendants. The tree is built by recursively following `parent_category` relationships. Currently our trees are at most two nodes deep (that is, a root with zero or more leaves), but clients **MUST** be able to handle trees of any depth. ### Category type and custom fields Categories can be associated with [Category Types](/api/documentation/v3#tag/Category-Types), determining which [Custom Fields](/api/documentation/v3#tag/Custom-Fields) are available to [Blocks](/api/documentation/v3#tag/Blocks) in the category. If the category has a relationship with a deactivated category type it is considered to have no category type. ### Effective category type The effective category type allows the category to inherit a category type relationship. *Note:* The following description of the algorithm is informational: clients that want the effective category type **MUST** use the `effective_category_type_id` property in the category resource object’s `meta` information, and **MUST NOT** manually compute the value using this algorithm, as the exact behavior may change without warning. If the given category has a relationship with an active (not deactivated, not deleted) category type that is the effective category type. If the given category does *not* have a relationship with an active category type, any ancestors that have a relationship with an active category type are selected, and the nearest ancestor (the ancestor with the largest `depth`) provides the effective category type. If the given category has no ancestors, or none of its ancestors have a relationship with an active category type, *and* the view *does* have a relationship to an active category type, the view’s category type is the effective category type. If none of the above conditions are met, the category does not have an effective category type. *Note*: The behavior doesn’t change based on where the given category is in the tree — the logic is the same for the root, leaves, and everything in-between. This is why the following table refers to ‘parent’ and ‘grandparent’, rather than using tree terminology. In the following * ‘✓’ means the column’s entry is associated to an active category type * the parent and grandparent demonstrate inheritance behavior if the given category has ancestors with an associated active category type | view | grandparent category | parent category | given category | effective category type comes from… | | :----: | :--------------------: | :---------------: | :--------------: | -------------------- | | | | | ✓ | given | | | | ✓ | ✓ | given | | | ✓ | | ✓ | given | | ✓ | | | ✓ | given | | | | ✓ | | parent | | | ✓ | ✓ | | parent | |✓ | | ✓ | | parent | | | ✓ | | | grandparent | | ✓ | ✓ | | | grandparent | | ✓ | | | | view | | | | | | 🚫 (no category type) |