This document describes an implementation of project planning and work coordination based on ActivityPub protocol and Valueflows vocabulary. It includes planning what people want to do, and (optionally) recording what is done.
This is a parallel submission to FEP-c5a1 To-do’s, which supports much simpler planning. Both planning submissions continue the idea of Valueflows extensions to ActivityPub/ActivityStreams based on use case, started by silverpill with FEP-0837 Federated Marketplace.
The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in this document are to be interpreted as described in RFC-2119.
This FEP will support work plans or projects of any size, using a Plan with one or more Processes, each with one or more input and/or output Commitments.
Consuming implementations which don’t have planning features MAY display plan-related objects similarly to Note objects.
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).
The representation of a plan is a JSON document with the following properties:
id (REQUIRED): the plan’s unique global identifier.type (REQUIRED): the type of the object SHOULD be Plan. If interoperability with other ActivityPub services is desirable, implementers MAY also use object types from Activity Vocabulary, such as Note.attributedTo (REQUIRED): the actor who published the plan.name (REQUIRED): the title of the plan.content (OPTIONAL): the description of the plan. The type of content SHOULD be text/html.published (RECOMMENDED): the date and time at which the plan was published.to (REQUIRED): the audience of the plan.planIncludes (REQUIRED): the processes that are part of this plan (see below).A Process is defined as An activity that changes inputs into outputs, by transforming or transporting economic resource(s). Processes that are part of a plan can be part of a series (graph) of processes that produce the final output(s) at the end; and/or they can be unrelated to each other, and produce separate final output(s) for the plan.
The representation of a process is a JSON document with the following properties:
id (REQUIRED): the process’s unique global identifier.type (REQUIRED): the type of the object MUST be Process.name (REQUIRED): an informal or formal textual identifier for a process.hasBeginning (OPTIONAL): the date and time the process is planned to begin.hasEnd (OPTIONAL): the date and time the process is planned to end.content (OPTIONAL): the description of what is to be done in the process. The type of content SHOULD be text/html.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.
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 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:
hasUnit (REQUIRED): name of the unit, according to Ontology of units of Measure 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:
hasUnit (REQUIRED): name of the unit, according to Ontology of units of Measure classification.hasNumericalValue (REQUIRED): amount of the effort.provider (RECOMMENDED): the actor who commits to providing the resource. If not included, it is assumed to be the attributedTo actor.receiver (RECOMMENDED): the actor who commits to receiving the resource. If not included, it is assumed to be the to actor.content (OPTIONAL): the description of what is to be done for this commitment. The type of content SHOULD be text/html.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",
"Commitment": "vf:Commitment",
"receiver": "vf:receiver",
"provider": "vf:provider",
"action": "vf:action",
"resourceConformsTo": "vf:resourceConformsTo",
"resourceQuantity": "vf:resourceQuantity",
"effortQuantity": "vf:effortQuantity",
"hasUnit": "om2:hasUnit",
"hasNumericalValue": "om2:hasNumericalValue",
"planIncludes": "vf:planIncludes",
"hasBeginning": "vf:hasBeginning",
"hasEnd": "vf:hasEnd",
"hasInput": "vf:hasInput",
"hasOutput": "vf:hasOutput"
}
],
"type": "Plan",
"id": "https://project.example/plans/ddde9d6f-6f3b-4770-a966-3a18ef006931",
"attributedTo": "https://project.example/actors/alice",
"name": "Making Apple Cider",
"content": "Annual weekend of community apple cider making",
"published": "2024-09-18T19:22:03.918737Z",
"to": "https://project.example/actors/gleaning-collective",
"planIncludes": [
{
"type": "Process",
"id": "https://project.example/processes/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick",
"name": "Pick Apples",
"hasBeginning": "2024-10-18T09:00:00.000000Z",
"hasEnd": "2024-10-18T18:00:00.000000Z",
"content": "Meet at the orchard, bring your own basket and a lunch, and be ready for some outdoor fall work and fun.",
"hasInput": [
{
"type": "Commitment",
"id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick1",
"action": "work",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q112729805",
"effortQuantity": {
"hasUnit": "hour",
"hasNumericalValue": "6"
},
"provider": "https://project.example/actors/bob",
"receiver": "https://project.example/actors/gleaning-collective"
},
{
"type": "Commitment",
"id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick2",
"action": "work",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q112729805",
"effortQuantity": {
"hasUnit": "hour",
"hasNumericalValue": "6"
},
"provider": "https://project.example/actors/chiam",
"receiver": "https://project.example/actors/gleaning-collective"
},
{
"type": "Commitment",
"id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick3",
"action": "work",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q112729805",
"effortQuantity": {
"hasUnit": "hour",
"hasNumericalValue": "6"
},
"provider": "https://project.example/actors/alice",
"receiver": "https://project.example/actors/gleaning-collective"
}
],
"hasOutput": [
{
"type": "Commitment",
"id": "https://project.example/outputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#pick4",
"action": "produce",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q89",
"resourceQuantity": {
"hasUnit": "pound",
"hasNumericalValue": "500"
},
"provider": "https://project.example/actors/gleaning-collective",
"receiver": "https://project.example/actors/gleaning-collective"
}
]
},
{
"type": "Process",
"id": "https://project.example/processes/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider",
"name": "Make Cider",
"hasBeginning": "2024-10-19T09:00:00.000000Z",
"hasEnd": "2024-10-19T16:00:00.000000Z",
"content": "Meet at the community building, be prepared to get messy. We will press the apples, then clean the press.",
"hasInput": [
{
"type": "Commitment",
"id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider1",
"action": "consume",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q89",
"resourceQuantity": {
"hasUnit": "pound",
"hasNumericalValue": "500"
},
"provider": "https://project.example/actors/gleaning-collective",
"receiver": "https://project.example/actors/gleaning-collective",
"content": "The apples picked the day before."
},
{
"type": "Commitment",
"id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider2",
"action": "use",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q674484",
"effortQuantity": {
"hasUnit": "hour",
"hasNumericalValue": "7"
},
"provider": "https://project.example/actors/diego",
"receiver": "https://project.example/actors/gleaning-collective",
"content": "Diego will drop his cider press off early in the morning, and pick it up later, preferably nice and clean."
},
{
"type": "Commitment",
"id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider3",
"action": "work",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q3485549",
"effortQuantity": {
"hasUnit": "hour",
"hasNumericalValue": "4"
},
"provider": "https://project.example/actors/chiam",
"receiver": "https://project.example/actors/gleaning-collective"
},
{
"type": "Commitment",
"id": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider4",
"action": "work",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q3485549",
"effortQuantity": {
"hasUnit": "hour",
"hasNumericalValue": "6"
},
"provider": "https://project.example/actors/bob",
"receiver": "https://project.example/actors/gleaning-collective"
}
],
"hasOutput": [
{
"type": "Commitment",
"id": "https://project.example/outputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider5",
"action": "produce",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q5977438",
"resourceQuantity": {
"hasUnit": "gallon-US",
"hasNumericalValue": "15"
},
"provider": "https://project.example/actors/gleaning-collective",
"receiver": "https://project.example/actors/food-pantry"
},
{
"type": "Commitment",
"id": "https://project.example/outputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider6",
"action": "produce",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q2836947",
"resourceQuantity": {
"hasUnit": "pound",
"hasNumericalValue": "100"
},
"provider": "https://project.example/actors/gleaning-collective",
"receiver": "https://project.example/actors/singing-trees-farm",
"content": "The apple remains will be great pig food, leave it in the big bin, and they will pick it up."
}
]
}
]
}
The object of Accept activity MUST be the id of the Commitment in the Plan object previously sent to the actor.
Activity MAY contain content property for further coordination.
Example:
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Accept",
"id": "https://project.example/activities/059f08fa-31b1-4136-8d76-5987d705a0ac",
"actor": "https://project.example/actors/bob",
"object": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider4",
"content": "I'll come early to help unload the cider press.",
"to": "https://project.example/actors/alice"
}
The object of Reject activity MUST be the id of the Commitment in the Plan object previously sent to the actor.
Activity MAY contain content property indicating the reason for rejection.
Example:
{
"@context": "https://www.w3.org/ns/activitystreams",
"type": "Reject",
"id": "https://project.example/activities/8c05f97f-1531-4b70-9ca8-4ee4a09f36a4",
"actor": "https://project.example/actors/chiam",
"object": "https://project.example/inputs/ddde9d6f-6f3b-4770-a966-3a18ef006931#cider3",
"content": "Sorry, already working elsewhere that day, will check with Eleanore.",
"to": "https://project.example/actors/alice"
}
In some cases, an actor might want to add a new commitment to the plan.
The representation of a commitment is a JSON document with the following properties:
id (REQUIRED): the commitment’s unique global identifier.type (REQUIRED): the type of the object SHOULD be Commitment. If interoperability with other ActivityPub services is desirable, implementers MAY also use object types from Activity Vocabulary, such as Note.attributedTo (REQUIRED): the actor who published the commitment.content (OPTIONAL): the description of the commitment or communication about the commitment. The type of content SHOULD be text/html.published (RECOMMENDED): the date and time at which the commitment was published.to (REQUIRED): the audience of the 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 for more information.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.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 classification.hasNumericalValue (REQUIRED): amount of the resource.effortQuantity: the amount and unit of the work or use effort-based action. 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 classification.hasNumericalValue (REQUIRED): amount of the resource.provider (RECOMMENDED): the actor who commits to providing the resource. If not included, it is assumed to be the attributedTo actor.receiver (RECOMMENDED): the actor who commits to receiving the resource. If not included, it is assumed to be the to actor.{
"@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",
"receiver": "vf:receiver",
"provider": "vf:provider",
"action": "vf:action",
"resourceConformsTo": "vf:resourceConformsTo",
"effortQuantity": "vf:effortQuantity",
"hasUnit": "om2:hasUnit",
"hasNumericalValue": "om2:hasNumericalValue"
}
],
"type": "Create",
"id": "https://project.example/activities/ad2f7ee1-6567-413e-a10b-72650cbdc743/create",
"actor": "https://project.example/actors/eleanore",
"object": {
"type": "Commitment",
"id": "https://project.example/inputs/ad2f7ee1-6567-413e-a10b-72650cbdc743",
"attributedTo": "https://project.example/actors/eleanore",
"context": "https://project.example/plans/ddde9d6f-6f3b-4770-a966-3a18ef006931",
"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",
"effortQuantity": {
"hasUnit": "hour",
"hasNumericalValue": "5"
},
"provider": "https://project.example/actors/eleanore",
"receiver": "https://project.example/actors/gleaning-collective"
},
"to": "https://project.example/actors/alice"
}
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.
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, 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.action (REQUIRED): the type of economic transaction. If the economic event is an input, the value of this property SHOULD be one of: work, use, consume, cite, pickup, accept. It the economic event is an output, the value of this property SHOULD be one of: produce, deliverService, dropoff, modify. See the action definitions and behaviors for more information.fulfills: the commitment the economic event is completely or partially fulfilling, REQUIRED if there is sucn a commitment, otherwise N/A.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.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 classification.hasNumericalValue (REQUIRED): amount of the resource.effortQuantity: the amount and unit of the work or use effort-based action. 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 classification.hasNumericalValue (REQUIRED): amount of the resource.provider (RECOMMENDED): the actor who provided the resource. If not included, it is assumed to be the attributedTo actor.receiver (RECOMMENDED): the actor who received the resource. If not included, it is assumed to be the to actor.finished (OPTIONAL): set to true if this economic event completes the commitment. (Note more than one economic event can be recorded against the same commitment.){
"@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",
"receiver": "vf:receiver",
"provider": "vf:provider",
"action": "vf:action",
"resourceConformsTo": "vf:resourceConformsTo",
"effortQuantity": "vf:effortQuantity",
"hasUnit": "om2:hasUnit",
"hasNumericalValue": "om2:hasNumericalValue",
"finished": "vf:finished"
}
],
"type": "Create",
"id": "https://project.example/activities/ad2f7ee1-6567-413e-a10b-72650cbdc932/create",
"actor": "https://project.example/actors/bob",
"object": {
"type": "EconomicEvent",
"id": "https://project.example/inputs/ad2f7ee1-6567-413e-a10b-72650cbdc932",
"attributedTo": "https://project.example/actors/bob",
"context": "https://project.example/plans/ddde9d6f-6f3b-4770-a966-3a18ef006931",
"published": "2024-10-21T14:16:41.843794Z",
"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",
"effortQuantity": {
"hasUnit": "hour",
"hasNumericalValue": "6.5"
},
"provider": "https://project.example/actors/bob",
"receiver": "https://project.example/actors/gleaning-collective",
"finished": true
},
"to": "https://project.example/actors/alice"
}
CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
To the extent possible under law, the authors of this Fediverse Enhancement Proposal have waived all copyright and related or neighboring rights to this work.