vf-graphql issueshttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues2024-02-21T12:20:23Zhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/105How do VF proposed changes work with graphql2024-02-21T12:20:23ZLynn FosterHow do VF proposed changes work with graphqlThis refers to https://lab.allmende.io/valueflows/valueflows/-/merge_requests/730, which is still in process. But the info related to my question is included below.
The question: What are the graphql implications of these changes? An...This refers to https://lab.allmende.io/valueflows/valueflows/-/merge_requests/730, which is still in process. But the info related to my question is included below.
The question: What are the graphql implications of these changes? And are they for the better or for the worse?
Basically, I'm adding some inverse naming explicitly in the spec (which shouldn't make any difference really), but more to the point, changing the way the many-to-many relationships work from a relational model to a more rdf-friendly model. Starting with only the ones without properties, and removing the `reciprocal` property from ProposedIntent.
Like this:
![Screenshot_from_2023-10-06_10-36-02](/uploads/109c1e966ca1d910feea162bb9acf183/Screenshot_from_2023-10-06_10-36-02.png)
![Screenshot_from_2023-10-06_10-36-13](/uploads/024ad0addee1e655b25c760920389dd1/Screenshot_from_2023-10-06_10-36-13.png)
For all the inverses I've added, see the [turtle file in the branch](https://lab.allmende.io/valueflows/valueflows/-/blob/inverse/release-doc-in-process/all_vf.TTL), look for `inverseOf`.
In an [ActivityPub exercise](https://codeberg.org/fediverse/fep/src/branch/main/fep/0837/fep-0837.md), which is part of explicitly defining VF extensions to AP, the json-ld example looks like this. It reminds me of graphql. (It doesn't support all of the VF structure, e.g. multiple primary and reciprocal intents. Also it "mixes up" the AP and VF properties.)
```
{
"@context": [
"https://www.w3.org/ns/activitystreams",
{
"om2": "http://www.ontology-of-units-of-measure.org/resource/om-2/",
"vf": "https://w3id.org/valueflows/",
"Proposal": "vf:Proposal",
"Intent": "vf:Intent",
"receiver": "vf:receiver",
"provider": "vf:provider",
"action": "vf:action",
"unitBased": "vf:unitBased",
"publishes": "vf:publishes",
"reciprocal": "vf:reciprocal",
"resourceConformsTo": "vf:resourceConformsTo",
"resourceQuantity": "vf:resourceQuantity",
"hasUnit": "om2:hasUnit",
"hasNumericalValue": "om2:hasNumericalValue"
}
],
"type": "Proposal",
"id": "https://market.example/proposals/ddde9d6f-6f3b-4770-a966-3a18ef006930",
"attributedTo": "https://market.example/users/alice",
"name": "Offering used bike",
"content": "Blue one-speed bike, 15 years old, some rust",
"published": "2023-06-18T19:22:03.918737Z",
"location": {
"type": "Place",
"longitude": -71.0,
"latitude": 25.0
},
"publishes": {
"type": "Intent",
"id": "https://market.example/proposals/ddde9d6f-6f3b-4770-a966-3a18ef006930#primary",
"action": "transfer",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q11442",
"resourceQuantity": {
"hasUnit": "one",
"hasNumericalValue": "1"
},
"availableQuantity": {
"hasUnit": "one",
"hasNumericalValue": "1"
},
"provider": "https://market.example/users/alice"
},
"reciprocal": {
"type": "Intent",
"id": "https://market.example/proposals/ddde9d6f-6f3b-4770-a966-3a18ef006930#reciprocal",
"action": "transfer",
"resourceConformsTo": "https://www.wikidata.org/wiki/Q4917",
"resourceQuantity": {
"hasUnit": "one",
"hasNumericalValue": "30"
},
"receiver": "https://market.example/users/alice"
},
"unitBased": false,
"to": "https://www.w3.org/ns/activitystreams#Public"
}
```pospipospihttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/104Define query API for `Unit`2023-04-03T04:21:13ZpospiDefine query API for `Unit`Time to start thinking about specs for retrieving and managing `Unit` records and the [OM ontology](https://github.com/HajoRijgersberg/OM/). See https://github.com/h-REA/hREA/pull/387#issuecomment-1426941156 for more.
- [ ] Extend `Unit...Time to start thinking about specs for retrieving and managing `Unit` records and the [OM ontology](https://github.com/HajoRijgersberg/OM/). See https://github.com/h-REA/hREA/pull/387#issuecomment-1426941156 for more.
- [ ] Extend `Unit` records with an optional `sameAs` field (corresponding to http://owl.semanticweb.org/page/Owl:sameAs.html). This would allow the GraphQL API to reference not only OM units, but units from other vocabs as well.
- [ ] Add `filter` parameters to the `units()` query API so that `sameAs: [URI!]` can be used to select sub-sets of well-known units.
Other questions:
- Is `owl:sameAs` the correct relationship to be modeling, or is this more of an `rdfs:subClassOf` situation? I figure reasoning logic that makes any comparisons is going to have to recursively fetch and compare all references either way (eg. an `hour` in the coffee shop's network is `sameAs` an `hour` in the bakery's network which is `sameAs` the OM2.0 'hour' term).
- Is one relationship (`sameAs: URI`) sufficient, or would we prefer multiple (`classifiedAs: [URI!]`)?
- Should `sameAs` return a self-referential URI to its own `Unit` record if no value is assigned? Should this be queryable for custom units?Lynn FosterLynn Fosterhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/103rename resource_effect to accounting_effect2022-08-18T23:04:40ZConnor Turlandrename resource_effect to accounting_effectBecause resource_effect sounds to general, and like it includes both accounting_effect and onhand_effect
https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/blob/sprout/lib/schemas/action.gql#L26Because resource_effect sounds to general, and like it includes both accounting_effect and onhand_effect
https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/blob/sprout/lib/schemas/action.gql#L26https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/102Finalise API for location-based queries2022-06-20T01:35:44ZpospiFinalise API for location-based queriesThere are a number of `withinLocation` queries defined in the document attached [here](https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/84#note_39817).
We need to implement these, and decide on an appropriate API format...There are a number of `withinLocation` queries defined in the document attached [here](https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/84#note_39817).
We need to implement these, and decide on an appropriate API format for querying them.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/101Abstract 'Agent', remove 'Person' & 'Organization'?2023-05-10T11:36:50ZpospiAbstract 'Agent', remove 'Person' & 'Organization'?It has become quite clear in implementing a GraphQL version of the spec that many of the `Person` and `Organization` fields are common to both types; and that having `Agent` defined as an interface leads to a great deal of duplicated que...It has become quite clear in implementing a GraphQL version of the spec that many of the `Person` and `Organization` fields are common to both types; and that having `Agent` defined as an interface leads to a great deal of duplicated query edges which all return basically the same data.
It seems as though it would be advisable to remove these statically declared concrete types and instead treat everything uniformly as `Agent`, adding a new `agentType` field which can be used to differentiate. Well-known values for this field achieving the same functionality would come from the [FOAF](http://xmlns.com/foaf/spec/) spec (`foaf:Person`, `foaf:Organization` and `foaf:Group`); and we could use these as filter parameters to query all people / orgs in applications which need to differentiate them.
This is particularly true given the intention to create other types of `Agent`— for example Bonfire has `Group` and hREA has `EcologicalAgent` (which we could define ourselves or link to in another grammar).
This does not seem like a change that need affect the core vocabulary, since it essentially treats these agent types differently already via the natural consequences of using RDF data structures.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/100Declare inverse query edges2022-06-22T11:25:46ZpospiDeclare inverse query edgesMore or less all inverses (found at https://www.valueflo.ws/specification/inverses/) are not yet defined as part of the spec.
We need to declare these to keep hREA moving, at least for agent. But we might as well add them all while we'r...More or less all inverses (found at https://www.valueflo.ws/specification/inverses/) are not yet defined as part of the spec.
We need to declare these to keep hREA moving, at least for agent. But we might as well add them all while we're at it.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/99discrepancy in graphql response type for Agreement2022-06-09T18:09:00ZConnor Turlanddiscrepancy in graphql response type for AgreementThis one is just an Agreement, instead of an AgreementResponse, like it would IntentResponse for example. Spotted by Wesley
https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/blob/0.9.x/lib/schemas/agreement.gql#L76This one is just an Agreement, instead of an AgreementResponse, like it would IntentResponse for example. Spotted by Wesley
https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/blob/0.9.x/lib/schemas/agreement.gql#L76https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/98Use nullability only when necessary2022-05-16T21:22:35Zsrfshallmende@havu.chUse nullability only when necessaryNow, I might look at this from a purist programmer's viewpoint, but this doesn't make sense to me. You see, with Booleans, for example, you don't need a "third case", that is, "true" and "false" are just enough to represent everything y...Now, I might look at this from a purist programmer's viewpoint, but this doesn't make sense to me. You see, with Booleans, for example, you don't need a "third case", that is, "true" and "false" are just enough to represent everything you need. Same with pretty much anything. My suggestion: use nullable fields when we are sure that we need that third, "empty" case.
I made some changes regarding this idea to some parts of the schemas, but carefully viewing each and every struct might be necessary to achieve this everywhere (for example, every boolean value). I'd like to take this task by myself.
One more thing related to this: you see, many programming languages initialize variables to their "zero" values, such as Java, C#, Go. Such as numbers become `0`, Booleans become `false`, and so on. With that in mind, it would be better to define default values of things (especially Booleans with this change, if it happens) carefully, and make the zero values most useful, which could mean changing the names of some fields to opposite to reflect that (assuming `true` makes the most sense for field X, we should make sure the name of X is actually NOT X in meaning).https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/97split Process into its own module?2022-06-08T07:41:35Zpospisplit Process into its own module?Nod from @lynnfoster that splitting `Process` away from the "observation" module might be a good idea, so that very simple apps only wanting to implement basic accounting don't need to think about it.Nod from @lynnfoster that splitting `Process` away from the "observation" module might be a good idea, so that very simple apps only wanting to implement basic accounting don't need to think about it.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/96remove holo-rea references from index.js2022-04-11T22:45:38ZConnor Turlandremove holo-rea references from index.jsConnor TurlandConnor Turlandhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/95Remove ability to edit `EconomicResource.containedIn`2022-02-09T03:04:31ZpospiRemove ability to edit `EconomicResource.containedIn`The new way of modifying this attribute is via the `pack` and `unpack` actions.The new way of modifying this attribute is via the `pack` and `unpack` actions.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/94Add descriptions for mutation parameters2022-01-24T02:44:26ZpospiAdd descriptions for mutation parametersJust had the feedback from @Connoropolous whilst [tinkering with](https://hackmd.io/@connoropolous/B1B5qAIpK) the hREA GraphQL explorer that these would assist newcomers a lot.
Some description of how to retrieve the builtin actions whe...Just had the feedback from @Connoropolous whilst [tinkering with](https://hackmd.io/@connoropolous/B1B5qAIpK) the hREA GraphQL explorer that these would assist newcomers a lot.
Some description of how to retrieve the builtin actions when they must be provided would also be worth adding.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/93track and trace2022-06-20T02:14:34ZLynn Fostertrack and traceI'd like to make a change to the way I earlier defined track and trace query naming. My question is about timing: is this an acceptable time to do this related to in-process projects? @pospi @mayel @srfsh
I'd like to change the curre...I'd like to make a change to the way I earlier defined track and trace query naming. My question is about timing: is this an acceptable time to do this related to in-process projects? @pospi @mayel @srfsh
I'd like to change the current `track` and `trace` to `previous` and `next`. That would be the query on all types within the flows, and would return only one step. (All types mean process, economic event, economic resource.)
Then we would use `track` and `trace` to return the entire outgoing or incoming flow(s), starting with a resource. So these queries would recursively call the previous or next logic at each step.
Also, there are probably some further expansions needed at some point.
* There might be bounded versions, like within a plan or scope.
* There are some also some known uses at the recipe or planning level, primarily for graph display.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/92QA pass on `inScopeOf` availability and editability2021-12-13T14:31:50ZpospiQA pass on `inScopeOf` availability and editabilitySome records seem to have this when they shouldn't (eg. `Plan`), and there might be other types that should include the field, but don't.
Also it has been stated that this field should never be updateable, but I'm uncertain about that. ...Some records seem to have this when they shouldn't (eg. `Plan`), and there might be other types that should include the field, but don't.
Also it has been stated that this field should never be updateable, but I'm uncertain about that. Can we review whether this is the case, and how to manage data entry errors etc if it can't be changed after record creation? For example, how would one share an intent to a wider scope than the one it was initially created within, in order to involve others outside of an organisation in its satisfying? Would you simply replicate the intent into the foreign scope? How would you link them after the fact... grouped by `ProposedIntent` to a `Proposal`?
It's currently updateable for `Claim`, `Process`, `Intent`, `Commitment`, `Proposal` and `Scenario`.Lynn FosterLynn Fosterhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/91Ensure all nullable / non-nullable field definitions are as intended2022-01-18T08:42:52ZpospiEnsure all nullable / non-nullable field definitions are as intendedThose yucky exclamation marks haven't been done consistently, and this has thus far been overlooked since loosely typed languages have historically been the only client apps. Bonfire's Elixr UIs are changing that, and such inconsistencie...Those yucky exclamation marks haven't been done consistently, and this has thus far been overlooked since loosely typed languages have historically been the only client apps. Bonfire's Elixr UIs are changing that, and such inconsistencies need to be fixed.
- [x] All `delete*` mutations should return non-nullable values.
- [x] All mutation input arguments should be non-nullable for mutations which accept a single structured payload as an argument.
- [x] All mutations should return non-nullable objects
- [x] Fix `AgentRelationship.inScopeOf` not being manageable via its create / update mutations.
- [x] For all `update*` mutations which accept a single structured data payload, all parameters except the `id` should be nullable. `RecipeProcessUpdateParams.processConformsTo` is the only known issue with regard to this, but a QA pass would be advisable.
Since it came up in QA, also note that `Measure.hasUnit` is intended to be nullable, and that `Measure` does not have an ID field.srfshallmende@havu.chsrfshallmende@havu.chhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/90Finalise connection filtering parameters2021-12-13T09:43:33ZpospiFinalise connection filtering parametersImplementations (Bonfire, hREA & potentially others) need to determine the appropriate filtering parameters for each record type and query edge.
Bridging schemas for `*.filtering.gql` need to be created to provide a `filter` parameter, ...Implementations (Bonfire, hREA & potentially others) need to determine the appropriate filtering parameters for each record type and query edge.
Bridging schemas for `*.filtering.gql` need to be created to provide a `filter` parameter, and the fields of these input types should be well documented in the spec to indicate to implementations how they should behave. Some fields will have complex logic - for example, `EconomicEvent.hasPointInTime` and `EconomicEvent.hasBeginning` might want to be matchable by a parameter `"startTime"`, and that parameter might want to accept logical operators like `<=`, `>=`, `==` etc.
A start has been made on `planning.filtering.gql`, which can be used as a template for the other modules.
See related issues #72, #82 & #85 for more fine-grained decisions & discussion regarding filtering.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/89Update closed resource fields if null?2021-12-13T13:59:10ZLynn FosterUpdate closed resource fields if null?As we have been discussing and tightening up the properties in EconomicResource that can and can't be updated directly, it occurred to me that for some of these (currentLocation, inScopeOf, probably others), it seems like we could allow ...As we have been discussing and tightening up the properties in EconomicResource that can and can't be updated directly, it occurred to me that for some of these (currentLocation, inScopeOf, probably others), it seems like we could allow direct update if they are currently null, without harmful effect.
What do you all think? More work and complexity for the backend apps and for UI apps too. But maybe saves some user annoyance and confusion. Or maybe not, don't know.
Or, is it not a good time to consider this, and we let it sit for this round of development?https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/88Add spec for revision handling2022-06-08T07:48:44ZpospiAdd spec for revision handlingFollowing #87, there needs to be a core specification for handling conflicting data and access to prior revisions in eventually consistent architectures.
All UIs (regardless of whether the backend implements such features) will need to ...Following #87, there needs to be a core specification for handling conflicting data and access to prior revisions in eventually consistent architectures.
All UIs (regardless of whether the backend implements such features) will need to implement these interfaces in order to be considered "fully compatible" with the spec. This implementor burden should be kept as minimal as possible; ergo the smallest number of additional fields and simplest application logic should be favoured.pospipospihttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/87Compatibility for eventually-consistent systems2021-12-13T09:38:54ZpospiCompatibility for eventually-consistent systemsThis is a complex issue with a potentially extreme amount of background information, justifying a fairly simple set of changes:
- [x] All record types which have an `id` should also include a `revisionId`.
- [x] All update and delete me...This is a complex issue with a potentially extreme amount of background information, justifying a fairly simple set of changes:
- [x] All record types which have an `id` should also include a `revisionId`.
- [x] All update and delete methods should accept the `revisionId` of a record, instead of its `id`.
- **Clients should reference revisions, rather than RESTful identities, when making alterations to existing data.**
- For UI code to be correct, it must ensure it passes the correct parameter.
- For backend systems which represent a single source of truth and do not support versioning, `revisionId` can simply be provided with the same value as `id` to no ill effects.
I will leave the background information to a minimum for now, to see how this lands with other folks (particularly @lynnfoster @mayel @ivan) before sinking time into explaining deeper.
I think this is the simplest API change that can accommodate the diverse spectrum of potential technologies to implement against— from the high-trust end of centralised, immediately consistent systems all the way through to low-trust, fully distributed and eventually-consistent networks in which forks are unavoidable.
Further reading:
- [InfoCentral's technical properties of distributed information](https://infocentral.org/drafts/DecentralizedInformation.html#no-mutable-references) (no mutable references)
- [Holochain 'RSM' migration guide](https://holochain-open-dev.github.io/blog/holochain-rsm-migration-guide/#crud) (low-level CRUD)
- [Release announcement about the upgraded HDK](https://medium.com/holochain/unpacking-the-new-holochain-f54da3ca99b7#7a69) (high-level description of changes)
- [Example code showing one mechanism for dealing with this](https://github.com/h-be/acorn-hc/blob/2b0e77dfc080267bc1440eeb966c4067d24f180d/crates/dna_help/src/lib.rs#L75), which just picks the latest item but unfortunately in doing so also makes it possible to attack a network by writing data with a newer timestamp than some record you want to replace and then reconnecting and allowing it to sync.pospipospihttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/86provider and receiver missing?2020-10-24T12:34:24ZLynn Fosterprovider and receiver missing?I went in to see if provider and receiver were required on EconomicEvent, and didn't find them at all in the observation schema, except for on a query parameter. Are these missing on purpose and located elsewhere, and it is my ignorance...I went in to see if provider and receiver were required on EconomicEvent, and didn't find them at all in the observation schema, except for on a query parameter. Are these missing on purpose and located elsewhere, and it is my ignorance? Or just missing? @pospi