1. JSON instead of XML

No more AtomPub. Was:

<?xml version="1.0" ?>
<service xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:sword="http://purl.org/net/sword/terms/"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://www.w3.org/2007/app">

    <sword:version>2.0</sword:version>
    <sword:maxUploadSize>16777216</sword:maxUploadSize>

    <workspace>
        <atom:title>Main Site</atom:title>

        <collection href="http://swordapp.org/col-iri/43">
            <atom:title>Collection 43</atom:title>
            <accept>*/*</accept>
            <accept alternate="multipart-related">*/*</accept>
            <sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
            <dcterms:abstract>Collection Description</dcterms:abstract>
            <sword:mediation>false</sword:mediation>
            <sword:treatment>Treatment description</sword:treatment>
            <sword:acceptPackaging>http://purl.org/net/sword/package/SimpleZip</sword:acceptPackaging>
            <sword:acceptPackaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:acceptPackaging>
            <sword:service>http://swordapp.org/sd-iri/e4</sword:service>
        </collection>
    </workspace>
</service>

Now

{
  "@context" : "https://swordapp.github.io/swordv3/swordv3.jsonld",

  "@id" : "http://example.com/service-document",
  "@type" : "ServiceDocument",

  "dc:title" : "Site Name",
  "dcterms:abstract" : "Site Description",

  "root" : "http://example.com/service-document",
  "acceptDeposits": true,

  "version": "http://purl.org/net/sword/3.0",
  "maxUploadSize" : 16777216000,
  "maxByReferenceSize" : 30000000000000000,
  "maxSegmentSize" : 16777216000,
  "minSegmentSize" : 1,
  "maxAssembledSize" : 30000000000000,
  "maxSegments" : 1000,

  "accept" : ["*/*"],
  "acceptArchiveFormat" : ["application/zip"],
  "acceptPackaging" : ["*"],
  "acceptMetadata" : ["http://purl.org/net/sword/3.0/types/Metadata"],

  "collectionPolicy" : {
    "@id" : "http://www.myorg.ac.uk/collectionpolicy",
    "description" : "...."
  },
  "treatment" : {
    "@id" : "http://www.myorg.ac.uk/treatment",
    "description" : "..."
  },

  "staging" : "http://example.com/staging",
  "stagingMaxIdle" : 3600,

  "byReferenceDeposit" : true,
  "onBehalfOf" : true,

  "digest" : ["SHA-256", "SHA", "MD5"],
  "authentication": ["Basic", "OAuth", "Digest", "APIKey"],

  "services" : [
    {
      "@id": "http://swordapp.org/deposit/43",

      "dc:title" : "Deposit Service Name",
      "dcterms:abstract" : "Deposit Service Description",

      "root" : "http://example.com/service-document",
      "parent" : "http://example.com/service-document",
      "acceptDeposits": true,

      "services" : []
    }
  ]
}

2. Some Terminology Changes

Collection - now referred to as a Service
Content - now referred to as the FileSet
Deposit Receipt - merged with the Statement and has become the Status Document
Statement - see above
Container - now referred to as an Object
Mediated Deposit - now referred to as On-Behalf-Of Deposit for consistency

3. Merged Deposit Receipt and Statement

Originally there were two documents:

Deposit Receipt - provided in response to any deposit operation, contained information about the operation and the item
Statement - provided detailed information about files and workflow state

These are now merged into a single Status Document

SWORDv2: Deposit Receipt

<entry xmlns="http://www.w3.org/2005/Atom"
        xmlns:sword="http://purl.org/net/sword/"
        xmlns:dcterms="http://purl.org/dc/terms/">

    <title>My Deposit</title>
    <id>info:something:1</id>
    <updated>2008-08-18T14:27:08Z</updated>
    <summary type="text">A summary</summary>
    <generator uri="http://www.myrepository.ac.uk/sword-plugin" version="1.0"/>

    <!-- the item's metadata -->
    <dcterms:abstract>The abstract</dcterms:abstract>
    <dcterms:accessRights>Access Rights</dcterms:accessRights>
    <dcterms:alternative>Alternative Title</dcterms:alternative>
    <dcterms:available>Date Available</dcterms:available>
    <dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
    <dcterms:contributor>Contributor</dcterms:contributor>
    <dcterms:description>Description</dcterms:description>
    <dcterms:hasPart>Has Part</dcterms:hasPart>
    <dcterms:hasVersion>Has Version</dcterms:hasVersion>
    <dcterms:identifier>Identifier</dcterms:identifier>
    <dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
    <dcterms:publisher>Publisher</dcterms:publisher>
    <dcterms:references>References</dcterms:references>
    <dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
    <dcterms:source>Source</dcterms:source>
    <dcterms:title>Title</dcterms:title>
    <dcterms:type>Type</dcterms:type>

    <sword:verboseDescription>Verbose description</sword:verboseDescription>
    <sword:treatment>Unpacked. JPEG contents converted to JPEG2000.</sword:treatment>

    <link rel="alternate" href="http://www.swordserver.ac.uk/col1/mydeposit.html"/>
    <content type="application/zip" src="http://www.swordserver.ac.uk/col1/mydeposit"/>
    <link rel="edit-media" href="http://www.swordserver.ac.uk/col1/mydeposit"/>
    <link rel="edit" href="http://www.swordserver.ac.uk/col1/mydeposit.atom" />
    <link rel="http://purl.org/net/sword/terms/add" href="http://www.swordserver.ac.uk/col1/mydeposit.atom" />
    <sword:packaging>http://purl.org/net/sword/package/BagIt</sword:packaging>

    <link rel="http://purl.org/net/sword/terms/originalDeposit"
            type="application/zip"
            href="http://www.swordserver.ac.uk/col1/mydeposit/package.zip"/>
    <link rel="http://purl.org/net/sword/terms/derivedResource"
            type="application/pdf"
            href="http://www.swordserver.ac.uk/col1/mydeposit/file1.pdf"/>
    <link rel="http://purl.org/net/sword/terms/derivedResource"
            type="application/pdf"
            href="http://www.swordserver.ac.uk/col1/mydeposit/file2.pdf"/>

    <link rel="http://purl.org/net/sword/terms/statement"
            type="application/atom+xml;type=feed"
            href="http://www.swordserver.ac.uk/col1/mydeposit.feed"/>
    <link rel="http://purl.org/net/sword/terms/statement"
            type="application/rdf+xml"
            href="http://www.swordserver.ac.uk/col1/mydeposit.rdf"/>

</entry>

SWORDv2: Statement

<atom:feed xmlns:sword="http://purl.org/net/sword/terms/"
            xmlns:atom="http://www.w3.org/2005/Atom">

    <atom:category scheme="http://purl.org/net/sword/terms/state"
        term="[state identifier]"
        label="State">
            The work has passed through review and is now in the archive
    </atom:category>

    <atom:entry>
        <atom:category scheme="http://purl.org/net/sword/terms/"
            term="http://purl.org/net/sword/terms/originalDeposit"
            label="Orignal Deposit"/>
        <atom:content type="application/zip"
                    src="http://localhost:8080/part-IRI/43/my_deposit/example.zip"/>
        <sword:packaging>http://purl.org/net/sword/package/SimpleZip</sword:packaging>
        <sword:depositedOn>2011-03-02T20:50:06Z</sword:depositedOn>
        <sword:depositedBy>sword</sword:depositedBy>
        <sword:depositedOnBehalfOf>jbloggs</sword:depositedOnBehalfOf>
    </atom:entry>

</atom:feed>

SWORDv3: Status Document

{
  "@context" : "https://swordapp.github.io/swordv3/swordv3.jsonld",

  "@id" : "http://www.myorg.ac.uk/sword3/object/1",
  "@type" : "Status",
  "eTag" : "...",

  "metadata" : {
    "@id" : "http://www.myorg.ac.uk/sword3/object/1/metadata",
    "eTag" : "..."
  },
  "fileSet" : {
    "@id" : "http://www.myorg.ac.uk/sword3/object/1fileset",
    "eTag" : "..."
  },

  "service" : "http://www.myorg.ac.uk/sword3",

  "state" : [
    {
      "@id" : "http://purl.org/net/sword/3.0/state/inProgress",
      "description" : "the item is currently inProgress"
    }
  ],

  "actions" : {
    "getMetadata" : true,
    "getFiles" : true,
    "appendMetadata" : true,
    "appendFiles" : true,
    "replaceMetadata" : true,
    "replaceFiles" : true,
    "deleteMetadata" : true,
    "deleteFiles" : true,
    "deleteObject" : true
  },

  "links" : [
    {
      "@id" : "http://www.myorg.ac.uk/col1/mydeposit.html",
      "rel" : ["alternate"],
      "contentType" : "text/html"
    },
    {
      "@id" : "http://www.myorg.ac.uk/sword3/object/1/package.zip",
      "rel" : ["http://purl.org/net/sword/3.0/terms/originalDeposit"],
      "contentType" : "application/zip",
      "packaging" : "http://purl.org/net/sword/3.0/package/SimpleZip",
      "depositedOn" : "[timestamp]",
      "depositedBy" : "[user identifier]",
      "depositedOnBehalfOf" : "[user identifier]",
      "byReference" : "http://www.otherorg.ac.uk/by-reference/file.zip",
      "status" : "http://purl.org/net/sword/3.0/filestate/ingested",
      "log" : "[any information associated with the deposit that the client should know]"
    },
    {
      "@id" : "http://www.myorg.ac.uk/sword3/object/1/file1.pdf",
      "rel" : [
        "http://purl.org/net/sword/3.0/terms/fileSetFile",
        "http://purl.org/net/sword/3.0/terms/derivedResource"
      ],
      "contentType" : "application/pdf",
      "derivedFrom" : "http://www.myorg.ac.uk/sword3/object1/package.zip",
      "dcterms:relation" : "http://www.myorg.ac.uk/repo/123456789/file1.pdf",
      "dcterms:replaces" : "http://www.myorg.ac.uk/sword3/object/1/versions/file1.1.pdf",
      "eTag" : "..."
    },
    {
      "@id" : "http://www.myorg.ac.uk/sword3/object/1/package.1.zip",
      "rel" : ["http://purl.org/net/sword/terms/packagedContent"],
      "contentType" : "application/zip",
      "packaging" : "http://purl.org/net/sword/3.0/package/SimpleZip"
    },
    {
      "@id" : "http://www.swordserver.ac.uk/col1/mydeposit/metadata.mods.xml",
      "rel" : ["http://purl.org/net/sword/3.0/terms/formattedMetadata"],
      "contentType" : "application/xml",
      "metadataFormat" : "http://www.loc.gov/mods/v3"
    },
    {
      "@id" : "http://www.myorg.ac.uk/sword3/object/1/versions/file1.1.pdf",
      "rel" : ["http://purl.org/net/sword/3.0/terms/derivedResource"],
      "contentType" : "application/pdf",
      "dcterms:isReplacedBy" : "http://www.myorg.ac.uk/sword3/object1/file1.pdf",
      "versionReplacedOn" : "[xsd:dateTime]"
    },
    {
      "@id" : "http://www.myorg.ac.uk/sword3/object/1/reference.zip",
      "rel" : [
        "http://purl.org/net/sword/3.0/terms/byReferenceDeposit",
        "http://purl.org/net/sword/3.0/terms/originalDeposit",
        "http://purl.org/net/sword/3.0/terms/fileSetFile"
      ],
      "byReference" : "http://www.otherorg.ac.uk/by-reference/file2.zip",
      "log" : "Any information on the download, especially if it failed",
      "eTag" : "...",
      "status" : "http://purl.org/net/sword/3.0/filestate/ingested"
    }
  ]
}

3.1. Key Differences

Metadata is now not included explicitly - instead it is available as a File to be downloaded
links provide equivalent capabilities as the Statement
The Status Document now allows you to link back to the Service through which the Object was deposited

4. Merged Concepts of Service Document and Collection

In SWORDv2 there was one Service Document, and that listed multiple (optionally nested) Collections.

In SWORDv3 there are only Services, which are represented by Service Documents. Services may or may not accept deposits, and may or may not contain nested Services.

SWORDv2: Service Document

<?xml version="1.0" ?>
<service xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:sword="http://purl.org/net/sword/terms/"
    xmlns:atom="http://www.w3.org/2005/Atom"
    xmlns="http://www.w3.org/2007/app">

    <sword:version>2.0</sword:version>
    <sword:maxUploadSize>16777216</sword:maxUploadSize>

    <workspace>
        <atom:title>Main Site</atom:title>

        <collection href="http://swordapp.org/col-iri/43">
            <atom:title>Collection 43</atom:title>
            <accept>*/*</accept>
            <accept alternate="multipart-related">*/*</accept>
            <sword:collectionPolicy>Collection Policy</sword:collectionPolicy>
            <dcterms:abstract>Collection Description</dcterms:abstract>
            <sword:mediation>false</sword:mediation>
            <sword:treatment>Treatment description</sword:treatment>
            <sword:acceptPackaging>http://purl.org/net/sword/package/SimpleZip</sword:acceptPackaging>
            <sword:acceptPackaging>http://purl.org/net/sword/package/METSDSpaceSIP</sword:acceptPackaging>
            <sword:service>http://swordapp.org/sd-iri/e4</sword:service>
        </collection>
    </workspace>
</service>

SWORDv3: Service Document

{
  "@context" : "https://swordapp.github.io/swordv3/swordv3.jsonld",

  "@id" : "http://example.com/service-document",
  "@type" : "ServiceDocument",

  "dc:title" : "Site Name",
  "dcterms:abstract" : "Site Description",

  "root" : "http://example.com/service-document",
  "acceptDeposits": true,

  "version": "http://purl.org/net/sword/3.0",
  "maxUploadSize" : 16777216000,
  "maxByReferenceSize" : 30000000000000000,
  "maxSegmentSize" : 16777216000,
  "minSegmentSize" : 1,
  "maxAssembledSize" : 30000000000000,
  "maxSegments" : 1000,

  "accept" : ["*/*"],
  "acceptArchiveFormat" : ["application/zip"],
  "acceptPackaging" : ["*"],
  "acceptMetadata" : ["http://purl.org/net/sword/3.0/types/Metadata"],

  "collectionPolicy" : {
    "@id" : "http://www.myorg.ac.uk/collectionpolicy",
    "description" : "...."
  },
  "treatment" : {
    "@id" : "http://www.myorg.ac.uk/treatment",
    "description" : "..."
  },

  "staging" : "http://example.com/staging",
  "stagingMaxIdle" : 3600,

  "byReferenceDeposit" : true,
  "onBehalfOf" : true,

  "digest" : ["SHA-256", "SHA", "MD5"],
  "authentication": ["Basic", "OAuth", "Digest", "APIKey"],

  "services" : [
    {
      "@id": "http://swordapp.org/deposit/43",

      "dc:title" : "Deposit Service Name",
      "dcterms:abstract" : "Deposit Service Description",

      "root" : "http://example.com/service-document",
      "parent" : "http://example.com/service-document",
      "acceptDeposits": true,

      "services" : []
    }
  ]
}

5. Support for Arbitrary Metadata

SWORDv2 provided implicit support for arbitrary metadata formats, with no standard way to indicate to the server what you were sending it.

SWORD v3 provides explicit support for arbitrary metadata formats, via the Metadata-Format header.

SWORDv2: Create a resource with metadata only

POST Col-IRI HTTP/1.1
Host: example.org
Authorization: Basic ZGFmZnk6c2VjZXJldA==
Content-Length: [content length]
Content-Type: application/atom+xml;type=entry
In-Progress: true
On-Behalf-Of: jbloggs
Slug: [suggested identifier]

<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom"
        xmlns:dcterms="http://purl.org/dc/terms/">
    <title>Title</title>
    <id>urn:uuid:1225c695-cfb8-4ebb-aaaa-80da344efa6a</id>
    <updated>2005-10-07T17:17:08Z</updated>
    <author><name>Contributor</name></author>
    <summary type="text">The abstract</summary>

    <!-- some embedded metadata -->
    <dcterms:abstract>The abstract</dcterms:abstract>
    <dcterms:accessRights>Access Rights</dcterms:accessRights>
    <dcterms:alternative>Alternative Title</dcterms:alternative>
    <dcterms:available>Date Available</dcterms:available>
    <dcterms:bibliographicCitation>Bibliographic Citation</dcterms:bibliographicCitation>
    <dcterms:contributor>Contributor</dcterms:contributor>
    <dcterms:description>Description</dcterms:description>
    <dcterms:hasPart>Has Part</dcterms:hasPart>
    <dcterms:hasVersion>Has Version</dcterms:hasVersion>
    <dcterms:identifier>Identifier</dcterms:identifier>
    <dcterms:isPartOf>Is Part Of</dcterms:isPartOf>
    <dcterms:publisher>Publisher</dcterms:publisher>
    <dcterms:references>References</dcterms:references>
    <dcterms:rightsHolder>Rights Holder</dcterms:rightsHolder>
    <dcterms:source>Source</dcterms:source>
    <dcterms:title>Title</dcterms:title>
    <dcterms:type>Type</dcterms:type>

</entry>

SWORDv3: Create a resource with metadata-only

(using a metadata format that is not the default)

POST Service-URL
Content-Type: application/xml
Content-Disposition: attachment; metadata=true
Digest: SHA-256=74b2851bd2760785b0987ba219debea69c228353f7ccc67a2bdcd9819f97fc71
Metadata-Format: http://www.loc.gov/mods/v3

<mods xmlns:mods="http://www.loc.gov/mods/v3">
  <originInfo>
    <place>
      <placeTerm type="code" authority="marccountry">nyu</placeTerm>
      <placeTerm type="text">Ithaca, NY</placeTerm>
    </place>
    <publisher>Cornell University Press</publisher>
    <copyrightDate>1999</copyrightDate>
  </originInfo>
</mods>

6. Concurrency Control

SWORDv2 did not have the concept of concurrency control.

SWORDv3 provides Optimistic Concurrency Control via the use of ETag and If-Match headers.

7. Segmented File Upload

SWORDv2 dealt only in full by-value deposits of files, which could be problematic if the files are very large.

In SWORDv3, to transfer a large file, the client can break it down into a number of equally sized segments of binary data (the final segment may be a different size to the rest). It can then initialise a Segmented File Upload with the server, and then transfer the segments. The server will reconstitute these segments into a single file, and then the client may deposit this file by-reference.

8. By-Reference Deposit

SWORDv2 did not have any formal mechanism for depositing files by-reference (although some workarounds existed)

SWORDv3 provides explicit support for By-Reference deposit, where the client provides the server with URLs for Files which it would like the server to retrieve asynchronously.

9. More Advanced Packaging

There has been a lot of pressure on the SWORD team to provide more detail about actual packaging formats. We have resisted for a long time, but for SWORDv3 we have introduced a BagIt profile which is slightly more advanced than the package formats required by SWORDv2

SwordBagIt
| -- bag-info.txt
| -- bagit.txt
| -- data
| -- | -- bitstreams ...
|    \ -- directories ...
|         \ bitstreams ...
| -- manifest-sha-256.txt
| -- metadata
|     \-- sword.json
\ -- tagmanifest-sha-256.txt

This allows us to represent the item as a combination of an arbitrary structure of bitstreams in the data directory (similar to SimpleZip), and the metadata in the sword default format in metadata/sword.json. A manifest (and tagmanifest) of sha-256 checksums is required, as well as the bagit.txt file and a bag-info.txt file.

10. Multipart Deposit has gone

SWORDv2 allowed for metadata and files to be depoisted in a multipart/related request.

This has been removed from SWORDv3 for the following reasons:

The new SwordBagIt packaging format makes this possible now
multipart/related was poorly supported by server-side web frameworks, and thus hard to implement
This came from an Atom extension, and we are no longer using Atom

11. Other Differences

Explicit support for redirect HTTP codes
More granular errors
JSON-LD contexts for all JSON documents, for better Linked Data support
More URIs for expressing status and relationships
Content Negotiation is gone

Differences between SWORDv3 and SWORDv2