[BE] Build endpoint for creating Competency Criteria

[thelmick-unicon]

Blocked by: #613 (5.1, the CBE data model) and 5.5 (a criterion attaches into a group that 5.5's endpoint creates; 5.5 also establishes the openedx-platform wiring this ticket's new route inherits). Confirmed against the openedx-core checkout: src/openedx_learning/ does not exist yet; there is no code for CompetencyCriterion anywhere in the repository. It exists only as approved design in ADR 0002 (docs/openedx_learning/decisions/0002-competency-criteria-model.rst:130-149).

Scope Split: This ticket covers core creation and baseline referential-integrity checks only. The three richer rules are tracked as a companion ticket, 5.6b.

Repo: openedx-core, single-repo.

Use Case

As a Platform Administrator, I want to create a Competency Criterion that associates a competency with a gradable subsection (aka assignment) in a course, stored under the correct Competency Criteria Group, so that this competency has a concrete rule the (future) evaluation pipeline can use to determine learner mastery.

Description

Current state

No endpoint exists today to create a CompetencyCriterion. Per ADR 0002, the model is a leaf node in a competency's criteria tree, stored in table CompetencyCriteria, with columns id, competency_criteria_group_id (FK to CompetencyCriteriaGroup), oel_tagging_objecttag_id (the tag/object association — this is how the criterion points at gradable content; there is no direct course or subsection FK), competency_rule_profile_id (nullable FK to CompetencyRuleProfile), rule_type_override, and rule_payload_override (both nullable, overriding the profile when set).

Requested change

A new endpoint, nested under an existing CompetencyCriteriaGroup, that creates a CompetencyCriterion:

• Resolves the target group from the URL and validates it belongs to the competency being associated (mirroring 5.5's parent-mismatch check).
• If the group is course-scoped (course_id set), validates the submitted course association matches that course.
• Accepts object_id (required) — a subsection-usage-key string identifying the gradable content, matching ObjectTag.object_id's existing opaque-string convention.Resolves-or-creates the underlying oel_tagging_objecttag association via a read-merge-write pattern (fetch the object's existing tags in that taxonomy, union in the new competency tag, call the existing tag_object() with the merged set) — never a raw replace, since tag_object()'s full-replace semantics would otherwise silently wipe out any other competency tag already on that object in the same taxonomy.
• Accepts optional competency_rule_profile_id, rule_type_override, rule_payload_override. It must accept either a competency_rule_profile_id or a rule_type_override and rule_payload_override.
• Reuses the can_change_taxonomy permission gating, scoped to the taxonomy owning the group's competency tag.

Explicitly out of scope

• Creating, updating, or deleting CompetencyCriteriaGroup rows (5.5 and 5.9).
• Listing or retrieving criteria/groups (5.7).
• Any UI (5.4/5.10).
• The three containment/isolation business rules — no duplicate competency along the same containment path; parent competency dominates scope over its children in a course branch; groups and courses as isolation boundaries. Tracked in the 5.6b stub. Low risk in the interim: no evaluation engine consumes this data yet, so a badly-shaped tree has no immediate blast radius.
• Course-level association — this ticket accepts a subsection-level object_id only.

Acceptance Criteria

These scenarios are verifiable via Postman.

Scenario: Create a Competency Criterion for a gradeable subsection association
  Given a valid Competency Criteria Group exists for a competency
  And the requesting user has can_change_taxonomy permission on that competency's taxonomy
  When a POST request is sent to the create-criteria endpoint with a valid group id and a valid gradeable subsection object_id
  Then the response returns status code 201
  And the response body includes the new criterion's "id", "competency_criteria_group_id", "oel_tagging_objecttag_id", and any supplied "rule_type_override" / "rule_payload_override"

Scenario: Reusing an object already tagged with a different competency preserves both tags
  Given a gradeable subsection is already tagged with competency A via a prior CompetencyCriterion
  When a POST request creates a criterion associating that same gradeable subsection with competency B
  Then the response returns status code 201
  And the gradeable subsection's object tags still include both competency A and competency B afterward

Scenario: Reject a group that does not belong to the specified competency
  Given a Competency Criteria Group exists for competency A
  When a POST request references competency B's context with that group's id
  Then the response returns status code 400
  And the response body identifies the group/competency mismatch

Scenario: Reject a gradeable subsection association that does not match the group's course scope
  Given a Competency Criteria Group is scoped to Course X
  When a POST request attempts to associate content from Course Y with that group
  Then the response returns status code 400
  And the response body identifies the course mismatch

Scenario: Reject creation with a missing or malformed object_id
  Given a POST request omits "object_id", or supplies a value that doesn't parse as a gradeable subsection key
  When the request is processed
  Then the response returns status code 400
  And the response body identifies the invalid or missing field

Scenario: Reject creation for a group that does not exist
  Given the referenced group id does not exist
  When a POST request is sent referencing that id
  Then the response returns status code 404

Scenario: Reject creation without permission
  Given the requesting user does not have can_change_taxonomy permission on the referenced competency's taxonomy
  When a POST request is sent to the create-criteria endpoint
  Then the response returns status code 403

Context

• 5.5: creates the CompetencyCriteriaGroup this ticket's criteria attach to; the can_change_taxonomy permission precedent and CreateAPIView + public-api.py-function pattern this ticket mirrors. 5.5 also adds the openedx-platform INSTALLED_APPS/cms/urls.py wiring that makes openedx_learning's REST API reachable from Studio at all — this ticket's new route registers inside the same rest_api/v1/urls.py 5.5 already wires in, so no additional openedx-platform file changes are needed here.
• ADR 0002 (docs/openedx_learning/decisions/0002-competency-criteria-model.rst:130-149, 228-263): canonical CompetencyCriterion field list; its worked example shows one object_id reused across multiple CompetencyCriterion rows without duplicating the tagging row — the reason this ticket uses read-merge-write rather than a raw tag-object replace.
• src/openedx_tagging/models/base.py:757-834 (ObjectTag): plain opaque object_id string field, unique_together on (object_id, taxonomy, tag) — no object-type discriminator or resolver exists; format validation is this ticket's job (via opaque_keys).
• src/openedx_tagging/api.py:176-214 (get_object_tags), :325-429 (tag_object, full-replace semantics per its own docstring) — the two public functions this ticket's read-merge-write logic composes.
• [BE] Implement CBE core data models (CompetencyTaxonomy, criteria, learner status) #613 (5.1): the model/migration this ticket depends on for implementation.
• 5.6b: the split-out companion ticket for the three deferred business rules.
• 5.4: the frontend course-search UI, the likely eventual caller of this endpoint — not designed here.
• 5.7: GET endpoint for groups + criteria, separate ticket.

Technical Notes

Files to Create

Conditional — check first whether 5.5 already created these:

File	Purpose
src/openedx_learning/applets/cbe/rest_api/v1/tests/test_views.py (extend if 5.5 created it)	view/permission/response-shape tests for criteria creation

Files to Modify

File	Nature of modification
src/openedx_learning/applets/cbe/api.py	add create_competency_criterion(group_id, object_id, competency_rule_profile_id=None, rule_type_override=None, rule_payload_override=None)
src/openedx_learning/applets/cbe/rest_api/v1/serializers.py	add CompetencyCriterionSerializer
src/openedx_learning/applets/cbe/rest_api/v1/views.py	add CompetencyCriterionCreateView(generics.CreateAPIView)
src/openedx_learning/applets/cbe/rest_api/v1/urls.py	register criteria-groups/<int:group_id>/criteria/

Implementation Notes

Build CompetencyCriterionCreateView(generics.CreateAPIView) at POST /cbe/rest_api/v1/criteria-groups/<int:group_id>/criteria/, mirroring 5.5's CreateAPIView-only, public-api.py-function pattern (perform_create calls create_competency_criterion(), never serializer.save() directly).

Request body: object_id (required string — a subsection UsageKey string
), plus optional competency_rule_profile_id, rule_type_override, rule_payload_override. The competency and taxonomy are never in the request body — both are derived from the group resolved via the URL's group_id.

Core creation steps:

1. Resolve CompetencyCriteriaGroup from group_id; 404 if missing.
2. Parse object_id via opaque_keys.edx.keys.UsageKey.from_string; 400 with a field-level error if it doesn't parse.
4. If the group's course_id is set, validate the parsed subsection’s parent course (parsed_key.course_key) matches it; 400 on mismatch.
5. Resolve-or-create the ObjectTag via read-merge-write: call get_object_tags(object_id, taxonomy_id=group.oel_tagging_tag.taxonomy_id), union the group's competency tag's value into the existing tag values for that object+taxonomy, call tag_object(object_id, taxonomy, tags=merged_values), then re-fetch the specific ObjectTag row for (object_id, taxonomy, tag) to get its id. Never call tag_object with only the new tag's value in isolation — that would replace, not add to, the object's existing tags in that taxonomy.
6. Create the CompetencyCriterion row: competency_criteria_group_id=group.id, oel_tagging_objecttag_id=<resolved>, plus any optional profile/override fields.
7. Return 201 with the created row's representation.

Permission class: reuse TaxonomyObjectPermissions/can_change_taxonomy, scoped to the taxonomy owning the group's competency tag — same precedent 5.5 established.

Explicitly not built here (tracked in 5.6b): any check that walks the criteria-group tree for containment-path duplicates, parent/child scope dominance, or cross-group/cross-course isolation. Structure create_competency_criterion() so a future _validate_containment(group, object_id) call can be inserted before step 5 without reshaping this function's signature.

Test strategy: unit tests for create_competency_criterion() (subsection-level object_id happy path, reuse of an existing ObjectTag across two groups — asserting both tags survive, rejection of an object_id that doesn’t parse as a UsageKey, group/competency mismatch, group/course mismatch) plus DRF integration tests (201/400/403/404).

Example Resolution Prompt

Implement ticket 5.6 (core creation only; containment validation is tracked separately in 5.6b). Assume 5.5 has landed src/openedx_learning/applets/cbe/api.py with create_competency_criteria_group(), the REST scaffolding (rest_api/v1/urls.py, views.py, serializers.py), and the openedx-platform wiring (INSTALLED_APPS, cms/urls.py include) — this ticket needs no further openedx-platform changes, only new code inside openedx-core. Assume #613/5.1 has
landed CompetencyCriteriaGroup and CompetencyCriterion models matching ADR docs/openedx_learning/decisions/0002-competency-criteria-model.rst:130-149.

Build:

1. src/openedx_learning/applets/cbe/api.py: add create_competency_criterion(group_id: int, object_id: str, competency_rule_profile_id: int | None = None, rule_type_override: str | None = None, rule_payload_override: dict | None = None) -> CompetencyCriterion. Resolve the CompetencyCriteriaGroup (raise on missing). Parse object_id via opaque_keys.edx.keys.UsageKey.from_string (raise ValueError if it doesn't parse). If group.course_id is set, validate the parsed subsection's parent course (parsed_key.course_key) matches it.
2. Resolve-or-create the ObjectTag using the read-merge-write pattern described above — call openedx_tagging.api.get_object_tags then openedx_tagging.api.tag_object with the merged tag set, never the new tag alone. Create and return the CompetencyCriterion row.
3. src/openedx_learning/applets/cbe/rest_api/v1/serializers.py: CompetencyCriterionSerializer(serializers.ModelSerializer) with a writable object_id field (serializer-only, not a model field on CompetencyCriterion) plus the optional override/profile fields. Do not expose competency_criteria_group_id or oel_tagging_objecttag_id as writable.
4. src/openedx_learning/applets/cbe/rest_api/v1/views.py: CompetencyCriterionCreateView(generics.CreateAPIView). In perform_create, resolve group_id from the URL kwarg and call api.create_competency_criterion(group_id, **serializer.validated_data). Reuse TaxonomyObjectPermissions, scoped to the taxonomy owning the group's competency tag.
5. src/openedx_learning/applets/cbe/rest_api/v1/urls.py: register path("criteria-groups/<int:group_id>/criteria/", views.CompetencyCriterionCreateView.as_view(), name="competency-criterion-create").

Return 201 on success; 400 if object_id doesn't parse as a subsection `UsageKey` or its parent course doesn't match the group's scope; 404 if the group doesn't exist; 403 if the caller lacks can_change_taxonomy. Do not implement containment/isolation-rule validation — that is 5.6b's scope, not this ticket's.

[thelmick-unicon]

The discussion period for this ticket is now complete, and we appreciate all the feedback. We'll be moving forward with development based on the current ticket pending final Axim sign-off. That said, the conversation doesn't have to stop. If you still have feedback, please continue to add to this ticket. We'll review anything new and determine whether it fits within the current timeline or makes more sense as its own ticket for future work. Thanks again for helping make this better!

@ormsbee This is ready for your review. Thank you!