Skip to content

feat: Add Knowledge Panel compliant route with enhanced formatting for Folksonomy Engine#317

Draft
teolemon with Copilot wants to merge 7 commits into
mainfrom
copilot/create-knowledge-panel-route
Draft

feat: Add Knowledge Panel compliant route with enhanced formatting for Folksonomy Engine#317
teolemon with Copilot wants to merge 7 commits into
mainfrom
copilot/create-knowledge-panel-route

Conversation

Copilot AI commented Oct 23, 2025

Copy link
Copy Markdown
  • Explore repository structure and understand existing API
  • Research Knowledge Panel format from OFF documentation and examples
  • Add Knowledge Panel data models to models.py
  • Implement GET /product/{barcode}/knowledge_panel endpoint in api.py
  • Add comprehensive tests for the new endpoint
  • Validate the implementation with manual testing
  • Verify OpenAPI schema generation
  • Run linter checks
  • Address code review feedback (pluralization)
  • Run security checks (CodeQL - no issues found)
  • Update CHANGELOG.md
  • Add property formatting (URLs, yes/no, colors, units)
  • Add wiki documentation and product list links

Summary

Successfully implemented a Knowledge Panel compliant route for the Folksonomy Engine with enhanced formatting and property links:

Endpoint

GET /product/{barcode}/knowledge_panel

New Features - Property Links

Enhanced Formatting Features

  • URLs as Links: Automatically converts URLs to clickable HTML links
  • Yes/No Emojis: "yes" → ✅, "no" → ❌
  • Color Emojis: "red" → 🔴 red, "blue" → 🔵 blue, "green" → 🟢 green, etc.
  • Unit Formatting: "height:mm" → "height (mm)", "weight:g" → "weight (g)", etc.
  • Readable Keys: Replaces colons with › and underscores with spaces

Example Output

Property: color (📖 🔍)                    | Value: 🔴 red
Property: same product (📖 🔍)             | Value: 3046920028363
Property: height (mm) (📖 🔍)              | Value: 150

Where:

  • 📖 links to wiki documentation
  • 🔍 links to all products with that property

All Features

  • ✅ Knowledge Panel compliant format
  • ✅ Structured table with Property/Value columns
  • ✅ Property documentation and discovery links
  • ✅ Enhanced visual formatting for better UX
  • ✅ Handles products with no properties gracefully
  • ✅ Supports authentication for private properties
  • ✅ Properties ordered alphabetically by key
  • ✅ Full OpenAPI documentation
  • ✅ Comprehensive test coverage
  • ✅ No security vulnerabilities detected
Original prompt

This section details on the original issue you should resolve

<issue_title>Create a Knowledge Panel compliant route for the Folksonomy Engine list of properties for a given barcode</issue_title>
<issue_description>### Problem

  • Create a Knowledge Panel compliant route for each barcode, so that we can integrate it in the ProductOpener Product Page or in the mobile app
  • This will allow for a flexible and evolutive layout, driven by the Folksonomy server
  • Optional is a link to a webview allowing property input (view to be created, you can open another ticket), until we can have basic server driven editing

Code pointers

Related issue

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

@teolemon We're also considering exposing a webcomponent. The two can be complementary, the webcomponent using the Knowledge Panel compliant API exposed by the Folksonomy Engine. @alexgarel @shradiphylleia yes that's it.

I have created an issue to have a knowledge panel web component here. (but it's independent).</comment_new>

Fixes #185


💬 We'd love your input! Share your thoughts on Copilot coding agent in our 2 minute survey.

@codecov-commenter

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.59%. Comparing base (b9cda65) to head (297d61f).
⚠️ Report is 130 commits behind head on main.

Additional details and impacted files
@@             Coverage Diff             @@
##             main     #317       +/-   ##
===========================================
- Coverage   95.06%   78.59%   -16.47%     
===========================================
  Files           5        4        -1     
  Lines         324      556      +232     
===========================================
+ Hits          308      437      +129     
- Misses         16      119      +103     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Copilot AI and others added 3 commits October 23, 2025 15:30
Co-authored-by: teolemon <1689815+teolemon@users.noreply.github.com>
Co-authored-by: teolemon <1689815+teolemon@users.noreply.github.com>
Co-authored-by: teolemon <1689815+teolemon@users.noreply.github.com>
Copilot AI changed the title [WIP] Create Knowledge Panel compliant route for Folksonomy Engine Add Knowledge Panel compliant route for Folksonomy Engine Oct 23, 2025
Copilot AI requested a review from teolemon October 23, 2025 15:42
@teolemon

Copy link
Copy Markdown
Member

@copilot I have allowlisted install.python-poetry.org and world.openfoodfacts.org

@teolemon

Copy link
Copy Markdown
Member

@copilot can you turn

  • URLs into links
  • "yes" values into ✅
  • "no" values into ❌
  • common colors into emojis like 🔴 red 🟠 orange, 🟡 yellow, 🟢 green, 🔵 blue, 🟣 purple, 🟤 brown, ⚫ black, ⚪ white
  • format well the units if they are included in the property name
  • Any way to make the data more enjoyable at scale (not too many code for just one property if possible)

Smartphone properties:
color
released_date
manufacturer:serie_reference
manufacturer:reference_number
manufacturer:suggested_retail_price:eu:eur
consumer_electronics:rom_memory:capacity:gb
height:mm
width:mm
depth:mm
weight:g
consumer_electronics:screen_size:diagonal:inch
consumer_electronics:ram_memory:capacity:gb
consumer_electronics:front_camera_resolution:mpx
consumer_electronics:rear_camera_resolution:mpx
consumer_eletronics:nb_of_rear_cameras
consumer_electronics:specific_absorption_rate_body:w_kg
consumer_electronics:specific_absorption_rate_head:w_kg
consumer_electronics:standby_autonomy:hours
consumer_electronics:official operating system
consumer_electronics:initial_operating_system:version
consumer_electronics:most_recent_network_generation
consumer_electronics:manufacturer_engagement_for_os_updates:years
consumer_electronics:manufacturer_engagement_for_os_updates:numbers
consumer_electronics:number_of_sim_slots:physical
consumer_electronics:number_of_sim_slots:esim
consumer_electronics:SIM_card_slot_type
consumer_electronics:sd_card_max_capacity:gb
consumer_electronics:battery_capacity:mah
ec_energy_label:url
energy_efficiency_class:eu
battery_autonomy_per_cycle:eu:hours_min
reliability_class_per_case:eu
repairability_class:eu
battery_lifespan_in_cycles:eu:higher_or_equal_to
ingress_protection_rating:ip:number
consumer_electronics:initial_operating_system
dimensions
consumer_electronics:wifi_supported_generation
consumer_electronics:screen_resolution:height:px
consumer_electronics:screen_resolution:width:px
consumer_electronics:screen_size:height:mm
consumer_electronics:screen_size:width:mm
consumer_electronics:screen_resolution_name
technical_specs_url
consumer_electronics:has_NFC:A
consumer_electronics:has_NFC:B
consumer_electronics:audio_port_type
wikidata:id
wikidata:url
wikipedia:en:url
consumer_electronics:wireless_charging:type
consumer_electronics:wireless_charging:max_power:w
consumer_electronics:bluetooth_version
consumer_electronics:form_factor
consumer_electronic:card_slot
consumer_electronic:card_slot_format
consumer_electronics:agps_capable
consumer_electronics:supported_3_g_network_bands
consumer_electronics:supported_3_g_plus_network_bands
consumer_electronics:supported_edge_network_bands
consumer_electronics:supported_gms_network_bands
consumer_electronics:supported_gprs_network_bands
consumer_electronics:supported_h_plus_network_bands
consumer_electronics:supported_video_formats
items_included_in_the_box
consumer_electronics:supported_image_formats
supported_languages
consumer_electronics:supported_audio_formats
items_available_in_following_colors
battery_replaceable
screen_max_refresh_rate
ip_certificate
frame_material
consumer_electronic:esim_suppport
biometrics_sensor
consumer_electronics:previous_model
battery_technology
consumer_electronics:autofocus_capable
consumer_electronics:call_autonomy_2g
consumer_electronics:call_autonomy_3g
consumer_electronics:digital_zoom
consumer_electronics:gps_capable
consumer_electronics:gpu
consumer_electronics:has_accelerometer
consumer_electronics:has_flash
consumer_electronics:has_light_sensor
consumer_electronics:has_magnetometer
consumer_electronics:has_proximity_sensor
consumer_electronics:internet_sharing_methods
consumer_electronics:is_arm_gpu
is_available_for_sale
consumer_electronics:is_google_mobile_services_enabled
consumer_electronics:is_multitouch_capable
consumer_electronics:is_usb_otg_capable
consumer_electronics:music_player_features
official_faq_url
consumer_electronics:cpu
consumer_electronics:cpu_clock_speed:ghz
quick_start_guide_url
security_advice_url
consumer_electronics:unofficial_kernel_repository_url
consumer_electronics:usb_port_version
user_guide_url
consumer_electronics:video_recording_framerate
consumer_electronics:white_balance_modes
consumer_electronics:wifi_supported_bands
consumer_electronics:xda_forums_tag_url

Other added Property (might be renamed in the future)

additive_error
age
age_recommendation
alcohol_percentage
allergen:legume
ambiguous_multilingual_typography
antiseptic
applicable_items
application_tips
assort
assort:how_many_kinds_of_products
assort:products-1:ja:name
assort:products-1:nutrition_facts:energy
assort:products-2:ja:name
assort:products-3:ja:name
assort:products-3:nutrition_facts:caffeine_content
author
availableduringchristmastime
barcode
barcode_clash
barcode_conflict
barcode_conflict:by
barcode_length_strange
barcode_wrong
battery
brand:changed
brand:original
cacaval-rucar
cartoon_character
category:kefir
ccv
chipset
cocoa_percent
codebarre
color
color_of_the_cap
colour_temperature
comment:de
confiserie
conservateur
conservation:date_type
conservation:do_not_freeze
conservation:shelf_life
conservation:temperature
consumer_electronics:agps_capable
consumer_electronics:audio_port_type
consumer_electronics:autofocus_capable
consumer_electronics:battery_capacity:mah
consumer_electronics:call_autonomy_2g
consumer_electronics:call_autonomy_3g
consumer_electronics:cpu
consumer_electronics:cpu_clock_speed:ghz
consumer_electronics:digital_zoom
consumer_electronics:front_camera_resolution:mpx
consumer_electronics:gps_capable
consumer_electronics:gpu
consumer_electronics:has_accelerometer
consumer_electronics:has_flash
consumer_electronics:has_light_sensor
consumer_electronics:has_magnetometer
consumer_electronics:has_proximity_sensor
consumer_electronics:initial_operating_system
consumer_electronics:internet_sharing_methods
consumer_electronics:is_arm_gpu
consumer_electronics:is_google_mobile_services_enabled
consumer_electronics:is_multitouch_capable
consumer_electronics:is_usb_otg_capable
consumer_electronics:music_player_features
consumer_electronics:ram_memory:capacity:gb
consumer_electronics:rear_camera_resolution:mpx
consumer_electronics:rom_memory:capacity:gb
consumer_electronics:screen_resolution_name
consumer_electronics:screen_size:diagonal:inch
consumer_electronics:specific_absorption_rate_body:w_kg
consumer_electronics:specific_absorption_rate_head:w_kg
consumer_electronics:standby_autonomy:hours
consumer_electronics:supported_3_g_network_bands
consumer_electronics:supported_3_g_plus_network_bands
consumer_electronics:supported_audio_formats
consumer_electronics:supported_edge_network_bands
consumer_electronics:supported_gms_network_bands
consumer_electronics:supported_gprs_network_bands
consumer_electronics:supported_h_plus_network_bands
consumer_electronics:supported_image_formats
consumer_electronics:supported_video_formats
consumer_electronics:unofficial_kernel_repository_url
consumer_electronics:usb_port_version
consumer_electronics:video_recording_framerate
consumer_electronics:white_balance_modes
consumer_electronics:wifi_supported_bands
consumer_electronics:xda_forums_tag_url
cooking_pan
data_issue:310
data_quality
data_quality_correction
data_quality_correction:energy
data_quality:fix_salt_bot_issue
data_quality:product_opener_issue
data_quality:robotoff_issue
data_quality:robotoff_issue:product_version
deposit_aut
depth
depth:mm
diameter
dilute
dilute:ratio
dimension
dimensions
display_size
display_type
distributed
distributor
ec_drop_grade
evolutions
fixme
foodgroup
french_environmental_cost
fssai_licence_number
fteoaw
funny_label
garanzia
god
godd
has_alcohol
has_funny_barcode
has_funny_barcode_around
healthstarrating
height
height:mm
images:ingredients:dutch
importer
ingredient_list:languages_mixed
ingredient_list:multiple
ingredients:allium
ingredients:changed
ingredients:garlic
ingredients:numberofparts
ink_color
irritante
is_available_for_sale
is_original
is-original
issue:nutrition:carbohydrates
issue:nutrition:energy
issue:nutrition:fat
issue:nutrition:fiber
issue:nutrition:proteins
issue:nutrition:salt
issue:nutrition:saturated_fat
issue:nutrition:sugars
issue:portion
issue:weight
items_available_in_following_colors
items_included_in_the_box
knockoff_brand
kosher
lactalis
lamp_finish
larghezza
length
length:blade
licensed_product
lieudefabrication
list_price:jp-reduced_tax_rate
lost_nutriscore
luminous_efficicacy
lunghezza
main_address_is
manufacturer_suggested_retail_price:eu:eur
marketed-as-rich-in
material
maximum_recommended_price
maximum_weight
menge
mouse:button:number_of
mouse:type
multipack
musicbrainz:release:id
musicbrainz:release:url
nc_recipe_id
new_picture_needed
nominal_lifetime
nominal_luminous_flux
non_applicale_items
non-veg
notepersonali
nova
number_of_items
number_of_switch_cycles
nutriscore
nutriscore_withdrawn
nutrition_facts
nutrition_facts:changed
nutrition_facts:energy
nutrition_facts:minerals
nutrition_facts:multiple
nutrition_facts:total
nutrition_facts:url
obfuscation
official_faq_url
openlibrary:edition:id
openlibrary:edition:url
opentrashfacts
operating_system
organic
origine
packaging:animal
packaging:character
packaging:character:wikidata
packaging:has_character
packaging:illustration_has_changed
packaging:inconsistent
packaging:material
packaging:nutriscore:multiple
packaging:weight
packaging:weight:recycle
packaging:weight:waste
period_after_opening
ph
pieces
pixelsnap_compatible
place_depicted
plastique
power_consumption
prescription_required:se
price
price_for_the_farmer
problem:nutrition:energy:kcal
producer_data_issue
producer_data_issue_repaired
producer_data_issue_solution
producer_data_issue:from_sent_data
producer_data_issue:proteins
producer_error
producer_issue
product_data:carbohydrates
product_franchise
product:changed
product:subproducts
producter_data
proproduction_site:changed
quality:energy:kj
quality:polyols
quantita
quantita_nominale_sgocciolata
quick_start_guide_url
ram
recalled_product
recalled_product:date
recalled_product:link
reformulated
reformulated:description
repairability_index_france
replaced_by
replaces
sal
same_product
scoville_scale
security_advice_url
serving_size:multiple
shelf_life
shopping_basket
shrinkflation
sim
sku
slightlyspicy
smartlabel
socket
spf
spolehliveceske
start_date
storage
storage_method:ja
string
substitution_for
supported_languages
technical_specs_url
test
thread_size
topic
toxins
unlikely_name
user_guide_url
utest
vandalism
variety
vegan
vintage
voltage
volume
volume:net
volumen
warranty_in_years
weight
weight_value_is_wrong
weight:drained
weight:drained:source
weight:g
weight:net
weight:net:source
weight:variable
width
width:mm
wikidata:id
wikidata:url
wind_resistance
with_gene_technology
wrong_information_provided_by_the_manufacturer
wrong_traceability_code

- Convert URLs to clickable HTML links
- Format yes/no values as ✅/❌ emojis
- Add color emojis (🔴 red, 🟢 green, 🔵 blue, etc.)
- Format units in property names (mm, g, GB, etc.)
- Replace colons with › and underscores with spaces for readability
- Add comprehensive tests for formatting functions

Co-authored-by: teolemon <1689815+teolemon@users.noreply.github.com>

Copilot AI commented Oct 31, 2025

Copy link
Copy Markdown
Author

@copilot can you turn

  • URLs into links
  • "yes" values into ✅
    ...

Done in commit c65f4b5. The Knowledge Panel now includes enhanced formatting:

Before:

Property: consumer_electronics:ram_memory:capacity:gb | Value: 8
Property: battery_replaceable                         | Value: no
Property: color                                       | Value: red
Property: wikidata:url                                | Value: https://example.com

After:

Property: consumer electronics › ram memory › capacity (GB) | Value: 8
Property: battery replaceable                              | Value: ❌
Property: color                                            | Value: 🔴 red
Property: wikidata › url                                   | Value: <a href="https://example.com">link</a>

Features implemented:

  • ✅ URLs → clickable HTML links
  • ✅ yes → ✅, no → ❌
  • ✅ Colors → emojis (🔴🟠🟡🟢🔵🟣🟤⚫⚪💗)
  • ✅ Units formatted: :mm → (mm), :g → (g), :gb → (GB), :mah → (mAh), etc.
  • ✅ Readable keys: colons → ›, underscores → spaces

The formatting keeps code minimal while making data more enjoyable at scale.

Copilot AI changed the title Add Knowledge Panel compliant route for Folksonomy Engine Add Knowledge Panel compliant route with enhanced formatting for Folksonomy Engine Oct 31, 2025
@teolemon

Copy link
Copy Markdown
Member

@copilot

  • can you add links to the wiki documentation of the property eg: https://wiki.openfoodfacts.org/Folksonomy/Property/same_product for the same_product property
  • can you add a link to other products with that tag: https://fr.openfoodfacts.org/property/images:ingredients:dutch for images:ingredients:dutch
  • it should be as unobtrusive as possible (possibly by making each property a tappable knowledge panel with a children knowledge panel, as described in the knowledge panel syntax)
  • also, can you create a beginner friendly Yaml documentation system for the properties, that's not reliant on the Open Food Facts wiki, but has a link to it, that allows to add standardized images/icons for properties (or property/value couples like 16GO, 32GO…) to allow user to quickly visually parse information, multilingual ready instructions on permitted values, what the property is about, example of usage, and anything you could find useful in such a system to improve the Folksonomy Engine experience for non technical users non familiar with a key value system.

Copilot AI commented Oct 31, 2025

Copy link
Copy Markdown
Author

@copilot

I can implement the wiki/property links as requested. However, the YAML documentation system is a substantial feature that would require:

  • Creating a new YAML schema and file structure
  • Building a property metadata system
  • Adding image/icon storage and serving
  • Multilingual support infrastructure

This seems like it should be a separate issue/PR rather than part of this Knowledge Panel endpoint implementation.

For this PR, I'll focus on:

  1. Adding wiki documentation links for each property
  2. Adding "view products" links for each property
  3. Making these links unobtrusive using source_url in text elements

Would you like me to proceed with items 1-3, and create a separate issue for the YAML documentation system?

@copilot

Implemented in commit 520bdc5. Property links are now included in an unobtrusive way:

Features added:

  1. ✅ Wiki documentation links: Each property has a 📖 icon linking to https://wiki.openfoodfacts.org/Folksonomy/Property/{property_name}
  2. ✅ Product list links: Each property has a 🔍 icon linking to https://world.openfoodfacts.org/property/{property_name}
  3. ✅ Unobtrusive design: Links appear in small text with emoji icons next to property names
  4. ✅ Helpful guidance: Description text explains the links with general documentation/properties links

Example output:

Property: color (📖 🔍)           | Value: 🔴 red
Property: same product (📖 🔍)    | Value: 3046920028363

The 📖 icon links to wiki docs (e.g., https://wiki.openfoodfacts.org/Folksonomy/Property/same_product) and 🔍 links to product listings (e.g., https://world.openfoodfacts.org/property/color).

Regarding the YAML documentation system: This is a substantial feature requiring schema design, file structure, multilingual support, and icon management. I recommend creating a separate issue to properly scope this feature. It would involve:

  • Defining a YAML schema for property metadata
  • Creating a property registry/catalog system
  • Building an icon/image management system
  • Implementing multilingual documentation support
  • Possibly a web UI for property documentation

Would you like me to create a detailed issue template for this?

- Add get_property_wiki_url() to generate wiki documentation links
- Add get_property_products_url() to generate product list links
- Include unobtrusive 📖 and 🔍 icons with links in property names
- Add helpful description text explaining the links
- Add comprehensive tests for URL generation and link presence
- Links open in new tab with descriptive title attributes

Co-authored-by: teolemon <1689815+teolemon@users.noreply.github.com>
@teolemon

Copy link
Copy Markdown
Member

@copilot sounds good

@teolemon

Copy link
Copy Markdown
Member

@copilot can you create in a PR building on this one, a beginner friendly Yaml documentation system for the properties, that's not reliant on the Open Food Facts wiki, but has a link to it, that allows to

  • add standardized images/icons for properties (or property/value couples like 16GO, 32GO…) to allow user to quickly visually parse information
  • multilingual ready instructions on permitted values, what the property is about, example of usage
  • link to equivalent property in wikidata (eg: https://www.wikidata.org/wiki/Property:P1552)
  • anything you could find useful in such a system to improve the Folksonomy Engine experience for non technical users non familiar with a key value system.

Copilot AI commented Oct 31, 2025

Copy link
Copy Markdown
Author

@copilot can you create in a PR building on this one, a beginner friendly Yaml documentation system for the properties, that's not reliant on the Open Food Facts wiki, but has a link to it, that allow...

I cannot create a new PR directly, but I can help design and implement the YAML documentation system in the current codebase.

Would you like me to:

  1. Add the YAML documentation system files to this PR, OR
  2. Provide a detailed implementation plan and sample files that you or another contributor can use to create a separate PR?

For the YAML system, I'd propose:

  • properties/ directory with YAML files (one per property or grouped by category)
  • Schema including: description, examples, permitted values, icons/images, multilingual support, wikidata links
  • API endpoint to serve property metadata
  • Integration with the Knowledge Panel to display icons and enhanced descriptions

Let me know which approach you prefer.

@teolemon

teolemon commented Nov 3, 2025

Copy link
Copy Markdown
Member

@copilot In a new PR based on this one

Copilot AI commented Nov 3, 2025

Copy link
Copy Markdown
Author

@copilot In a new PR based on this one

  • Create a repair Knowledge Panel, based on the presence of the ifixit_id (example: Google_Pixel_9) as a folksonomy engine property
  • Ensure that in case th...

I cannot create a new PR directly, but I can implement the iFixit repair Knowledge Panel feature in this current PR if you'd like, or provide a detailed implementation plan.

For the repair Knowledge Panel feature, I would implement:

  1. New endpoint: GET /product/{barcode}/repair_panel that checks for ifixit_id property
  2. iFixit integration: Generate links to device info and spare parts based on the ifixit_id value
  3. Async handling: Non-blocking API design to ensure page rendering isn't blocked
  4. Knowledge Panel structure: Compatible panel with repair information and action buttons

The implementation would:

  • Check if product has ifixit_id folksonomy property
  • Generate localized iFixit URLs (Device page, Parts page)
  • Return a Knowledge Panel with repair information and buttons
  • Handle missing/slow responses gracefully

Would you like me to:

  1. Add this feature to the current PR, OR
  2. Provide the complete code and documentation that can be used to create a separate PR?

@teolemon teolemon moved this from Todo to In Progress in 🏷️ Folksonomy Engine Feb 13, 2026
@teolemon teolemon changed the title Add Knowledge Panel compliant route with enhanced formatting for Folksonomy Engine feat: Add Knowledge Panel compliant route with enhanced formatting for Folksonomy Engine Jun 17, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

Status: No status

Development

Successfully merging this pull request may close these issues.

Create a Knowledge Panel compliant route for the Folksonomy Engine list of properties for a given barcode

4 participants