vf-graphql issueshttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues2023-04-03T04:21:13Zhttps://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/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/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/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/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/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/85Finalise query API for proposals as used in marketplace-like apps2021-12-13T09:16:51ZpospiFinalise query API for proposals as used in marketplace-like appsComing from some [Proposals test cases](https://github.com/holo-rea/app-offers-needs-marketplace/issues/1#issuecomment-667715994) offered by @lynnfoster, in response to work on CommonsPub by @mayel & Ivan (who doesn't yet seem to have an...Coming from some [Proposals test cases](https://github.com/holo-rea/app-offers-needs-marketplace/issues/1#issuecomment-667715994) offered by @lynnfoster, in response to work on CommonsPub by @mayel & Ivan (who doesn't yet seem to have an account here?)
The new additions look great, though there is some divergence from the spec in this that I would like to clean up since I am implementing much the same features at the moment.
### primaryIntents & reciprocalIntents relationships
These are new fields with a bit of extra logic in them. The current way of accessing the Intent data is to go through `Proposal.publishes.publishes`, and then filter those results by the value of `Proposal.publishes.reciprocal`.
**Are these simplified query edges something we think should be included in the core spec?**
### Proposal category
I like it as an idea but for me I think that's a display detail and not something I would want to put in the backend at this stage. Though it is the same logic as `offersOnly` and `requestsOnly` (below), might be an idea to have it in simply for those reasons.
### Query fields
- `includeExpired` and `inScopeOf` sound sensible, happy to add these. Presume default behaviour (without `includeExpired`) would be to omit proposals with `hasEnd < now()`? Or should the default be to return *everything*, and if you only want what's active then provide `includeExpired: true`? I suggest the latter would be a better general pattern to follow.
- `offersOnly` and `requestsOnly` I basically have the same grammatic questions as "proposal category" above. Are these sub-groupings for "proposal types" something we can agree on as a core part of the spec?
- `location`: I'd be happy to have this in there, but the way it would work with the expectations outlined by the GraphQL spec are that you would perform any more complex location-based queries against a dedicated location service, yielding a list of IDs for specific locations. You would then take those IDs and pass them into this query parameter to return any proposals which are located at the given locations. So, `location` should have the type `[ID!]` (an array of IDs). If CommonsPub are thinking to do geo-based queries directly from this endpoint then I think that's a more nonstandard approach.Lynn FosterLynn Fosterhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/84Standardize paginated queries2022-06-20T01:35:45ZMayelStandardize paginated queriesThis is the approach we currently take with CommonsPub, it would be good if we could standardise to use compatible queries between apps
Query:
` intentsPages(limit: Int, before: [Cursor!], after: [Cursor!]): IntentsPage!`
Return Type:...This is the approach we currently take with CommonsPub, it would be good if we could standardise to use compatible queries between apps
Query:
` intentsPages(limit: Int, before: [Cursor!], after: [Cursor!]): IntentsPage!`
Return Type:
`type IntentsPage {
edges: [Intent!]!
pageInfo: PageInfo!
totalCount: Int!
}`
PageInfo type:
`type PageInfo {
endCursor: [Cursor!]
hasNextPage: Boolean
hasPreviousPage: Boolean
startCursor: [Cursor!]
}`
`Cursor` is a scalar defined as an opaque position marker for pagination. Paginated queries return a PageInfo struct with start and end cursors (which are actually lists of Cursor). You can then issue queries requesting results before the start or after the end cursors to request the previous or next page respectively.
It's actually a string or integer. May be extended in future.MayelpospiMayelhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/83Standardise querying of date fields2021-11-19T02:07:32ZpospiStandardise querying of date fieldsWe've had a bit of a discussion of this in #75 & #15 which got far too complicated far too quickly. I know others have opinions on handling date-based queries and I think I can summarise a few of them, so let's see:
- two search param...We've had a bit of a discussion of this in #75 & #15 which got far too complicated far too quickly. I know others have opinions on handling date-based queries and I think I can summarise a few of them, so let's see:
- two search parameters, `startDate` and `endDate`, should be sufficient
- `startDate` and `endDate` can be provided as either ISO8912 dates or as date+time+seconds; "start" will be taken as the beginning of the interval and "end" as its conclusion
- eg. `startDate = 2020-10-02, endDate = 2020-10-02` returns all records between `2020-10-02 00:00:00` and `2020-10-03 00:00:00`
- for simplicity, we should match only on `hasPointInTime` and `hasBeginning`, and ignore `hasEnd`
- results should always be returned in chronological order
Thoughts on this as a general approach going forward?Lynn FosterMayelpospiLynn Fosterhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/82Design per-agent intent & commitment query API2021-12-13T09:41:40ZpospiDesign per-agent intent & commitment query APIBased on comments @fosterlynn has [previously made](https://github.com/valueflows/vf-graphql/issues/73#issuecomment-596644499), there might be some complexity involved in the logic for querying intents for the offers & needs UI.
Are t...Based on comments @fosterlynn has [previously made](https://github.com/valueflows/vf-graphql/issues/73#issuecomment-596644499), there might be some complexity involved in the logic for querying intents for the offers & needs UI.
Are there some existing queries in the CommonsPub UI that we can pull into the core spec for standardisation?Lynn FosterMayelpospiLynn Fosterhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/72Agree on API for agent inventory queries2021-12-13T09:41:40ZpospiAgree on API for agent inventory queriesI want to start logging these here to loop in @ivanminutillo as I work through porting Shroom to work on the latest `vf-graphql` spec. So far it has been minor things like allowing string IDs (in addition to integers) but it will quickly...I want to start logging these here to loop in @ivanminutillo as I work through porting Shroom to work on the latest `vf-graphql` spec. So far it has been minor things like allowing string IDs (in addition to integers) but it will quickly become a discussion about which queries are optimal and easiest to build UIs on top of.
I began with the inventory section of the app. Shroom has `Agent.ownedEconomicResources(category: INVENTORY)`. Here the closest we have is `inventoriedEconomicResources()`.
So the first question is, how to split this up? Separate methods for "owned", "inventoried", "onhand"; or a single query edge for `Agent.economicResources` that includes a category filter as one of its criteria?Lynn FosterpospiLynn Fosterhttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/71Finish schema documentation2020-03-02T05:33:27ZpospiFinish schema documentationhttps://github.com/valueflows/vf-graphql/pull/69 made huge progress; now the input type documentation is to an equivalent standard to the query types, and that helps greatly since these are generally the first structs newcomers encounter...https://github.com/valueflows/vf-graphql/pull/69 made huge progress; now the input type documentation is to an equivalent standard to the query types, and that helps greatly since these are generally the first structs newcomers encounter in GraphQL playgrounds (they have to create data before they can query it!).
There are still some holes that it would be good to have coverage on:
- [ ] top-level query methods
- [ ] top-level mutations: mutation & parameter descriptions (only fields are currently documented, not types)
- [ ] input types (again, only fields are documented- not the structs themselves)https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/68Use `extends` syntax in bridging schema modules2020-02-12T05:43:23ZpospiUse `extends` syntax in bridging schema modulesAs of June 2018 GraphQL supports extending types with other fields, which would make the schemas in `schemas/bridging/` more idiomatic in the way they're written. Would be worth doing this, if the merging logic being used supports the ch...As of June 2018 GraphQL supports extending types with other fields, which would make the schemas in `schemas/bridging/` more idiomatic in the way they're written. Would be worth doing this, if the merging logic being used supports the changes.
Further reading https://stackoverflow.com/a/56204966https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/67Polish schema compilation process2020-02-12T04:34:44ZpospiPolish schema compilation processThere are some rough edges around #61 that could be worth adding.
- [ ] infer from `@depends` tags in file header comments and throw warnings if dependant modules are not specified
- [ ] create a CLI script to generate SDL schema fil...There are some rough edges around #61 that could be worth adding.
- [ ] infer from `@depends` tags in file header comments and throw warnings if dependant modules are not specified
- [ ] create a CLI script to generate SDL schema files from dynamic combinations of schema moduleshttps://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/64Resolve logic for ResourceSpecification / EconomicResource units2020-01-12T08:39:36ZpospiResolve logic for ResourceSpecification / EconomicResource unitsThere was some stuff in VF0.3 that used `ResourceSpecification.unitOfEffort` to infer things about `EconomicResource.unitOfEffort` upon resource creation. Those things went away in VF0.4 as the attribute moved to `RecipeResource.unitOfEf...There was some stuff in VF0.3 that used `ResourceSpecification.unitOfEffort` to infer things about `EconomicResource.unitOfEffort` upon resource creation. Those things went away in VF0.4 as the attribute moved to `RecipeResource.unitOfEffort`, but then it was impossible to determine the default units for a resource without the *recipe* module, and that didn't seem adequate.
Since the expectation for these release(s) was mostly to use `unitOfEffort` as a UI hint, we opted to re-add `ResourceSpecification.defaultUnitOfEffort` to the Holochain implementation in order to not rethink the logic and purpose of these fields too much. Thus it was re-added to the GraphQL spec in `0.4.3`.
Some work needs to be undertaken in VF core in order to determine the final path for this field, until then it remains in the GraphQL spec but not in the RDF; and this inconsistency remains to be resolved.https://lab.allmende.io/valueflows/vf-schemas/vf-graphql/-/issues/63Add ProcessSpecification.conformingProcesses2020-06-01T02:33:58ZpospiAdd ProcessSpecification.conformingProcessesThere needs to be a way to query all `Processes` via the specification that defines their behaviour, in order to locate all processes of a given type.
The `conformingProcesses` need to be filterable by many criteria, TBC...There needs to be a way to query all `Processes` via the specification that defines their behaviour, in order to locate all processes of a given type.
The `conformingProcesses` need to be filterable by many criteria, TBC...