[AShatsila]

Description

Closes #814.

An archived tag still holds its value and external_id, because the per-taxonomy unique constraints include archived rows. Before this change, creating or importing a tag with such a value failed with a plain "already exists" message that pointed at a tag the administrator cannot see, and an import could update or revive the archived tag. This PR makes create and import refuse those collisions with a message that names the cause, and pins that export and re-import leave archived tags out.

Stacked PR. This PR is stacked on #856 (#776, adds Tag.archived) and tbain#1 (#778, hides archived records from read paths and export). Until those two merge, the diff also shows their seven commits. The #814 change is only the last four commits, 2c8b34d through 78e19ac: compare view. #778 keeps its own PR and is reviewed there.

What changes

Create a tag (Taxonomy.add_tag, and the REST serializer's validate_tag_value):

• A value held by an archived tag is refused with Tag value '<value>' belongs to an archived tag in this taxonomy. Use a different value. The serializer returns the same text in its own quoting style.
• An external_id held by an archived tag is refused with Tag external_id '<id>' belongs to an archived tag in this taxonomy. Use a different external_id.
• A value or external_id held by an unarchived tag keeps its existing message byte for byte.
• Adding a tag under an archived tag, or under a tag below one, is refused with Cannot add a tag under the archived tag '<value>'.

Import (TagImportPlan.generate_actions):

• A new plan-level validator checks every row's value, id, previous_id and parent_id. A row that points at an archived tag, or at a tag under one, produces an ArchivedTagCollisionError, for example Row 2's value (Photosynthesis) belongs to an archived tag in this taxonomy. Use a different value. When any row fails, the plan builds no actions, so nothing is imported.
• The match runs in the database, not in Python. The import actions look rows up through the column collation, so the guard must use the same comparison. MySQL's utf8mb4_unicode_ci also ignores accents and trailing spaces, which Python's casefold() does not. A parity test asserts that the plan's verdict equals the database's for Straße/STRASSE and Café/Cafe.
• A replace import (replace=True) never deletes an archived tag or any tag under it. The export leaves that subtree out, so its absence from the file is no reason to delete it. An archived tag whose unarchived parent is deleted is moved to the root, as any kept child already is.

Export: no code change. Tests pin that JSON and CSV exports omit archived tags (#778's behavior), that an export imports cleanly into an empty taxonomy, and that a replace re-import of a taxonomy's own export keeps its archived subtrees.

Decisions beyond the ticket

The ticket's acceptance criteria cover archived tags themselves. Three rules were added during implementation and review. Please push back on any of them:

1. A tag under an archived tag is treated as outside the taxonomy, just like the archived tag. The export and the replace sweep already treated the subtree that way, so the guard and add_tag now agree with them.
2. A replace import keeps archived subtrees instead of deleting them.
3. A parent_id or previous_id that points at an archived tag is a plan error.

Open questions for reviewers

• Message copy. The approved thread on [Arch] Implementation approach for competency data delete/edit guardrails #655 suggested telling the administrator to "contact an operator to manually un-archive it". This PR uses "Use a different value", because no restore path exists yet. The ticket asks for copy review, so please confirm or suggest wording.
• Replace-import deletes after [BE] Branch tag and taxonomy deletes between archiving and hard delete #780. [BE] Branch tag and taxonomy deletes between archiving and hard delete #780 makes delete_tags() archive a tag instead of deleting it when something depends on it. A replace import deletes through its own DeleteTag action, which [BE] Branch tag and taxonomy deletes between archiving and hard delete #780 does not mention, so after [BE] Branch tag and taxonomy deletes between archiving and hard delete #780 a replace import could still hard-delete a depended-upon tag. Should [BE] Branch tag and taxonomy deletes between archiving and hard delete #780's scope cover import, or should this get its own issue?
• Reading of AC 8. The round-trip test reads "contains only the tags that were not archived" as "contains only what the export holds". Under that reading, an unarchived tag under an archived tag is absent from the result, because [BE] Exclude archived tagging records from read paths and block edits to them #778's export leaves it out. Please confirm.
• ADR. No tagging ADR describes archiving yet. It may be worth a proposed ADR at the level of [Arch] Implementation approach for competency data delete/edit guardrails #655 that states the rules across [BE] Add an archived field to Tag, Taxonomy, and ObjectTag, and a deletion_locked field to ObjectTag #776, [BE] Exclude archived tagging records from read paths and block edits to them #778, [BE] Branch tag and taxonomy deletes between archiving and hard delete #780 and this PR. That would be a separate docs PR and does not block this one.

Known limits, not addressed here

• When a row points at an archived tag, the plan stops before other plan-level checks, so errors such as cycles show up only after the archived rows are fixed.
• One row that matches an archived tag on both value and id gets two errors.
• Renaming a tag to an archived value through the Python method Taxonomy.update_tag raises an IntegrityError. This predates the change and is outside [BE] Treat an archived tag as no longer part of its taxonomy on create, import, and export #814. The REST rename path is covered by the serializer.

Testing instructions

pytest tests/openedx_tagging --no-cov -q

Locally on SQLite: 705 passed. mypy, pylint, pycodestyle, isort and lint-imports are clean, and makemigrations --check reports no changes. MySQL was not run locally, so the MySQL collation cases rely on CI.

Manual check through the API, with a taxonomy that has an archived tag Photosynthesis:

1. POST /tagging/rest_api/v1/taxonomies/<id>/tags/ with {"tag": "Photosynthesis"} returns 400 with the archived-tag message.
2. Importing a JSON file that contains a tag with value Photosynthesis fails, the import log lists the archived-tag error, and the taxonomy is unchanged.
3. Exporting the taxonomy does not list Photosynthesis.

AI usage

The implementation, tests, and this description were written with Claude Code (Claude Opus 5.5), and reviewed and directed by the author. The change was reviewed by separate AI review passes before opening.

🤖 Generated with Claude Code

[openedx-webhooks]

Thanks for the pull request, @AShatsila!

This repository is currently maintained by @axim-engineering.

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:

• Overview of Review Process for Community Contributions
• Pull Request Status Guide
• Making changes to your pull request

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.

[mgwozdz-unicon]

Claude flagged this while I was looking into why #814 was inccorectly tagged as a frontend ticket. FYI @tbain for your review:

The PR description looks like it was carried over from the #778 work and not updated for the #814 commits on top of it. Three places disagree with the code in this branch:

• "Closes [BE] Exclude archived tagging records from read paths and block edits to them #778" is the only closing reference, but the title and branch are for [BE] Treat an archived tag as no longer part of its taxonomy on create, import, and export #814, and the last four commits implement [BE] Treat an archived tag as no longer part of its taxonomy on create, import, and export #814's acceptance criteria: the archived-specific error on create, refusing import rows that match an archived tag, and the export-then-import round-trip test.
• "Related" lists [BE] Treat an archived tag as no longer part of its taxonomy on create, import, and export #814 as separate work that "covers creating or importing over an archived tag's value", but this PR does that work.
• "Known gaps" says "Importing into an active taxonomy can still rename or re-parent an archived tag in it ([BE] Treat an archived tag as no longer part of its taxonomy on create, import, and export #814)", which the commit "refuse import rows that point at an archived tag" fixes.

@AShatsila Could you update the description so it matches what the branch delivers? Either "Closes #778 and closes #814" with the #814 behavior described alongside the #778 behavior, or, if you'd rather keep the two tickets reviewable on their own, split the #814 commits into a second PR stacked on this one. I lean toward the single PR since the #814 import changes build directly on the unarchived() queryset and import plan changes here, but either works.