User-guide refresh #99
Conversation
content/user-guide.md
Outdated
| Keywords are instructions for the processor of the file to refer to | ||
| previously stored information. This means that the exact same information can | ||
| be included multiple times, and pulled from a consistent source. |
There was a problem hiding this comment.
Not necessarily. @type and @list do not refer to other information for example.
There was a problem hiding this comment.
Agreed — and to add some clarification around the @ properties: most JSON-LD keywords do not pull in other data. Instead, they provide instructions on how the values in the file should be interpreted. In a CodeMeta file, properties that start with @ are JSON-LD keywords and help tools understand the structure and meaning of the data.
For example, the @type keyword indicates what kind of thing is being described. In a CodeMeta file, you might see:
"@type": "SoftwareSourceCode"This allows tools reading the file to recognize that the information refers to a software project, rather than something like a person or an organization. Another keyword, @list, is used in cases where the order of items matters, such as when listing contributors in a specific sequence.
The @context keyword plays a different role. It links the property names used in the file to a shared vocabulary or ontology that tools can refer to. CodeMeta files typically use the standard CodeMeta context hosted on GitHub (https://github.com/codemeta), which gives well-defined meanings to terms like author, name, and license.
content/user-guide.md
Outdated
|  | ||
|
|
||
| The "author" JSON object illustrates the use of the JSON-LD keyword "@id", which is used to associate an IRI with the JSON object. Any such node object can be assigned an `@id`, and we may use the `@id` to refer to this same object (the person, Peter), elsewhere in the document; e.g. we can indicate the same individual is also the `maintainer` by adding: | ||
| The JSON-LD "@type" keyword associates a JSON value or object with a well | ||
| known type. In the previous example, the statement `"@type":"Person"` | ||
| associates the `author` object with `http://schema.org/Person`. It is good | ||
| practice to always provide the `@type` for any property which specifies a node | ||
| (JSON object). The [terms page](/terms/) indicates these node types. |
There was a problem hiding this comment.
Where does this diagram come from? it implies that any @ refers to external data but only @context does. (And we typically have @context at the beginning of the document.)
There was a problem hiding this comment.
The diagram is from my newbie understanding of JSON-LD. I'll revise this section.
There was a problem hiding this comment.
Hi, the problems with the current diagram is that it
(i) emphasizes pairwise mappings instead of CodeMeta’s real role as a hub; we can also
(ii) use the colour to give semantic meaning; and untangle
(iii) the arrows which mix conversion, alignment, and information flow; also it is
(iv) hard to tell what is authoritative vs what is derived.
There was a problem hiding this comment.
I'm starting to think about this here : https://codepen.io/collection/rBjdmV
(i) https://codepen.io/lindangulopez/pen/LENKgEO is a attempt to show a Canonical CodeMeta 3.x vocabulary alignment diagram. The arrows denote semantic alignment between CodeMeta and external metadata vocabularies, with direction indicating whether the alignment is largely invertible or only partially covered.
There was a problem hiding this comment.
Hi Linda, thanks for the feedback and apologies for the delay in response.
The diagram you linked is not the one discussed here, this is, and after some time away from it I am definitely less happy with it.
At the same time I'm not sure your diagram is useful in the context either, or in this guide in particular given the target audience.
Since I'm also not really sure how to make a visualization that does this justice, I'm leaning towards removing the diagram as it is not really effective.
Some other parts of this section also need revising in my opinion.
There was a problem hiding this comment.
Dear @meldra ,
Rather than iterating further on this in the PR, I believe it would be more effective to rework the diagram collaboratively with the wider CodeMeta group. This will allow us to align on what the diagram should communicate and to whom, ensuring we avoid a visual that is technically incorrect and potentially misleading.
It’s clear that, in its current form, the diagram is both technically flawed and causing more confusion than clarity. Given this, I agree that we should remove it for now and decide later how best to integrate a new diagram.
My proposal was intended to follow up and spark a discussion in this PR, not as a finalized solution. To facilitate further collaboration on this, I’ve opened a discussion in the CodeMeta forums (Discussion #467) to gather broader input. I will also bring this up in our next meeting, this coming Wednesday, January 14th.
Once we have clearer alignment, I’ll report back here with recommendations.
Kind regards,
Linda
There was a problem hiding this comment.
Just pushed a commit to retract the diagram pending workshopped replacement.
|
Tagging @lindangulopez |
Co-authored-by: Val Lorentz <progval+github@progval.net>
content/user-guide.md
Outdated
| Some refer to external resources (such as `@context`), some (like `@list` and | ||
| `@type`) add new constraints on the values for the property, while others | ||
| include a copy of previously recorded information (`@id`). |
There was a problem hiding this comment.
| Some refer to external resources (such as `@context`), some (like `@list` and | |
| `@type`) add new constraints on the values for the property, while others | |
| include a copy of previously recorded information (`@id`). | |
| `@context` refers to external sources, some (like `@list` and `@set`) change value semantics, | |
| while others (like `@type` and `@id`) intrinsically describe objects. |
There was a problem hiding this comment.
Actually forget that, I have a better way to phrase the introduction. See below
content/user-guide.md
Outdated
| Some refer to external resources (such as `@context`), some (like `@list` and | ||
| `@type`) add new constraints on the values for the property, while others | ||
| include a copy of previously recorded information (`@id`). |
There was a problem hiding this comment.
Actually forget that, I have a better way to phrase the introduction. See below
Co-authored-by: Val Lorentz <progval+github@progval.net>
| known type. In the previous example, the statement `"@type":"Person"` | ||
| associates the `author` object with `http://schema.org/Person`. The | ||
| `@type` for any property which specifies a node (JSON object) should be | ||
| provided. The [terms page](/terms/) indicates these node types. |
There was a problem hiding this comment.
I'm not entirely confident that the terms page is indicating these sufficiently for the target audience; which includes people composing a codemeta.json as their first contact with JSON-LD. While yes they're described, as a newcomer to the concepts I would be opening that page and doing ctrl+f for one of the strings above such as @type and that simply has no match.
4 participants
This is a version of the user-guide that is rearranged for flow and readability, and partially rewritten or rephrased (some chunks remain mostly untouched as I'm nowhere near up to speed enough to override what's already documented). Please point out any misunderstandings on my part, and any gaps that still need filling or enhancing with visuals.
This also includes some style changes for improved readability. These changes also affect the dev guide.
@moranegg please tag linda, I'm not sure what her username is.