FEP-3264: Federated Work Coordination
Summary
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.
History
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.
Requirements
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.
Planning a project or some work
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 bePlan
. If interoperability with other ActivityPub services is desirable, implementers MAY also use object types from Activity Vocabulary, such asNote
.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 betext/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 beProcess
.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 betext/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 beCommitment
.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 thework
action). Could be any URI.resourceQuantity
(OPTIONAL): the amount and unit of the non-effort-based economic resource. EitherresourceQuantity
oreffortQuantity
is RECOMMENDED, and both can be included in case ofuse
. 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 theattributedTo
actor.receiver
(RECOMMENDED): the actor who commits to receiving the resource. If not included, it is assumed to be theto
actor.content
(OPTIONAL): the description of what is to be done for this commitment. The type of content SHOULD betext/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."
}
]
}
]
}
Accepting a Commitment
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"
}
Rejecting a Commitment
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"
}
Adding a Commitment to the Plan
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 beCommitment
. If interoperability with other ActivityPub services is desirable, implementers MAY also use object types from Activity Vocabulary, such asNote
.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 betext/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. EitherinputOf
oroutputOf
is REQUIRED.outputOf
: the process for which this commitment is an output. EitherinputOf
oroutputOf
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 thework
action). Could be any URI.resourceQuantity
: the amount and unit of the non-effort-based economic resource. EitherresourceQuantity
oreffortQuantity
is RECOMMENDED, and both can be included in case ofuse
. 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. EitherresourceQuantity
oreffortQuantity
is RECOMMENDED, and both can be included in case ofuse
. 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 theattributedTo
actor.receiver
(RECOMMENDED): the actor who commits to receiving the resource. If not included, it is assumed to be theto
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"
}
Recording what actually was done
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 beEconomicEvent
. If interoperability with other ActivityPub services is desirable, implementers MAY also use object types from Activity Vocabulary, such asNote
.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 betext/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. EitherinputOf
oroutputOf
is REQUIRED.outputOf
: the process for which this commitment is an output. EitherinputOf
oroutputOf
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 thework
action). Could be any URI.resourceQuantity
: the amount and unit of the non-effort-based economic resource. EitherresourceQuantity
oreffortQuantity
is RECOMMENDED, and both can be included in case ofuse
. 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. EitherresourceQuantity
oreffortQuantity
is RECOMMENDED, and both can be included in case ofuse
. 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 theattributedTo
actor.receiver
(RECOMMENDED): the actor who received the resource. If not included, it is assumed to be theto
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"
}
参考文献
- [ActivityPub] Christine Lemmer Webber, Jessica Tallon, ActivityPub, 2018
- [Valueflows] Lynn Foster, elf Pavlik, Bob Haugen Valueflows, 2024
- [RFC-2119] S. Bradner, Key words for use in RFCs to Indicate Requirement Levels, 1997
- [Activity Vocabulary] James M Snell, Evan Prodromou, Activity Vocabulary, 2017
- [Ontology of units of Measure] Hajo Rijgersberg, Don Willems, Xin-Ying Ren, Mari Wigham, Jan Top, Ontology of units of Measure, 2017
著作権
CC0 1.0 ユニバーサル (CC0 1.0) パブリック ドメイン
法律で認められる範囲において、この Fediverse 拡張提案の著者は、この作品に対するすべての著作権および関連する権利または隣接する権利を放棄しています。