Unify terms to use in model-related code

[sdruskat]

We should:

• Decide on a fixed set of terms to use for specific model concepts, especially when talking about JSON-LD stuff.

We should then:

• Refactor code to use the terms we agreed on.

I've read up a bit, and it seems that the following are as correct and precise as words can ever be, for all of our intents and purposes:

context

• Semantically, the JSON-LD docs make it clear that in describing a thing (which is what we do), this description always has exactly one (abstract) context.
• I propose that we use context for whenever we talk about the context of the description of a single thing that is being described in a publication with hermes.
• Although a JSON-LD document can have multiple contexts, they cannot be nested (i.e., a context cannot be expressed as a direct child of another context). E.g., in this example in the JSON-LD docs, while the document has indeed multiple contexts (2), it contains descriptions for two rather than one thing.

vocabulary

• The things that provide the definitions of the terms that are used to describe the thing-that-is-described (here: software) are vocabularies, not schemas, contexts, or something else. Again, the JSON-LD docs also use vocabulary. Schema.org says that schema.org is not intended as a universal ontology. We expect it to be used alongside other vocabulary that shares our basic datamodel and our use of underlying standards like JSON-LD, Microdata and RDFa., etc.

Others

We may have to talk about things like term, field, value, etc. as well.

[led02]

Some additinal terms that will be important:

• term - a specific key that describes a well-defined concept within a context
• prefix - a specific key that mapps an compact IRI prefix to its expansion
• context vocabulary definition - the mapping that binds terms to prefixes or term definitions
• context vocabulary reference - an URI that points to a context definition.

[sdruskat]

I think we're getting there, here's my next iteration, nearing completion. I try to avoid synonymies and thus terminology from the programming domain.

---

• term - a vocabulary item that describes a "real-world" (here: software-world) concept

Examples: programmingLanguage, author, funding

• vocabulary - a collection of terms (usually collected for the purpose of describing a specific set of semantically related things)

Examples: CodeMeta, Schema, The Hermes Schema

• default vocabulary - a special vocabulary within a given context, in that the default vocabulary's terms' compact IRIs are special in that they do not include a (or rather: include a null) prefix, can therefore omit the colon separator, and are therefore homoglyphic with the term (e.g., funding is a term, but also the compact IRI for the term IRI https://codemeta.github.io/terms/funding)

• assigned vocabulary - a non-default vocabulary, i.e., one that has been assigned a prefix

• prefix - a shorthand name for a vocabulary

Examples: schema, hermes

• compact IRI - combines a prefix with a term, separated by a colon (<prefix>:<term>) and can be used to identify the term in its vocabulary if the mapping from prefix to vocabulary IRI is known, so that vocabulary IRI and term can be combined (often simply concatenated) to reconstruct the term IRI

Examples: schema:Organization, hermes:gitBranch

• term IRI - a fully qualified IRI that combines a vocabulary's vocabulary IRI with a term to uniquely identify the term in the vocabulary

Examples: https://codemeta.github.io/terms/funding, https://schema.org/Organization

• vocabulary IRI - an IRI identifying a vocabulary; the vocabulary IRI is used in expansion to combine with a term to create the term IRI

Examples: https://codemeta.github.io/terms/, https://schema.org/

• context - a collection of vocabularies that are selected to describe software in a specific document

---

There is a wee bit of semantic cross-dimensionality in there, but I think it's fine.
This, I think, is good enough for me, and I hope it reaches some agreement 😅.

There are still some more things that we may need to talk about, but others I think can be glossed via the context we use them in, e.g., whenever we talk about dynamicity (processing), we can stick to what Python gives us, so a "field" is really a "key", a "value" is just that, and a combination of "key" and "value" is an "item" in mapping, etc.

[led02]

Looking promising. Where do we want to put this glossary?

However, I think there is still a mis-conception related to the term IRI: For example, the vocabulary IRI is https://doi.org/10.5063/schema/codemeta-2.0. However, the prefix used to construct a term IRI is https://codmeta.github.io/terms/.
In most cases, this boils down to the same URI, but it is not required.
Another example can be found directly in the W3C docs.
The referenced vocabulary does only use terms from other vocabularies and does not even provide an own prefix.

Hence, when we modify the example to explicitly assign a prefix to the vocabulary, we get the following:

{
  "@context": {"person": "https://json-ld.org/contexts/person.jsonld"},
  "person:name": "Manu Sporny",
  "person:homepage": "http://manu.sporny.org/",
  "person:image": "http://manu.sporny.org/images/manu.png"
}

Yet, the expanded keys won't be "https://json-ld.org/contexts/person.jsonld/name", "https://json-ld.org/contexts/person.jsonld/homepage" , and "https://json-ld.org/contexts/person.jsonldimage" but "http://xmlns.com/foaf/0.1/name", "http://xmlns.com/foaf/0.1/img", and "http://xmlns.com/foaf/0.1/homepage".

Still, if the value for an "@id" like "person:homepage" would be set to "person:foo", it would be expanded to "https://json-ld.org/contexts/person.jsonldfoo".