Update ShEx shapes to be more self-documented #246
Conversation
Just some comments for discussion - it would be nice to be able to share this file (with explanatory Turtle perhaps) with external parties who may be looking at modelling these ideas using Upper/Mid-Level Ontologies, but it would need some clarifications first I think... (and comments explaining 'missing' terms, etc.)
|
This pull request is being automatically deployed with Vercel (learn more). 🔍 Inspect: https://vercel.com/inrupt/pod-browser/4msw0loah |
Should make it easier to understand each shape and their relationship between each other
|
I've added some comments that should make each ShEx shape more capable of documenting how they're used |
megoth
changed the title
Co-authored-by: Pat McBennett <patm@inrupt.com>
| PREFIX xsd: <https://www.w3.org/2001/XMLSchema#> | ||
|
|
||
| # This shape describes part of the information we store when adding a group to | ||
| # an address book. The resource it is used for is an index of groups. There will |
There was a problem hiding this comment.
I wouldn't say "The resource it is used for is an index of groups", since it could be reused in a million different ways by other people. You could just add that as an example of where it could be used, but if so I'd suggest rewording it slightly to something like "could be used to represent a group within an index of groups" (but then what's the difference between "an index of groups" and "a collection of groups", or "a container containing groups"...?).
Co-authored-by: Pat McBennett <patm@inrupt.com>
Co-authored-by: Pat McBennett <patm@inrupt.com>
Co-authored-by: Pat McBennett <patm@inrupt.com>
megoth
left a comment
megoth
left a comment
There was a problem hiding this comment.
I think this is a big step in improving the documentation, so I'm happy to approve as-is. But left a couple of suggestions for improvements, but not strictly necessary.
Co-authored-by: Matthieu Bosquet <matthieubosquet@gmail.com>
Co-authored-by: Matthieu Bosquet <matthieubosquet@gmail.com>
matthieubosquet
left a comment
matthieubosquet
left a comment
There was a problem hiding this comment.
I submitted separate PRs raising concerns about the Address Book entity which I think is essentially a vcard:Group and about the use of a WebID class, which I feel is not appropriate in this context.
I'm also concerned about the idea of caching in index resources. But that would be a separate discussion I believe.
Just some comments for discussion - it would be nice to be able to share this file (with explanatory Turtle perhaps) with external parties who may be looking at modelling these ideas using Upper/Mid-Level Ontologies, but it would need some clarifications first I think... (and comments explaining 'missing' terms, etc.)