docs: OpenAPI documentation for new product nutrition data schema #12132

Vic142 · 2025-07-07T20:11:07Z

The API v3 is going to use a new nutrition data schema for products.
In this PR new OpenAPI documentation is created for the new product nutrition data schema (see 2025 - API - Nutrition Facts Schema and API for more information on the new schema).

Every nutrient in the nutrients.txt taxonomy file is added in the nutrient field of the new nutrition schema documentation.

stephanegigandet · 2025-07-08T07:33:06Z

docs/api/ref/schemas/product_nutrition_v3.yaml

+          description: |
+            todo
+          properties:
+            nutrient_sets_index:


For the selected proposal (see https://docs.google.com/document/d/19ZRrlWJraJm61E6U7AwxQ1uubPDvmSuNfl9F1oLC0Tg/edit?tab=t.0#heading=h.oqf07hovz1m5 ) we decided that we would not include a nutrients_sets_index, but that we would have a separate nutrient_set_preferred set instead

stephanegigandet · 2025-07-08T07:33:57Z

docs/api/ref/schemas/product_nutrition_v3.yaml

+                  preparation:
+                    type: string
+                    enum:
+                      - as sold


Suggested change

- as sold

- as_sold

stephanegigandet · 2025-07-08T07:37:34Z

docs/api/ref/schemas/product_nutrition_v3.yaml

+                      - manufacturer
+                      - usda
+                      - estimate
+                      - preferred


There's no "preferred" source for the option we selected

stephanegigandet · 2025-07-08T07:44:02Z

docs/api/ref/schemas/product_nutrition_v3.yaml

+                    example: "g"
+                  source:
+                    type: string
+                    enum:


I'm not sure about the enum there, as some clients could break if we add a new string (e.g. a new database). It may be better to list the possible values in the description, and state that new values may be added.

e.g. an article about how clients could try to handle unexpected valeus in enums in Flutter, but that's a lot of complexity on the client, and each client would need to do it: https://medium.com/@amjadhamdoun0/efficient-enum-handling-in-dart-with-json-converters-5d98dba17c8c

stephanegigandet · 2025-07-08T07:45:55Z

docs/api/ref/schemas/product_nutrition_v3.yaml

+                  nutrients:
+                    type: object
+                    description: |
+                      All known nutrients for the product.


We should indicate that new nutrients are regularly added, and that clients should not break if they encounter an unexpected nutrient.

stephanegigandet · 2025-07-08T07:47:50Z

docs/api/ref/schemas/product_nutrient_values.yaml

@@ -0,0 +1,103 @@
+type: object
+description: |
+  Quantity of sodium


Suggested change

Quantity of sodium

Quantity of a nutrient

stephanegigandet · 2025-07-08T07:51:35Z

docs/api/ref/schemas/product_nutrient_values.yaml

+
+        **Note**: For most use cases, you should not use this unit, as it can change depending on how the value was entered.
+        Instead use the `<nutrient>_100g` or `<nutrient>_serving` fields, and convert them to the unit you need.
+    enum:


I'm not sure we should list possible values in an enum, as clients may break if we add a new unit that they do not expect.

I'll ask for feedback in #api and #productopener

should I wait for other feedbacks on this before removing the enum ?

@Vic142 I would say no enum there, because you are creating an expectation that won't hold.

stephanegigandet · 2025-07-08T07:53:23Z

docs/api/ref/schemas/product_nutrient_values.yaml

+    enum: ["<", "<=", "~", ">=", ">"]
+    description: |
+      todo (this property is optional)
+  source:


"source" and "source_per" would be only for the nutrient_set_preferred object, not for the objects in the nutrient_sets array

so we must have a separate object product_nutrient_values_sources that we can add to preferred_set definitions (we already use a AllOf declaration)

silkgh · 2025-07-08T12:12:54Z

docs/api/ref/schemas/product_nutrient_values.yaml

+        "�e",
+        "�dh",
+        "gpg",
+      ]


What about foods sold as whole items? e.g. oranges etc - typically nutrition is given as "each"/ per "item" - in my own app I use "item" for this

@silkgh So far we have not encountered any source of nutrition data that gives nutrition facts per item (unless the item is equal to the serving, and in that case we have a serving quantity in g / ml). Do you have example of products where nutrition facts are listed per item without a specified weight / volume?

While I agree that all foods should be recorded in valid, scientific measurements (e.g. per 100g), I find that pretty much all fruits are recorded per item - not saying it's right but it seems to be a thing in the wonderful world of nutrition

@silkgh you comment better applies to product_nutrition_properties.yaml, per property.

"I find that pretty much all fruits are recorded per item" --> @silkgh are you talking about input data? i.e. that we get from the packaging that 1 apple = 50g of sugars? or about a desired output, that you would like to get the OFF API to tell you that an apple is 50 of sugars?
Because I have never seen a input source that specifies nutrients per item. EU and US law etc. mandate that the nutrition facts are for a specific quantity (which can be equal to 1 serving which is 1 item, but it needs to specifiy how much g it is)

… on comments

alexgarel

Thanks for the good work @Vic142 !

alexgarel · 2025-07-10T08:01:24Z

docs/api/ref/schemas/nutrients_v3.yaml

+      New nutrients are regularly added.
+
+      Clients should not break if they encounter an unexpected nutrient to preserve compatibility.
+    properties:


Personally, here I would concentrate on main nutrients (energy, salt, sugar, etc) and let people see the rest with taxonomies, because I feel like it will be overwhelming otherwise to read this documentation), and also it makes a duplicate effort with the taxonomy to maintain this. (Otherwise we could seek to generate this file from the taxonomy, but again it would make it far too long a documentation IMO).

We can add a additionalProperty to support SDK generations tools, letting them know there are other values.

That sounds like a good option to me. We can specficially name only the "mandatory" nutrients for energy-kj, energy-kcal, proteins, fats, saturated-fats, carbohydrates, sugars, fibers and salt. Maybe total_carbohydrates as well, and whatever nutrients are mandatory in the US and Canada (e.g. calcium and a few others)

alexgarel · 2025-07-10T08:02:57Z

docs/api/ref/schemas/product_nutrient_values.yaml

+  unit:
+    type: string
+    description: |
+        The unit of the value entered by the contributor (a user or the manufacturer), for the product as sold (not prepared).


Now it's not determined, it depends in which entry it's used.

Suggested change

The unit of the value entered by the contributor (a user or the manufacturer), for the product as sold (not prepared).

The unit of the value entered by the contributor (a user or the manufacturer), for the product.

alexgarel · 2025-07-10T08:04:15Z

docs/api/ref/schemas/product_nutrient_values.yaml

+
+        **Note**: For most use cases, you should not use this unit, as it can change depending on how the value was entered.
+        Instead use the `<nutrient>_100g` or `<nutrient>_serving` fields, and convert them to the unit you need.
+    enum:


@Vic142 I would say no enum there, because you are creating an expectation that won't hold.

alexgarel · 2025-07-10T08:05:41Z

docs/api/ref/schemas/product_nutrient_values.yaml

+    enum: ["<", "<=", "~", ">=", ">"]
+    description: |
+      todo (this property is optional)
+  source:


so we must have a separate object product_nutrient_values_sources that we can add to preferred_set definitions (we already use a AllOf declaration)

alexgarel · 2025-07-10T08:07:02Z

docs/api/ref/schemas/product_nutrient_values.yaml

+        "�e",
+        "�dh",
+        "gpg",
+      ]


@silkgh you comment better applies to product_nutrition_properties.yaml, per property.

alexgarel · 2025-07-10T08:07:58Z

docs/api/ref/schemas/product_nutrition_properties.yaml

+    description: |
+      The nutrition data on the package can be per serving, per 100g or per 100ml.
+      When the data is given per serving, the actual quantity that defines one serving may vary 
+      between products and should be stored in this field.


I would remove the "should be" the API defines things

Suggested change

between products and should be stored in this field.

between products and is stored in this field.

alexgarel · 2025-07-10T08:09:39Z

docs/api/ref/schemas/product_nutrition_properties.yaml

+      The nutrition data on the package can be per serving, per 100g or per 100ml.
+      When the data is given per serving, the actual quantity that defines one serving may vary 
+      between products and should be stored in this field.


nit: when I break line in markdown I prefer to do it in meaninful places.
Because if you edit this text afterwards, you would have to redo all the line splitting if your text does not fit anymore. So it's better to treat it as code, and make meaningfull lines.
Like:

Suggested change

The nutrition data on the package can be per serving, per 100g or per 100ml.

When the data is given per serving, the actual quantity that defines one serving may vary

between products and should be stored in this field.

The nutrition data on the package can be per serving, per 100g or per 100ml.

When the data is given per serving,

the actual quantity that defines one serving may vary between products

and should be stored in this field.

alexgarel · 2025-07-10T08:14:58Z

html/images/misc/android-apk.svg

why changes in this file ?

i didn't touch it and the changes don't appear in my branch locally so I don't know how it appeared on GitHub, I'm going to check why it says there were changes

stephanegigandet · 2025-07-11T14:15:49Z

docs/api/ref/schemas/nutrients_v3_with_source.yaml

+          (per 100g, per 100ml or per serving) in a standard unit (g or ml)
+        allOf:
+          - $ref: "../schemas/product_nutrient_values.yaml"
+          - type: object


Turn this into a ref to a new product_nutrient_source.yml

sonarqubecloud · 2025-07-11T19:22: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

feat: new product nutrition data openapi documentation

5af9e17

Vic142 self-assigned this Jul 7, 2025

Vic142 added the Nutrition facts label Jul 7, 2025

Vic142 added this to 📚 🛠️ - Server - Document the Open Food Facts API Jul 7, 2025

Vic142 added 📚 Documentation Documentation issues improve the project for everyone. API v3 labels Jul 7, 2025

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

github-project-automation bot added this to 📚 Document Open Food Facts Jul 7, 2025

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

teolemon added this to 🍊 Open Food Facts Server issues Jul 7, 2025

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

teolemon added this to 🛠️ - Server - API Jul 7, 2025

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

Vic142 removed this from 🛠️ - Server - API Jul 7, 2025

Vic142 removed this from 📚 Document Open Food Facts Jul 7, 2025

Vic142 removed this from 🍊 Open Food Facts Server issues Jul 7, 2025

Vic142 added this to 🛠️ - Server - API and 🍊 Open Food Facts Server issues Jul 7, 2025

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

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

stephanegigandet reviewed Jul 8, 2025

View reviewed changes

silkgh reviewed Jul 8, 2025

View reviewed changes

doc: updated openapi nutrition schema based on selected proposal

8ebe40e

teolemon added this to 📚 Document Open Food Facts Jul 9, 2025

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

Vic142 added 2 commits July 9, 2025 16:22

corrected values in properties of nutrition openapi schema

429b953

updated properties descriptions in new openapi nutrition schema based…

2ab4e7f

… on comments

alexgarel reviewed Jul 10, 2025

View reviewed changes

Vic142 added 4 commits July 10, 2025 14:59

updated source and source_per properties in new openapi nutrition schema

98b0003

removed enum in unit property of new nurtition schema

0728d81

removed unnecessary nutrients from new nutrition schema

c5c2cba

updated descriptions and examples of new openapi nutrition schema

863f108

stephanegigandet reviewed Jul 11, 2025

View reviewed changes

Vic142 added 2 commits July 11, 2025 15:00

changed order of nutrients in nutrition schema

988bc7c

added ref for nutrients source in nutrition schema

decb74e

teolemon moved this from To discuss and validate to PRs in 🍊 Open Food Facts Server issues Jul 16, 2025

	The unit of the value entered by the contributor (a user or the manufacturer), for the product as sold (not prepared).
	The unit of the value entered by the contributor (a user or the manufacturer), for the product.

	between products and should be stored in this field.
	between products and is stored in this field.

Uh oh!

docs: OpenAPI documentation for new product nutrition data schema #12132

Are you sure you want to change the base?

docs: OpenAPI documentation for new product nutrition data schema #12132

Uh oh!

Conversation

Vic142 commented Jul 7, 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!

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!

alexgarel left a comment

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!

sonarqubecloud bot commented Jul 11, 2025

Quality Gate passed

Uh oh!

Uh oh!