stock proposal

[elf-pavlik]

This PR serves as space to discuss introducing concept of stock as container for resources. I included one example with stock of serial resources.

TODO

• vf:maximumQuantity - (quid:QuanittyValue) limit on quantity which this stock can contain
• contained element can have more specific resource types, child resource types of the stock. for example each bike can have its own product model.
• examples
  • fariphone2 devices at community lab
  • deskspaces at coworking space
  • roomspaces in coliving house

[bhaugen]

Some of your examples seem more like resources themselves, as well as containers for other resources.

A deskspace is a resource. So is a roomspace.

[elf-pavlik]

I intended both deskspace and roomspace as serial resources, each one has IRI we can identify it with. Still sometimes we may want to treat them as stock, adding more deskspaces will increment it and a desk or chair falling apart will temporary decrement it.

Does the already included example, with stock of bicycles, look clear?

[fosterlynn]

I think vf:contains is useful, but want to keep open the discussion of what is vf:stock. The vf:stock I think is the rea:EconomicResource. I'd like to keep vf:resource consistent with that.

[bhaugen]

Reading between the lines, I think I have seen three different meanings of @elf-pavlik 's vf:stock idea.

• A stock keeping location like a warehouse bin where some quantity of resources, usually of the same resource type, are stored, usually temporarily.
• A group of such resources that are handled together like a bundle for whatever purpose.
• A container or package with more than resource contained in it.

Could we clarify?

[elf-pavlik]

Do you have examples from REA where serial resources also get managed as stocks? For example stock of 10 GPS trackers. Each of them has it's own URI to identify it directly, but often we just need to reserve a number of them no matter which particular ones. Still we track which particular ones get used in processes, for example in cases where a person who checked them out reports receiving damaged device. For mapping party, one person goes to pick up 5 devices from the lab's storage and than 5 different people will use them during mapping. After that again a single person will transport them back to the lab's storage.

• A stock keeping location like a warehouse bin where some quantity of resources, usually of the same resource type, are stored, usually temporarily.
• A group of such resources that are handled together like a bundle for whatever purpose.
• A container or package with more than resource contained in it.

I don't use it do describe a bin or 'packaging' itself - I see those as distinct resources to keep track on, I see stock more of the contents of that bin or package.

We can also think of scenarios with bottled goods, where each of the bottles has QR code with distinct URI to identify that particular bottle. Still they mostly get handled as lot controlled resources.

[bhaugen]

Do you have examples from REA where serial resources also get managed as stocks?

I don't have examples of inventory management in REA at all. Officially, REA does not care. It's all about the economic events. Bill McCarthy just summarizes all the events for a resource and says that is the current quantity. He does not even care about locations. He is a minimalist, and wants REA to have the minimum number of concepts that can do the job. Other people can add other concepts as needed and connect them to the appropriate REA primitive.

That being said, REA practitioners do add other concepts, but Lynn and I are the only people we know of who have developed operational software that is in actual production use based on REA that includes inventory. WorkDay is a popular app based on REA for human resource management, some accounting systems have been developed, and Michael Linton's mutual credit software uses REA principles.

[elf-pavlik]

I'll add commit which besides vf:maximumQuantity also proposes vf:preferredQuantity. Both can help when casting intents.

[elf-pavlik]

from README:

Some people use the terms "stock" and "stock flow". A stock is a resource; a stock flow is an event. (The term stock is too limiting, since a resource could be digital, like a document or media file.)

Document or media file seems more of a serial resource, if we talk about web resources they will have IRI (http://) which we would use as @id. Also we most likely wouldn't increment or decrement them. More likely vf:improve.

For vf:Service (subclass of vf:Resource) we also don't do increment and decrement. I think vf:Stock could provide a type that one can increment and decrement. It could 'contain' serial resources or lot controlled resources. If we can represent a bicycle with serial number as vf:Resource which can move between stocks. IMO we also can represent 10 bricks as vf:Resource which can move between stocks.
The way I think of proposed here vf:Stock seems to match better my understanding of nrp:EconomicResource than how I currently tend to use instances of vf:Resource in various examples.

[bhaugen]

vf:Stock seems to match better my understanding of nrp:EconomicResource than how I currently tend to use instances of vf:Resource in various examples.

nrp:EconomicResource can handle stock resources (identified only by resource type and other properties of the stock, but not otherwise individually identifiable or lot-identifiable), lot controlled resources, or serialized resources.

It cannot handle more than 1 serialized resources as a set, although they could all be in the same location.

[fosterlynn]

Document or media file seems more of a serial resource, if we talk about web resources they will have IRI (http://) which we would use as @id. Also we most likely wouldn't increment or decrement them. More likely vf:improve.

I think this is mostly true, but they would have to get incremented when created.

For vf:Service (subclass of vf:Resource) we also don't do increment and decrement.

If we do vf:Service as an output created when the service process happens, then that would increment it (creates it, increments to 1). When it gets exchanged, it would get decremented to 0: when we transfer the service to another agent, decrements on the give side. Seems possibly silly to increment on the receive side since services don't hang around?? But I think you do have to increment it to exchange it.... but I am still struggling with how to make services less cumbersome, since at the end of the process they have been transferred.

[bhaugen]

My REA compadres are still failing to respond to questions about how they handle services. I suspect they don't know. That is, as usual, we are the only people who are doing operational systems for the real world.

[bhaugen]

Don't get me wrong, I still love REA. But a lot of academics in that community.

[elf-pavlik]

When it gets exchanged, it would get decremented to 0: when we transfer the service to another agent, decrements on the give side. Seems possibly silly to increment on the receive side since services don't hang around?? But I think you do have to increment it to exchange it....

Since vf:Transfer modifies only rights to resources, not resources themselves. I would really like to track resources with processes only and 'overlay' transfers of rights 'on top of that'. So resources can't move between stocks at different locations without vf:Transportation. Virtual stocks withing same actual stock (~ shares) might change without processes.

If you want to have two records for the same service (same resource), I guess you look in direction of multiple sources of truth and cross validation

My REA compadres are still failing to respond to questions about how they handle services. I suspect they don't know. That is, as usual, we are the only people who are doing operational systems for the real world.

I don't know if REA focuses mostly on stocks of material goods and stocks of monetary currencies. I think people nowadays give more and more importance to services, usage and as in case of your 'cite' events - attributions and knowledge resources (which have very different behavior than stocks of material goods). While we work with data snippets for use cases we work with, I trust in two of you that you will analyze it 'wearing REA goggles'. I find it crucial that we will start converging more and more on terminology and model of VF, but at current stage I still take quite some freedom to see things in a way that currently makes sense to me. I will make more effort to not get stuck in 'my way of seeing things' but systematically build shared way of seeing and describing economic interactions.

[bhaugen]

I don't know if REA focuses mostly on stocks of material goods and stocks of monetary currencies.

Neither. It is deliberately general, abstract and minimal. Wants to be able to deal with any economic interactions. Practitioners have been mostly academic and they work through examples of applying the REA models to different use cases.

At the same time I was starting to use REA for software in the 1990's, several other people were doing the same.

One of them was working on a semantic model which could be used to assemble systems from software components. That project failed to get any users and is dead as far as I know. It was curiously started by a guy who worked for Microsoft at the time.

IBM had a project to use REA for an accounting system.

Workday took off in the "human resources" domain (a phrase I hate).

The next wave started when I brought Bill McCarthy into some standards orgs, which culminated in the ISO standard, which is also very general.

I know a lot of other software-focused projects have happened recently in Europe, but I have not been in touch with many of them. I haven't seen anything that deals explicitly with services, and have asked for such examples several times in several ways, always coming up empty.

[fosterlynn]

Since vf:Transfer modifies only rights to resources, not resources themselves. I would really like to track resources with processes only and 'overlay' transfers of rights 'on top of that'.

Yeah, I do actually agree on that, even though it sounds like I don't. 😊

I've been trying to avoid it to get some core settled on, but maybe we do need to figure out exactly how that would work. Do we still need events? Is it a different resource because it is in a different context? Of course we know that in the real world it is probably the same exact thing or service, but in the accounting of resources and their "flows" that we need to coordinate an economy, how does the "owner" or "manager" or "coordinator" or whatever rights in relation to the resource matter to identification of the resource?

We have an interesting use case unfolding as we speak, I'll start a new issue for that, maybe VF could help us figure out what to do. 😄

[elf-pavlik]

I think we need to consider stocks of resources managed as serial, I made this illustration some days ago. It shows 'tools library' which has stocks of resources managed as serial ones:

I see it very interesting in commitment stage, since we have commitment for certain number of items managed as serial in a stock that 'contains' particular quantity of them. At the same time we don't make commitment on particular items, just "2 out of this stock".

[fosterlynn]

Is there any problem with both the stock and the serialized contained resources both being vf:Resource?

[elf-pavlik]

Is there any problem with both the stock and the serialized contained resources both being vf:Resource?

If we have a stock of 'cargo bikes' (wikidata category) with only one bike contained in it with some particular model (eg. ose:CargoBike2). We need to see how we keep count on quantities. Since we don't have 2 resources each one with quantity: 1 each (which may suggest 2 each since we have 2 resources).

[fosterlynn]

If we have a stock of 'cargo bikes' (wikidata category) with only one bike contained in it with some particular model (eg. ose:CargoBike2). We need to see how we keep count on quantities. Since we don't have 2 resources each one with quantity: 1 each (which may suggest 2 each since we have 2 resources).

I am assuming the stock could at some other time have more than one cargo bike in it?

But I also don't see any problem with 1 stock resource of cargo bikes that vf:contains 1 resource of a specific cargo bike. The contains relationship lets us know what is what.

I do see that it is a lot cleaner if vf:Resource is always vf:Resource.

[bhaugen]

What I've seen in pretty sparse doc for systems that handle serialized resources is that everywhere you see an inventory stock or event including more than one serialized resource, the stock or event gives a list of the included serial numbers. So it would tell you the resource type once, and then a list of serial numbers.

I'm not saying we need to do it that way, but that way apparently works.

[elf-pavlik]

Let's take 2 examples

• stock of cargo bikes, each one with serial number
• stock of hammers (tools), where each hammer does NOT have serial number

We can write examples for issue / receive, I guess for bikes they should reference both, the stock and particular bikes. use - can we use bikes & hammers without need to issue them first ?
The main difference seems that for stock of serial resources, events may need to reference both, the stock and the resource contained in it.

[fosterlynn]

can we use bikes & hammers without need to issue them first ?

I think so. Especially if you just take one to use in your process (with permission from a general agreement let's say) - so there is no issue in the real world. For the bikes, seems like if it matters which one you use, you can reference serialized resource; if not, you can just say you used 1 from the stock resource. The related resources can find each other if needed.

[elf-pavlik]

'@context': https://w3id.org/valueflows/v1-dev
affects: https/tool-library.example/hammers#stock
quantity:
  'qudt:numericValue': 20

'@context': https://w3id.org/valueflows/v1-dev
id: https://tool-library.example/we9wrwe98#commitment
type: Commitment
action: use
provider: https://tool-library.example/#identity
receiver: https://alcie.example/#identity
affects: https/tool-library.example/hammers#stock
quantity:
  'qudt:numbericValue': 3
  'qudt:unit': ??? # we still haven't figured out how to do *each*
# https://en.wikipedia.org/wiki/ISO_8601#Times
startTime: 2017-04-05T14:30Z
# https://www.w3.org/TR/xmlschema11-2/#duration
# https://en.wikipedia.org/wiki/ISO_8601#Durations
duration: PT6H

Above also relates to valueflows/valueflows#192
In practice the stock will get 'decremented' when use event starts and then 'incremented' back after it's duration. Possibly we may need to have explicit issue and receive to capture that 'increment' and 'decrement'.

Bikes managed as serial should look similar on commitment but I guess we will get one event per bike which together will fulfill the commitment for number of bikes.

[elf-pavlik]

variant with commitments on issue & receive, which seems more general case

'@context': https://w3id.org/valueflows/v1-dev
affects: https/tool-library.example/hammers#stock
quantity:
  'qudt:numericValue': 20

'@context': https://w3id.org/valueflows/v1-dev
id: https://tool-library.example/we9wrwe98#commitment
type: Commitment
action: issue
provider: https://tool-library.example/#identity
receiver: https://alice.example/#identity
affects: https/tool-library.example/hammers#stock
decrementQuantity:
  'qudt:numbericValue': 3
  'qudt:unit': ??? # we still haven't figured out how to do *each*
startTime: 2017-04-05T14:30Z

'@context': https://w3id.org/valueflows/v1-dev
id: https://tool-library.example/dafpdf9af0a#commitment
type: Commitment
action: receive
provider: https://alice.example/#identity
receiver: https://tool-library.example/#identity
affects: https/tool-library.example/hammers#stock
incrementQuantity:
  'qudt:numbericValue': 3
  'qudt:unit': ??? # we still haven't figured out how to do *each*
startTime: 2017-04-05T20:30Z

'@context': https://w3id.org/valueflows/v1-dev
affects: https/alice.example/hammers#stock
quantity:
  'qudt:numericValue': 0
  
'@context': https://w3id.org/valueflows/v1-dev
id: https://alice.example/adfdapdofafjpa#commitment
type: Commitment
action: receive
provider: https://tool-library.example/#identity
receiver: https://alice.example/#identity
affects: https/alice.example/hammers#stock
incrementQuantity:
  'qudt:numbericValue': 3
  'qudt:unit': ??? # we still haven't figured out how to do *each*
startTime: 2017-04-05T14:30Z

'@context': https://w3id.org/valueflows/v1-dev
id: https://tool-library.example/afdapfiajpfja#commitment
type: Commitment
action: issue
provider: https://alice.example/#identity
receiver: https://tool-library.example/#identity
affects: https/alice.example/hammers#stock
decrementQuantity:
  'qudt:numbericValue': 3
  'qudt:unit': ??? # we still haven't figured out how to do *each*
startTime: 2017-04-05T20:30Z

'@context': https://w3id.org/valueflows/v1-dev
id: https://alice.example/afdajfoapfa#commitment
type: Commitment
action: use
affects: https/alice.example/hammers#stock
startTime: 2017-04-05T14:30Z
duration: PT6H

the pairs of issue and receive that have the same start time, one commited by library and other by alice (1 & 3, 2 & 4) seem like part of the same process that happens between library and alice (no context agent)

[fosterlynn]

@elf-pavlik

'@context': https://w3id.org/valueflows/v1-dev
affects: https/tool-library.example/hammers#stock
quantity:
  'qudt:numericValue': 20

I'm confused about this, what is it?

we still haven't figured out how to do each

Can we just say 'Each'? Or do we need to find it in qudt or something?

[fosterlynn]

Can we just say 'Each'? Or do we need to find it in qudt or something?

Never mind, I see they are object properties.

[fosterlynn]

Re. vf:Stock vs vf:Resource, @elf-pavlik and I and @bhaugen had a long gitter chat several days ago, and didn't end up with a conclusion. I'm revisiting the topic here, based on this recent comment, https://github.com/valueflows/intent/issues/5#issuecomment-284271269

Excerpt:

'@context': https://w3id.org/valueflows/v1-dev
id: https://bumblebee.example/bd8c416c-8f93-420f-b945-153ddc3a5b9f#stock
type: Stock
category: https://www.wikidata.org/wiki/Q89 # apple
quantity:
  numericValue: 500
  unit: unit:Kilogram

I propose we use vf:Resource for what we call a "stock resource". So the above vf:Stock would be vf:Resource. I will try to pull together a definition from previous discussions and documents, and I understand this is not immediately intuitive. We can then determine if we need something else for serialized or lot based resources - I'm not sure we do, but more detail work needs to be done, and if we do, that's totally fine. But for the base resource that works in the REA pattern, I would like to use vf:Resource.

I could do a PR on the readme in the Resource repo.... to be continued there....

[bhaugen]

We can then determine if we need something else for serialized or lot based resources - I'm not sure we do,

Need a resource identifier, which could either be a Lot ID or a serial number or something else.

A resource that contains more than one serialized resource typically offers a list of contained serial numbers.

Lots are never mixed in the same resource, although a lot could be split into several resources differentiated by location and probably event history.

[fosterlynn]

Need a resource identifier, which could either be a Lot ID or a serial number or something else.

We have those, as properties, not identifiers, optional. But you could certainly match up on those to track them as needed.

[bhaugen]

Need a resource identifier, which could either be a Lot ID or a serial number or something else.

We have those, as properties, not identifiers, optional. But you could certainly match up on those to track them as needed.

Whatever you want to call them...but while lots may be optional, depending on the situation, where lots are required, lot tracking is not optional.

[elf-pavlik]

Need a resource identifier, which could either be a Lot ID or a serial number or something else.
Lots are never mixed in the same resource, although a lot could be split into several resources differentiated by location and probably event history.

As @fosterlynn mentioned Lot never acts as 'the identifier' of what we currently have as instance of vf:Resource (~= rea:EconomicResource). In VF each resource has URI/IRI used as 'the identifier' @id. One can also have multiple resources with same lot at the same location, but they will stay denoted by different IRIs @id.

Currently we can also have more than one instances of vf:Resource with the very same serial number, but only one of them should have quantity 1 and all the other ones quantity 0. So serial number itself doesn't acts as 'the identifier' of what we currently call vf:Resource, since an instance of vf:Resource currently doesn't represent the actual tangible resource but more a stock which while having that S/N assigned to it can only contain that real world resource with that S/N or stay empty. Once again, any number of instances of vf:Resource managed by the same inventory can have the same S/N, but only one of them should have quantity: 1 and all the rest quantity: 0

[bhaugen]

I may not be using the word "identifier" precisely as @elf-pavlik and @fosterlynn have agreed. Difficult for me to keep up.

But consider what a Lot is. Its alternate name is Batch. It's the source for some set of resources that then get split, transported, and transferred, into different locations and contexts, and become separate REA:EconomicResources. But they all need to be trackable as parts of the same lot, wherever they go.

If I were doing this in LOD, I would give the Lot itself a URI/IRI with the details of its source, whether that be a crop in a field, a manufacturing process, or an animal, or whatever.

Note: I am not suggesting we add Lot as a concept in VF now. Sufficient to use a single attribute, which unfortunately, @elf-pavlik , is almost always called Lot ID, which is short for Lot Identifier. But people could also use a URI/IRI.

[fosterlynn]

In terms of the word "identifier", I don't think any of us have said how to use it. In computing, there's often a difference between the technical id and the logical id. In terms of types of resources, there can also be a difference between the logical identifiers, based on agent preference, the type of resource, etc. (See the readme on Resource, section called Unique Identifiers for Resources, for some details of this.)

[fosterlynn]

@elf-pavlik are you OK if we close this without merging, and stick with vf:Resource for resources managed as stock?

As I mentioned in gitter, I can compromise on lots of naming, but I think it is important that this one continue to map with REA, and include the word "Resource". Secondarily most people don't know what "stock" is really, it is pretty much a manufacturing term, somewhat narrow for what we are doing.

For serialized and unique resources, I'm pretty sure vf:Resource will be fine there too; but we can look at that in more detail if you don't think so.

[elf-pavlik]

Let's close it but I still think we need to look more into this resource vs. stock relation. Once we start getting closer to clarifying it I can always make new PR.