practical valueflows

[orangeman]

How to get started using valueflows in concrete apps?

Afaics the vf ontology is specified in .ttl and .jsonld formats. Are these the same, just in different syntax?

There are also json-schemas. Are these autogenerated from the ontology? Are they less expressive?

I would like to try the valueflows vocabulary in a very simple todo-list app https://gitlab.com/orangeman/2nix (~100 loc) ToDo items involve the planning layer and are basically scheduled processes? They would commit to concrete resource inputs (eg work hours) and create (valuable) output resources when they get checkmarked. Economic events are observed and can later be accounted for in value equations to fairshare the flow of value appreciation..

How do I go from .ttl to concrete json data? How to validate valueflows data conformance?

[fosterlynn]

Hello @orangeman

Afaics the vf ontology is specified in .ttl and .jsonld formats. Are these the same, just in different syntax? There are also json-schemas. Are these autogenerated from the ontology? Are they less expressive?

The .ttl file is the system of record: https://github.com/valueflows/valueflows/blob/master/release-doc-in-process/all_vf.TTL. The specification found in https://valueflo.ws linked on the left as 'Classes and Properties' is generated from that file.

If you see jsonld formats around, they may be about examples in process or be old.

The json schemas are in process and not reliable. We're also working on a graphql reference, but that is also in process and not reliable. And atm both are being created manually. But in general, they shouldn't be less expressive. Although there may be small structural differences.

I would like to try the valueflows vocabulary in a very simple todo-list app https://gitlab.com/orangeman/2nix (~100 loc) ToDo items involve the planning layer and are basically scheduled processes? They would commit to concrete resource inputs (eg work hours) and create (valuable) output resources when they get checkmarked. Economic events are observed and can later be accounted for in value equations to fairshare the flow of value appreciation..

Nice!

How do I go from .ttl to concrete json data?

I can make you some json-schemas for the pieces you need if you like. Sounds like Commitment, Process, EconomicEvent, Fulfillment, EconomicResource (maybe). Possibly also ResourceSpecification for defining the types of work and types of output resources created. Or you can use classifications found on the web for that too.

How to validate valueflows data conformance?

Good question. It would be good for us to have something automated for that, maybe a set of test suites - but I think that will be awhile. In the meantime, I'm happy to do reviews. And also to work with you on your specific use case up front in terms of VF treatment.

P.S. You are probably aware, but just in case: the vocabulary is in process; the core model you are talking about is fairly stable as a model, but some of the property naming is being re-discussed. We will try to move that along! [edit: There are a handful of projects currently implementing VF. We are happy to help any and all of them, and can do that at this stage. It helps them, and helps us validate the vocabulary.]

P.P.S. Are you familiar with Sensorica's value equations? Your idea sounds very similar.

[orangeman]

Sensorica's value equations? Your idea sounds very similar.

Yes, this thinking comes here from the wikis (not my ideas). // ToDo better attribution

vocabulary is in process...

I really like the simplicity of the core model - seems compatible with every imaginable economic activity. It's all just ever evolving flows of value...

---

a concrete example (adapted from https://github.com/valueflows/valueflows/blob/master/json-schemas/sample-process-flow.json)

{
  "id": "ToDo1",
  "name": "Seed carrots",
  "inputs": [
    {
      "action": "use",
      "affects": {
        "id": "BedA1",
        "resourceClassifiedAs": "prepped garden bed"
      }
    },
    {
      "action": "consume",
      "affects": {
        "currentLocation": "storage/A/5",
        "resourceClassifiedAs": "carrot seed variety"
      },
      "affectedQuantity": {
         "numericValue": "120",
         "unit": "Gramms"
      }
    },
    {
      "action": "work",
      "affects": {
        "resourceClassifiedAs": "gardening skill level 3"
      },
      "affectedQuantity": {
         "numericValue": "20",
         "unit": "Minutes"
      },
      "provider": {
        "id": "Bob"
      }
    }
  ],
  "outputs": [
    {
      "action": "produce",
      "affects": {
        "id": "BedA1",
        "resourceClassifiedAs": "seeded garden bed"
      },
      "affectedQuantity": {
        "numericValue": "1",
        "unit": "Each"
      }
    }
  ]
}

Is resource classification and specification the same concept?

Would a prepped garden bed and a seeded garden bed be different resource classifications? Or would you use eg action 'improve' to change the "state" of the same garden bed resource?

Or simply use the garden bed for the whole process: bedprep -> seed -> weed -> harvest -> wash?

Is a Process just one "step" / node in the resource flow graph? or can it comprise sub-processes/steps (with duration in between) (eg that there should be 65-77 days between seed and harvest..?)

Why does each input have a start date? Wouldn't a whole todo have a planned/observed due timestamp? and duration/end?

posting a new todo would be a planning Commitment? (self)assigning to a todo would update the Commitment? marking a todo 'done' would be observation Fulfillment?

[orangeman]

In this example todo-logs would help identify valuable crops/varieties (with high market sale value and low labor and few bed-foot-days) and derive best practices / recipes from collected experience to forecast/plan and coordinate that everything gets done...

[fosterlynn]

Is resource classification and specification the same concept?

Sometimes. Here is a recent explanation, and I also have a todo to improve the doc.

The ResourceSpecification is part of VF, and part of the recipe. 
It is used when you need to have more definition than you can 
find in a simple taxonomy, whether there is a recipe or not, 
but is required in a recipe.

All the classification references are meant for existing taxonomies 
on the web, such as wikidata and others. So they are all urls. 
Those taxonomies are outside of VF. They can be used as a fairly 
specific definition, and/or as a list of more general classifications 
that can be used in matching / searching.

I really like the simplicity of the core model - seems compatible with every imaginable economic activity. It's all just ever evolving flows of value...

So do we! And that was the purpose of REA when Bill McCarthy set about simplifying accounting to its core model, now that we had computers. If you find something it doesn't do, we'd like to know so we can make sure it does.

Would a prepped garden bed and a seeded garden bed be different resource classifications? Or would you use eg action 'improve' to change the "state" of the same garden bed resource?

Or simply use the garden bed for the whole process: bedprep -> seed -> weed -> harvest -> wash?

The vocabulary should handle any of those choices. I guess I would look at the bed as a separate resource from the produce in the bed, and use the bed, but then I'm not a gardener or farmer either, others may disagree. Although if you are looking to also improve the soil, and can measure that, then that is another interesting angle - but still a separate resource.

In terms of the veggies, seeds seem more practical as a separate resource also - again, others may disagree. Once they start growing though, improve seems useful, if you want to keep track of the stages of the veggies resource during the season, seeded, weeded, harvested. Or if you don't, maybe just produce at the end of the season.

A note on using accept and improve. Depending on what you want to do in your app, you may have a need to identify the veggie resource differently at the end of seeding, weeding, harvesting. VF hasn't yet addressed this explicitly, but in NRP we have used the process classification along with the regular id for that when we have needed it, like to prevent cycles when tracking or tracing value flows. Something like "carrots@weeded", "carrots@harvested".

Is a Process just one "step" / node in the resource flow graph? or can it comprise sub-processes/steps (with duration in between) (eg that there should be 65-77 days between seed and harvest..?)

Defining the level of your processes is somewhat of an art or a choice - but generally if you are producing something you want to track or inventory in the middle of a process, you probably want another process in sequence. We don't have any facility atm for sub-processes, although we have discussed them. My view is it is better for operational steps to divide into more processes that have resource flows between them rather than create hierarchies of processes. My gut feel is that seeding, weeding, harvesting, washing are separate processes. They definitely are if say you would harvest from one field but then wash everything together from 3 fields, or something like that.

And yes, things that are far apart also lend themselves to more than one process if you want to clearly schedule them during the season. On the other hand you could do that with times on the different events, like "seed May 15 - 30, weed July 1 - 15, etc.

People have also used the process descriptions for documenting steps within a process for people executing the process, when you don't care about recording what all comes out of the steps.

Why does each input have a start date? Wouldn't a whole todo have a planned/observed due timestamp? and duration/end?

Actually we changed that. Each event (and also commitment and intent) has a "time" that can be a duration or an instant, using https://www.w3.org/TR/owl-time/. We're still nailing down the naming on that though. Will let you know asap!

....Oops, got to go, will post more later.....

[fosterlynn]

posting a new todo would be a planning Commitment?

First, you aren't using the word "todo" as something part of VF, right? Sensorica has "todo's" on the UI, but yes, behind the scenes they are just Commitments and Economic Events.

So, basically yes, a todo would be a work Commitment if you are assigning it to yourself or someone else. It would be a work Intent if you are posting it looking for someone to commit to it. (Sensorica didn't have Intents.)

(self)assigning to a todo would update the Commitment?

Assigning a todo that is an Intent is creating a Commitment that satisfies that intent, using Satisfaction.

marking a todo 'done' would be observation Fulfillment?

That would be creating an EconomicEvent that fulfills the Commitment, using Fulfillment.

Note Fulfillment and Satisfaction resolve many-to-many's, which you may not need for your use case. But they are sometimes needed.

In this example todo-logs would help identify valuable crops/varieties (with high market sale value and low labor and few bed-foot-days) and derive best practices / recipes from collected experience to forecast/plan and coordinate that everything gets done...

This sounds very interesting! Your example with the carrots in the garden bed seems like you are going the right direction to accomplish that. I think you will need more than "todo's" which I interpret to mean work, you'll need all of those inputs and outputs for that kind of analysis. We'd be very interested in how you end up doing the metrics!

[orangeman]

Thank You for the detailed explanations! It helps me to think in concrete examples

divide into more processes that have resource flows between them rather than create hierarchies of processes

My question about sub-processes was motivated by reusing them in other processes.

In the above example 'bedprep' could look like eg:

• clean bed of plant residue (output biomass)
• loosen ground with broadfork (input tool use)
• apply fresh compost (input compost L/sqfeet)
• smoothen surface with (low till) tilther (tool)
• irrigate thoroughly (input water)
• cover with landscape fabric (used for ten days)
• wait ten days (for weeds to sprout)
• flameweed

'bedprep' would then be used in 'grow carrots' and as well in 'grow salad'

Are 'recipes' a hierarchical grouping of processes? Input ResourceSpecifications can lead to (sub-)recipes that produce the required resource? Eg if a recipe process requires a 'prepped / stale seed bed' as input.

Fulfillment and Satisfaction resolve many-to-many's

agents assign to many todos todos can have many assignees

That means there are possibly several Commitments all satisfying the same Intent?

you aren't using the word "todo" as something part of VF, right?

Yes, 'todo' is human facing ui language. Valueflows is computer facing protocol language.

HowTo <-> Recipe ToDo <-> Intent assign -> Commitment Log -> Events

A todo list (issue tracker) is in some (but not in other) sense the simplest possible app. It is highly general purpose and a useful coordination tool to get anything done collaboratively. Everything starts with todos. It is also the standard helloworld for vuejs.org which I wanted to try out (together with matrix protocol and value flows)

[orangeman]

Regarding the veggies that are improving. How about action grow? In some sense it is the opposite of improve as eg nutrient density goes down from sprouts to microgreens to baby leaf greens to grownup salad. Hence the market value per kilo decreases but at the same time the market value per bed feet increases.

[fosterlynn]

Are 'recipes' a hierarchical grouping of processes? Input ResourceSpecifications can lead to (sub-)recipes that produce the required resource? Eg if a recipe process requires a 'prepped / stale seed bed' as input.

Sort of hierarchical. In the sense that if you have 2 recipes that have the same input, the recipe for that input will apply to both of the recipes that have that, and fall into place accordingly, you don't have to repeat it. But not in the sense of processes being defined by a series of sub-processes. Hope that is somewhat clear - in any case, you can reuse them, and they will be added to the flow.

Like bedprep > grow carrots, and bedprep > grow salad. Or if you had each of those bedprep steps as a separate process, they would still fall in line before grow carrots and grow salad, as long as the output of one process becomes the input of the next process.

That means there are possibly several Commitments all satisfying the same Intent?

Yes there can possibly be several Commitments satisfying the same Intent, and possibly several EconomicEvents fulfilling the same Commitment. And you could possibly have one Commitment to more than Intents. And you could possibly have one EconomicEvent for multiple Commitments. Although I think the main example for this is paying based on a statement rather than each invoice, or similar arrangements when exchanging, doesn't have to be money. I doubt that would really occur in process-related stuff. But it keeps the model consistent.

Yes, 'todo' is human facing ui language. Valueflows is computer facing protocol language.

Got it thanks.

Regarding the veggies that are improving. How about action grow? In some sense it is the opposite of improve as eg nutrient density goes down from sprouts to microgreens to baby leaf greens to grownup salad. Hence the market value per kilo decreases but at the same time the market value per bed feet increases.

Yes, maybe the veggies aren't clearly improving, and there are other examples like that. We should probably change that name to something like change -- grow fits your situation, but might be kind of limited?

[fosterlynn]

Yes, maybe the veggies aren't clearly improving, and there are other examples like that. We should probably change that name to something like change -- grow fits your situation, but might be kind of limited?

P.S. The process would be totally good as "Grow" though.

[orangeman]

How would a typical sales offer look as example VF json? an Intent to exchange a Resource for another Resource with an intended exchange rate? or two Intents? one for product and one for money? somehow connected with (per-unit) "price" implicit?

[orangeman]

I wonder how observed VF data would be interpreted for accountability... Somehow input-process-output reminds me of credit-tx-debit (flow graph)

In accounting inputs and outputs are "tagged" with (hierarchical) accounts (There might be different account hierarchies (taggings) for different purposes) Agents or Locations or ResourceClassifications can be seen as accounts

How to compute a balance sheet from a year of observed VF data? (monetary units (of account) as well as time or other resources) Does this flow-graph thinking make any sense to you?

[bhaugen]

@orangeman

How would a typical sales offer look as example VF json?

Intents are not fully cooked in VF yet, but in general, offers to sell could be connected to the expected reciprocity or compensation. Exactly how that is all stated is under discussion. Stay tuned.

[bhaugen]

@orangeman

I wonder how observed VF data would be interpreted for accountability... Somehow input-process-output reminds me of credit-tx-debit (flow graph)

It's not the same. VF data is based on REA which does not use debits and credits. although you can generate them if you want them from REA data.

In accounting inputs and outputs are "tagged" with (hierarchical) accounts (There might be different account hierarchies (taggings) for different purposes) Agents or Locations or ResourceClassifications can be seen as accounts

Don't need all that, REA does not use hierarchical account tags, but can generate a hierarchical general ledger automatically. More info on how at the last link below.

WorkDay offers somewhat-REA-based accounting software and has user-defined meaningful non-hierarchical tags, more like social media tags than account IDs: https://www.workday.com/en-us/applications/financial-management/accounting-and-finance.html

How to compute a balance sheet from a year of observed VF data? (monetary units (of account) as well as time or other resources)

Here's some info on generating various of kinds of reports from REA data: https://pad.disroot.org/p/REA-reports

[fosterlynn]

How would a typical sales offer look as example VF json?

Intents are not fully cooked in VF yet, but in general, offers to sell could be connected to the expected reciprocity or compensation. Exactly how that is all stated is under discussion. Stay tuned.

In the meantime, we're pretty sure it will look like 2 Intents, both part of a Proposal (name not solid). There will also be something that can explicitly represent "unit pricing" (won't be that name).

If you want to work on your concrete app that needs this and we aren't there yet, we would accelerate. And we could work together too, we prefer to have use cases on the ground as part of defining the vocabulary, if you can manage the extra commotion.

[almereyda]

We have moved the ValueFlows organization from GitHub to https://lab.allmende.io/valueflows.

This issue has been closed here, and all further discussion on this issue can be done at

https://lab.allmende.io/valueflows/forum-valueflo-ws/-/issues/130.

If you have not done so, you are very welcome to register at https://lab.allmende.io and join the ValueFlows organization there.