FEP-0837: Federated Marketplace

helge · August 18, 2023, 2:47pm

Hello!

This is a discussion thread for the proposed FEP-0837: Federated Marketplace.
Please use this thread to discuss the proposed FEP and any potential problems
or improvements that can be addressed.

Summary

This document describes a minimal implementation of a federated marketplace based on ActivityPub protocol and Valueflows vocabulary. In such marketplace actors can publish offers and requests, respond to offers and requests published by other actors, enter into agreements and exchange information necessary to complete these agreements.

bashrc · August 20, 2023, 10:15am

There are Proposals and Offers on them, but what about items Wanted?

silverpill · August 20, 2023, 1:21pm

Wanted items should also be Proposals, and the directionality can be specified using provider and receiver properties of the intents.

@lynnfoster and I talked about this in another thread:

FEP-d767: Extend ActivityPub with Valueflows

We think of it that the money side would always be the reciprocal side, and that would follow through, not be based on the stage of the conversation. So primary always means “this is why we are doing this”. So even a “request for a service” exists because you want the service. The directionality is determined by the provider vs receiver.

One practical aspect of that way of thinking about it is that in a marketplace, if you are searching for what you are interested in, you shouldn’t have to see the reciprocal intents in your results. Or if there is matching logic between offers and requests, then reciprocal intents wouldn’t be part of that. I suspect our doc needs to be improved there.

Also noting that the reciprocal side won’t always be money, but in any case it will be “not the reason” that the proposal was made.

So, for example, if you have an Offer, the intents would look like this:

{
  "type": "Proposal",
  "attributedTo": "https://market.example/users/alice",
  "publishes": {
    "provider": "https://market.example/users/alice"
  },
  "reciprocal": {
    "receiver": "https://market.example/users/alice"
  }
}

And if you have a Request:

{
  "type": "Proposal",
  "attributedTo": "https://market.example/users/alice",
  "publishes": {
    "receiver": "https://market.example/users/alice"
  },
  "reciprocal": {
    "provider": "https://market.example/users/alice"
  }
}

It would be easier to use a single boolean property, but if I understood correctly Valueflows vocabulary doesn’t have it at the moment.

lynnfoster · August 21, 2023, 12:17pm

Valueflows doesn’t have it, but there has been discussion, and I’d be happy to add it to vf:Proposal, as you say it would be easier, and also more clear. I think it would be safer as not a boolean, because there could be other options in the future, perhaps involving multi-party barter or other exchange - not in this marketplace, but in the broader context. So a code of sorts, maybe “offer”, “want”? Or “request”?

silverpill · August 21, 2023, 9:38pm

Yes, a new property with a string value is fine too.
On the other hand, if you introduce a new property, there will be two ways to specify the direction of a proposal. Maybe it’s not worth it.

srosset81 · August 23, 2023, 7:49am

I have proposed to add the Request activity (in addition to the actual Offer activity) for this same reason, but this has not been understood yet:

github.com/w3c/activitystreams

Why no Request in addition to Offer ?

opened 08:51AM - 18 Jan 22 UTC

srosset81

Pending Closure Resolved

## Type * [ ] Editorial * [ ] Question * [x] Feedback * [ ] Blocking Iss…ue * [ ] Non-Blocking Issue ## Issue In the ActivityStreams vocabulary spec, it is written: > The Offers use case deals with activities involving offering one object to another. It can include, for instance, activities such as "Company A is offering a discount on purchase of Product Z to Sally", "Sally is offering to add a File to Folder A", etc. To open the possibility of using ActivityStreams for classifieds or marketplace-like apps, couldn't we consider adding a `Request` activity, which would be the other side of `Offer` ? `Offer` can be used in many cases but I feel `Request` can be more explicit. In the second example above ("Sally is offering to add a File to Folder A"), it is clearly a suggestion. But a `Request` would be more affirmative, and it would imply that an answer is expected. ## Background We are writing an [event management app](https://github.com/assemblee-virtuelle/activitypods/tree/master/packages/events), where events are private by default and can only be seen by invitees. The organizser can give some invitees the right to invite their own contacts. We use the Offer activity in two cases: - When the organiser wants to tell an invitee he has the right to invite his own contacts, he sends an activity of type: Offer > Invite > Event - When an "inviter" (someone with the right to invite) wants the organizer to invite some of his contacts, we also use an activity of type: Offer > Invite > Event. In the first case, `Offer` is appropriate because it is a suggestion ("Please invite your friends"). But in the second case, we feel that the `Request` verb could be more appropriate ("Alright, so you can invite John and Jill"). We also plan to write a classifieds app, where Requests and Offers would be central.

silverpill · September 12, 2023, 10:01pm

The proposal has been updated: #159 - FEP-0837: Update proposal - fep - Codeberg.org

Notable changes:

Clarified the difference between offers and requests.
Removed inReplyTo property from Offer activity. It is not necessary because commitment object already has satisfies property pointing to a proposal.
Reframed (Offer → Accept/Reject) flow as negotiation process.

lynnfoster · September 15, 2023, 11:10pm

Valueflows plans to add the offer/request code to Proposal, I re-opened the issue. Although you correctly pointed out the trade-offs, we think clarity of understanding is the most important. Also, the first choice on the page in all timebank software I’ve seen is a dropdown of offer or request. We haven’t named it yet, if you have suggestions, they are welcome. I thought of Proposal.activity, but I don’t know if that would be confusing or helpful vs. ActivityStreams? On the other hand, if we could actually get Request defined as a new AS Activity, then maybe you wouldn’t even need this new code, it could be redundant. Or not, don’t know, see question below about Create.

There is one other new element you might want to consider, that was requested by a user group (a supply chain network, not a marketplace). That is Intent.minimumQuantity. This would be a unitBased proposal where the provider had a minimum order quantity. I don’t know if marketplaces would run into a need. Buying clubs and other groups doing wholesale purchases would need that.

And a change, sorry about that: where you have Agreement.commitments, we’ve been defining some inverse relationships explicitly, and we’d like to use Agreement.clauses (inverse of .clauseOf).

I spent some time reviewing your FEP again. It is really clearly written, and will be useful to me and others to write the next VF one.

Question: What is the Activity you would use for Proposal and Commitment objects? Would it be Create, and then Update/Delete if needed? And should that be defined explicitly in the example?

A note: Alice wouldn’t need availableQuantity in this case, because the bike is not unitBased. On the other hand, maybe it is still good to have in the example?

The satisfies property of this Commitment object MUST reference the primary intent of the proposal.

I’m wondering about this. If there is negotiating going on, wouldn’t that frequently involve the reciprocal side? Like paying more or less for what is offered, or something else entirely like barter or another currency? I’m not exactly sure how to do this with 2 commitments (objects) in the message though. Because often you do need to specify the quantity you want on the primary side. Or maybe we can assume there isn’t negotiating in a marketplace?

silverpill · September 16, 2023, 7:23am

I think “direction” is a good term.

A single type is easier to work with, in my opinion. And adding Request to AS will likely take many years

minimumQuantity looks unnecessary, but if there will be a demand from implementers, we’ll add it.

No problem! AFAIK there are no implementations yet, so we can easily change it.

For proposals, I think Create, Update and Delete are appropriate. I’ll mention that in the FEP. Commitments are only used as parts of other objects.

Yes, it’s good to have all properties presented in the example.

The Offer(Commitment) activity is a compact form of Offer(Agreement). The party who responds to a proposal is supposed to make repeated Offer(s) until the proposing party accepts the terms and creates the final Agreement.

I was hesitant to use Offer(Agreement) because it’s more verbose.

silverpill · September 19, 2023, 5:12am

@lynnfoster I think the benefits of using full Agreement outweigh the costs.
The quantity in the reciprocal side of the agreement can be calculated by the proposer, but that makes protocol more fragile due to possibility or rounding errors. And as you noted, the interested party may want to ask for a lower price or a different currency/resource.

Updating the spec: #164 - FEP-0837: Use Offer(Agreement) instead of Offer(Commitment) - fep - Codeberg.org

lynnfoster · January 10, 2024, 4:38pm

@silverpill if you are interested, we did add this to Valueflows

Proposal.purpose, choices are offer and request. (Sorry about not using direction, we thought too limiting for possible additional choices in the future.)

lynnfoster · January 14, 2024, 10:22pm

@silverpill

clauses (REQUIRED): the list of commitments associated with the agreement.

The first commitment MUST satisfy the primary intent of the proposal. The second commitment MUST satisfy the reciprocal intent of the proposal.

We added a relationship from Agreement to Commitment, so you can explicitly use the vocabulary for the primary vs reciprocal on Agreements. And we changed the name again; using verbs so there is no problem with plural vs no plural for multiples.

Agreement stiplulates Commitment
Agreement stipulatesReciprocal Commitment

Hopefully we have this stabilized, apologies. And there may be other places to change it in your FEP.

Also, in general, we’ve added a bunch of explicit inverses to accommodate the natural flow in json(-ld), instead of being driven by relational structures. So… besides getting some VF extensions to AP, this whole process is very helpful to Valueflows itself, thanks again for doing this FEP! I’m working on another use-case-based one, using yours as an example.

silverpill · January 16, 2024, 7:03pm

@lynnfoster Good news! I can’t find these new properties at Valueflows Ontology, is there some other place where they are documented?

lynnfoster · January 16, 2024, 7:38pm

Sorry about that, we took that report off of the site because they are in the middle of an upgrade and it isn’t working for us right now. Here are alternatives:

http://150.146.207.114/lode/extract?owlapi=true&url=https://lab.allmende.io/valueflows/valueflows/-/raw/master/mkdocs/docs/assets/all_vf.TTL (that is basically the same report, linked from RDF Specification - Valueflows - it goes down from time to time, which is why we also had the hard-generated one that is now missing)

UML Diagram - Valueflows (only for diagram lovers)

pages/assets/all_vf.TTL at main - valueflows/pages - Codeberg.org (the turtle file system of record) [edited 1/17 to point to main instead of the branch]

silverpill · January 16, 2024, 11:08pm

I assume this upgrade will be completed soon?

The https://w3id.org/valueflows/ context also doesn’t have new terms yet. I would prefer to wait for an update before making changes to the FEP.

lynnfoster · January 17, 2024, 12:37pm

I have no idea, that’s why we removed the link from the site. The first link above is basically the same report, just a different tool. I’ll take the report out of the repo too, for people who have it bookmarked directly.

The https://w3id.org/valueflows/ context also doesn’t have new terms yet. I would prefer to wait for an update before making changes to the FEP.

Good catch! Yes, that hasn’t worked since we moved from github quite awhile ago now, and we haven’t needed it, so have let it slide. I pinged the person who volunteered to set it up properly, and will let you know when it is done. Thanks for that reminder, it’s something we should have done!

silverpill · January 28, 2024, 7:55pm

The @context in FEP-0837 examples is quite big. Maybe we should list all required terms in FEP-specific context and use that instead?

lynnfoster · January 29, 2024, 5:06pm

The https://w3id.org/valueflows/ context also doesn’t have new terms yet.

Update: We think we have w3id working now for VF, at least for ttl, jsonld, html responses. Hopefully it works well for you!

But we have changed our directory structure on w3id for future flexibility, based on the experience of the person who did the upgrade for VF. It is now https://w3id.org/valueflows/ont/vf.

Also, as part of that work, we put the static html spec file back (now generating it ourselves locally with pyLODE instead of relying on their online site), it is here: Valueflows Ontology, or linked from RDF Specification - Valueflows.

silverpill · January 30, 2024, 1:36am

I submitted an update containing changes we discussed earlier: #253 - FEP-0837: Update proposal - fediverse/fep - Codeberg.org

lynnfoster · January 30, 2024, 1:17pm

I don’t have an opinion, leaving it up to you and others more closely connected to the whole FEP workflow and developing documentation structure.