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.
|
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>
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.