What does it mean to implement ?

This page outlines the technical considerations for platforms joining the Food Data Collaboration (FDC) Commons.

There are other considerations for partners in the FDC Commons:

  • We require partner organisations to align with the values outlined in our Vision and Mission, listed on our About page.
  • We also invite all platform partners to consider whether they’d be willing (and have capacity) to participate in our Governance circle.
  1. Background

The Food Data Collaboration project aims to leverage the work of the (French-initiated) Data Food Consortium (DFC) project. This project is defining an interoperability web standard for short supply chain food data.

The documentation of the DFC standard, including information on its evolution and documentation of various decisions that have been taken along the way is available on gitbook.

A lot of useful information relating to the DFC project and standard are available on their GitHub homepage.

  • Ontology

The Data Food Consortium has defined an ontology that we align to. The DFC ontology provides a general knowledge framework that maps the concepts used within Short Foodchain Systems in a machine readable format. It is a more logically rigorous form than an application Model but for our purposes it can be thought of as similar.

It is not necessary to understand the ontology in order to implement. 

However, if you’d like to take a look, the technical details of the ontology are available here:

  • The source of truth for the ontology is the DFC Github repository. Files are also published (on release) to the DFC website: https://docs.datafoodconsortium.org/ontology/  
  • The latest pre-release/development version can be found in the NextOntology branch. Consult with the FDC team to confirm which branch of the ontology you need, as they correspond to difference versions of the standard.
  • Taxonomies (product type, units etc…) can be found in a separate repository. 
  • Both the taxonomy files and the business onotology can also be viewed on the DFC site, using the ShowVOC tool.
  • If you need to enhance/enrich any of the Taxonomies, you can propose changes through the Vocbench tool.

Some useful tools for viewing/understanding ontologies:

  • Prototype

The Data Food Consortium have also built a prototype, this facilitates product data testing for platforms and is currently the primary interface between the systems – as per the DFC standard. 

In the longer term it is intended that any member of the Data Commons will be able to directly push reads and changes (record create, update and delete statements), for the data they own and control, to all other platforms within the Commons, via a JSON-LD API that conforms to the DFC ontology. 

The prototype provides an intermediary step to facilitate systems debugging their interfaces and further development of the standard. The prototype is published under an MIT licence and code is available on github. The current instance of the prototype is available here: https://proto.datafoodconsortium.org/ 

  1. FDC Phase 1 

There are 3 major technical steps in Phase 1 (the currently funded phase) of the FDC project:

  1. Interface the platforms with an Open ID Connect (OIDC) provider: currently the DFC project manages a realm on the Les Communs (website in French) Keycloak server.
    1. This involves implementing OIDC interface technology within the platform. Further information on this can be found here, briefly:
      1. Your platform will need to be authorised to connect to the DFC realm of Les Communs and supplied with a client id & secret.
      2. Other configuration required to connect to the DFC OIDC realm can be found here.
      3. Within FDC we are utilising signed JWT tokens in the authorization header.
      4. Your platform will need to integrate Open ID Connect functionality.
        • You will need to support the following:
          • Authentication & Authorization Flows
          • Logout Flows
          • Refresh Token Flow
          • Secure storage of Access & Refresh Tokens (in particular offline access)
      5. A good primer for OIDC can be found here. Also more detail on Oauth flows (including Refresh Flow) here.
      6. There are supported libraries in all major programming languages & web application frameworks. A list of certified OIDC libraries can be found on the website here, and there are some uncertified libraries also available. Care should be taken to ensure any library selected supports all required functionality.
  1. A producer or hub user on your platform will need to be able to either:
    1. Login & set-up a hub/supplier account with a Les Communs ID, or
    2. Link an existing producer/hub account to an OIDC account provided by Les Communs.
    3. It is not necessary for shoppers/customers to have access to the OIDC logins or a Les Communs account. Although if you wish to support that on your platform, that’s fine.
  1. Users must also be able to opt out of data sharing via the FDC.
    • This requirement would be supported by using the link/delink existing accounts on your platform strategy outlined above.
  1. In addition FDC Commons Governance requires all platforms to have the ability to exclude individual users from the Commons (in cases of extreme or repeated breaches of Commons Rules). The FDC does not seek to control who can or cannot use individual platforms, however we have a duty to protect the integrity of the Commons.
    • This could take the form of a superadmin override that allows you to restrict access to the OIDC functionality/account linking.
    • If you wish to allow users to create accounts with Les Communs IDs, it may be more complex to implement these controls whilst continuing to allow banned users to access your platform.
    • This functionality potentially overlaps with the functionality required for the planned pilot roll-outs to specific geographic areas/subsets of users.
  1. Create and publish a CRUD API for Products (Supplied Products and Catalog Items in DFC terms) data utilising the DFC JSON-LD standard (example here).
    1. Including:
      ❇ Read an individual Enterprise details (including linked Person, Products & Catalogs)
      ❇ A bulk GET of all Products (for all Enterprises linked to a User)
      ❇ Create an individual Product (for a specific Enterprise and User)
      ❇ Read an individual Product (for a specific Enterprise and User)
      ❇ Update an individual Product (for a specific Enterprise and User)
      ❇ Delete an individual Product (for a specific Enterprise and User) 
    2. The API will need to be authenticated against an OIDC user, and access control managed so that only products controlled by that user are visible/updateable.
    3. The API responsiveness will need to be within agreed timeliness and availability criteria (these are to be agreed with Tech Partners).
    4. An example API specification for DFC endpoints is available here.This is currently a work in progress and covers more than is required for this phase of work, contact FDC for clarification.

  1. Exposure (and consumption) of Product data from anywhere else in the Food Data Collaboration Commons within the platform’s shopfront.
    1. Enabling querying of DFC Product data from other platforms
    2. Displaying that data in the shopfront of your platform
    3. Ensuring any caching (for performance) is managed, esp. within checkout processes such that only up to date stock is sold from any source platform.
    4. Ensuring any stock updates (sales and returns) are pushed to the source platform within the commons in a timely manner (SLA’s will be agreed within the Technical working group).
  • To test integrations are working, we initially suggest testing against the DFC Prototype. Your test server will need to interface with this prototype to verify your API is working correctly.
    • You will need to provide the URL for your bulk product GET endpoint, we will configure Keycloak access and provide the Client ID & Secret.
    • We will verify the prototype can bulk import product data from your platform.
    • Products can be edited and manually linked to products from other platforms within the Prototype.
    • We will verify that the prototype can push data updates back to your platform (e.g. a linked product can have description and/or stock updates pushed to align multiple platforms)
  • We also follow up with an integration test using active test instances of pre-integrated platforms.
  • FDC Platforms are currently implementing standard version v1.9:  
  • The Data Food Consortium have developed a Connector Tool – which utilises Acceleo to generate code libraries to facilitate implementation of the DFC Ontology as a Model within applications. See a short (and old) demo here.
  • This library allows an application to access the DFC structures as any other model object – create and populate instances of the various classes in the ontology and output as JSON-LD, compliant with the DFC standard. It is highly recommended platforms implement utilising these libraries.
    • Currently releases include:
    • The Connector is designed to be implemented into other programming languages (using the acceleo framework). Development costs are anticipated at £1,500-£3,000, and to be borne by the associated project.
    • Packages for the connectors will be published on appropriate code repositories (e.g. NPM, Rubygems etc…)
    • Please note the connector relies on a UML model. This is not a complete map of the DFC Ontology. If you require specific entities, they may need to be added to the model before regenerating the connector code.

Implementation

The FDC project is currently funded to perform several pilots within the UK:

The first pilot is with the Hodmedods trade store, testing our advanced Orders functionality (beyond the scope outlined here) between Shopify storefronts. Whilst this may seem stage, it allows us to test our interoperability functionality against a single platform and provides value to our pilot users by automating updates to the product catalogue (including pricing) and placing of purchase orders/stock management.

The second pilot involves linking a small producer using a Shopify store with an Open Food Network hub for integrated Ordering.

Our third pilot will link a group of OFN Hubs with the Hodmedods trade store to allow combined bulk orders to reduce costs to hubs whilst automating the complexity of managing group orders (including split cases).

Conclusion

So, a brief overview of the journey…

  • Implement the Open ID Connect functionality to enable your platform to authenticate across the commons
  • Expose your data in a REST API that fits the DFC Standard
  • Consume the same data from other platforms in your shopfront
  • Test this functionality using the DFC Prototype
  • Engage with our pilots

We hope you’re inspired to join us on this journey. We anticipate more complexity and will update this (and other documents) with more accurate information based on our findings and failures as we progress. We believe this digital infrastructure has the potential to change the face of local food systems in the UK (and beyond) – if you agree please get in touch.