Changeset View
Changeset View
Standalone View
Standalone View
docs/specs/spec-meta-deposit.rst
| .. _spec-metadata-deposit: | .. _spec-metadata-deposit: | ||||
| The metadata-only deposit | The metadata-only deposit | ||||
| ^^^^^^^^^^^^^^^^^^^^^^^^^ | ========================= | ||||
| Goal | Goal | ||||
| ==== | ---- | ||||
| A client may wish to deposit only metadata about an origin or object already | A client may wish to deposit only metadata about an origin or object already | ||||
| present in the Software Heritage archive. | present in the Software Heritage archive. | ||||
| The metadata-only deposit is a special deposit where no content is | The metadata-only deposit is a special deposit where no content is | ||||
| provided and the data transferred to Software Heritage is only | provided and the data transferred to Software Heritage is only | ||||
| the metadata about an object in the archive. | the metadata about an object in the archive. | ||||
| Requirements | Requirements | ||||
| ============ | ------------ | ||||
| 1. Create a metadata-only deposit through a :ref:`POST request<API-create-deposit>` | 1. Create a metadata-only deposit through a :ref:`POST request<API-create-deposit>` | ||||
| 2. It is composed of ONLY one Atom XML document | 2. It is composed of ONLY one Atom XML document | ||||
| 3. It MUST comply with :ref:`the metadata requirements<metadata-requirements>` | 3. It MUST comply with :ref:`the metadata requirements<metadata-requirements>` | ||||
| 4. It MUST reference an **object** or an **origin** in a deposit tag | 4. It MUST reference an **object** or an **origin** in a deposit tag | ||||
| 5. The reference SHOULD exist in the SWH archive | 5. The reference SHOULD exist in the SWH archive | ||||
| 6. The **object** reference MUST be a SWHID on one of the following artifact types: | 6. The **object** reference MUST be a SWHID on one of the following artifact types: | ||||
| - origin | - origin | ||||
| - snapshot | - snapshot | ||||
| - release | - release | ||||
| - revision | - revision | ||||
| - directory | - directory | ||||
| - content | - content | ||||
| 7. The SWHID MAY be a `core identifier`_ with or without `qualifiers`_ | 7. The SWHID MAY be a `core identifier`_ with or without `qualifiers`_ | ||||
| 8. The SWHID MUST NOT reference a fragment of code with the classifier `lines` | 8. The SWHID MUST NOT reference a fragment of code with the classifier `lines` | ||||
| .. _core identifier: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#core-identifiers | .. _core identifier: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#core-identifiers | ||||
| .. _qualifiers: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#qualifiers | .. _qualifiers: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html#qualifiers | ||||
| A complete metadata example | A complete metadata example | ||||
| =========================== | --------------------------- | ||||
| The reference element is included in the metadata xml atomEntry under the | The reference element is included in the metadata xml atomEntry under the | ||||
| swh namespace: | swh namespace: | ||||
| .. code:: xml | .. code:: xml | ||||
| <?xml version="1.0"?> | <?xml version="1.0"?> | ||||
| <entry xmlns="http://www.w3.org/2005/Atom" | <entry xmlns="http://www.w3.org/2005/Atom" | ||||
| xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0" | xmlns:codemeta="https://doi.org/10.5063/SCHEMA/CODEMETA-2.0" | ||||
| Show All 20 Lines | <entry xmlns="http://www.w3.org/2005/Atom" | ||||
| <swh:deposit> | <swh:deposit> | ||||
| <swh:reference> | <swh:reference> | ||||
| <swh:origin url='https://github.com/user/repo'/> | <swh:origin url='https://github.com/user/repo'/> | ||||
| </swh:reference> | </swh:reference> | ||||
| </swh:deposit> | </swh:deposit> | ||||
| </entry> | </entry> | ||||
| References | References | ||||
| ========== | ---------- | ||||
| The metadata reference can be either on: | The metadata reference can be either on: | ||||
| - an origin | - an origin | ||||
| - a graph object (core SWHID with or without qualifiers) | - a graph object (core SWHID with or without qualifiers) | ||||
| Origins | Origins | ||||
| ------- | ^^^^^^^ | ||||
| The metadata may be on an origin, identified by the origin's URL: | The metadata may be on an origin, identified by the origin's URL: | ||||
| .. code:: xml | .. code:: xml | ||||
| <swh:deposit> | <swh:deposit> | ||||
| <swh:reference> | <swh:reference> | ||||
| <swh:origin url="https://github.com/user/repo" /> | <swh:origin url="https://github.com/user/repo" /> | ||||
| </swh:reference> | </swh:reference> | ||||
| </swh:deposit> | </swh:deposit> | ||||
| Graph objects | Graph objects | ||||
| ------------- | ^^^^^^^^^^^^^ | ||||
| It may also reference an object in the `SWH graph <data-model>`: contents, | It may also reference an object in the `SWH graph <data-model>`: contents, | ||||
| directories, revisions, releases, and snapshots: | directories, revisions, releases, and snapshots: | ||||
| .. code:: xml | .. code:: xml | ||||
| <swh:deposit> | <swh:deposit> | ||||
| <swh:reference> | <swh:reference> | ||||
| Show All 20 Lines | |||||
| and they should be provided whenever relevant, especially ``origin``. | and they should be provided whenever relevant, especially ``origin``. | ||||
| Other qualifiers are not allowed (for example, ``line`` isn't because SWH | Other qualifiers are not allowed (for example, ``line`` isn't because SWH | ||||
| cannot store metadata at a finer level than entire contents). | cannot store metadata at a finer level than entire contents). | ||||
| Loading procedure | Loading procedure | ||||
| ================= | ----------------- | ||||
| In this case, the metadata-deposit will be injected as a metadata entry of | In this case, the metadata-deposit will be injected as a metadata entry of | ||||
| the relevant object, with the information about the contributor of the deposit. | the relevant object, with the information about the contributor of the deposit. | ||||