Eaternity Schema Reference

The Eaternity schema defines the data model for the Environmental Operating System (EOS), Eaternity's platform for food sustainability assessment. The ESFC Glossary includes 40 Eaternity terms: 24 schema classes and 16 property terms.

Overview

Eaternity schema terms provide a direct mapping between user data and the EOS API, enabling semantic matching of CSV columns to schema fields and supporting zero-configuration data import.

Key Statistics:

Schema Classes: 24 terms
Property Terms: 16 terms
Total Terms: 40
Format: LinkML YAML with JSON-LD context
Source: gitlab.com/eaternity/eos

Purpose and Applications

Primary Use Cases

Data Import Mapping
- Semantic matching of user CSV columns to EOS fields
- Automatic field recognition and validation
- Zero-configuration data integration
API Integration
- Direct mapping to EOS API endpoints
- Type-safe data structures
- Schema validation
Food Sustainability Assessment
- Environmental impact calculations
- Carbon footprint analysis
- Sustainability scoring
Research and Analysis
- Food system modeling
- Supply chain analysis
- Sustainability metrics development

Schema Classes (24 Terms)

Core Flow Classes

FlowNode

Description: Represents material flows in the food system.

Key Properties:

product_name - Product identification
amount - Quantity
flow_location - Geographic origin
glossary_tags - Product categorization

Use Cases:

Ingredient tracking
Material flow accounting
Supply chain mapping

Example:

'@type': FlowNode
product_name: "Organic Wheat Flour"
amount: 500
unit: "kg"
flow_location: "CH"
glossary_tags: ["grain", "wheat", "organic"]

FoodProductFlowNode

Description: Specialized flow node for food products with additional food-specific properties.

Extends: FlowNode

Additional Properties:

amount_per_category_required_for_flow - Required quantity
raw_processing - Processing method
raw_production - Production method
raw_conservation - Conservation method
raw_labels - Certifications and labels

Use Cases:

Food product LCA
Recipe environmental impact
Ingredient sustainability assessment

Example:

'@type': FoodProductFlowNode
product_name: "Grass-fed Beef"
amount: 1000
raw_production: "extensive-pasture"
raw_labels: ["organic", "grass-fed"]
flow_location: "CH"

ActivityNode

Description: Represents production and processing activities in the food system.

Key Properties:

activity_type - Type of activity (production, processing, transport)
activity_location - Where activity occurs
inputs - Input flows
outputs - Output flows

Use Cases:

Process modeling
Activity-based costing
Supply chain analysis

Example:

'@type': ActivityNode
activity_type: "wheat-milling"
activity_location: "CH"
inputs: [wheat-grain-flow]
outputs: [wheat-flour-flow]

Impact Assessment Classes

ImpactAssessment

Description: Environmental impact calculation results.

Key Properties:

gwp_total - Total global warming potential
water_use - Water consumption
land_use - Land occupation
biodiversity_impact - Biodiversity effects

Use Cases:

Carbon footprint reporting
Environmental impact disclosure
Sustainability scoring

Example:

'@type': ImpactAssessment
gwp_total: 2.5  # kg CO₂-eq
water_use: 150  # liters
land_use: 0.5   # m²

Data Management Classes

Recipe

Description: Multi-ingredient food products with preparation methods.

Key Properties:

recipe_name - Recipe identifier
ingredients - List of ingredient flows
preparation_steps - Cooking/preparation activities
yield - Recipe output quantity

Use Cases:

Menu carbon footprinting
Recipe optimization
Meal planning sustainability

SupplyChain

Description: Complete supply chain from farm to fork.

Key Properties:

origin - Starting point
destination - End point
stages - List of activities and flows
total_impact - Aggregated environmental impact

Use Cases:

Full supply chain LCA
Hotspot identification
Transparency reporting

Auxiliary Classes

Other schema classes include:

NutrientValues - Nutritional composition
Producer - Producer/manufacturer information
Supplier - Supplier details
Location - Geographic location data
Label - Certification and label information
ProcessingMethod - Food processing details
ProductionMethod - Agricultural/production practices
ConservationMethod - Storage and preservation
TransportMode - Transportation methods
PackagingInfo - Packaging details
And 8+ more specialized classes

Property Terms (16 Terms)

Property terms represent individual fields within schema classes, enabling granular semantic matching.

Priority Classification

Properties are classified by their importance for calculation accuracy:

High-Priority: Required fields that significantly impact environmental calculations (product identity, quantity, origin)
Standard Properties: Additional fields that refine calculations but have sensible defaults

High-Priority Properties (6 terms)

These properties are essential for accurate environmental impact calculations:

1. Product Name

ID: eaternity-property-productname Python Field: product_name Parent Schema: FlowNode Data Type: String Domain: Identification

Usage Examples:

Product Name
Product
Item Name
Food Name
Name
Produktname (German)

Value Examples:

"Organic Wheat Flour"
"Grass-fed Beef"
"Tomato Sauce"

2. Quantity

ID: eaternity-property-amount Python Field: amount Parent Schema: FlowNode Data Type: Numeric (with unit) Domain: Measurement

Usage Examples:

Quantity
Amount
Weight
Mass
Volume
Menge (German)

Value Examples:

500 (kg)
1.5 (L)
250 (g)

3. Required Amount

ID: eaternity-property-amountpercategoryrequiredforflow Python Field: amount_per_category_required_for_flow Parent Schema: FoodProductFlowNode Data Type: Numeric Domain: Measurement

Usage Examples:

Required Amount
Required Quantity
Flow Amount
Benötigte Menge (German)

4. Origin Country

ID: eaternity-property-flowlocation Python Field: flow_location Parent Schema: FlowNode Data Type: Categorical (country codes) Domain: Geography

Usage Examples:

Origin Country
Origin
Country
Location
Herkunftsland (German)

Value Examples:

"CH" (Switzerland)
"DE" (Germany)
"IT" (Italy)

5. Processing Method

ID: eaternity-property-rawprocessing Python Field: raw_processing Parent Schema: FoodProductFlowNode Data Type: Categorical Domain: Process

Usage Examples:

Processing
Processing Method
Processing Type
Verarbeitung (German)

Value Examples:

"fresh"
"frozen"
"canned"
"dried"

6. Product Category

ID: eaternity-property-glossarytags Python Field: glossary_tags Parent Schema: FlowNode Data Type: Array of strings Domain: Classification

Usage Examples:

Category
Type
Classification
Product Category
Kategorie (German)

Value Examples:

["grain", "wheat", "organic"]
["dairy", "cheese", "hard"]
["meat", "beef", "fresh"]

Medium-Priority Properties (10 terms)

7. Nutritional Values

ID: eaternity-property-nutrientvalues Python Field: nutrient_values Parent Schema: FoodProductFlowNode Domain: Nutrition

Usage Examples:

Nutritional Values
Nutrients
Nutrition Facts
Nährwerte (German)

8. Ingredients

ID: eaternity-property-ingredientsdeclaration Python Field: ingredients_declaration Parent Schema: Recipe/FoodProductFlowNode Domain: Composition

Usage Examples:

Ingredients
Ingredient List
Components
Zutaten (German)

9. Production Method

ID: eaternity-property-rawproduction Python Field: raw_production Parent Schema: FoodProductFlowNode Domain: Process

Usage Examples:

Production
Production Method
Growing Method
Produktion (German)

Value Examples:

"organic"
"conventional"
"greenhouse"
"grass-fed"

10. Conservation Method

ID: eaternity-property-rawconservation Python Field: raw_conservation Parent Schema: FoodProductFlowNode Domain: Process

Usage Examples:

Conservation
Storage Method
Preservation
Konservierung (German)

Value Examples:

"fresh"
"frozen"
"refrigerated"
"ambient"

11. Labels & Certifications

ID: eaternity-property-rawlabels Python Field: raw_labels Parent Schema: FoodProductFlowNode Domain: Certification

Usage Examples:

Labels
Certifications
Quality Marks
Label (German)

Value Examples:

["organic", "fair-trade"]
["bio-suisse"]
["eu-organic", "carbon-neutral"]

12. Producer

ID: eaternity-property-producer Python Field: producer Parent Schema: FoodProductFlowNode Domain: Organization

13. Supplier

ID: eaternity-property-supplier Python Field: supplier Parent Schema: FoodProductFlowNode Domain: Organization

14. Product Code (GTIN)

ID: eaternity-property-gtin Python Field: gtin Parent Schema: FoodProductFlowNode Domain: Identification

Value Examples:

"7610200078753"
"4260123456789"

15. Storage Duration

ID: eaternity-property-storagetime Python Field: storage_time Parent Schema: FoodProductFlowNode Domain: Temporal

16. Unit

ID: eaternity-property-unit Python Field: unit Parent Schema: FlowNode Domain: Measurement

Value Examples:

"kg"
"L"
"piece"

Semantic Matching Workflow

User CSV to EOS API

The Eaternity property terms enable automatic mapping:

Step 1: User CSV Column Header
"Product Name" or "Produktname" or "Item Name"
    ↓
Step 2: Semantic Search in ESFC Glossary
Finds: eaternity-property-productname
    ↓
Step 3: Extract Python Field Name
pythonFieldName: "product_name"
    ↓
Step 4: Map to EOS API Field
FlowNode.product_name
    ↓
Step 5: Validate and Submit
Data validated against schema

Example CSV Import

User CSV:

Product Name,Weight,Origin Country,Processing
Organic Tomatoes,500,IT,fresh
Wheat Flour,1000,CH,milled

Semantic Matching:

"Product Name" → eaternity-property-productname → FlowNode.product_name
"Weight" → eaternity-property-amount → FlowNode.amount
"Origin Country" → eaternity-property-flowlocation → FlowNode.flow_location
"Processing" → eaternity-property-rawprocessing → FoodProductFlowNode.raw_processing

EOS API Payload:

{
  "@type": "FoodProductFlowNode",
  "product_name": "Organic Tomatoes",
  "amount": 500,
  "unit": "kg",
  "flow_location": "IT",
  "raw_processing": "fresh"
}

Integration Examples

TypeScript with EOS API

import { Glossary, Term } from './glossary.types'

// Load glossary
const glossary: Glossary = await fetch('/glossary.json')
  .then(r => r.json())

// Get Eaternity property terms
const eosProperties = glossary.terms.filter(t =>
  t.source === 'eaternity' &&
  t.id.startsWith('eaternity-property-')
)

// Map CSV header to EOS field
function mapHeaderToEOSField(header: string): string | null {
  const normalized = header.toLowerCase().trim()

  for (const property of eosProperties) {
    const usageExamples = property.properties?.usageExamples || []
    if (usageExamples.some(ex =>
      ex.toLowerCase() === normalized
    )) {
      return property.properties?.pythonFieldName || null
    }
  }

  return null
}

// Example usage
const headers = ['Product Name', 'Produktname', 'Weight', 'Menge']
headers.forEach(header => {
  const field = mapHeaderToEOSField(header)
  console.log(`${header} → ${field}`)
})
// Output:
// Product Name → product_name
// Produktname → product_name
// Weight → amount
// Menge → amount

Python Data Import

import json
import pandas as pd

# Load glossary
with open('glossary.json') as f:
    glossary = json.load(f)

# Get EOS property terms
eos_properties = [
    t for t in glossary['terms']
    if t['source'] == 'eaternity' and
       t['id'].startswith('eaternity-property-')
]

# Build mapping dictionary
header_to_field = {}
for prop in eos_properties:
    python_field = prop.get('properties', {}).get('pythonFieldName')
    if python_field:
        examples = prop.get('properties', {}).get('usageExamples', [])
        for example in examples:
            header_to_field[example.lower()] = python_field

# Map user CSV
user_df = pd.read_csv('user_data.csv')
mapped_columns = {}

for col in user_df.columns:
    eos_field = header_to_field.get(col.lower())
    if eos_field:
        mapped_columns[col] = eos_field
        print(f"Mapped: {col} → {eos_field}")

# Rename columns for EOS API
eos_df = user_df.rename(columns=mapped_columns)

SQL Queries

-- Get all Eaternity property terms
SELECT id, name, properties->>'pythonFieldName' as python_field,
       properties->>'domain' as domain,
       properties->>'priority' as priority
FROM terms
WHERE source = 'eaternity'
  AND id LIKE 'eaternity-property-%'
ORDER BY priority, domain;

-- Find property by usage example
SELECT id, name, properties->>'pythonFieldName' as python_field
FROM terms
WHERE source = 'eaternity'
  AND properties->>'usageExamples' LIKE '%Weight%'
  OR properties->>'usageExamples' LIKE '%Menge%';

-- Get high-priority properties
SELECT id, name, properties
FROM terms
WHERE source = 'eaternity'
  AND id LIKE 'eaternity-property-%'
  AND properties->>'priority' = 'high';

Property Domains

Properties are organized by domain for better categorization:

Domain	Properties	Examples
Identification	2	Product Name, GTIN
Measurement	3	Quantity, Required Amount, Unit
Geography	1	Origin Country
Process	3	Processing, Production, Conservation
Classification	1	Product Category
Nutrition	1	Nutritional Values
Composition	1	Ingredients
Certification	1	Labels & Certifications
Organization	2	Producer, Supplier
Temporal	1	Storage Duration

Multilingual Support

Property terms include usage examples in multiple languages:

English:

Product Name
Quantity
Origin Country

German:

Produktname
Menge
Herkunftsland

Future Expansion:

French (Nom du produit, Quantité, Pays d'origine)
Italian (Nome prodotto, Quantità, Paese di origine)
Spanish (Nombre del producto, Cantidad, País de origen)

Best Practices

Property Selection

Use Most Specific Property
- Prefer specific properties over generic ones
- Match domain to your data type
- Consider data validation requirements
Multilingual Headers
- Support multiple language variants
- Normalize headers before matching
- Case-insensitive matching
Validation
- Check expected data types
- Validate categorical values
- Ensure unit consistency

Data Quality

Completeness:

Include all required properties
Provide optional properties when available
Document missing data

Consistency:

Use standardized values for categorical fields
Apply consistent units
Follow EOS data quality guidelines

Traceability:

Record mapping decisions
Link to source data
Document transformations

Version and Updates

Current Version: Synchronized with EOS release Update Method: Manual extraction from EOS schema Update Frequency: With each EOS major release

Extraction Process

# Parse Eaternity schema
npm run parse:eaternity

# Generates:
# - output/eaternity/processed/terms.yaml (24 schema classes)
# - output/eaternity/processed/property-terms.yaml (16 properties)

# Build complete glossary
npm run build

Resources

EOS Schema Resources

GitLab Repository: gitlab.com/eaternity/eos
Schema Definition: Python class definitions
API Documentation: EOS API reference
Field Descriptions: Inline documentation

ESFC Glossary Resources

40 Eaternity terms (24 classes + 16 properties)
Semantic matching for CSV import
Direct API mapping via pythonFieldName
TypeScript types for integration

Future Enhancements

Phase 3 Expansion

Additional Properties (50-100+ terms):

All remaining FlowNode fields (~10 more)
Complete ActivityNode properties (~20 more)
Nested property fields (nutrient sub-fields)
Impact assessment properties

Enhanced Descriptions:

More multilingual variations (FR, IT, ES)
Data validation rules
Expected value ranges
Links to FoodEx2/Hestia mappings

API Integration:

OpenAPI schema generation
Request validators
Form field generators
Auto-documentation

Data Sources - Overview of all 10 sources
Semantic Mapping - AI-powered matching
Data Formats - Export formats
Hestia Reference - Environmental impact data
FoodEx2 Reference - Food classification

License

License: Proprietary (Eaternity) Usage: EOS schema terms available for reference Integration: Free for EOS API users Full Schema: Requires EOS license

Overview​

Purpose and Applications​

Primary Use Cases​

Schema Classes (24 Terms)​

Core Flow Classes​

FlowNode​

FoodProductFlowNode​

ActivityNode​

Impact Assessment Classes​

ImpactAssessment​

Data Management Classes​

Recipe​

SupplyChain​

Auxiliary Classes​

Property Terms (16 Terms)​

High-Priority Properties (6 terms)​

1. Product Name​

2. Quantity​

3. Required Amount​

4. Origin Country​

5. Processing Method​

6. Product Category​

Medium-Priority Properties (10 terms)​

7. Nutritional Values​

8. Ingredients​

9. Production Method​

10. Conservation Method​

11. Labels & Certifications​

12. Producer​

13. Supplier​

14. Product Code (GTIN)​

15. Storage Duration​

16. Unit​

Semantic Matching Workflow​

User CSV to EOS API​

Example CSV Import​

Integration Examples​

TypeScript with EOS API​

Python Data Import​

SQL Queries​

Property Domains​

Multilingual Support​

Best Practices​

Property Selection​

Data Quality​

Version and Updates​

Extraction Process​

Resources​

EOS Schema Resources​

ESFC Glossary Resources​

Future Enhancements​

Phase 3 Expansion​

Related Documentation​

License​

Overview

Purpose and Applications

Primary Use Cases

Schema Classes (24 Terms)

Core Flow Classes

FlowNode

FoodProductFlowNode

ActivityNode

Impact Assessment Classes

ImpactAssessment

Data Management Classes

Recipe

SupplyChain

Auxiliary Classes

Property Terms (16 Terms)

High-Priority Properties (6 terms)

1. Product Name

2. Quantity

3. Required Amount

4. Origin Country

5. Processing Method

6. Product Category

Medium-Priority Properties (10 terms)

7. Nutritional Values

8. Ingredients

9. Production Method

10. Conservation Method

11. Labels & Certifications

12. Producer

13. Supplier

14. Product Code (GTIN)

15. Storage Duration

16. Unit

Semantic Matching Workflow

User CSV to EOS API

Example CSV Import

Integration Examples

TypeScript with EOS API

Python Data Import

SQL Queries

Property Domains

Multilingual Support

Best Practices

Property Selection

Data Quality

Version and Updates

Extraction Process

Resources

EOS Schema Resources

ESFC Glossary Resources

Future Enhancements

Phase 3 Expansion

Related Documentation

License