valueflows

name

valueflows

description

ValueFlows 1.0 ontology mapping and reference. Maps domain entities and data models to VF classes and properties, explains ontology concepts, generates TypeScript/GraphQL/JSON-LD types from VF classes, and validates existing mappings against the VF 1.0 spec. Use when working with valueflows, vf: ontology, REA accounting, hREA, distributed/commons economic networks, economic events, economic resources, agents, commitments, intents, processes, recipes, agreements, or proposals; or when a user asks to map a schema to valueflows, generate VF types, or validate a VF mapping.

ValueFlows Skill

Reference and mapping assistant for the ValueFlows 1.0 ontology, a vocabulary for distributed economic networks coordinating creation, distribution, and exchange of economic resources.

Quick Reference

Namespace: vf: = https://w3id.org/valueflows/ont/vf# · Version 1.0.0

Layers at a glance:

• Core — EconomicResource, EconomicEvent, Agent, Process, Action, Measure, ResourceSpecification
• Planning — Intent, Commitment, Claim, Plan
• Exchange — Agreement, Proposal
• Recipe — Recipe, RecipeProcess, RecipeFlow

The REA flow: Intent → Commitment → EconomicEvent (planned → promised → observed)

Workflow Routing

Pick the workflow that matches the task, then load the referenced file on demand.

Workflow	Trigger	File
Map entity	"map to valueflows", "what vf class is", "map this entity/schema/model"	Workflows/map-entity.md
Explain concept	"explain vf:X", "what is vf class Y", "difference between X and Y in VF"	Workflows/explain-concept.md
Generate types	"generate vf types", "typescript for vf", "graphql schema for vf", "json-ld context for vf"	Workflows/generate-types.md
Validate mapping	"validate this mapping", "check vf mapping", "is this correct VF"	Workflows/validate-mapping.md

All workflows assume ontology.md will be loaded for class and property lookups. Load it when the task involves any specific VF class, property, or IRI.

Gotchas

These are the non-obvious points where mappings most often go wrong. Read them before producing any mapping or validation output.

• accountingQuantity vs onhandQuantity — accounting is the amount the agent has rights/responsibilities over (ownership); onhand is the amount physically present under direct control. Custody transfers move onhand but not accounting; rights transfers move accounting but not onhand.
• Instance vs specification — EconomicResource is a real tracked thing; ResourceSpecification is the kind/template. Same for Process vs RecipeProcess. Always check which one the domain entity actually is.
• Intent vs Commitment vs EconomicEvent — Intent is one-party desire/estimate, Commitment is bilateral promise, EconomicEvent is observed flow. Lifecycle stage drives the class, not the data shape.
• Agreement vs Commitment — Agreement is the container; Commitments are its clauses. An Agreement on its own with no Commitments is empty.
• provider and receiver are always Agents, never resources. The resource flows between them via resourceInventoriedAs / toResourceInventoriedAs.
• toResourceInventoriedAs is only needed when the sender and receiver track the same physical resource as different inventory items (i.e. the resource shows up in two different inventories). For purely internal moves, use only resourceInventoriedAs.
• Action vocabulary is fixed. Use only the actions listed in ontology.md (consume, produce, use, work, cite, transfer, transfer-all-rights, transfer-custody, move, raise, lower, accept, modify, dropoff, pickup, deliver-service). Custom actions break interoperability.
• transfer vs transfer-all-rights vs transfer-custody — transfer moves both rights and custody; transfer-all-rights moves accountability only; transfer-custody moves physical custody only. Choose deliberately.
• Unmapped fields — When a domain field has no direct VF equivalent, use vf:classifiedAs (URI/tag categorisation) or vf:note (free text) as the fallback. Flag these explicitly in any mapping output rather than silently dropping them.

Conventions

• Always cite the full IRI on first reference (https://w3id.org/valueflows/ont/vf#ClassName), then the prefixed form (vf:ClassName) afterwards.
• When generating code, include JSDoc/comments linking each type back to its VF IRI so the mapping is auditable.
• Report unmapped concepts explicitly rather than hiding them.

References

• ontology.md — Full VF 1.0 class and property reference, action vocabulary, datatype properties, and common patterns. Load whenever the task touches a specific class or property.
• Workflows/map-entity.md — Decision tree and output template for mapping a domain entity or schema to VF.
• Workflows/explain-concept.md — Structure for explaining a VF class or property in depth.
• Workflows/generate-types.md — TypeScript / GraphQL / JSON-LD generation patterns.
• Workflows/validate-mapping.md — Validation checks and report template.
• Upstream spec: https://www.valueflo.ws/specification/spec-overview/
• TTL source: https://codeberg.org/valueflows/pages/src/branch/main/assets/all_vf.TTL