Differential D7174 Diff 26192 docs/specs/protocol-reference.rst

Changeset View

Standalone View

docs/specs/protocol-reference.rst

Show First 20 Lines • Show All 267 Lines • ▼ Show 20 Lines <entry xmlns="http://www.w3.org/2005/Atom"

</entry> </entry>

For details on the semantics, see the For details on the semantics, see the

:ref:`metadata deposit specification <spec-metadata-deposit>` :ref:`metadata deposit specification <spec-metadata-deposit>`

.. _deposit-metadata-provenance:

Metadata provenance

-------------------

To indicate where the metadata is coming from, deposit clients can use a

moraneggUnsubmitted

Not Done

can we use <swh:metadata-provenance> and <swh:deposit> as introduced in the example below, instead of <swhdeposit:metadata-provenance> and <swhdeposit:deposit> ?

moranegg: can we use `<swh:metadata-provenance>` and `<swh:deposit>` as introduced in the example below…

vlorentzAuthorUnsubmitted

Done

This document already uses swhdeposit: in text and swh: in example to show the prefix does not matter; but I think I will change this in a future diff, because it is indeed confusing.

vlorentz: This document already uses `swhdeposit:` in text and `swh:` in example to show the prefix does…

moraneggUnsubmitted

Not Done

sure, in a future diff.
I know we have it elsewhere as well, but it might be confusing that it depends on the declaration of the namespace.

moranegg: sure, in a future diff. I know we have it elsewhere as well, but it might be confusing that it…

``<swhdeposit:metadata-provenance>`` element in ``<swhdeposit:deposit>`` whose content is

the object the metadata is coming from,

moraneggUnsubmitted

Not Done

what is the schema.org namespace?

moranegg: what is the schema.org namespace?

vlorentzAuthorUnsubmitted

Done

it's a synonym for "schema.org vocabulary", but I'm using the terminology used in XML.

vlorentz: it's a synonym for "schema.org vocabulary", but I'm using the terminology used in XML.

moraneggUnsubmitted

Not Done

it's a synonym for "schema.org vocabulary", but I'm using the terminology used in XML.

yes right, I don't understand this specific context.
Is it just for the type url? do we use schema.org anywhere else?
BTW, I didn't find a provenance property in schema.org, maybe you had more luck.

moranegg: > it's a synonym for "schema.org vocabulary", but I'm using the terminology used in XML. yes…

vlorentzAuthorUnsubmitted

Done

yes, for now it's only for url, but I phrased it this way to be extensible.

provenance seems outside schema.org's scope. there's https://www.w3.org/ns/prov if you really want a dedicated vocabulary, but it's waaaay outside what we can use while remaining compatible with codemeta.

vlorentz: yes, for now it's only for `url`, but I phrased it this way to be extensible. provenance seems…

ardumontUnsubmitted

Not Done

To indicate where the metadata is coming from, deposit clients can use a

- ``<swhdeposit:metadata-provenance>`` element in ``<swhdeposit:deposit>`` whose content is

- the object the metadata is coming from,

- preferably using the ``https://schema.org/`` namespace.

+ ``<swhdeposit:metadata-provenance>`` element in ``<swhdeposit:deposit>``. This metadata

+ provenance content declares from where the metadata (describing the object) is coming

+ from. It's defined using the ``https://schema.org/`` namespace.

For example, when the metadata is coming from Wikidata, then the

i think it's clearer. @vlorentz, @moranegg thoughts?

Also I'm more inclined towards imposing the namespace (last sentence). Because
otherwise, we could be annoyed by the various differences we'll be receiving and bug
will slip through.

If not ^, then the last sentence can be reworded as:

It's preferably defined using...

ardumont: i think it's clearer. @vlorentz, @moranegg thoughts? Also I'm more inclined towards imposing…

preferably using the ``https://schema.org/`` namespace.

For example, when the metadata is coming from Wikidata, then the

``<swhdeposit:metadata-provenance>`` should be the page of a Q-entity, such as

``https://www.wikidata.org/wiki/Q16988498`` (not the Q-entity

``http://www.wikidata.org/entity/Q16988498`` itself, as the Q-entity **is** the

object described in the metadata)

Or when the metadata is coming from a curated repository like HAL, then

``<swhdeposit:metadata-provenance>`` should be the HAL project.

In particular, Software Heritage expects the ``<swhdeposit:metadata-provenance>`` object

to have a ``https://schema.org/url`` property, so that it can appropriately link

to the original page.

For example, to deposit metadata on GNU Hello:

.. code:: xml

<?xml version="1.0"?>

<entry xmlns="http://www.w3.org/2005/Atom"

xmlns:schema="https://schema.org/">

<swh:deposit>

<swh:metadata-provenance>

<schema:url>https://www.wikidata.org/wiki/Q16988498</schema:url>

</swh:metadata-provenance>

</swh:deposit>

</entry>

Here is a more complete example of a metadata-only deposit on version 2.9 of GNU Hello,

to show the interaction with other fields,

.. code:: xml

<?xml version="1.0"?>

<entry xmlns="http://www.w3.org/2005/Atom"

xmlns:swh="https://www.softwareheritage.org/schema/2018/deposit"

xmlns:schema="https://schema.org/"

xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0">

<swh:deposit>

<swh:reference>

<swh:object swhid="swh:1:dir:9b6f93b12a500f560796c8dffa383c7f4470a12f;origin=https://ftp.gnu.org/gnu/hello/;visit=swh:1:snp:1abd6aa1901ba0aa7f5b7db059250230957f8434;anchor=swh:1:rev:3d41fbdb693ba46fdebe098782be4867038503e2" />

</swh:reference>

<swh:metadata-provenance>

<schema:url>https://www.wikidata.org/wiki/Q16988498</schema:url>

</swh:metadata-provenance>

</swh:deposit>

<codemeta:name>GNU Hello</codemeta:name>

<codemeta:id>http://www.wikidata.org/entity/Q16988498</codemeta:id>

<codemeta:url>https://www.gnu.org/software/hello/</codemeta:url>

<codemeta:isPartOf>http://www.wikidata.org/entity/Q7598</codemeta:isPartOf>

</entry>

Schema Schema

------ ------

Here is an XML schema to summarize the syntax described in this document: Here is an XML schema to summarize the syntax described in this document:

.. literalinclude:: swh.xsd .. literalinclude:: swh.xsd

:language: xml :language: xml

.. _SWORDv2: http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html .. _SWORDv2: http://swordapp.github.io/SWORDv2-Profile/SWORDProfile.html

.. _AtomPub: https://tools.ietf.org/html/rfc5023 .. _AtomPub: https://tools.ietf.org/html/rfc5023

.. _DublinCore: https://www.dublincore.org/ .. _DublinCore: https://www.dublincore.org/

.. _CodeMeta: https://codemeta.github.io/ .. _CodeMeta: https://codemeta.github.io/