MeSoCoRe

docs/_ext/ld_properties.py

+from typing import Any, Dict, List, Tuple
+
+from docutils.nodes import (
+    Element,
+    Node,
+    TextElement,
+    literal,
+    reference,
+    system_message,
+)
+from sphinx.util.docutils import ReferenceRole
+
+PREFIXES = {
+    "schema": "http://schema.org/",
+    "codemeta": "https://codemeta.github.io/terms/",
+    "forge": "https://forgefed.org/vocabulary.html#",
+    "as": "https://www.w3.org/TR/activitystreams-vocabulary/#",
+    "wikidata": "http://www.wikidata.org/entity/",
+    "mesocore": "https://www.softwareheritage.org/schema/2022/mesocore/",
+}
+
+
+class PropertyRole(ReferenceRole):
+    def run(self) -> Tuple[List[Node], List[system_message]]:
+        (prefix, local_name) = self.target.split(":", 1)
+        try:
+            namespace = PREFIXES[prefix]
+        except KeyError:
+            msg = self.inliner.reporter.error(
+                __("invalid prefix %s") % prefix, line=self.lineno
+            )
+            prb = self.inliner.problematic(self.rawtext, self.rawtext, msg)
+            return [prb], [msg]
+
+        full_name = namespace + local_name
+
+        text = literal("", self.target)
+        link = reference(
+            "", "", text, internal=False, refuri=full_name, classes=["ld-property"]
+        )
+        return [link], []
+
+
+def setup(app: "Sphinx") -> Dict[str, Any]:
+    from docutils.parsers.rst import roles
+
+    roles.register_local_role("prop", PropertyRole())

docs/conf.py

+import pathlib
+import sys
+
 from swh.docs.sphinx.conf import *  # NoQA
+
+sys.path.append(str(pathlib.Path(__file__).parent / "_ext"))
+extensions += ["ld_properties"]

docs/index.rst

@@ -14,6 +14,7 @@ information from archive source code artifacts.
    README.md
    dev-info.rst
    metadata-workflow.rst
+   mesocore.rst
 
 
 Reference Documentation

docs/mesocore.rst

+Metadata on Social Code Repositories
+====================================
+
+MeSoCoRe is a vocabulary which complements ontologies like schema.org/CodeMeta
+and DOAP in describing software projects. While the latter are meant to describe
+source code projects, MeSoCoRe describes VCS repositories of these projects.
+This includes, for example, "stars" and "watchers" on platforms like GitHub, Gitlab,
+or Gitea.
+
+The namespace is ``https://www.softwareheritage.org/schema/2022/mesocore/``;
+and it is meant to be used primarily in alongside CodeMeta/schema.org
+and ForgeFed/ActivityStreams.
+
+
+The following prefixes are used throughout this document for readability:
+
+.. code-block:: json
+
+    {
+        "schema": "http://schema.org/",
+        "codemeta": "https://codemeta.github.io/terms/",
+        "forge": "https://forgefed.org/vocabulary.html#",
+        "as": "https://www.w3.org/TR/activitystreams-vocabulary/#",
+        "wikidata": "http://www.wikidata.org/entity/",
+        "mesocore": "https://www.softwareheritage.org/schema/2022/mesocore/",
+    }
+
+For example, here is a document using all three together:
+
+.. code-block:: json
+
+    {
+      "@context": {
+        "as": "https://www.w3.org/ns/activitystreams#",
+        "codemeta": "https://codemeta.github.io/terms/",
+        "forge": "https://forgefed.org/ns#",
+        "mesocore": "https://www.softwareheritage.org/schema/2022/mesocore/",
+        "schema":"http://schema.org/",
+        "wikidata": "http://www.wikidata.org/entity/"
+      },
+      "@type": "forge:Repository",
+      "@id": "https://github.com/octocat/linguist",
+      "schema:name": "Linguist",
+      "schema:description": "Language Savant",
+      "codemeta:issueTracker": "https://github.com/octocat/linguist/issues",
+      "mesocore:vcs": {
+        "@type": "schema:SoftwareApplication",
+        "@id": "wikidata:Q186055",
+        "schema:name": "Git"
+      },
+      "mesocore:containsSourceCode": {
+        "@type": "schema:SoftwareSourceCode",
+        "schema:name": "Linguist",
+        "schema:description": "This library is used on GitHub.com to detect blob languages"
+      },
+      "as:followers": {
+        "@type": "as:OrderedCollection",
+        "as:totalitems": 123
+      },
+      "forge:forks": {
+        "@type": "as:OrderedCollection",
+        "as:totalItems": 138
+      },
+      "forge:forkOf": {
+        "@type": "forge:Repository",
+        "@id": "https://github.com/github/linguist",
+        "schema:name": "Linguist"
+      }
+    }
+
+
+Types
+-----
+
+*This section is not normative*
+
+None, MeSoCoRe reuses ``https://forgefed.org/ns#Repository``.
+
+Relation properties
+-------------------
+
+Relation properties from other specifications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*This section is not normative*
+
+The following properties are typically used in MeSoCoRe documents:
+
+* The :prop:`as:followers` property lists actors (typically persons) subscribed
+  to a repository.
+  As it is an :prop:`as:OrderedCollection`, its :prop:`as:totalItems` attribute contains
+  the number of followers, which matches ``watchers_count`` on GitHub and GitLab;
+  which can also be expressed with :prop:`schema:InteractionCounter`
+* :prop:`forge:forkedFrom` and :prop:`forge:forks` properties to describe relationships
+  between repositories. (:prop:`forge:forks` is also an :prop:`as:OrderedCollection`).
+
+Mirrors
+^^^^^^^
+
+TODO
+
+Social properties
+-----------------
+
+Social properties from other specifications
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+*This section is not normative*
+
+* The :prop:`as:likes` property lists actors (typically persons) who "like"
+  to a repository.
+  As it is an :prop:`as:OrderedCollection`, its :prop:`as:totalItems` attribute contains
+  the number of followers, which matches ``stargazers_count`` on GitHub and
+  ``star_count`` on GitLab;
+  which can also be expressed with :prop:`schema:InteractionCounter`
+
+.. comment:
+
+    * The common concept of star(gazers) and watchers on GitHub/GitLab/Gitea can
+      be represented using :prop:`schema:InteractionCounter` with types
+      :prop:`schema:LikeAction` and :prop:`schema:FollowAction` (note that the latter can
+      also be expressed using :prop:`as:followers`):
+      TODO: use :prop:`as:likes` instead?
+
+    .. code-block:: json
+
+        {
+          "@context": {
+            "as": "https://www.w3.org/ns/activitystreams#",
+            "codemeta": "https://codemeta.github.io/terms/",
+            "forge": "https://forgefed.org/ns#",
+            "mesocore": "https://www.softwareheritage.org/schema/2022/mesocore/",
+            "schema":"http://schema.org/",
+            "wikidata": "http://www.wikidata.org/entity/"
+          },
+          "@type": "forge:Repository",
+          "@id": "https://github.com/octocat/linguist",
+          "schema:interactionStatistic": [
+            {
+              "@type": "schema:InteractionCounter",
+              "schema:interactionType": "http://schema.org/LikeAction",
+              "schema:userInteractionCount": 146
+            },
+            {
+              "@type": "schema:InteractionCounter",
+              "schema:interactionType": "http://schema.org/FollowAction",
+              "schema:userInteractionCount": 123
+            },
+          ]
+        }
+
+Configuration properties
+------------------------
+
+Statistics properties
+---------------------