Merge pull request #108 from EGA-archive/docs

adding the doc about the error messages
EGA-archive · Jun 14, 2020 · e4eaadc · e4eaadc
2 parents da08361 + 64f035d
commit e4eaadc
Show file tree

Hide file tree

Showing 3 changed files with 149 additions and 0 deletions.
diff --git a/docs/amqp.rst b/docs/amqp.rst
@@ -170,6 +170,19 @@ preferred. For example, a request for an Accession ID could be:
 
 .. note:: When requesting an Accession ID, the md5 decrypted_checksums field is, for the moment, mandatory.
 
+When an error occurs on the Local EGA side, but the error is
+user-related, such as an invalid encryption format, or a missing file
+in the inbox (after deletion, for example), the error message must
+contain a field named ``reason``, explaining why the error occured. For example:
+
+.. code::
+
+		{
+                                 "user": "john",
+                             "filepath": "/inbox/user/dir1/file.txt.c4gh",
+                               "reason": "File not found in inbox"
+		}
+
 The messages sent by the inbox hooks capture operation of the files,
 be it a (re)upload, a rename or a removal.  They must contain the
 fields: ``user``, ``filepath``, ``operation``, where the value is

diff --git a/ingestion/schemas/ingestion-accession.json b/ingestion/schemas/ingestion-accession.json
@@ -130,6 +130,11 @@
                 [ { "type": "sha256", "value": "82E4e60e7beb3db2e06A00a079788F7d71f75b61a4b75f28c4c942703dabb6d6" },
                   { "type": "md5"   , "value": "7Ac236b1a8dce2dac89e7cf45d2b48BD" }]
             ],
+	    "contains": {
+                "type": "object",
+                "properties": { "type": { "const": "md5" } },
+                "required": ["type"],
+            },
             "additionalItems": false,
             "items": {
 		"anyOf": [ { "$ref": "#/definitions/checksum-sha256" },

diff --git a/ingestion/schemas/ingestion-user-error.json b/ingestion/schemas/ingestion-user-error.json
@@ -0,0 +1,131 @@
+{
+    "title": "JSON schema for Local EGA message interface to Central EGA",
+    "$id": "https://github.com/EGA-archive/LocalEGA/tree/master/schemas/ingestion-user-error.json",
+    "$schema": "http://json-schema.org/draft-07/schema",
+    "type": "object",
+    "required": [
+        "user",
+        "filepath",
+        "reason"
+    ],
+    "additionalProperties": true,
+    "definitions": {
+	"checksum-sha256": {
+            "$id": "#/definitions/checksum-sha256",
+            "type": "object",
+            "title": "The sha256 checksum schema",
+            "description": "A representation of a sha256 checksum value",
+            "examples": [
+                {
+                    "type": "sha256",
+                    "value": "82e4e60e7beb3db2e06a00a079788f7d71f75b61a4b75f28c4c942703dabb6d6"
+                }
+            ],
+            "required": [
+                "type",
+                "value"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "type": {
+                    "$id": "#/definitions/checksum-sha256/properties/type",
+                    "type": "string",
+                    "const": "sha256",
+                    "title": "The checksum type schema",
+                    "description": "We use sha256"
+                },
+                "value": {
+                    "$id": "#/definitions/checksum-sha256/properties/value",
+                    "type": "string",
+                    "title": "The checksum value in hex format",
+                    "description": "The checksum value in (case-insensitive) hex format",
+		    "pattern": "^[a-fA-F0-9]{64}$",
+                    "examples": [
+                        "82E4e60e7beb3db2e06A00a079788F7d71f75b61a4b75f28c4c942703dabb6d6"
+                    ]
+                }
+            }
+	},
+	"checksum-md5": {
+            "$id": "#/definitions/checksum-md5",
+            "type": "object",
+            "title": "The md5 checksum schema",
+            "description": "A representation of a md5 checksum value",
+            "examples": [
+                {
+                    "type": "md5",
+                    "value": "7Ac236b1a8dce2dac89e7cf45d2b48BD"
+                }
+            ],
+            "required": [
+                "type",
+                "value"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "type": {
+                    "$id": "#/definitions/checksum-md5/properties/type",
+                    "type": "string",
+                    "const": "md5",
+                    "title": "The checksum type schema",
+                    "description": "We use md5"
+                },
+                "value": {
+                    "$id": "#/definitions/checksum-md5/properties/value",
+                    "type": "string",
+                    "title": "The checksum value in hex format",
+                    "description": "The checksum value in (case-insensitive) hex format",
+		    "pattern": "^[a-fA-F0-9]{32}$",
+                    "examples": [
+                        "7Ac236b1a8dce2dac89e7cf45d2b48BD"
+                    ]
+                }
+            }
+	}
+    },
+    "properties": {
+	"user": {
+            "$id": "#/properties/user",
+            "type": "string",
+            "title": "The username",
+            "description": "The username",
+            "examples": [
+                "user.name@central-ega.eu"
+            ]
+        },
+        "filepath": {
+            "$id": "#/properties/filepath",
+            "type": "string",
+            "title": "The new filepath",
+            "description": "The new filepath",
+            "examples": [
+                "/ega/inbox/user.name@central-ega.eu/the-file.c4gh"
+            ]
+        },
+        "reason": {
+            "$id": "#/properties/reason",
+            "type": "string",
+            "title": "A user-related error",
+            "description": "The reason why the error occured",
+            "examples": [
+                "File not found in the inbox",
+                "Invalid file decryption"
+            ]
+        },
+        "encrypted_checksums": {
+            "$id": "#/properties/encrypted_checksums",
+            "type": "array",
+            "title": "The checksums of the original file",
+            "description": "The checksums of the original file. The md5 one is required",
+            "examples": [
+                [ { "type": "sha256", "value": "82E4e60e7beb3db2e06A00a079788F7d71f75b61a4b75f28c4c942703dabb6d6" },
+                  { "type": "md5"   , "value": "7Ac236b1a8dce2dac89e7cf45d2b48BD" }]
+            ],
+            "additionalItems": false,
+            "items": {
+		"anyOf": [ { "$ref": "#/definitions/checksum-sha256" },
+			   { "$ref": "#/definitions/checksum-md5" } ]
+	    }
+        }
+    }
+}