Define a good way and a good place to document properties of each taxonomy (e.g. ingredients)

[stephanegigandet]

@john-gom implemented a new feature that allows ingredients to have a max_percent:en property that is used to estimate the percentage of each ingredient of a product (e.g. if the ingredients list is "milk, flavours", we can assume that there is more than 95% of milk): #7639

It brings an interesting question: how and where should we document taxonomy properties?

In particular, it would be very interesting to specifically list for each taxonomy:

• which properties exist
• what property value are expected
• what is each property used for? (e.g. "percent_max:en is used during the analysis of the ingredients list to estimate the percentage of each ingredient")

Some possible places:

• A page for each taxonomy in the wiki: https://wiki.openfoodfacts.org/Ingredients_taxonomy
• A list of all supported and used properties, as comments at the top of the taxonomy .txt source file
• A set of .md files in /docs/reference/[taxonomy].md on GitHub
• OpenAPI / JSON schemas to list the properties of each taxonomy, with possible values, a description and examples

[alexgarel]

1. A list of all supported and used properties, as comments at the top of the taxonomy .txt source file

Has the advantage of being close to code, but the disadvantage of being less accessible to new-comers (and taxonomy editor is on its way).

Maybe we could put it in taxonomy file but generate an html from it to put on github pages ? (have a delimiter, write markdown, add markdown file to docs/reference at documentation generation time)

[stephanegigandet]

We could have the documentation in /docs/reference/ and then have a link to it at the top of the file.

taxonomy editor is on its way).

Actually that's an important point. If we put the documentation of properties in a JSON schema, then it can be displayed (in English only though) easily in tools like the taxonomy editor. In fact it can drive the taxonomy editor, which can use the JSON schema to suggest or display the properties of each taxonomy, and that can use the schema to verify the values.

e.g. for ingredients, we have a vegan:en: property that must have values from a specific set: yes, no, maybe, ignore

[alexgarel]

OpenAPI / JSON schemas to list the properties of each taxonomy, with possible values, a description and examples

Indeed I did not read this line correctly. I think this is the best solution, you are right.
It's close enough to source being in the same git repo.

[aleene]

Is it possible to use a wikidata kind of approach, with one entry per ingredient?

[stephanegigandet]

Is it possible to use a wikidata kind of approach, with one entry per ingredient?

@aleene : one entry per property you mean? Something like https://www.wikidata.org/wiki/Property:P110 ?
That would be another option, if we decided to use wikibase to define and store taxonomies. That would be a completely different model though, this issue is more about how to address our immediate needs to document properties in the existing taxonomy system.

[john-gom]

I would suggest an Item per ingredient with a Statement / claim for each property. I've been looking at the Wikidata / Wikibase model a bit more and I think the general concepts could work but we'd probably want a bit more control. For example, a CIQUAL link would be a Statement / claim on an ingredient Item but we'd want to limit the selection to valid CIQUAL entries. Same for AGRIBALYSE and other sources or links between our own taxonmies, e.g. nutrient lists.

[aleene]

I see that all taxonomy entries get more and more properties and related semantics. This reminded me of wikidata. I can envisage the off taxonomies as a better curated subset of wikidata.

I have no idea if this could work in practice.

[github-actions]

This issue is stale because it has been open 90 days with no activity.