feat(subsequences): add OpenAPI schema for advanded features DEV-1230 #6547

Guitlle · 2025-12-12T06:47:56Z

🗒️ Checklist

run linter locally
update developer docs (API, README, inline, etc.), if any
for user-facing doc changes create a Zulip thread at #Support Docs Updates, if any
draft PR with a title <type>(<scope>)<!>: <title> DEV-1234
assign yourself, tag PR: at least Front end and/or Back end or workflow
fill in the template below and delete template comments
review thyself: read the diff and repro the preview as written
open PR & confirm that CI passes & request reviewers, if needed
delete this section before merging

📣 Summary

Add OpenAPI schema for the /api/v2/assets/{uid_asset}/advanced-features/ endpoint.

📖 Description

The API schema output files and the generated Orval types have been updated with the schema details for the action parameters in the QuestionAdvancedFeature model.

… dev-1230-openapi-schema-for-advanded-features

Signed-off-by: Guillermo <[email protected]>

noliveleger · 2025-12-13T18:25:11Z

kobo/apps/subsequences/views.py

    open_api_201_created_response,
 )
 from kpi.utils.viewset_mixins import AssetNestedObjectViewsetMixin
+from kpi.versioning import APIV2Versioning


Let's specify the custom lookup_field, i.e.:

lookup_field = 'uid_advanced_feature'

noliveleger · 2025-12-13T18:30:18Z

kobo/apps/subsequences/views.py

        parameters=[
            OpenApiParameter(
-                name='uid',
+                name='id',


Let's use the name custom lookup_field uid_advanced_feature instead.

noliveleger · 2025-12-13T18:31:01Z

kobo/apps/subsequences/views.py

                type=str,
                location=OpenApiParameter.PATH,
                required=True,
                description='UID of the action',


Maybe action is not really accurate in this context?

noliveleger · 2025-12-13T18:31:18Z

kobo/apps/subsequences/views.py

        parameters=[
            OpenApiParameter(
-                name='uid',
+                name='id',


Please update the name

noliveleger · 2025-12-13T18:55:00Z

kpi/schema_extensions/v2/subsequences/extensions.py

+                },
+                'options': {'type': 'object'},
+            },
+            'required': ['uuid', 'type', 'labels'],


We should enforce that choices should be present only when type is qualSelectMultiple or qualSectionOne.

noliveleger · 2025-12-13T19:01:11Z

kobo/apps/subsequences/views.py

            require_auth=False,
            raise_access_forbidden=False,
        ),
+        examples=get_advanced_features_create_examples(),


The examples of the response seems wrong. I assume they should match the list.

noliveleger · 2025-12-13T19:14:36Z

kobo/apps/subsequences/views.py

            raise_access_forbidden=False,
            validate_payload=False,
        ),
+        examples=get_advanced_features_list_examples(),


Some examples are missing (manual transcription, automatic google translation).
If you did it in purpose, let's add a description with your example and make the example more generic.

See Delete NLP action for supplement details "

Moreover, the examples are showing a double nested list.

[ [ { "action": "manual_translation", "question_xpath": "q1", "params": [ { "language": "es" } ], "uid": "qa123456789AbCdEfGhIjklm" } ] ]

noliveleger · 2025-12-13T19:17:13Z

kobo/apps/subsequences/views.py

 )
 @extend_schema_view(
    create=extend_schema(
        description=read_md('subsequences', 'subsequences/create.md'),


Please update the markdowns. They could be simplified thanks to the examples you have added to this PR. (e.g. no need to explain what params should look like anymore in the markdown, the examples do the trick).

noliveleger · 2025-12-13T19:22:11Z

kobo/apps/subsequences/views.py

        ],
+        examples=get_advanced_features_update_examples(),
    ),
    retrieve=extend_schema(


The example is ~~wrong~~ , is misleading.

Let's reuse examples of the list. Consider to use the description of the example like describe previously for Delete NLP action for supplement details

noliveleger · 2025-12-13T19:24:03Z

kobo/apps/subsequences/views.py

+        examples=get_advanced_features_list_examples(),
    ),
    partial_update=extend_schema(
        description=read_md('subsequences', 'subsequences/update.md'),


Same comment as for "retrieve" .

Moreover, I'm not sure to understand the labels of the examples. Many are missing too.

noliveleger · 2025-12-13T19:31:33Z

kpi/schema_extensions/v2/subsequences/extensions.py

+    def _get_action_refs(cls, registry):
+        nlp_component = ResolvedComponent(
+            name='NLPActionParams',
+            schema=cls._get_nlp_params_schema(),
+            type=ResolvedComponent.SCHEMA,
+            object=dict,
+        )
+        registry.register_on_missing(nlp_component)
+        qual_component = ResolvedComponent(
+            name='QualActionParams',
+            schema=cls._get_qual_params_schema(),
+            type=ResolvedComponent.SCHEMA,
+            object=dict,
+        )
+        registry.register_on_missing(qual_component)
+
+        return [
+            nlp_component.ref,
+            qual_component.ref,
+        ]


I created a mixin in #6535 for that purpose. Let's refactor the code when both branches are merged

noliveleger · 2025-12-13T19:52:30Z

kpi/schema_extensions/v2/subsequences/extensions.py

+            name='NLPActionParams',
+            schema=cls._get_nlp_params_schema(),
+            type=ResolvedComponent.SCHEMA,
+            object=dict,


I don't think it's expect dict here. If you look at drf-spectular code, it's used to detect collision based on object.__class__ , so it returns type all the time for dict.

Not a big deal, though!

What do you think?
(I personaly used the instance of the OpenApiSerializerExtension class).

…a-for-advanded-features # Conflicts: # jsapp/js/api/models/advancedFeaturePostRequestParamsItem.ts # jsapp/js/api/models/advancedFeatureResponseParamsItem.ts # jsapp/js/api/models/assetAdvancedSubmissionSchema.ts # jsapp/js/api/models/assetAnalysisFormJsonEngines.ts # jsapp/js/api/models/dataSupplementResponse.ts # jsapp/js/api/models/nLPActionParamsItem.ts # jsapp/js/api/models/patchedAdvancedFeaturePatchRequestParamsItem.ts # jsapp/js/api/models/patchedDataSupplementPayload.ts # jsapp/js/api/models/patchedDataSupplementPayloadOneOfOneOfQualOneOfAllOf.ts # jsapp/js/api/models/qualActionParamsItemChoicesItemLabels.ts # static/openapi/schema_v2.json # static/openapi/schema_v2.yaml

Guitlle added 4 commits December 11, 2025 12:04

Adding advanced features viewset to the v2 api version

6bfe0ef

Merge remote-tracking branch 'origin/refactor-subsequences-2025' into…

785e37b

… dev-1230-openapi-schema-for-advanded-features

fix drf warnings for subsequences

1fd581e

add subsequences action params schemas to api docs

a20d5d1

Guitlle self-assigned this Dec 12, 2025

Guitlle added API Changes related to API endpoints Back end labels Dec 12, 2025

Guitlle added 5 commits December 12, 2025 00:48

format python code

40e8f25

Merge remote-tracking branch 'origin/refactor-subsequences-2025' into…

dcd24ea

… dev-1230-openapi-schema-for-advanded-features

add examples for the advanced features endpoint

ef21718

add fixme comment for default versioning

f2bab57

Signed-off-by: Guillermo <[email protected]>

update schema outputs

ba93833

Guitlle marked this pull request as ready for review December 12, 2025 23:59

Guitlle requested review from jnm, magicznyleszek and noliveleger as code owners December 12, 2025 23:59

Guitlle added 2 commits December 12, 2025 19:51

fix params schemas for advanced features API docs

1945b5f

update schema outputs and fix qual component name

0927690

Guitlle removed request for jnm and magicznyleszek December 13, 2025 02:28

noliveleger requested changes Dec 13, 2025

View reviewed changes

noliveleger reviewed Dec 13, 2025

View reviewed changes

noliveleger changed the title ~~feat(subsequences): add openapi schema for advanded features DEV-1230~~ feat(subsequences): add OpenAPI schema for advanded features DEV-1230 Dec 14, 2025

Uh oh!

feat(subsequences): add OpenAPI schema for advanded features DEV-1230 #6547

Are you sure you want to change the base?

feat(subsequences): add OpenAPI schema for advanded features DEV-1230 #6547

Conversation

Guitlle commented Dec 12, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🗒️ Checklist

📣 Summary

📖 Description

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Guitlle commented Dec 12, 2025 •

edited

Loading