valueflows

valueflows docs
git clone https://s.sonu.ch/~srfsh/valueflows.git
Log | Files | Refs | README

commit 8cf7aed22d3eb388ec4b39cad5469dc8541b8776
parent 6077de6273e2f26c7db7bbe6ab97ec339c7d9eb3
Author: Bob Haugen <bob.haugen@gmail.com>
Date:   Sat,  3 Aug 2019 14:04:20 -0500

Merge pull request #529 from valueflows/fixes

changes from review of whole doc
Diffstat:
Mdocs/README.md | 2+-
Mdocs/SUMMARY.md | 4++--
Mdocs/introduction/accounting.md | 2+-
Mdocs/introduction/agents.md | 8++++----
Mdocs/introduction/classification.md | 2+-
Mdocs/introduction/concepts.md | 4++--
Mdocs/introduction/contributors.md | 1+
Mdocs/introduction/core.md | 2+-
Mdocs/introduction/exchanges.md | 12++++++------
Mdocs/introduction/flows.md | 54++++++++++++++++++++++++++++--------------------------
Mdocs/introduction/principles.md | 2+-
Mdocs/introduction/processes.md | 10+++++-----
Mdocs/introduction/proposals.md | 8+++-----
Mdocs/introduction/recipes.md | 1-
Mdocs/introduction/resources.md | 8++++----
Mdocs/introduction/scoping.md | 6+++---
Mdocs/introduction/status.md | 34+++++++++++++++-------------------
Mdocs/introduction/transfers.md | 10+++++-----
Mdocs/specification/diagrams/uml.md | 4++--
Mdocs/specification/diagrams/vowl.md | 2+-
Mdocs/specification/external-terms.md | 2+-
21 files changed, 87 insertions(+), 91 deletions(-)

diff --git a/docs/README.md b/docs/README.md @@ -7,7 +7,7 @@ Purpose: to enable internetworking among many different software projects for re Or, with less buzzwords, "let's help a lot of alternative economic software projects that are solving different pieces of the same puzzle be able to work together". -One of the purposes of this vocab is to support resource flows connecting many websites. These flows may be oriented around Processes, Exchanges, or combinations of both. +One of the purposes of this vocab is to support resource flows connecting many software applications. These flows may be oriented around Processes, Exchanges, or combinations of both. We want to support RDF based and non-RDF based use of the vocabulary, basically any way that people want to use software and data on the internet to help create economic networks. diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md @@ -23,8 +23,8 @@ * [Transfers](introduction/transfers.md) * [Exchanges](introduction/exchanges.md) * [Proposals](introduction/proposals.md) -* [Operational Planning](introduction/plans.md) -* [Estimated Planning](introduction/estimates.md) +* [Operational Planning](introduction/plan.md) +* [Budgeting and Analysis](introduction/estimates.md) * [Scoping](introduction/scoping.md) * [Classification](introduction/classification.md) * [Recipes](introduction/recipes.md) diff --git a/docs/introduction/accounting.md b/docs/introduction/accounting.md @@ -20,4 +20,4 @@ Or potentially, views for a global value system economy (really). * from a network to the community * from a network to the ecosystem -Accounting isn't always just counting beans. It will be important for community economies: what resources do we have, what happened with them, how are they doing? What resources do we need? Who needs what? Who can provide what? +Accounting isn't always just counting beans. It will be important for community economies: what resources do we have, what happened with them, how are they doing? What resources do we need? Who needs what? Who can provide what? What waste have we generated and how can we improve? diff --git a/docs/introduction/agents.md b/docs/introduction/agents.md @@ -2,15 +2,15 @@ The agent vocabulary describes networks of people, organizations and networks, constructed using a simple but powerful model of agents and their relationships. -In ValueFlows, we are talking about economic agents, agents who can create or exchange value, and make agreements with each other - who have economic agency. But we want to re-use existing vocabularies for commonly defined things, so we have elected to use those as much as possible here, even though they tend to be more broadly defined. +In ValueFlows, we are talking about economic agents, agents who can create or exchange value, and make agreements with each other - who have economic agency. But we want to re-use existing vocabularies for commonly defined things (foaf:Agent, foaf:Person, org:Organization), so we have elected to use those as much as possible here, even though they are sometimes more broadly defined. We also want to acknowledge that some people prefer to think of themselves as independent and decentralized agents who interact in different places in the economy as individuals, and some people think of themselves more as members of different groups and networks and communities and interact more in the context of those groups and networks and communities. Many experiments are going on as people strive towards another economy. We want to support all these experiments, so want to support both of these ways of thinking and organizing ourselves. The agent vocabulary is very flexible, and will support these as well as current conventional structures. -So, if people want to form a group that has agency as a group, fine. If people want to consider that their group does not have agency as a group, also fine. Not all groups, and especially not all networks, will be vf:Agents. That depends on the agreement of the people in the group. Note that within the vocabulary, network formations will appear, as agents have economic interactions with each other in the world. This does not mean that the network is necessarily a vf:Agent. +So, if people want to form a group that has agency as a group, fine. If people want to consider that their group does not have agency as a group, also fine. Not all groups, and especially not all networks, will be Agents in ValueFlows. That depends on the agreement of the people in the group. Note that within the vocabulary, network formations will appear, as agents have economic interactions with each other in the world. This does not mean that the network is necessarily a ValueFlows Agent. ## Agent Relationships -Agent relationships have many nuances, thus the ability to define one's own kinds of relationships. For example people might "participate" with an organization by means of agreeing to terms and conditions. Or people might have more active "membership" in a group or organization. Or people might consider themselves members but want a more independently flavored term such as "affiliates". +Agent relationships have many nuances, thus VF provides the ability to define one's own kinds of relationships. For example people might "participate" with an organization by means of agreeing to terms and conditions. Or people might have more active "membership" in a group or organization. Or people might consider themselves members but want a more independently flavored term such as "affiliates". A relationship can be direct, like "steward", or more like a role, for example "grower" or "harvester" for a food network. @@ -18,7 +18,7 @@ There are a number of useful Properties in existing vocabularies that can be use Relationships have direction: For example, in "Michael is a member of Enspiral", Michael is the subject and Enspiral is the object. In this case the inverse is also valid, "Enspiral has member Michael". -Relationships can be in a context (or not): For example, "Kathy is mentor of Sam, in the context of Enspiral." +Relationships can be in a scope (or not): For example, "Kathy is mentor of Sam, in the scope of Enspiral." ## Examples diff --git a/docs/introduction/classification.md b/docs/introduction/classification.md @@ -1,6 +1,6 @@ # Classification -Classification creates references to categories, models, and other classifications of the economic resources, processes, and exchanges. The classifications can be a part of a taxonomy, flat list, tag set, faceted classification scheme, and any other structure desired. ValueFlows will not include the structures that the classifications are part of, and assume that is handled outside the VF scope. +Classification creates references to categories and other classifications of the economic resources and processes, and exchanges. The classifications can be a part of a taxonomy, flat list, tag set, faceted classification scheme, and any other structure desired. ValueFlows will not include the structures that the classifications are part of, and assume that is handled outside the VF scope. Classifications can be created by user groups for themselves, or can be existing semantic structures, such as wikidata. diff --git a/docs/introduction/concepts.md b/docs/introduction/concepts.md @@ -1,4 +1,4 @@ -# Flows of Resources +# Flows of Value ![networks of networks picture](https://rawgit.com/valueflows/valueflows/master/release-doc-in-process/network-of-networks.png) @@ -9,7 +9,7 @@ This forms an economic network, where resources flow from agent to agent to agen ### Flows of value in which you can participate -Like Activity Streams, but about value network activities. +Like: * Needs, ideas, offers, requests, plans, new recipes, creations, work to do, stuff we need, income, exchanges * You will be able to subscribe to feeds from networks, with selections of types of activity. * You will be able to respond: offer work, stuff, money, ideas, requests, orders, improvements, etc. diff --git a/docs/introduction/contributors.md b/docs/introduction/contributors.md @@ -30,6 +30,7 @@ * Bill McCarthy * Wim Laurier * Christian Scheller +* Anders Hessellund * Pavel Hruby * Graham Gal * Richard Newmark diff --git a/docs/introduction/core.md b/docs/introduction/core.md @@ -20,4 +20,4 @@ All the levels of the REA ontology are similarly flexible and configurable: * The Plan level represents offers, requests, schedules and promises. * The Observation level represents what really happened. -The core VF vocabulary includes some concepts for which we suggest using other vocabularies. There will also be terms that applications will need that are not part of the VF economic model. This means that it expects people developing those applications to use VF together with other vocabularies / web ontologies. This documentation will suggest other vocabularies and specific terms from them that will come useful in common scenarios that VF aims to address. +The core ValueFlows vocabulary includes some concepts for which we suggest using other rdf-based vocabularies. There will also be terms that applications will need that are not part of the ValueFlows economic model. This means that it expects people developing those applications to use VF together with other vocabularies / web ontologies. This documentation will suggest other vocabularies and specific terms from them that will come useful in common scenarios that VF aims to address. diff --git a/docs/introduction/exchanges.md b/docs/introduction/exchanges.md @@ -1,8 +1,8 @@ # Exchange -Here we look at exchanges of resources from an independent or neutral viewpoint (not the viewpoint of one of the Agents in the exchange). For example, from one Agent's viewpoint, the exchange may be a Purchase, from the other Agent's viewpoint, it might be a Sale. From the neutral viewpoint, it is an exchange of resources, with usually at least two flows of resources, one from each direction. So for example, the seller might give some goods to the buyer, and the buyer might give some money to the seller. Or in a barter exchange, one agent might give the other some books, and the other agent might compensate with some cookies. +Here we look at exchanges of resources from an independent or neutral viewpoint (not the viewpoint of one of the Agents in the exchange). For example, from one Agent's viewpoint, the exchange may be a Purchase, from the other Agent's viewpoint, it might be a Sale. From the neutral viewpoint, it is an exchange of resources, with usually at least two flows of resources, from different directions. So for example, the seller might give some goods to the buyer, and the buyer might give some money to the seller. Or in a barter exchange, one agent might give the other some books, and the other agent might compensate with some cookies. -Exchange is ubiquitous on the internet today, with offers everywhere. In ValueFlows, we want to track not only the offers and promises, but also the actual flows of resources in networks, in all directions. And we support exchanges that don't involve money as well as those that do. +Exchange is ubiquitous on the internet today, with offers everywhere. In ValueFlows, we track not only the offers and promises, but also the actual flows of resources in networks, in all directions. And we support exchanges that don't involve money as well as those that do. Valueflows enables multilateral exchange agreements as well. Any number of agents can commit to flows where they provide something and flows where they receive something. This way creating a reciprocal cycle in the flows graph. So for example, Alice can provide apples from her orchard to Bob, who can provide accommodation to Claire, who can provide tutoring to Alice's children. Such exchanges can happen in infinite number of possible ways, as long as all agents participating agree on specific reciprocal cycle in the flows graph. @@ -11,13 +11,13 @@ We also support non-reciprocal one-way transfers, such as in a gift economy. Ho ### Exchanges and flows -Exchanges as modeled in VF actually relate to flows, not resources. Flows involved in transfers of rights and responsibilities are more obvious. Process related flows can also imply a transfer, and can thus be used as part of an exchange. +Exchanges as modeled in VF actually relate to flows within agreements, not resources directly. Flows involved in transfers of rights and responsibilities are more obvious. Process related flows can also imply a transfer, and can thus be used as part of an exchange. -For example, most timebanks exchange work for credits. The work event can be part of a process that produces something for some other agent. It is also part of an exchange in the timebank. The transfer of credits on the other hand, is not part of any process that creates or transports something, it is merely the recording of one account being decremented and one account being credited. +* For example, most timebanks exchange work for credits. The work event can be part of a process that produces something for some other agent. It is also part of an exchange in the timebank. The transfer of credits on the other hand, is not part of any process that creates or transports something, it is merely the recording of one account being decremented and one account being credited. -Exchange of work also happens in open value networks, where people record work events as input to many processes, and then when income is received for outputs of that work, people receive part of that income, in exchange for their work. +* Exchange of work also happens in open value networks, where people record work events as input to many processes, and then when income is received for outputs of that work, people receive part of that income, in exchange for their work. -Another example is when a service is created as an output of a process, where that service delivery event can be considered an implied transfer, and exchanged for some other resource. +* Another example is when a service is created as an output of a process, where that service delivery event can be considered an implied transfer, and exchanged for some other resource. ### Agreements diff --git a/docs/introduction/flows.md b/docs/introduction/flows.md @@ -5,60 +5,60 @@ Flows are a fundamental construct in the ValueFlows ontology. When put in chrono 1. Intents which can lead to Commitments 2. Commitments which can lead to Economic Events (or Intents can lead directly to Economic Events) -## Intent +### Intent -Intents describe potential future events which have not been agreed to by other agents. Intents are often used for discovering another agent to participate in a desired event. On the process side, for example, planned work could be an Intent, but planned work that some agent committed to is a Commitment. +Intents describe potential future events which have not been agreed to by other agents, such as offers and requests. Intents are often used for discovering another agent to participate in a desired event. On the process side, for example, planned work could be an Intent, but planned work that some agent committed to is a Commitment. -## Commitment +### Commitment -Commitments describe potential future events which the involved agents have already agreed to pursue. Commitments can be considered contractual promises from one agent to another. Commitments are "mirrors" of economic events, and Economic Events can fulfull Commitments. Commitments can satisfy Intents. +Commitments describe potential future events which the involved agents have already agreed to pursue. Commitments can be considered contractual promises from one agent to another. Commitments can be thought of as "mirrors" of economic events, and Economic Events can fulfull Commitments. Commitments can satisfy Intents. -## Economic Events +### Economic Events Economic Events describe past events, something observed, never some potential future event. They can fulfill Commitments or satisfy Intents (when there is no Commitment). -## Claims +### Claims -Claims resemble commitments, but are initiated by the receiver, not the provider. An economic event can trigger a reciprocal claim. Claims do not have to be instantiated, often they can be implied from an economic event and an agreement. +Claims resemble Commitments, but are initiated by the receiver, not the provider. An Economic Event can trigger a reciprocal Claim. Claims do not have to be instantiated, often they can be implied from an Economic Event and an Agreement. For example, if Alice has agreed to sell Bob some carrots for $2, then if Alice delivers the carrots to Bob, she has a claim for $2 from Bob". -## Timeline, plans and observations +### Timeline, plans and observations -Figure below shows that Economic Events have to be observed and for that reason only appear as records of the past. Future plans get represented with Intents and Commitments. +The figure below shows that Economic Events have to be observed and for that reason only appear as records of the past. Future plans get represented with Intents and Commitments. ![flows](https://raw.githubusercontent.com/valueflows/valueflows/master/assets/flows.png) -## Matching Intents +### Matching Intents -Often agents will start their plans independently and record their initial intents. Later once they make a Commitment with other agent, it will represent a specific shared part of their plans. For that reason any Commitment can result in Satisfaction of providing agent's Intent as well as Satisfaction of receiving agent Intent. +Often agents will start their plans independently and record their initial intents. Later once they make a Commitment with another agent, it will represent a specific shared part of their plans. For that reason any Commitment can result in Satisfaction of the providing agent's Intent as well as Satisfaction of the receiving agent's Intent. ![matching](https://raw.githubusercontent.com/valueflows/valueflows/master/assets/matched.png) -## Granularity +### Granularity Intents, Commitments, and Economic Events can occur at any granularity that is needed or for which data can be obtained. So they primarily are used for all operational needs, but can also be used at higher levels for budgeting for organizations, analytical and high level planning needs for communities or regions, etc. ![Intent-Commitment-Event](https://rawgit.com/valueflows/valueflows/master/release-doc-in-process/i-c-e.png) -## Actions +### Actions All flows use an action property to designate what the flow is doing and how it will affect an economic resource (or not). Actions are defined as follows. * vf:produce - new resource created in that process or an existing stock resource added to * vf:use - for example a tool used in process, after the process, the tool still exists -* vf:consume - for example an ingredient composed into the output, after the process the ingredient is gone +* vf:consume - for example an ingredient or component composed into the output, after the process the ingredient is gone * vf:cite - for example a design file, neither used nor consumed, the file remains available at all times -* vf:work - labor power towards a process +* vf:work - labor power applied to a process * vf:load - transported resource enters the process, the same resource will appear in output with *vf:unload* verb * vf:unload - transported resource leaves the process, the same resource will appear in input with *vf:load* verb -* vf:accept - in processes like repair or maintentance, the same resource will appear in output with *vf:modify* verb -* vf:modify - in processes like repair or maintentance, the same resource will appear in input with *vf:accept* verb -* vf:service - new service produced and delivered (being a service implies that an agent actively receives the service +* vf:accept - in processes like repair or modification, the same resource will appear in output with *vf:modify* verb +* vf:modify - in processes like repair or modification, the same resource will appear in input with *vf:accept* verb +* vf:service - new service produced and delivered (a service implies that an agent actively receives the service) * vf:transfer - give rights and/or possession of a resource from one agent to another -* vf:move - change location and/or identity of a resource with no change of agent +* vf:move - change location and possibly identifier, if location is part of the identification, of a resource with no change of agent rights or possession * vf:raise - adjusts a quantity up based on a beginning balance or inventory count * vf:lower - adjusts a quantity down based on a beginning balance or inventory count @@ -66,22 +66,24 @@ Action | Affect | I/O | Changes existence | Pairs with | ------ | ------ | --- | ----------------- | ---------- | produce | Increment | Output | Yes | N/A | consume | Decrement | Input | Yes | N/A | -use | No effect(1) | Input | No s | N/A | +use | No effect(1) | Input | No | N/A | work | No effect(1) | Input | N/A | N/A | cite | No effect | Input | No | N/A | load | No effect | Input | No | unload | unload | No effect | Output | No | load | -accept | No effect | Input | No | improve | -improve | No effect | Output | No | accept | -transfer | Incr+Decr | N/A | No | N/A | -move | Incr+Decr | N/A | No | N/A | +accept | No effect | Input | No | modify | +modify | No effect | Output | No | accept | +transfer | Incr+Decr(2) | N/A | No | N/A | +move | Incr+Decr(2) | N/A | No | N/A | raise | Increment | N/A | No | N/A | lower | Decrement | N/A | No | N/A | -We have defined a core set of actions, but expect that this will be extended with others. If extended, they should be defined as part of this or another formal vocabulary so that all can use them and assume the same meaning. +We have defined a core set of actions, but expect that this will be extended with some others. If extended, they should be defined as part of this or another formal vocabulary so that all can use them and assume the same meaning. (1) The actions `use` and `work` are time-based actions, either with or without an explicit schedule. If the schedule is documented as part of the economic resource, then those economic events could decrement that schedule, although not the "current quantity" of the resource. -## Examples +(2) The actions `transfer` and `move` can optionally define a second identified resource on the receiver side. + +### Examples [import, lang:"yaml"](../../examples/fulfill-satisfy.yaml) diff --git a/docs/introduction/principles.md b/docs/introduction/principles.md @@ -9,5 +9,5 @@ These principles are about the model behind the vocabulary. 5. The model must be able to support circular economies, value flows where resources come full cycle to be fed into the same set or other processes so that recycling, re-use, and other ways to encourage resources not becoming waste. 5. The model must be fractal. It must support global views of networks in aggregate as well as drilling down to lower and lower levels of detail. Those lower levels of detail, for example inside one organization, may require permissions. 6. The model must also work on the Knowledge, Plan and Observation levels, where the objects on each level are linked appropriately to the other levels. -7. The model must support non-business-as-usual organizational forms and economic relationships in addition to traditional business organizations and relationships. These organizational forms can be as varied as the people and groups who create them want. VF in particular embraces this experimentation towards next-economy/solidarity-economy/commons-based-economy/P2P-economy/etc., in this transitional time. +7. The model must support non-business-as-usual organizational forms and economic relationships in addition to traditional business organizations and relationships. These organizational forms can be as varied as the people and groups who create them want. VF in particular embraces this experimentation towards next-economy / solidarity-economy / commons-based-economy / P2P-economy/etc. in this transitional time. 8. The model must support systems where all the contributors can get shares of the outcome to allocate as they wish. In other words, a group can choose to introduce various monetary currencies into their flows but can also do all the coordination and accounting without introducing such artifacts. diff --git a/docs/introduction/processes.md b/docs/introduction/processes.md @@ -2,17 +2,17 @@ By Process, we mean an activity that transforms inputs into outputs. The outputs might then become inputs to other processes, forming networks and chains. Those chains may be circular, where an output from one process becomes an input to another process that occurred previously in the same chain. -For example: a farming process takes compost, soil, seeds, water and human and mechanical work as inputs, and transforms them into grains, nuts, fruit, and vegetables. Those ingredients may go to kitchens that create dinners for people to eat. Some of those ingredients may be pared off in preparation, or spoil, or be left on plates. Those leftovers go into compost, which starts the process chain over from the beginning. +* For example: a farming process takes compost, soil, seeds, water and human and mechanical work as inputs, and transforms them into grains, nuts, fruit, and vegetables. Those ingredients may go to kitchens that create dinners for people to eat. Some of those ingredients may be pared off in preparation, or spoil, or be left on plates. Those leftovers go into compost, which starts the process chain over from the beginning. -Or for a bad example: a CAFO (Confined Animal Feeding Operation) produces a lot of manure. They put manure into big lagoons, which drain into the water table, and come back up in people's drinking water, causing diseases, for which the people become inputs to a hospital. +* Or for a bad example: a CAFO (Confined Animal Feeding Operation) produces a lot of manure. They put manure into big lagoons, which drain into the water table, and come back up in people's drinking water, causing diseases, for which the people become inputs to hospital processes. -One of the inputs to the CAFO process is antibiotics. The animals are filled with antibiotics because they get sick in the CAFO environment. And the antibiotics are also an output, mixed in with the manure. + * One of the inputs to the CAFO process is antibiotics. The animals are filled with antibiotics because they get sick in the CAFO environment. And the antibiotics are also an output, mixed in with the manure and meat. -The antibiotics then breed resistant bacteria, which end up in the people, and send them to the hospital, and then kill the people, because the common antibiotics no longer work. And the resistant bacteria remain in the hospital to kill other people. + * The antibiotics then breed resistant bacteria, which end up in the people, and send them to the hospital, and then kill the people, because the common antibiotics no longer work. And the resistant bacteria remain in the hospital to kill other people. Connected processes enable us to see cause and effect, if we want. -Below is a view of processes, which occur in resource flow networks, and live in three layers: Abstract, which describe how processes work. Plans, which describe processes which are intended to happen. And Observation, which is a record of processes that have already happened. +Below is a view of processes, which occur in resource flow networks, and live in three layers: Knowledge, which describe how processes work. Plans, which describe processes which are intended to happen. And Observation, which is a record of processes that have already happened. ![process resource flow](https://rawgit.com/valueflows/valueflows/master/release-doc-in-process/process-layer.png) diff --git a/docs/introduction/proposals.md b/docs/introduction/proposals.md @@ -6,12 +6,10 @@ Proposals are everywhere in advertising. But we see many groups posting proposa Proposals can stay directed to broad or specific *audience*. In the broadest case, they stay available for anyone (public proposals). In the most narrow case, the stay available only for specific agent. In between those two extremes a whole spectrum exists, for example two distinct proposals can exist on providing particular product or service - one for club members and one for general public etc. -They are more general, often not commercial at all, expressed not in identified products but in categories, tags, and text. But they want to find each other. The offers want to find the matching requests. The requests want to find the matching offers. +Proposals are more general, often not commercial at all, expressed not in identified products but in categories, tags, and text. But they want to find each other. The offers want to find the matching requests. The requests want to find the matching offers. -When they find their match, those with the matching offer and request enter into a [conversation for action](cfa.html) which might result in an agreement, possibly an exchange agreement. +When they find their match, those with the matching offer and request enter into a [conversation for action](cfa.html) which might result in an agreement. -A proposal to do something might enter into conversation for action which might result in commitments for a process. - -Proposals may lead to conversations for action, which may lead to more and better cycles of engagement: +A proposal to do something might enter into conversation for action which might result in commitments for a process. This may lead to more and better cycles of engagement: ![funnel](https://cloud.githubusercontent.com/assets/117439/11401215/144641f6-9357-11e5-8ddd-f01f5bcf4012.png) diff --git a/docs/introduction/recipes.md b/docs/introduction/recipes.md @@ -15,7 +15,6 @@ Recipe patterns can be used alone, or mixed and matched in a recipe: * Bake bread from flour, yeast, water, etc., using an oven. * <b>Workflow pattern</b>: change the same resource into a different stage of the same resource. This describes a sequence of processes used to complete work on one resource. They create a series of stages that one resource will go through until it is finished. For example: * Translate a source document, edit the translation, format for publication, and publish. - * Harvest, dry and garble (refine) batches of herbs. * Repair a bike. * Do quality testing on something that was created using the manufacturing pattern. diff --git a/docs/introduction/resources.md b/docs/introduction/resources.md @@ -14,14 +14,14 @@ Also, we prefer to think of use value, but economic resources also often have ex An economic resource is observable. Its specification or classification defines what kind of thing the economic resource is. -So, for example, most things offered for sale on an e-commerce site are specifications, which can be searched using classifications. The one in a box delivered to your door is a resource. +So, for example, most listings of things offered for sale on an e-commerce site are specifications, which can be searched using classifications. The one in a box delivered to your door is a resource. Or the description of the book entitled "The Power of Babel: A Natural History of Language", ISBN ISBN-13: 978-0060520854, is a specification. Your library may have two copies that you can check out. Those are resources. #### The difference between a resource specification and a resource classification -An economic resource or a flow can have only *resource specification*, defined by `resourceConformsTo`. This defines the lowest level useful type or kind of the resource that is needed. It can be defined within the ValueFlows vocabulary as a ResourceSpecification, or can refer to a specification elsewhere using a uri. Note that often taxonomies and other references on the web can define very specific resource specifications. +An economic resource or a flow can have only *resource specification*, defined by `resourceConformsTo`. This defines the lowest level useful type or kind of the resource that is needed. It can be defined within the ValueFlows vocabulary as a ResourceSpecification, or can refer to a specification elsewhere using a uri. Note that often taxonomies and other references on the web can define very specific resource specifications at their leaf levels. An economic resource or a flow can have any number of *resource classifications*. They are used to filter, match, or group economic resources. Resource classifications can be part of a taxonomy. That means they can be defined very broadly and generally and maybe vaguely, or they can be defined very narrowly, but fit into broader classifications. @@ -42,13 +42,13 @@ a) serialized resources, where each individual instance has a unique identifier, b) lot-controlled resources, where each lot or batch has a unique identifier, but the lot or batch may contain many individual instances, and c) count or volume or stock resources, where individual instances are indistinguishable, or in the case of fluids, only exist on a molecular level. -Serialized resources would fit the direct identification pattern. Lots can be split up, so the identification of a subset of a lot would require some other properties, such as location. Stock resources can only be described indirectly, by means of some combination of properties, such as model and location. (Location is a complex ontology of its own: for example, in warehousing, a location is often composed of warehouse:room:aisle:row:tier.) +Serialized resources would fit the direct identification pattern. Lots can be split up, so the identification of a subset of a lot would require some other properties, such as location. Stock resources can only be described indirectly, by means of some combination of properties, such as specification and location. (Location is a complex ontology of its own: for example, in warehousing, a location is often composed of warehouse:room:aisle:row:tier.) Moreover, identification of resources will depend on context and purpose. We want to allow each context to define resources that they have relationships with, according to the combination of properties that works best for them, which might include which agent has which relationship with a resource. And then in the "independent view", for larger-scale analysis of resource flows, or for example for lot tracking for public health issues like mad cow disease, different combinations of properties might be needed. -Substitutability: This defines if any resources of that specification or classification can be freely substituted for any other resource of that same specification or classification when used, consumed, traded, etc. For example, "B9R-1-red DLP resin photopolymer" is probably substitutable. While each resource for a resource classification called "English-Spanish translation" is probably not substitutable because each will be a different document. +Substitutability: This defines if any resources of that specification or classification can be freely substituted for any other resource of that same specification or classification when used, consumed, traded, etc. For example, one container of "B9R-1-red DLP resin photopolymer" is probably substitutable for another container of the same photopolymer. While each resource for a resource classification called "English-Spanish translation" is probably not substitutable because each will be a different document. #### Inventory diff --git a/docs/introduction/scoping.md b/docs/introduction/scoping.md @@ -2,13 +2,13 @@ `vf:inScopeOf` -Scoping allows grouping entities together in a defined boundary or context. Mostly used for sets of economic events, commitments, and intents. This can be for purposes of: +Scoping allows grouping entities together in a defined boundary or context. Mostly used for sets of economic events, commitments, and intents. Some examples we are familiar with: * accounting * planning * distributing incoming resources -The scope is where work is done, where processes live, where value is created and exchanged. Economic events, commitments and intents can reference an organization (an agent) as an entity that defines their scope. It may be a formal or informal organization, and will include the network(s) themselves. Or economic events, commitments and intents can reference a geographic area (a city, a bio-region, etc.), or a community, or a loose network, or a less formal shorter lived project, or plan, or any other bounded concept that is useful for grouping economic events. +The scope is where work is done, where processes live, where value is created and exchanged. Economic events, commitments and intents can reference an organization (an agent) as an entity that defines their scope. It may be a formal or informal organization, and will include the network(s) themselves. Or economic events, commitments and intents can reference a geographic area (a city, a bio-region, etc.), or a community, or a loose network, or a less formal shorter lived project, or plan, or any other bounded concept that is useful for accounting for economic events. An economic event, commitment or intent can reference any number of entities which scope it. It is not required that events, commitments, or intents designate a scope. In fact, sometimes the scope is the same as the provider or recipient agent. Or sometimes there is no useful scope. @@ -25,7 +25,7 @@ Accounting is usually done for an agent or other bounded scope. Where a computer ## Planning -Sometimes a generic recipe will cross scope boundaries for particular agents. For example one agent could produce a resource that consumes a component made by another agent. In this case, can the first agent schedule the production of the component by the second agent? Possibly yes, if there are agreements in place for that, and the first agent has verified that inventory does not already exist. Or possibly, based again on agreements, the first agent can assume the second agent will provide the component, with the second agent taking responsibility for checking if it is onhand, and if not, scheduling it for production. Or possibly, the first agent plans only to source the component in some way. +Sometimes a generic recipe will cross scope boundaries for particular agents. For example one agent could produce a resource that consumes a component made by another agent. In this case, can the first agent schedule the production of the component by the second agent? Possibly yes, if there are agreements in place for that, and the first agent has verified that inventory does not already exist. Or possibly, based again on agreements, the first agent can assume the second agent will provide the component, with the second agent taking responsibility for checking if it is onhand, and if not, scheduling it for production. Or possibly, the first agent plans only to source the component in some yet-to-be-defined way. ## Distributing Incoming Resources diff --git a/docs/introduction/status.md b/docs/introduction/status.md @@ -1,28 +1,24 @@ # Status of the vocabulary -This documentation is for release 0.2. +This documentation is for release 0.3. -The relatively consolidated parts of the vocabulary include: +This vocabulary is based on decades of work in academia and some limited work in the field in software implementations - and further development by the VF team through documenting and studying use cases. The stability of the model reflects this history. The core model is fairly stable, more so in structure, somewhat less in naming. However, there are many edge cases and possibly not-so-edge cases where the model will need to be adjusted for the reality in the field based on further experience. Also, this model represents something new, something that we want to be able to support the next economy, with all the unknowns that will bring. + +So we see continuous improvements happening as the vocabulary is adopted by more people, through ongoing collaboration between the VF team and the adopters. + +The core model from academia includes: +* Resources, Events, Agents (REA) +* Commitments +* the classifications/specifications in the knowledge layer + +Other relatively consolidated parts of the vocabulary include: * Agent model -* Core Resource model * Core Input-Process-Output model -* Core Commitments -* Beginning of Intents -* Beginning of Exchange * Core Recipe model -* Classifications -Some things yet to come: -* Intents - complete -* Exchange and transfer - complete +Less stable are: +* Intents and Proposals +* Budgeting and Analysis * Recipes - forking/versioning -* Budgets, community analysis, plans -* Transportation -* Time-based resources (scheduling) -* Claims * Conversations for Action/Agreement -* More examples - -A note about the status. This vocabulary is based on decades of work in academia and some limited work in the field in software implementations - and further development by the VF team through documenting and studying use cases. The stability of the model reflects this history. The core model is fairly stable. However, there are many edge cases and possibly not-so-edge cases where the model will need to be adjusted for the reality in the field based on further experience. Also, this model represents something new, something that we want to be able to support the next economy, with all the unknowns that will bring. - -So we see continuous improvements happening as the vocabulary is adopted by more people, through ongoing collaboration between the VF team and the adopters. +* Claims diff --git a/docs/introduction/transfers.md b/docs/introduction/transfers.md @@ -1,13 +1,13 @@ # Transfer -A transfer is an activity that assigns some rights and responsibilities for an economic resource from one agent to another. +A transfer is an activity that assigns some rights and responsibilities for an economic resource from one agent to another, but does not transform or transport the economic resource. -We think that now, and more so in the future, there will be more gradations of rights and responsibilities for resources than are sometimes considered now. For example, as a society we may decide that we should take more responsibility for recycling or upcycling resources at the end of their useful life for us, or not wasting them. The concept of "ownership" may transition more into "stewardship" in a concept of the world that does not put humans in a position of controlling the world's resources. +We think that now, and more so in the future, there will be more gradations of rights and responsibilities for resources than are sometimes considered now. For example, as a society we may decide that we should take more responsibility for recycling or upcycling resources at the end of their useful life for us, or not wasting them. The concept of "ownership" may transition more into "stewardship" in a concept of the world that does not put humans in a position of controlling the world's resources or abdicating responsibilities to the ecosystem in the name of ownership. -For example, perhaps some agent has many apple trees, and plans on pressing apple cider. Another agent has an apple press and agrees to exchange use of the press (a resource) for a portion of the apple cider. The use of the press involves some rights (to use the press for some period of time) and responsibilities (to not run it beyond its capacity and to clean it up before returning it), and the rights and responsibilities to a portion of apple cider is transferred in exchange. +* For example, perhaps some agent has many apple trees, and plans on pressing apple cider. Another agent has an apple press and agrees to exchange use of the press (a resource) for a portion of the apple cider. The use of the press involves some rights (to use the press for some period of time) and responsibilities (to not run it beyond its capacity and to clean it up before returning it), and the rights and responsibilities to a portion of apple cider is transferred in exchange. -Or in a library, a book can be checked out for a period of time. The agent who checks it out is responsible for caring for it and returning it on time, and can read it, or use it however they want. +* Or in a library, a book can be checked out for a period of time. The agent who checks it out is responsible for caring for it and returning it on time, and can read it, or use it however they want. -Or let's say that a community has farmland and equipment held in common. The community transfers that to some farmers to use and take care of. The community also transfers seeds every year to the farmers, enough to grow the food the community needs. During the year, the harvests are distributed (transferred) to the community members for their consumption. In reciprocity, the community provides for other needs of the farmers. +* Or let's say that a community has farmland and equipment held in common. The community transfers that to some farmers to use and take care of. The community also transfers seeds every year to the farmers, enough to grow the food the community needs. During the year, the harvests are distributed (transferred) to the community members for their consumption. In reciprocity, the community provides for other needs of the farmers. In spite of these examples, we also want to note that transfers do not imply explicit or implicit exchanges, only a one-directional flow. diff --git a/docs/specification/diagrams/uml.md b/docs/specification/diagrams/uml.md @@ -1,9 +1,9 @@ ### UML Representation -![VF uml picture](https://rawgit.com/valueflows/valueflows/master/release-doc-in-process/ValueFlowsUML.png) - Note: There are some differences in this representation and the RDF based representation. * This is to support object oriented and relational implementations, as well as open vocabularies that are not RDF based. This is mostly where there are rdf properties not associated with classes. * This includes all elements necessary for the vocabulary, so includes (and denotes) necessary elements that we re-use from other vocabularies. +![VF uml picture](https://rawgit.com/valueflows/valueflows/master/release-doc-in-process/ValueFlowsUML.png) + Credit: https://support.draw.io/ diff --git a/docs/specification/diagrams/vowl.md b/docs/specification/diagrams/vowl.md @@ -2,7 +2,7 @@ You can view this in an active environment [here](http://www.visualdataweb.de/webvowl/#iri=https://raw.githubusercontent.com/valueflows/valueflows/master/release-doc-in-process/all_vf.TTL). -Note that this diagram includes only the linked open data VF namespace, so does not include important items for which we are re-using other namespaces. See [the UML Diagram](specification/diagrams/uml.md) for a complete model with the namespaces identified. +Note that this diagram includes only the linked open data VF namespace, so does not include important items for which we are re-using other namespaces. See [the UML Diagram](https://valueflo.ws/specification/diagrams/uml.html) for a complete model with the namespaces identified. ![VF uml picture](https://rawgit.com/valueflows/valueflows/master/release-doc-in-process/all-vf-vowl.svg) diff --git a/docs/specification/external-terms.md b/docs/specification/external-terms.md @@ -1,6 +1,6 @@ # External terms -Most applications using VF will need terms defined in various other vocabularies. Below we recommend reusing some from well established vocabularies (web ontologies). +Most applications using VF will need terms defined in various other vocabularies. In fact, some of these are essential to the complete ValueFlows model. Below are the essential elements we are reusing from well established vocabularies (web ontologies). ## SKOS