Skip to content

feat: return taxonomy_type on the object tags endpoint - #39259

Merged
mgwozdz-unicon merged 4 commits into
openedx:masterfrom
ufedaseyeuconsultant:ufedaseyeu/783-returning-taxonomy-type-ontag-object-get-endpoint
Nov 16, 2026
Merged

mgwozdz-unicon merged 4 commits into
openedx:masterfrom
ufedaseyeuconsultant:ufedaseyeu/783-returning-taxonomy-type-ontag-object-get-endpoint

Conversation

@ufedaseyeuconsultant

@ufedaseyeuconsultant ufedaseyeuconsultant commented Oct 19, 2026 •

Copy link
Copy Markdown
Contributor

Description

Closes openedx/openedx-core#783.

GET /api/content_tagging/v1/object_tags/{object_id}/ returns a content object's tags grouped by taxonomy. Each taxonomy entry in that response now has a taxonomy_type field. Its value is "competency" when the taxonomy is a competency taxonomy and "tags" otherwise. The same field already exists on the taxonomy endpoints (openedx/openedx-core#618), and it uses the same values. The Course Outline and Libraries pages read this endpoint through the shared content-tags-drawer module of frontend-app-authoring. They need the field to hide the remove control on competency tags (openedx/openedx-core#784).

{"block-v1:...": {"taxonomies": [
  {"name": "Nursing Competencies", "taxonomy_id": 7, "export_id": "nursing-competencies",
   "can_tag_object": true, "taxonomy_type": "competency", "tags": [...]}
]}}

How it works

  • ObjectTagOrgByTaxonomySerializer.to_representation() calls the base openedx_tagging serializer. It then adds taxonomy_type to each taxonomy entry, using the CBE public API is_competency_taxonomy and the TaxonomyType enum, exactly as TaxonomyOrgSerializer does. The rule appears in two places, so I called the same check directly rather than extracting a shared helper. A third caller would justify the helper.
  • is_competency_taxonomy checks whether the taxonomy has a competency row, and without a join that check costs one query per taxonomy. So the serializer collects the taxonomy ids of the object tags, loads those taxonomies once through the CBE public helper select_competency_taxonomies(), and records which ids is_competency_taxonomy reports as competency. The check costs one query per response, whatever the number of taxonomies. For an untagged object the id set is empty, and Django runs no query.
  • PUT on the same endpoint returns its result through the same retrieve path, so its response includes the field too.
  • The ObjectTagOrgView docstring names taxonomy_type and its two values.
  • Nothing in openedx_tagging or the CBE app changes, per openedx-core ADR 0013.

Who is affected

Supporting information

Testing instructions

Automated, from a CMS test environment:

pytest --no-cov --ds=cms.envs.test \
  openedx/core/djangoapps/content_tagging/rest_api/v1/tests/test_views.py -k TestObjectTagViewSet

The new tests in TestObjectTagViewSet:

  • A competency taxonomy's entry reports "competency". An ordinary taxonomy's entry reports "tags".
  • An object tagged from both kinds reports each type on its own entry.
  • An untagged object returns exactly {"<object_id>": {"taxonomies": []}}.
  • A PUT that tags an object from a competency taxonomy returns "competency" on that entry.
  • An object tagged from 3 taxonomies, one of them competency, takes the same number of queries as an object tagged from 1.
  • The existing full-entry assertions in test_get_tags and test_get_copied_tags now expect the extra key. Every other existing key and value is unchanged. Every case of test_object_tags_query_count expects one more query, the competency check.

Manual:

  1. In Studio, create a competency taxonomy and an ordinary taxonomy, each available to the course's org, and tag a unit from both.
  2. GET /api/content_tagging/v1/object_tags/<usage_key>/ as a course author.
  3. Each taxonomy entry has taxonomy_type. It reads "competency" for the competency taxonomy and "tags" for the other one. All other fields are as before.

Deadline

None.

Other information

  • This depends on openedx-core with the CBE public API (is_competency_taxonomy and select_competency_taxonomies). The pinned openedx-core 1.23.0 already has both.
  • No migrations. Only the response gains a field.
  • Pre-existing, not changed here: on this endpoint, each taxonomy owned by a specific org (as opposed to one available to all orgs) costs extra queries. The can_tag_object permission check runs once per taxonomy, and the prefetch loads the taxonomy's ownership rows but not their organizations, so each org-owned taxonomy fetches its organization separately. The count is the same with and without this PR. So the new query-count test uses taxonomies available to all orgs, which measures only the cost of taxonomy_type. I propose a follow-up issue for the org-owned cost, described in a comment below.

🤖 Generated with Claude Code

@openedx-webhooks openedx-webhooks added the open-source-contribution PR author is not from Axim or 2U label Oct 19, 2026
@openedx-webhooks

Copy link
Copy Markdown

Thanks for the pull request, @ufedaseyeuconsultant!

This repository is currently maintained by @openedx/wg-maintenance-openedx-platform-oncall.

Once you've gone through the following steps feel free to tag them in a comment and let them know that your changes are ready for engineering review.

🔘 Get product approval

If you haven't already, check this list to see if your contribution needs to go through the product review process.

  • If it does, you'll need to submit a product proposal for your contribution, and have it reviewed by the Product Working Group.
    • This process (including the steps you'll need to take) is documented here.
  • If it doesn't, simply proceed with the next step.
🔘 Provide context

To help your reviewers and other members of the community understand the purpose and larger context of your changes, feel free to add as much of the following information to the PR description as you can:

  • Dependencies

    This PR must be merged before / after / at the same time as ...

  • Blockers

    This PR is waiting for OEP-1234 to be accepted.

  • Timeline information

    This PR must be merged by XX date because ...

  • Partner information

    This is for a course on edx.org.

  • Supporting documentation
  • Relevant Open edX discussion forum threads
🔘 Get a green build

If one or more checks are failing, continue working on your changes until this is no longer the case and your build turns green.

Details
Where can I find more information?

If you'd like to get more details on all aspects of the review process for open source pull requests (OSPRs), check out the following resources:

When can I expect my changes to be merged?

Our goal is to get community contributions seen and reviewed as efficiently as possible.

However, the amount of time that it takes to review and merge a PR can vary significantly based on factors such as:

  • The size and impact of the changes that it introduces
  • The need for product review
  • Maintenance status of the parent repository

💡 As a result it may take up to several weeks or months to complete a review and merge your PR.

@ufedaseyeuconsultant

Copy link
Copy Markdown
Contributor Author

While writing the query-count test for this PR, I found a pre-existing N+1 on the same endpoint, and I'd like to open a follow-up issue for it rather than fix it here.

What happens. GET /api/content_tagging/v1/object_tags/{object_id}/ runs the can_tag_object permission check once per taxonomy. For a taxonomy owned by a specific org, that check reads the organization on each of the taxonomy's ownership rows (TaxonomyOrg.get_organizations, called from check_taxonomy_context_key_org in content_tagging/utils.py). The filter backend prefetches taxonomy__taxonomyorg_set but not __org, so each org-owned taxonomy fetches its organization in a separate query. Taxonomies available to all orgs exit the check early and cost nothing.

Measured on master, with and without this PR, same results. One course, as staff, after a warm-up request: 1, 3, and 3 all-org taxonomies (one of them competency) each take 10 queries. One org-owned taxonomy takes 12, alone or next to an all-org one. I haven't measured two or more org-owned taxonomies yet.

Where it comes from. #34200 added the loop over prefetched taxonomyorg_set and the prefetch without __org. #34270 then put that lookup on the can_tag_object path.

Proposed fix, for the follow-up. Change the three prefetch_related('taxonomy__taxonomyorg_set') calls in ObjectTagTaxonomyOrgFilterBackend to 'taxonomy__taxonomyorg_set__org'. TaxonomyOrgView already does this. Then confirm that the all-orgs list in TaggingRulesCache loads once per request, and add a query-count test over several org-owned taxonomies.

Why not in this PR. The cost comes from the permission check and the filter backend, not from taxonomy_type. Fixing it changes permission-path code and possibly the existing query-count numbers, and that is easier to review on its own. This PR's own query-count test uses all-org taxonomies so that it measures only what taxonomy_type adds.

Does that sound reasonable? If so, I'll open the issue and link it.

@mphilbrick211 mphilbrick211 moved this from Needs Triage to Ready for Review in Contributions Oct 22, 2026

@jesperhodge jesperhodge left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hi @ufedaseyeuconsultant ,

looks great. Manual testing worked.

I find your observation of the N+1 query very observant. Please open an issue and PR for it in our project.

AI found only one really small issue and a few nits:

"

Must fix before merge

The change depends on an internal detail of another library that an accepted design decision says this project must not depend on.

Details

In ObjectTagOrgView.get_queryset (openedx/core/djangoapps/content_tagging/rest_api/v1/views.py) the queryset gets .select_related("taxonomy__competencytaxonomy"). ADR 0013 says openedx-platform must reach this relation only through the CBE app's public API, and this string is the only place competencytaxonomy appears in openedx-platform; TaxonomyOrgView on master uses select_competency_taxonomies(). Your code comment is accurate that the helper only accepts a Taxonomy queryset and this one holds ObjectTag rows.

Two things soften the risk without removing it. A rename upstream would make Django raise FieldError here, so the platform tests would fail at the pin bump rather than silently. But the join only prevents the per-taxonomy query because is_competency_taxonomy happens to be implemented as hasattr on that accessor; if openedx-core reimplemented the helpers, the join would stop helping and only your new query-count test would notice. The PR body also cites the taxonomy__taxonomyorg_set prefetch as the same pattern, but TaxonomyOrg is openedx-platform's own model, so the precedent does not apply.

Pick one:

Option Extra queries per request Follows ADR 0013 Work outside this PR
B. Batch the check in the serializer: collect the entries' non-null taxonomy_id values, run select_competency_taxonomies(Taxonomy.objects.filter(pk__in=ids)) once, record which pks is_competency_taxonomy says are competency, and delete the view override. One, whatever the number of taxonomies. Django skips it for an empty id set. Yes None. Expected numbers in test_object_tags_query_count go up by one for the cases with tags.
C. Add a CBE API variant in openedx-core that takes a lookup prefix or an ObjectTag queryset, and use it here. None Yes, and the ADR expects this growth An openedx-core release and a pin bump. Correct #783's wording to match the ADR.
A. Keep the code. None No, an explicit exception None, but the get_queryset comment should say it is an exception and link a follow-up issue for option C, and the "same pattern" sentence should leave the PR body.

Option B is the smallest change that follows the ADR. It also removes the hidden dependency the serializer docstring warns about ("costs no extra query only if the taxonomies were loaded with their competency row joined, as ObjectTagOrgView does"). A Prefetch on taxonomy with a custom queryset does not work, because get_object_tags() already uses select_related("taxonomy") and Django skips a prefetch for an already-cached relation.

Improvements worth doing

One new test checks less of the response than the acceptance criterion it covers.

Details

test_get_tags_untagged_object asserts that the helper's return value, response.data[object_id]["taxonomies"], is empty. The criterion says the response "contains no taxonomy type information". The test did fail when the review made the serializer emit an entry for an untagged object, so the criterion counts as covered, but it cannot see anything outside that list. Assert the whole payload: response.data == {str(self.courseA): {"taxonomies": []}}.

A claim in the pull request description has no test behind it.

Details

The PR body says PUT responses include the field because update returns through retrieve. The review confirmed it by reading the base view and by a throwaway PUT that returned taxonomy_type: "competency"; removing the join added exactly one query per taxonomy on PUT too. Add one PUT assertion on taxonomy_type.

A defensive check handles a state this endpoint cannot produce, and its comment gives an incomplete reason.

Details

In the new to_representation, taxonomy is not None and is_competency_taxonomy(taxonomy) carries the comment "A tag whose taxonomy was deleted has no taxonomy, so it can't be a competency". The model facts are right. But get_object_tags() excludes tags with taxonomy=None unless asked for deleted ones, and the view never asks. The review tagged a course, deleted the taxonomy, and fetched the tags as two different users: the response was {"taxonomies": []}. The commit message for e607ed3c1d says the guard also keeps mypy happy, which the comment omits, and the comment sits above the dictionary lookup rather than the guard. Either drop the guard and comment, or keep the guard and reword the comment to its real reason (type narrowing, and safety for a direct serializer call) on the guard's line.

The endpoint's documentation does not mention the new field.

Details

ObjectTagOrgView's docstring says "Refer to ObjectTagView docstring for usage details." That base docstring lists each entry's taxonomy_id, can_tag_object, and tags, and under ADR 0013 it can never list taxonomy_type. Add one sentence naming taxonomy_type and its two values.

Two of the three new tests for the field's values fail only when the third also fails.

Details

Every break that failed test_get_tags_taxonomy_type_competency or test_get_tags_taxonomy_type_ordinary also failed test_get_tags_taxonomy_type_mixed. The three map one-to-one to the ticket's first three scenarios, which has traceability value, so keeping them is defensible. To have fewer tests, keep the mixed one and name it after criteria 1 to 3.

@ufedaseyeuconsultant
ufedaseyeuconsultant force-pushed the ufedaseyeu/783-returning-taxonomy-type-ontag-object-get-endpoint branch from ff9abd3 to 036797c Compare October 29, 2026 19:23
@ufedaseyeuconsultant

Copy link
Copy Markdown
Contributor Author

@jesperhodge
Rebased onto current master. The merge commit from master is gone, and the branch now has the two feature commits plus one fix commit.

ADR 0013 dependency (must fix). Went with option B. ObjectTagOrgByTaxonomySerializer.to_representation() now collects the non-null taxonomy_id values of the object tags and loads those taxonomies once with select_competency_taxonomies(Taxonomy.objects.filter(pk__in=ids)). It then records which pks is_competency_taxonomy reports as competency. The ObjectTagOrgView.get_queryset() override and its taxonomy__competencytaxonomy path are deleted, so competencytaxonomy no longer appears in openedx-platform. The serializer docstring no longer says the check depends on how the view loaded the taxonomies. Every case of test_object_tags_query_count expects one more query. When I put back a per-taxonomy check instead of the batch, all 14 query-count tests fail, which includes the new one comparing 1 and 3 taxonomies. I also removed the "same pattern" sentence from the PR body.

Untagged-object test. test_get_tags_untagged_object now asserts the whole payload: response.data == {str(self.courseA): {"taxonomies": []}}.

PUT claim. Added test_put_tags_response_includes_taxonomy_type. It tags the course from a competency taxonomy through PUT and asserts "competency" on that entry.

Defensive check on a deleted taxonomy. Gone, together with its comment. The batch only collects non-null taxonomy ids, so a tag without a taxonomy simply reports "tags", and there is no None left for mypy to narrow.

Endpoint docs. The ObjectTagOrgView docstring now names taxonomy_type and its two values, "competency" and "tags".

Three value tests. I kept them, since each maps to one of the ticket's first three scenarios.

N+1 on org-owned taxonomies. I'll open the issue.

@jesperhodge jesperhodge left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ufedaseyeuconsultant awesome work!

In the future, if you could make sure that you have a separate commit for the review fixes so I can tell what happened after the review instead of before, that would be amazing.

@mphilbrick211 mphilbrick211 moved this from Ready for Review to In Eng Review in Contributions Nov 4, 2026
@ufedaseyeuconsultant
ufedaseyeuconsultant force-pushed the ufedaseyeu/783-returning-taxonomy-type-ontag-object-get-endpoint branch from 036797c to 9aefb8b Compare November 7, 2026 18:22

@mgwozdz-unicon mgwozdz-unicon left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@ufedaseyeuconsultant the change itself looks good: it follows ADR 0013, every acceptance criterion of openedx/openedx-core#783 has a test behind it, and CI is green. Following are the findings from my and Claude's review:

  1. Merge conflict in rest_api/v1/serializers.py. #39369 changed the COURSES_MANAGE_TAGS import on master, on the line next to the import this PR extends. Please rebase, keeping from openedx_authz.authz import COURSES_MANAGE_TAGS from master and your from openedx_learning.api import is_competency_taxonomy, select_competency_taxonomies.

  2. test_get_tags_query_count_independent_of_taxonomy_type_check takes a roundabout path to its assertion. The loop over two courses, the list of counts, and query_counts[0] == query_counts[1] make the reader work out which course has one taxonomy and which has three. Counting the queries for the same object twice, once with one taxonomy and once after adding two more, and then comparing two named counts, reads more directly. A sketch is below. I have not run it. With it, the user parameter of _get_taxonomy_entries has no caller and can go.

def test_get_tags_query_count_independent_of_taxonomy_type_check(self):
    """
    The query count does not grow with the number of taxonomies, competency ones included.

    All taxonomies here are all-org on purpose. For org-owned taxonomies, ``can_tag_object`` makes its own
    organization lookups, a separate cost that this test leaves out so it isolates the cost of ``taxonomy_type``.
    """
    object_id = str(self.courseA)
    url = OBJECT_TAGS_URL.format(object_id=object_id)
    self.client.force_authenticate(user=self.staff)
    tagging_api.tag_object(object_id=object_id, taxonomy=self.t1, tags=["android"])
    self.client.get(url)  # Warm up the site and waffle flag caches, as test_object_tags_query_count does.
    with CaptureQueriesContext(connection) as queries_with_one_taxonomy:
        self.client.get(url)

    competency = self._create_competency_taxonomy()
    extra = tagging_api.create_taxonomy(name="Extra all-org taxonomy", enabled=True)
    Tag.objects.create(taxonomy=extra, value="Extra")
    TaxonomyOrg.objects.create(taxonomy=extra, org=None, rel_type=TaxonomyOrg.RelType.OWNER)
    tagging_api.tag_object(object_id=object_id, taxonomy=competency, tags=["Triage"])
    tagging_api.tag_object(object_id=object_id, taxonomy=extra, tags=["Extra"])

    with CaptureQueriesContext(connection) as queries_with_three_taxonomies:
        response = self.client.get(url)

    assert len(response.data[object_id]["taxonomies"]) == 3
    assert len(queries_with_three_taxonomies) == len(queries_with_one_taxonomy)
  1. if obj_tag.taxonomy_id is not None in ObjectTagOrgByTaxonomySerializer.to_representation guards a state this endpoint cannot produce. get_object_tags excludes tags whose taxonomy was deleted unless the caller asks for them, and this view never does. Please drop the condition.

  2. The to_representation docstring says what the code does and leaves out why. The second paragraph could be one sentence giving the reason for the batch: is_competency_taxonomy costs one query per taxonomy unless the taxonomies are loaded through select_competency_taxonomies. That is what stops a later reader from simplifying it back into a per-taxonomy check.

  3. PR description. It says the pinned openedx-core is 1.17.0, and the pin on this branch is 1.21.0.

ufedaseyeuconsultant and others added 4 commits November 16, 2026 19:09
Each taxonomy entry returned by GET /api/content_tagging/v1/object_tags/{object_id}/
now carries taxonomy_type ("competency" or "tags"), computed with the CBE
public API is_competency_taxonomy, the same way TaxonomyOrgSerializer does.
ObjectTagOrgView joins each taxonomy's competency row so the check adds no
per-taxonomy query.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
ObjectTag.taxonomy is nullable, since deleting a taxonomy leaves its tags
with no taxonomy. Report such entries as "tags", which also satisfies mypy.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
ObjectTagOrgView joined taxonomy__competencytaxonomy into its queryset,
reaching a CBE model relation directly, which ADR 0013 rules out. The
serializer now loads the object tags' taxonomies once through
select_competency_taxonomies() and asks is_competency_taxonomy() which
of them are competency taxonomies, so the check is one query per
response, and none for an untagged object. The view override is gone.

Also document taxonomy_type on ObjectTagOrgView, assert the whole
payload for an untagged object, and cover taxonomy_type on PUT.

Co-Authored-By: Claude Opus 5.5 <[email protected]>
The query-count test now requests the same object before and after
adding a competency taxonomy and an all-org taxonomy to it, and
asserts the query count is unchanged. The earlier version compared
two different objects, so differences between the objects could hide
a per-taxonomy query.

The serializer no longer skips tags without a taxonomy. The object
tags endpoint never returns them, because the object-tag lookup
excludes tags whose taxonomy was deleted and this view does not ask
for them.

The to_representation docstring now gives the reason for the batch:
is_competency_taxonomy costs one query per taxonomy unless the
taxonomies are loaded through select_competency_taxonomies.

Co-authored-by: Mary Gwozdz <[email protected]>
Co-Authored-By: Claude Fable 5 <[email protected]>
@ufedaseyeuconsultant
ufedaseyeuconsultant force-pushed the ufedaseyeu/783-returning-taxonomy-type-ontag-object-get-endpoint branch from 9aefb8b to 87ade87 Compare November 16, 2026 16:18
@ufedaseyeuconsultant

Copy link
Copy Markdown
Contributor Author

@mgwozdz-unicon Done

@mgwozdz-unicon mgwozdz-unicon left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you!

@mgwozdz-unicon
mgwozdz-unicon merged commit 449f6c4 into openedx:master Nov 16, 2026
42 checks passed
@github-project-automation github-project-automation Bot moved this from In Eng Review to Done in Contributions Nov 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

open-source-contribution PR author is not from Axim or 2U

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

[BE] Return taxonomy type on the per-object tag endpoint

4 participants