From c93fcbbb34306c93115377f91f4dd3bdb647e97e Mon Sep 17 00:00:00 2001 From: Lynn Foster Date: Tue, 21 Apr 2026 23:03:44 +0200 Subject: [PATCH] Bring VF planning FEPs up to date (#830) Bring up to VF 1.0.0, correct ResourceSpecification, update for newer FEP requirements. Reviewed-on: https://codeberg.org/fediverse/fep/pulls/830 --- fep/3264/fep-3264.md | 66 +++++++++++++++++++++++--------------------- fep/c5a1/fep-c5a1.md | 48 +++++++++++++++++++------------- 2 files changed, 64 insertions(+), 50 deletions(-) diff --git a/fep/3264/fep-3264.md b/fep/3264/fep-3264.md index 81ea5a2..89b4fb1 100644 --- a/fep/3264/fep-3264.md +++ b/fep/3264/fep-3264.md @@ -1,6 +1,7 @@ --- slug: "3264" authors: Lynn Foster +type: implementation status: DRAFT dateReceived: 2024-01-31 trackingIssue: https://codeberg.org/fediverse/fep/issues/255 @@ -28,7 +29,7 @@ Consuming implementations which don't have planning features MAY display plan-re In all cases, the objects can also be discussed using `Note` objects and `replyTo`. -Valueflows defines a `Plan` as **a logical collection of processes that constitute a body of scheduled work with defined deliverable(s).** +Valueflows defines a `Plan` as **A logical collection of processes, with optional connected agreements, that constitute a body of scheduled work with defined deliverable(s).** The representation of a plan is a JSON document with the following properties: @@ -54,13 +55,13 @@ The representation of a process is a JSON document with the following properties - `hasInput` (OPTIONAL): the input commitment(s) of the process (see below). - `hasOutput` (OPTIONAL): the output commitment(s) of the process (see below). -A `Commitment` is defined as **A planned economic flow that has been promised by an agent to another agent.** +A `Commitment` is defined as **A planned economic flow that has been scheduled or promised by an agent to another agent.** - `id` (REQUIRED): the commitment's unique global identifier. - `type` (REQUIRED): the type of the object MUST be `Commitment`. - `action` (REQUIRED): the type of economic transaction. If the commitment is an input, the value of this property SHOULD be one of: `work`, `use`, `consume`, `cite`, `pickup`, `accept`. It the commitment is an output, the value of this property SHOULD be one of: `produce`, `deliverService`, `dropoff`, `modify`. See [the action definitions and behaviors](https://www.valueflo.ws/concepts/actions/) for more information. -- `resourceConformsTo` (RECOMMENDED): the type of an economic resource (can be a skill or type of work for the `work` action). Could be any URI. -- `resourceQuantity` (OPTIONAL): the amount and unit of the non-effort-based economic resource. Either `resourceQuantity` or `effortQuantity` is RECOMMENDED, and both can be included in case of `use`. This is an object with two properties: +- `resourceConformsTo` (RECOMMENDED): the type of an economic resource (can be a skill or type of work for the `work` action). URI to a `ResourceSpecification`. +- `resourceQuantity` (OPTIONAL): the amount and unit of the non-effort-based economic resource. Either `resourceQuantity` or `effortQuantity` is RECOMMENDED, and both can be included in case of `use` or `work`. This is an object with two properties: - `hasUnit` (REQUIRED): name of the unit, according to [Ontology of units of Measure](http://www.ontology-of-units-of-measure.org/) classification. - `hasNumericalValue` (REQUIRED): amount of the resource. - `effortQuantity` (OPTIONAL): the amount and unit of the work or use effort-based action. This is an object with two properties: @@ -77,7 +78,6 @@ Example: "@context": [ "https://www.w3.org/ns/activitystreams", { - "om2": "http://www.ontology-of-units-of-measure.org/resource/om-2/", "vf": "https://w3id.org/valueflows/ont/vf#", "Plan": "vf:Plan", "Process": "vf:Process", @@ -117,7 +117,7 @@ Example: "type": "Commitment", "id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick1", "action": "work", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q112729805", + "resourceConformsTo": "https://project.example/resourcespecs/apple-picking", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "6" @@ -129,7 +129,7 @@ Example: "type": "Commitment", "id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick2", "action": "work", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q112729805", + "resourceConformsTo": "https://project.example/resourcespecs/apple-picking", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "6" @@ -141,7 +141,7 @@ Example: "type": "Commitment", "id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick3", "action": "work", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q112729805", + "resourceConformsTo": "https://project.example/resourcespecs/apple-picking", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "6" @@ -155,7 +155,7 @@ Example: "type": "Commitment", "id": "https://project.example/outputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick4", "action": "produce", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q89", + "resourceConformsTo": "https://project.example/resourcespecs/apples", "resourceQuantity": { "hasUnit": "pound", "hasNumericalValue": "500" @@ -177,7 +177,7 @@ Example: "type": "Commitment", "id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider1", "action": "consume", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q89", + "resourceConformsTo": "https://project.example/resourcespecs/apples", "resourceQuantity": { "hasUnit": "pound", "hasNumericalValue": "500" @@ -190,7 +190,7 @@ Example: "type": "Commitment", "id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider2", "action": "use", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q674484", + "resourceConformsTo": "https://project.example/resourcespecs/cider-press", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "7" @@ -203,7 +203,7 @@ Example: "type": "Commitment", "id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider3", "action": "work", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q3485549", + "resourceConformsTo": "https://project.example/resourcespecs/manual-work", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "4" @@ -215,7 +215,7 @@ Example: "type": "Commitment", "id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider4", "action": "work", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q3485549", + "resourceConformsTo": "https://project.example/resourcespecs/manual-work", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "6" @@ -229,7 +229,7 @@ Example: "type": "Commitment", "id": "https://project.example/outputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider5", "action": "produce", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q5977438", + "resourceConformsTo": "https://project.example/resourcespecs/apple-cider", "resourceQuantity": { "hasUnit": "gallon-US", "hasNumericalValue": "15" @@ -241,7 +241,7 @@ Example: "type": "Commitment", "id": "https://project.example/outputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider6", "action": "produce", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q2836947", + "resourceConformsTo": "https://project.example/resourcespecs/food-scraps", "resourceQuantity": { "hasUnit": "pound", "hasNumericalValue": "100" @@ -312,7 +312,7 @@ The representation of a commitment is a JSON document with the following propert - `inputOf`: the process for which this commitment is an input. Either `inputOf` or `outputOf` is REQUIRED. - `outputOf`: the process for which this commitment is an output. Either `inputOf` or `outputOf` is REQUIRED. - `context` (OPTIONAL): the plan the commitment is part of. -- `resourceConformsTo` (RECOMMENDED): the type of an economic resource (can be a skill or type of work for the `work` action). Could be any URI. +- `resourceConformsTo` (RECOMMENDED): the type of an economic resource (can be a skill or type of work for the `work` action). URI for a `ResourceSpecification`. - `resourceQuantity`: the amount and unit of the non-effort-based economic resource. Either `resourceQuantity` or `effortQuantity` is RECOMMENDED, and both can be included in case of `use`. This is an object with two properties: - `hasUnit` (REQUIRED): name of the unit, according to [Ontology of units of Measure](http://www.ontology-of-units-of-measure.org/) classification. - `hasNumericalValue` (REQUIRED): amount of the resource. @@ -327,7 +327,6 @@ The representation of a commitment is a JSON document with the following propert "@context": [ "https://www.w3.org/ns/activitystreams", { - "om2": "http://www.ontology-of-units-of-measure.org/resource/om-2/", "vf": "https://w3id.org/valueflows/ont/vf#", "Commitment": "vf:Commitment", "inputOf": "vf:inputOf", @@ -336,8 +335,8 @@ The representation of a commitment is a JSON document with the following propert "action": "vf:action", "resourceConformsTo": "vf:resourceConformsTo", "effortQuantity": "vf:effortQuantity", - "hasUnit": "om2:hasUnit", - "hasNumericalValue": "om2:hasNumericalValue" + "hasUnit": "vf:hasUnit", + "hasNumericalValue": "vf:hasNumericalValue" } ], "type": "Create", @@ -351,7 +350,7 @@ The representation of a commitment is a JSON document with the following propert "published": "2024-09-21T14:13:41.843794Z", "inputOf": "https://project.example/processes/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider", "action": "work", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q3485549", + "resourceConformsTo": "https://project.example/resourcespecs/manual-work", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "5" @@ -367,7 +366,7 @@ The representation of a commitment is a JSON document with the following propert Actual economic activity is represented with EconomicEvents in Valueflows. Economic events can be recorded as fulfilling a planned commitment, or by themselves if they were not explicitly planned. In either case, in the scope of this FEP, they are also inputs or outputs of a process. -This FEP does *not* include creating and updating of actual resource inventory, which is also effected through economic events. +This FEP does *not* include creating and updating of actual resource inventory, which is also effected through economic events, by the backend software. The representation of an economic event is a JSON document with the following properties: @@ -382,7 +381,7 @@ The representation of an economic event is a JSON document with the following pr - `inputOf`: the process for which this economic event is an input. Either `inputOf` or `outputOf` is REQUIRED. - `outputOf`: the process for which this commitment is an output. Either `inputOf` or `outputOf` is REQUIRED. - `context` (OPTIONAL): the plan the economic event is part of. -- `resourceConformsTo` (RECOMMENDED): the type of an economic resource (can be a skill or type of work for the `work` action). Could be any URI. +- `resourceConformsTo` (RECOMMENDED): the type of an economic resource (can be a skill or type of work for the `work` action). URI for a `ResourceSpecification`. - `resourceQuantity`: the amount and unit of the non-effort-based economic resource. Either `resourceQuantity` or `effortQuantity` is RECOMMENDED, and both can be included in case of `use`. This is an object with two properties: - `hasUnit` (REQUIRED): name of the unit, according to [Ontology of units of Measure](http://www.ontology-of-units-of-measure.org/) classification. - `hasNumericalValue` (REQUIRED): amount of the resource. @@ -398,7 +397,6 @@ The representation of an economic event is a JSON document with the following pr "@context": [ "https://www.w3.org/ns/activitystreams", { - "om2": "http://www.ontology-of-units-of-measure.org/resource/om-2/", "vf": "https://w3id.org/valueflows/ont/vf#", "EconomicEvent": "vf:EconomicEvent", "inputOf": "vf:inputOf", @@ -407,8 +405,8 @@ The representation of an economic event is a JSON document with the following pr "action": "vf:action", "resourceConformsTo": "vf:resourceConformsTo", "effortQuantity": "vf:effortQuantity", - "hasUnit": "om2:hasUnit", - "hasNumericalValue": "om2:hasNumericalValue", + "hasUnit": "vf:hasUnit", + "hasNumericalValue": "vf:hasNumericalValue", "finished": "vf:finished" } ], @@ -424,7 +422,7 @@ The representation of an economic event is a JSON document with the following pr "fulfills": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider4", "inputOf": "https://project.example/processes/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider", "action": "work", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q3485549", + "resourceConformsTo": "https://project.example/resourcespecs/manual-work", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "6.5" @@ -439,11 +437,17 @@ The representation of an economic event is a JSON document with the following pr ## References -- [ActivityPub] Christine Lemmer Webber, Jessica Tallon, [ActivityPub](https://www.w3.org/TR/activitypub/), 2018 -- [Valueflows] Lynn Foster, elf Pavlik, Bob Haugen [Valueflows](https://valueflo.ws/), 2024 -- [RFC-2119] S. Bradner, [Key words for use in RFCs to Indicate Requirement Levels](https://tools.ietf.org/html/rfc2119.html), 1997 -- [Activity Vocabulary] James M Snell, Evan Prodromou, [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/), 2017 -- [Ontology of units of Measure] Hajo Rijgersberg, Don Willems, Xin-Ying Ren, Mari Wigham, Jan Top, [Ontology of units of Measure](http://www.ontology-of-units-of-measure.org/), 2017 +- Christine Lemmer-Webber, Jessica Tallon, Erin Shepherd, Amy Guy, Evan Prodromou, [ActivityPub], 2018 +- Lynn Foster, elf Pavlik, Bob Haugen, [Valueflows][Valueflows], 2026 +- S. Bradner, [Key words for use in RFCs to Indicate Requirement Levels][RFC-2119], 1997 +- James M Snell, Evan Prodromou, [Activity Vocabulary][ActivityVocabulary], 2017 +- Hajo Rijgersberg, Don Willems, Xin-Ying Ren, Mari Wigham, Jan Top, [Ontology of units of Measure][OntologyOfUnits], 2017 + +[ActivityPub]: https://www.w3.org/TR/activitypub/ +[Valueflows]: https://valueflo.ws/ +[RFC-2119]: https://tools.ietf.org/html/rfc2119.html +[ActivityVocabulary]: https://www.w3.org/TR/activitystreams-vocabulary/ +[OntologyOfUnits]: http://www.ontology-of-units-of-measure.org/ ## Copyright diff --git a/fep/c5a1/fep-c5a1.md b/fep/c5a1/fep-c5a1.md index 47bec13..6dfb2a3 100644 --- a/fep/c5a1/fep-c5a1.md +++ b/fep/c5a1/fep-c5a1.md @@ -1,6 +1,7 @@ --- slug: "c5a1" authors: Lynn Foster +type: implementation status: DRAFT dateReceived: 2024-01-31 trackingIssue: https://codeberg.org/fediverse/fep/issues/256 @@ -34,13 +35,14 @@ Valueflows defines a commitment is defined as **A planned economic flow that has - `type` (REQUIRED): the type of the object MUST be `Commitment`. - `attributedTo` (REQUIRED): the actor who published the commitment. - `published` (RECOMMENDED): the date and time at which the commitment was published. -- `resourceConformsTo` (OPTIONAL): the skill or type of work involved. Could be any URI. -- `effortQuantity` (OPTIONAL): the estimated or expected amount and unit of the work. This is an object with two properties: - - `hasUnit` (REQUIRED): name of the unit, according to [Ontology of units of Measure](http://www.ontology-of-units-of-measure.org/) classification. - - `hasNumericalValue` (REQUIRED): amount of the resource. +- `effortQuantity` (OPTIONAL): the estimated or expected amount and unit of the work, usually a time quantity. This is an object with two properties: + - `hasUnit` (REQUIRED): name of the unit, according to [Ontology of units of Measure](http://www.ontology-of-units-of-measure.org/) classification. This will usually be a time unit such as `hour`. + - `hasNumericalValue` (REQUIRED): estimated amount of the effort. +- `action` (RECOMMENDED): the type of economic transaction. The value of this property will usually be `work` for to-do's. If the `action` is not included, `work` is assumed. - `provider` (RECOMMENDED): the actor who commits to providing the resource, including doing the work. If not included, it is assumed to be the `to` actor. - `receiver` (RECOMMENDED): the actor who will be receiving the resource. If not included, it is assumed to be the `attributedTo` actor. -- `content` (RECOMMENDED): the description of what is to be done. The type of content SHOULD be `text/html`. +- `content` (REQUIRED): the description of what is to be done. The type of content SHOULD be `text/html`. +- `due` (OPTIONAL): the due date/time. - `to` (REQUIRED): the audience of the commitment. Example: @@ -50,15 +52,15 @@ Example: "@context": [ "https://www.w3.org/ns/activitystreams", { - "om2": "http://www.ontology-of-units-of-measure.org/resource/om-2/", "vf": "https://w3id.org/valueflows/ont/vf#", "Commitment": "vf:Commitment", "receiver": "vf:receiver", "provider": "vf:provider", "resourceConformsTo": "vf:resourceConformsTo", "effortQuantity": "vf:effortQuantity", - "hasUnit": "om2:hasUnit", - "hasNumericalValue": "om2:hasNumericalValue" + "hasUnit": "vf:hasUnit", + "hasNumericalValue": "vf:hasNumericalValue", + "action": "vf:action" } ], "type": "Create", @@ -70,7 +72,8 @@ Example: "attributedTo": "https://project.example/actors/alice", "content": "Please proofread the document at https://project.example/docs/45, and let me know what you think could be improved.", "published": "2024-05-18T19:22:03.918737Z", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q834191", + "due": "2024-05-23T17:00:00.000000Z", + "action": "work", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "2" @@ -135,17 +138,17 @@ Actual economic activity is represented with an `EconomicEvent` in Valueflows. The representation of an economic event is a JSON document with the following properties: - `id` (REQUIRED): the economic event's unique global identifier. -- `type` (REQUIRED): the type of the object SHOULD be `EconomicEvent`. If interoperability with other ActivityPub services is desirable, implementers MAY also use object types from [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/#object-types), such as `Note`. +- `type` (REQUIRED): the type of the object MUST include `EconomicEvent`. If interoperability with other ActivityPub services is desirable, implementers MAY also use object types from [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/#object-types), such as `Note`. - `attributedTo` (REQUIRED): the actor who published the economic event. - `content` (OPTIONAL): the description of the economic event or communication about the economic event. The type of content SHOULD be `text/html`. - `published` (RECOMMENDED): the date and time at which the economic event was published. - `to` (REQUIRED): the audience of the economic event. - `fulfills` (REQUIRED): the commitment the economic event is completely or partially fulfilling. -- `resourceConformsTo` (OPTIONAL): the type of an economic resource (for to-do's, can be a skill or type of work). Could be any URI. It does not have to match the commitment, but if not included, can be assumed it is the same. - `effortQuantity` (OPTIONAL): the amount and unit of the work done (for to-do's, usually a time quantity). This is an object with two properties: - `hasUnit` (REQUIRED): name of the unit, according to [Ontology of units of Measure](http://www.ontology-of-units-of-measure.org/) classification. - - `hasNumericalValue` (REQUIRED): amount of the resource. -- `provider` (RECOMMENDED): the actor who commits to doing the work. If not included, it is assumed to be the `attributedTo` actor. + - `hasNumericalValue` (REQUIRED): amount of the effort. +- `action` (RECOMMENDED): the type of economic transaction. The value of this property will usually be `work` for to-do's. If the `action` is not included, the action is assumed to be the same as the commitment action. +- `provider` (RECOMMENDED): the actor who did the work. If not included, it is assumed to be the `attributedTo` actor. - `receiver` (RECOMMENDED): the actor who will be receiving the benefit. If not included, it is assumed to be the `to` actor. - `finished` (OPTIONAL): set to true if this economic event completes the commitment, or the commitment is no longer open for some reason. @@ -164,6 +167,7 @@ The representation of an economic event is a JSON document with the following pr "effortQuantity": "vf:effortQuantity", "hasUnit": "om2:hasUnit", "hasNumericalValue": "om2:hasNumericalValue", + "action": "vf:action", "finished": "vf:finished" } ], @@ -176,13 +180,13 @@ The representation of an economic event is a JSON document with the following pr "attributedTo": "https://project.example/actors/bob", "published": "2024-10-21T14:16:41.843794Z", "fulfills": "https://project.example/todos/ddde9d6f-6f3b-4770-a966-4dkjh8w32e59", - "resourceConformsTo": "https://www.wikidata.org/wiki/Q3485549", "effortQuantity": { "hasUnit": "hour", "hasNumericalValue": "1.5" }, "provider": "https://project.example/actors/bob", "receiver": "https://project.example/actors/alice", + "content": "Looks great, I left a few comments.", "finished": true }, "to": "https://project.example/actors/alice" @@ -218,11 +222,17 @@ The `Commitment` can alternatively be marked as `finished`, without recording an ## References -- [ActivityPub] Christine Lemmer Webber, Jessica Tallon, [ActivityPub](https://www.w3.org/TR/activitypub/), 2018 -- [Valueflows] Lynn Foster, elf Pavlik, Bob Haugen [Valueflows](https://valueflo.ws/), 2024 -- [RFC-2119] S. Bradner, [Key words for use in RFCs to Indicate Requirement Levels](https://tools.ietf.org/html/rfc2119.html), 1997 -- [Activity Vocabulary] James M Snell, Evan Prodromou, [Activity Vocabulary](https://www.w3.org/TR/activitystreams-vocabulary/), 2017 -- [Ontology of units of Measure] Hajo Rijgersberg, Don Willems, Xin-Ying Ren, Mari Wigham, Jan Top, [Ontology of units of Measure](http://www.ontology-of-units-of-measure.org/), 2017 +- Christine Lemmer-Webber, Jessica Tallon, Erin Shepherd, Amy Guy, Evan Prodromou, [ActivityPub], 2018 +- Lynn Foster, elf Pavlik, Bob Haugen, [Valueflows][Valueflows], 2026 +- S. Bradner, [Key words for use in RFCs to Indicate Requirement Levels][RFC-2119], 1997 +- James M Snell, Evan Prodromou, [Activity Vocabulary][ActivityVocabulary], 2017 +- Hajo Rijgersberg, Don Willems, Xin-Ying Ren, Mari Wigham, Jan Top, [Ontology of units of Measure][OntologyOfUnits], 2017 + +[ActivityPub]: https://www.w3.org/TR/activitypub/ +[Valueflows]: https://valueflo.ws/ +[RFC-2119]: https://tools.ietf.org/html/rfc2119.html +[ActivityVocabulary]: https://www.w3.org/TR/activitystreams-vocabulary/ +[OntologyOfUnits]: http://www.ontology-of-units-of-measure.org/ ## Copyright