docs: Document unwanted ingredients attribute feature #12586

Copilot · 2025-10-31T12:52:05Z

Documentation update for ingredient unwanted ingredients feature:

Expand the unwanted ingredients section with comprehensive documentation
Document how to send queries with ingredients to flag
Add documentation for both food (Open Food Facts) and cosmetics (Open Beauty Facts) usage
Update OpenAPI specification (docs/api/ref/api-v3.yaml) with detailed parameter documentation
Update v2 API specification (docs/api/ref/api.yaml) with parameter documentation
Add examples showing how to use the feature in practice

Original prompt

This section details on the original issue you should resolve

<issue_title>Document the new ingredient ban feature.</issue_title>
<issue_description>### Task

Please document: https://github.com/openfoodfacts/openfoodfacts-server/pull/12321/files
and move the information from https://wiki.openfoodfacts.org/Product_Attributes here, in the /docs/api folder, docs: Create getting-personal-with-attributes.md #12197, while updating it with the ban ingredients attribute, explaining how to get suggestions for ingredients, and how to send queries with the ingredients to flag

update the OpenAPI doc as needed.

Please document usage for food and cosmetics, since it's deployed on both sides
</issue_description>

Comments on the Issue (you are @copilot in this section)

Fixes Document the new ingredient ban feature. #12585

✨ Let Copilot coding agent set things up for you — coding agent works faster and does higher quality work when set up for your repo.

Co-authored-by: teolemon <[email protected]>

docs/api/explain-product-attributes.md

…edictions section Co-authored-by: teolemon <[email protected]>

sonarqubecloud · 2025-10-31T13:11:09Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

sonarqubecloud · 2025-11-03T17:59:31Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

teolemon · 2025-11-04T08:20:29Z

Here's the associated issue and comment by @monsieurtanuki
openfoodfacts/openfoodfacts-dart#1134
cc @stephanegigandet

stephanegigandet · 2025-11-05T15:23:38Z

docs/api/explain-product-attributes.md

  - Vegetarian
  - Palm oil
-  - Unwanted ingredients (unwanted ingredients are specified by the user)
+  - Unwanted/Banned ingredients (user-specified list of ingredients to avoid; requires API v3.4+)


The name "Unwanted ingredients" is better, "banned" can be understood as banned in one country.

stephanegigandet · 2025-11-05T15:30:57Z

docs/api/explain-product-attributes.md

 - as a cookie with the name `attribute_unwanted_ingredients_tags`: this is used in particular on the website so that we do not have URLs with an extra query parameter.
 - as a query parameter in the URL (e.g. ?attribute_unwanted_ingredients_tags=en:garlic,en:kiwi)

+##### Getting ingredient suggestions


All the things below are interesting, but this doc is about explaining product attributes (in general) succinctly. Explain docs should stay on topic, and all the detailed examples, guidance etc. can go into a separate tutorial "How to implement the unwanted ingredients attribute".

stephanegigandet · 2025-11-05T15:32:35Z

docs/api/ref/api-v3.yaml

          description: |-
            When knowledge_panels are requested, you can specify which panels to exclude from the response. All the others will be included.
            If a panel is both excluded and included (with the knowledge_panels_excluded parameter), it will be excluded.
+        - schema:


This should go into a separate request body schema, so that's it's not duplicated for API v2 and API v3.

teolemon · 2025-11-06T07:00:51Z

docs/api/explain-product-attributes.md

  - Vegetarian
  - Palm oil
-  - Unwanted ingredients (unwanted ingredients are specified by the user)
+  - Unwanted/Banned ingredients (user-specified list of ingredients to avoid; requires API v3.4+)


Suggested change

- Unwanted/Banned ingredients (user-specified list of ingredients to avoid; requires API v3.4+)

- Unwanted ingredients (user-specified list of ingredients to avoid; requires API v3.4+)

teolemon · 2025-11-06T07:01:02Z

docs/api/explain-product-attributes.md

 Apps can request Product Attributes through API queries (`/api/v3/product` or `/api/v2/search`) by including `attribute_groups` or `attribute_groups_[language code]` (or `attribute_groups_data` to get only the machine-readable data) in the `fields` parameter.

-#### Product Attributes with Parameters (e.g. Unwanted ingredients)
+#### Product Attributes with Parameters (e.g. Unwanted/Banned ingredients)


Suggested change

#### Product Attributes with Parameters (e.g. Unwanted/Banned ingredients)

#### Product Attributes with Parameters (e.g. Unwanted ingredients)

teolemon · 2025-11-06T07:01:19Z

docs/api/explain-product-attributes.md

+#### Product Attributes with Parameters (e.g. Unwanted/Banned ingredients)

-In September 2025, we introduced support for attributes that can be configured with parameters. The first is the **Unwanted ingredients** attribute that takes a list of canonical ingredients as a parameter.
+In September 2025, we introduced support for attributes that can be configured with parameters. The first is the **Unwanted ingredients** attribute (also referred to as "banned ingredients" in cosmetics contexts) that takes a list of canonical ingredients as a parameter.


Suggested change

In September 2025, we introduced support for attributes that can be configured with parameters. The first is the **Unwanted ingredients** attribute (also referred to as "banned ingredients" in cosmetics contexts) that takes a list of canonical ingredients as a parameter.

In September 2025, we introduced support for attributes that can be configured with parameters. The first is the **Unwanted ingredients** attribute that takes a list of canonical ingredients as a parameter.

teolemon · 2025-11-06T07:01:32Z

docs/api/explain-product-attributes.md

+
+This feature is available on both:
+- **Open Food Facts** (food products): for filtering out unwanted ingredients based on dietary preferences, allergies, or personal choices
+- **Open Beauty Facts** (cosmetic products): for identifying banned or unwanted ingredients in cosmetics


Suggested change

- **Open Beauty Facts** (cosmetic products): for identifying banned or unwanted ingredients in cosmetics

- **Open Beauty Facts** (cosmetic products): for identifying unwanted ingredients in cosmetics

teolemon · 2025-11-06T07:02:27Z

docs/api/explain-product-attributes.md


+##### Getting ingredient suggestions
+
+To help users identify ingredients to flag as unwanted/banned, you can use the **Robotoff API** to get ingredient predictions and suggestions:


Suggested change

To help users identify ingredients to flag as unwanted/banned, you can use the **Robotoff API** to get ingredient predictions and suggestions:

To help users identify ingredients to flag as unwanted/banned, you can use the **Taxonomies or Suggestions APIs** to get ingredient suggestions:

teolemon · 2025-11-06T07:02:55Z

docs/api/explain-product-attributes.md

+curl "https://world.openfoodfacts.org/api/v3/product/3017620422003?fields=attribute_groups&attribute_unwanted_ingredients_tags=en:garlic,en:kiwi"
+```
+
+**Example 2: Checking cosmetic products for banned ingredients**


Suggested change

**Example 2: Checking cosmetic products for banned ingredients**

**Example 2: Checking cosmetic products for unwanted ingredients**

teolemon · 2025-11-06T07:03:22Z

docs/api/explain-product-attributes.md

+**For Open Beauty Facts (cosmetic products):**
+- Common use cases include avoiding controversial cosmetic ingredients (e.g., parabens, sulfates, certain preservatives)
+- Ingredients are matched against the cosmetic ingredients taxonomy
+- Some jurisdictions have lists of banned ingredients in cosmetics that can be referenced


Suggested change

- Some jurisdictions have lists of banned ingredients in cosmetics that can be referenced

Initial plan

6f3b79a

Copilot AI assigned Copilot and teolemon Oct 31, 2025

Copilot started work on behalf of teolemon October 31, 2025 12:52 View session

teolemon added this to 🍊 Open Food Facts Server issues Oct 31, 2025

github-project-automation bot moved this to To discuss and validate in 🍊 Open Food Facts Server issues Oct 31, 2025

Copilot AI and others added 2 commits October 31, 2025 13:01

Document unwanted/banned ingredients feature with comprehensive examples

7db27a2

Co-authored-by: teolemon <[email protected]>

Fix trailing spaces in YAML documentation files

4e51679

Co-authored-by: teolemon <[email protected]>

teolemon reviewed Oct 31, 2025

View reviewed changes

docs/api/explain-product-attributes.md Outdated Show resolved Hide resolved

teolemon reviewed Oct 31, 2025

View reviewed changes

docs/api/explain-product-attributes.md Outdated Show resolved Hide resolved

Copilot AI changed the title ~~[WIP] Document the new ingredient ban feature~~ Document unwanted/banned ingredients attribute feature Oct 31, 2025

Copilot AI requested a review from teolemon October 31, 2025 13:05

Copilot finished work on behalf of teolemon October 31, 2025 13:05

Copilot started work on behalf of teolemon October 31, 2025 13:06 View session

Address review feedback: fix date and remove irrelevant ingredient pr…

c848d73

…edictions section Co-authored-by: teolemon <[email protected]>

Copilot finished work on behalf of teolemon October 31, 2025 13:09

teolemon changed the title ~~Document unwanted/banned ingredients attribute feature~~ docs: Document unwanted/banned ingredients attribute feature Oct 31, 2025

github-actions bot added 📚 Documentation Documentation issues improve the project for everyone. API v3 📚 OpenAPI labels Oct 31, 2025

github-project-automation bot added this to 📚 Document Open Food Facts and 📚 🛠️ - Server - Document the Open Food Facts API Oct 31, 2025

github-project-automation bot moved this to In progress in 📚 🛠️ - Server - Document the Open Food Facts API Oct 31, 2025

github-project-automation bot moved this to Todo in 📚 Document Open Food Facts Oct 31, 2025

teolemon added this to 🛠️ - Server - API Nov 3, 2025

github-project-automation bot moved this to In progress in 🛠️ - Server - API Nov 3, 2025

Merge branch 'main' into copilot/document-ingredient-ban-feature

e4581fe

teolemon marked this pull request as ready for review November 3, 2025 21:39

teolemon requested a review from a team as a code owner November 3, 2025 21:39

github-actions bot added the 💥 Merge Conflicts 💥 Merge Conflicts label Nov 5, 2025

stephanegigandet reviewed Nov 5, 2025

View reviewed changes

teolemon changed the title ~~docs: Document unwanted/banned ingredients attribute feature~~ docs: Document unwanted ingredients attribute feature Nov 6, 2025

teolemon reviewed Nov 6, 2025

View reviewed changes

	- Unwanted/Banned ingredients (user-specified list of ingredients to avoid; requires API v3.4+)
	- Unwanted ingredients (user-specified list of ingredients to avoid; requires API v3.4+)

	#### Product Attributes with Parameters (e.g. Unwanted/Banned ingredients)
	#### Product Attributes with Parameters (e.g. Unwanted ingredients)

	In September 2025, we introduced support for attributes that can be configured with parameters. The first is the Unwanted ingredients attribute (also referred to as "banned ingredients" in cosmetics contexts) that takes a list of canonical ingredients as a parameter.
	In September 2025, we introduced support for attributes that can be configured with parameters. The first is the Unwanted ingredients attribute that takes a list of canonical ingredients as a parameter.

	- Open Beauty Facts (cosmetic products): for identifying banned or unwanted ingredients in cosmetics
	- Open Beauty Facts (cosmetic products): for identifying unwanted ingredients in cosmetics


		##### Getting ingredient suggestions

		To help users identify ingredients to flag as unwanted/banned, you can use the Robotoff API to get ingredient predictions and suggestions:

	Example 2: Checking cosmetic products for banned ingredients
	Example 2: Checking cosmetic products for unwanted ingredients

Uh oh!

docs: Document unwanted ingredients attribute feature #12586

Are you sure you want to change the base?

docs: Document unwanted ingredients attribute feature #12586

Conversation

Copilot AI commented Oct 31, 2025 • edited by teolemon Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Comments on the Issue (you are @copilot in this section)

Uh oh!

Uh oh!

Uh oh!

sonarqubecloud bot commented Oct 31, 2025

Quality Gate passed

Uh oh!

sonarqubecloud bot commented Nov 3, 2025

Quality Gate passed

Uh oh!

teolemon commented Nov 4, 2025

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

Copilot AI commented Oct 31, 2025 •

edited by teolemon

Loading