Skip to content

Developer considerations

Jump to bottom
Alex Dutton edited this page Jul 14, 2020 · 7 revisions

Here are some things to consider in designing a SWORDv3-compliant implementation.

In-progress deposits

Deposits are considered complete as soon as they are updated without an In-Progress: true header.

Dereferencing and unpacking during an in-progress deposit

You should consider whether you want to defer dereferencing or unpacking any files until the deposit is marked complete.

While not necessary, it could lead to a simpler implementation that doesn't need to consider race conditions with subsequent dereferencing, unpacking or deletion actions.

Consider:

  1. A user uploads a large SimpleZip archive, containing a file README.txt
  2. A user uploads a second SimpleZip archive, also containing the file README.txt
  3. The two archives are unpacked asynchronously, with the second README.txt unpacked first
  4. Before the first archive has finished being unpacked, the user deletes the original archive file

The correct behaviour would be to record which archive provided each version of README.md and store them all, and then ignore or remove any versions from deleted archives.

The specification is built on JSON-LD

The specification encodes document semantics through JSON-LD. This has some implications:

  • You should use a JSON-LD parser when processing JSON-LD document submissions, including in SWORD metadata
  • Your JSON-LD parser will attempt to dereference the @context attribute to discover namespace prefix definitions. You should ensure that this cannot be exploited by clients to perform DoS attacks or access your internal network. You should handle parse errors caused by the referenced context being unresolvable
  • Any extensions should use a non-default namespace

Alternative metadata formats

Although the SWORD Metadata Format support is mandated, that doesn't stop you supporting other metadata formats for your client and server applications. If you do this, you should consider how multiple formats interplay when creating the canonical version of your deposited record.

As SWORD is a deposit protocol, you do not need to reconcile between metadata formats from the perspective of the SWORD client.

See #1 for the issue tracking this consideration.

Clone this wiki locally