refactor some definitions into a separate file and add schemas for API endpoints

11 files changed, 370 insertions, 168 deletions

diff --git a/api_mapping_description-1.schema.json b/api_mapping_description-1.schema.json
new file mode 100644
index 0000000..5bac876
--- /dev/null
+++ b/api_mapping_description-1.schema.json
@@ -0,0 +1,11 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://hydrilla.koszko.org/api_mapping_description-1.schema.json",
+    "title": "Mapping description",
+    "description": "Definition of a Hydrilla mapping, as served through HTTP API",
+    "allOf": [{
+	"$ref": "./common_definitions-1.schema.json#/definitions/mapping_definition_base"
+    }, {
+	"$ref": "./common_definitions-1.schema.json#/definitions/item_definition"
+    }]
+}
diff --git a/api_mapping_description-1.schema.json.license b/api_mapping_description-1.schema.json.license
new file mode 100644
index 0000000..f41d511
--- /dev/null
+++ b/api_mapping_description-1.schema.json.license
@@ -0,0 +1,5 @@
+SPDX-License-Identifier: CC0-1.0
+
+Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
+
+Available under the terms of Creative Commons Zero v1.0 Universal.
diff --git a/api_query_result-1.schema.json b/api_query_result-1.schema.json
new file mode 100644
index 0000000..a8dd30a
--- /dev/null
+++ b/api_query_result-1.schema.json
@@ -0,0 +1,23 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://hydrilla.koszko.org/api_query_result-1.schema.json",
+    "title": "Query result",
+    "description": "Object with a list of references to mappings that contain payloads for requested URL",
+    "type": "object",
+    "required": [
+	"api_schema_version",
+	"mappings"
+    ],
+    "properties": {
+	"api_schema_version": {
+	    "$ref": "./common_definitions-1.schema.json#/definitions/schema_version"
+	},
+	"mappings": {
+	    "description": "References to mappings using at least one pattern that matches the requested URL",
+	    "type": "array",
+	    "items": {
+		"$ref": "./common_definitions-1.schema.json#/definitions/item_ref"
+	    }
+	}
+    }
+}
diff --git a/api_query_result-1.schema.json.license b/api_query_result-1.schema.json.license
new file mode 100644
index 0000000..f41d511
--- /dev/null
+++ b/api_query_result-1.schema.json.license
@@ -0,0 +1,5 @@
+SPDX-License-Identifier: CC0-1.0
+
+Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
+
+Available under the terms of Creative Commons Zero v1.0 Universal.
diff --git a/api_resource_description-1.schema.json b/api_resource_description-1.schema.json
new file mode 100644
index 0000000..fc653f5
--- /dev/null
+++ b/api_resource_description-1.schema.json
@@ -0,0 +1,20 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://hydrilla.koszko.org/api_resource_description-1.schema.json",
+    "title": "Resource description",
+    "description": "Definition of a Hydrilla resource, as served through HTTP API",
+    "allOf": [{
+	"$ref": "./common_definitions-1.schema.json#/definitions/resource_definition_base"
+    }, {
+	"$ref": "./common_definitions-1.schema.json#/definitions/item_definition"
+    }, {
+	"type": "object",
+	"properties": {
+	    "scripts": {
+		"description": "Which files are resource's scripts and need to be installed",
+		"$ref": "./common_definitions-1.schema.json#/definitions/file_ref_list_sha256",
+		"default": []
+	    }
+	}
+    }]
+}
diff --git a/api_resource_description-1.schema.json.license b/api_resource_description-1.schema.json.license
new file mode 100644
index 0000000..f41d511
--- /dev/null
+++ b/api_resource_description-1.schema.json.license
@@ -0,0 +1,5 @@
+SPDX-License-Identifier: CC0-1.0
+
+Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
+
+Available under the terms of Creative Commons Zero v1.0 Universal.
diff --git a/api_source_description-1.schema.json b/api_source_description-1.schema.json
new file mode 100644
index 0000000..bb3784f
--- /dev/null
+++ b/api_source_description-1.schema.json
@@ -0,0 +1,61 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://hydrilla.koszko.org/api_source_description-1.schema.json",
+    "title": "Source description",
+    "description": "Built description of a Hydrilla source package",
+    "type": "object",
+    "required": [
+	"api_schema_version",
+	"source_name",
+	"source_copyright",
+	"source_archives",
+	"upstream_url",
+	"definitions"
+    ],
+    "properties": {
+	"api_schema_version": {
+	    "$ref": "./common_definitions-1.schema.json#/definitions/schema_version"
+	},
+	"source_name": {
+	    "$ref": "./common_definitions-1.schema.json#/definitions/source_name"
+	},
+	"source_copyright":  {
+	    "description": "Which files indicate license terms of the source package",
+	    "$ref": "./common_definitions-1.schema.json#/definitions/file_ref_list_sha256"
+	},
+	"source_archives": {
+	    "description": "What archive extensions are available for this package's sources",
+	    "type": "object",
+	    "required": ["zip"],
+	    "additionalProperties": {
+		"description": "What is the SHA256 sum of given source archive",
+		"type": "object",
+		"required": ["sha256"],
+		"properties": {
+		    "sha256": {
+			"$ref": "./common_definitions-1.schema.json#/definitions/sha256"
+		    }
+		}
+	    },
+	    "examples": [{
+		"zip": {
+		    "sha256": "688461da362ffe2fc8e85db73e709a5356d41c8aeb7d1eee7170c64ee21dd2a2"
+		}
+	    }]
+	},
+	"upstream_url": {
+	    "description": "Where this software/work initially comes from",
+	    "type": "string"
+	},
+	"comment": {
+	    "$ref": "./common_definitions-1.schema.json#/definitions/comment"
+	},
+	"definitions": {
+	    "description": "References to site resources and pattern->payload mappings",
+	    "type": "array",
+	    "items": {
+		"$ref": "./common_definitions-1.schema.json#/definitions/typed_item_ref"
+	    }
+	}
+    }
+}
diff --git a/api_source_description-1.schema.json.license b/api_source_description-1.schema.json.license
new file mode 100644
index 0000000..f41d511
--- /dev/null
+++ b/api_source_description-1.schema.json.license
@@ -0,0 +1,5 @@
+SPDX-License-Identifier: CC0-1.0
+
+Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
+
+Available under the terms of Creative Commons Zero v1.0 Universal.
diff --git a/common_definitions-1.schema.json b/common_definitions-1.schema.json
new file mode 100644
index 0000000..0deca24
--- /dev/null
+++ b/common_definitions-1.schema.json
@@ -0,0 +1,222 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "$id": "https://hydrilla.koszko.org/common_definitions-1.schema.json",
+    "title": "Common definitions",
+    "description": "Definitions used by other Hydrilla schemas",
+    "definitions": {
+	"version": {
+	    "description": "Version expressed as an array of integers",
+	    "type": "array",
+	    "minItems": 1,
+	    "items": {
+		"type": "integer",
+		"minimum": 0
+	    },
+	    "contains": {
+		"type": "integer",
+		"minimum": 1
+	    },
+	    "minItems": 1
+	},
+	"schema_version": {
+	    "description": "Which version of appropriate schema a JSON document conforms to (major number is assumed to be 1)",
+	    "allOf": [{
+		"$ref": "#definitions/version"
+	    }, {
+		"type": "array",
+		"items": [{
+		    "const": 1
+		}]
+	    }]
+	},
+	"source_name": {
+	    "description": "Unique identifier of this source package",
+	    "type": "string",
+	    "pattern": "^[-0-9a-z.]+$"
+	},
+	"comment": {
+	    "description": "An optional comment",
+	    "type": "string"
+	},
+        "file_ref_list": {
+	    "description": "List of simple file references",
+	    "type": "array",
+	    "items": {
+		"type": "object",
+		"required": ["file"],
+		"properties": {
+		    "file": {
+			"description": "Filename relative to source package main directory; separator is '/'",
+			"type": "string",
+			"pattern": "^[^/]"
+		    }
+		}
+	    }
+        },
+	"sha256": {
+	    "description": "An SHA256 sum, in hexadecimal",
+	    "type": "string",
+	    "pattern": "^[0-9a-f]{64}$"
+	},
+        "file_ref_list_sha256": {
+	    "description": "List of file references with files' SHA256 sums included",
+	    "allOf": [{
+		"$ref": "#/definitions/file_ref_list"
+	    }, {
+		"type": "array",
+		"items": {
+		    "type": "object",
+		    "required": ["sha256"],
+		    "properties": {
+			"sha256": {
+			    "$ref": "#/definitions/sha256"
+			}
+		    }
+		}
+	    }]
+        },
+	"item_identifier": {
+	    "description": "Identifier of an item (shared with other versions of the item, otherwise unique)",
+	    "type": "string",
+	    "pattern": "^[-0-9a-z]+$"
+	},
+	"item_ref": {
+	    "description": "An object containing a subset of fields from full item definition",
+	    "type": "object",
+	    "required": ["identifier", "long_name", "version"],
+	    "properties": {
+		"identifier": {
+		    "$ref": "#/definitions/item_identifier"
+		},
+		"long_name": {
+		    "description": "User-friendly alternative to the identifier",
+		    "type": "string"
+		},
+		"version": {
+		    "$ref": "#definitions/version"
+		}
+	    }
+	},
+	"typed_item_ref": {
+	    "description": "An object containing a subset of fields from full item definition, including type",
+	    "allOf": [{
+		"$ref": "#/definitions/item_ref"
+	    }, {
+		"type": "object",
+		"required": ["type"],
+		"properties": {
+		    "type": {
+			"description": "What kind of item is it (resource or mapping)",
+			"enum": ["resource", "mapping"]
+		    }
+		}
+	    }]
+	},
+	"item_definition_base": {
+	    "description": "Definition of a resource/mapping (fields common to source definitions and built definitions)",
+	    "allOf": [{
+		"$ref": "#/definitions/typed_item_ref"
+	    }, {
+		"type": "object",
+		"required": ["uuid", "description"],
+		"properties": {
+		    "uuid": {
+			"description": "UUIDv4 of this item (shared with other versions of this item, otherwise unique)",
+			"type": "string",
+			"pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
+		    },
+		    "description": {
+			"description": "Item's description",
+			"type": "string"
+		    },
+		    "comment": {
+			"$ref": "#/definitions/comment"
+		    }
+		}
+	    }]
+	},
+	"resource_definition_base": {
+	    "description": "Definition of a resource (fields common to source definitions and built definitions)",
+	    "allOf": [{
+		"$ref": "#/definitions/item_definition_base"
+	    }, {
+		"type": "object",
+		"required": ["type", "revision"],
+		"properties": {
+		    "type": {
+			"description": "Identify this item as a resource",
+			"const": "resource"
+		    },
+		    "revision": {
+			"description": "Which revision of a packaging of given version of an upstream resource is this",
+			"type": "integer",
+			"minimum": 1
+		    },
+		    "scripts": {
+			"description": "What scripts are included in the resource",
+			"$ref": "#/definitions/file_ref_list",
+			"default": []
+		    }
+		}
+	    }]
+	},
+	"mapping_definition_base": {
+	    "description": "Definition of a mapping (fields common to source definitions and built definitions)",
+	    "allOf": [{
+		"$ref": "#/definitions/item_definition_base"
+	    }, {
+		"type": "object",
+		"required": ["type"],
+		"properties": {
+		    "type": {
+			"description": "Identify this item as a mapping",
+			"const": "mapping"
+		    },
+		    "payloads": {
+			"description": "Which payloads are to be applied to which URLs",
+			"additionalProperties": {
+			    "description": "Which payload applies to URLs matching given pattern",
+			    "type": "object",
+			    "required": ["identifier"],
+			    "properties": {
+				"identifier": {
+				    "$ref": "#/definitions/item_identifier"
+				}
+			    }
+			},
+			"default": {},
+			"examples": [{
+			    "https://hydrillabugs.koszko.org/***": {
+				"identifier": "helloapple"
+			    },
+			    "https://*.koszko.org/***": {
+				"identifier": "hello-potato"
+			    }
+			}]
+		    }
+		}
+	    }]
+	},
+	"item_definition": {
+	    "description": "Definition of a resource/mapping (fields specific to built definitions)",
+	    "type": "object",
+	    "required": [
+		"api_schema_version",
+		"source_name",
+		"source_copyright"
+	    ],
+	    "properties": {
+		"api_schema_version": {
+		    "$ref": "#/definitions/schema_version"
+		},
+		"source_name": {
+		    "$ref": "#/definitions/source_name"
+		},
+		"source_copyright": {
+		    "description": "Which files indicate license terms of the source package and should be installed",
+		    "$ref": "#/definitions/file_ref_list_sha256"
+		}
+	    }
+	}
+    }
+}
diff --git a/common_definitions-1.schema.json.license b/common_definitions-1.schema.json.license
new file mode 100644
index 0000000..f41d511
--- /dev/null
+++ b/common_definitions-1.schema.json.license
@@ -0,0 +1,5 @@
+SPDX-License-Identifier: CC0-1.0
+
+Copyright (C) 2022 Wojtek Kosior <koszko@koszko.org>
+
+Available under the terms of Creative Commons Zero v1.0 Universal.
diff --git a/package_source-1.schema.json b/package_source-1.schema.json
index 3a0ce03..392183d 100644
--- a/package_source-1.schema.json
+++ b/package_source-1.schema.json
@@ -13,106 +13,36 @@
     ],
     "properties": {
 	"source_schema_version": {
-	    "description": "Which version of Hydrilla source package schema this definition conforms to",
-	    "type": "array",
-	    "minItems": 1,
-	    "items": [{
-		"const": 1
-	    }],
-	    "additionalItems": {
-		"type": "integer",
-		"minimum": 0
-	    },
-	    "minItems": 1
+	    "$ref": "./common_definitions-1.schema.json#/definitions/schema_version"
 	},
 	"source_name": {
-	    "description": "Unique identifier of this source package",
-	    "type": "string",
-	    "pattern": "^[-0-9a-z.]+$"
+	    "$ref": "./common_definitions-1.schema.json#/definitions/source_name"
 	},
 	"copyright":  {
 	    "description": "Which files from the source package indicate its license terms and should be included in the distribution packages",
-	    "type": "array",
-	    "items": {
-		"$ref": "#/definitions/file_ref"
-	    }
+	    "$ref": "./common_definitions-1.schema.json#/definitions/file_ref_list"
 	},
 	"upstream_url": {
 	    "description": "Where this software/work initially comes from",
 	    "type": "string"
 	},
 	"comment": {
-	    "$ref": "#/definitions/comment"
+	    "$ref": "./common_definitions-1.schema.json#/definitions/comment"
 	},
 	"definitions": {
 	    "description": "Definitions of site resources and pattern->payload mappings",
 	    "type": "array",
 	    "items": {
-		"allOf": [{
-		    "description": "Item definition (fields common to both resources and mappings)",
-		    "type": "object",
-		    "required": [
-			"type",
-			"identifier",
-			"long_name",
-			"uuid",
-			"version",
-			"description"
-		    ],
-		    "properties": {
-			"type": {
-			    "description": "What kind of item is being defined (resource or mapping)",
-			    "enum": ["resource", "mapping"]
-			},
-			"identifier": {
-			    "$ref": "#/definitions/item_identifier"
-			},
-			"long_name": {
-			    "description": "User-friendly alternative to an identifier",
-			    "type": "string"
-			},
-			"uuid": {
-			    "description": "UUIDv4 of this item (shared with other versions of this item, otherwise unique)",
-			    "type": "string",
-			    "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$"
-			},
-			"version": {
-			    "description": "Item's version number",
-			    "type": "array",
-			    "minItems": 1,
-			    "items": {
-				"type": "integer",
-				"minimum": 0
-			    },
-			    "contains": {
-				"type": "integer",
-				"minimum": 1
-			    },
-			    "minItems": 1
-			},
-			"description": {
-			    "description": "Item's description",
-			    "type": "string"
-			},
-			"comment": {
-			    "$ref": "#/definitions/comment"
-			}
-		    }
+		"anyOf": [{
+		    "$ref": "./common_definitions-1.schema.json#/definitions/resource_definition_base"
 		}, {
-		    "anyOf": [{
-			"$ref": "#/definitions/resource_definition"
-		    }, {
-			"$ref": "#/definitions/mapping_definition"
-		    }]
+		    "$ref": "./common_definitions-1.schema.json#/definitions/mapping_definition_base"
 		}]
 	    }
 	},
 	"additional_files": {
 	    "description": "Files which should be included in the source archive produced by Hydrilla builder in addition to script and copyright files",
-	    "type": "array",
-	    "items": {
-		"$ref": "#/definitions/file_ref"
-	    },
+	    "$ref": "./common_definitions-1.schema.json#/definitions/file_ref_list",
 	    "default": []
 	},
 	"reuse_generate_spdx_report": {
@@ -120,95 +50,5 @@
 	    "type": "boolean",
 	    "default": false
 	}
-    },
-    "definitions": {
-	"comment": {
-	    "description": "An optional comment",
-	    "type": "string"
-	},
-        "file_ref": {
-	    "type": "object",
-	    "required": ["file"],
-	    "properties": {
-		"file": {
-		    "description": "Filename relative to source package main directory; separator is '/'",
-		    "type": "string",
-		    "pattern": "^[^/]"
-		}
-	    }
-        },
-	"item_identifier": {
-	    "description": "Identifier of an item (shared with other versions of the item, otherwise unique)",
-	    "type": "string",
-	    "pattern": "^[-0-9a-z]+$"
-	},
-	"resource_definition": {
-	    "description": "Resource definition (fields specific to resource)",
-	    "type": "object",
-	    "required": [
-		"type",
-		"revision"
-	    ],
-	    "properties": {
-		"type": {
-		    "description": "Identify this item as a resource",
-		    "const": "resource"
-		},
-		"revision": {
-		    "description": "Which revision of a packaging of given version of an upstream resource is this",
-		    "type": "integer",
-		    "minimum": 1
-		},
-		"scripts": {
-		    "description": "Which files from the source package are scripts to be included in the resource",
-		    "type": "array",
-		    "items":{
-			"$ref": "#/definitions/file_ref"
-		    },
-		    "default": []
-		},
-		"dependencies": {
-		    "description": "What other resources this one depends on",
-		    "type": "array",
-		    "items": {
-			"$ref": "#/definitions/item_identifier"
-		    },
-		    "default": []
-		}
-	    }
-	},
-	"mapping_definition": {
-	    "description": "Mapping definition (fields specific to mapping)",
-	    "type": "object",
-	    "required": ["type"],
-	    "properties": {
-		"type": {
-		    "description": "Identify this item as a mapping",
-		    "const": "mapping"
-		},
-		"payloads": {
-		    "description": "Which payloads are to be applied to which URLs",
-		    "additionalProperties": {
-			"description": "Which payload applies to URLs matching given pattern",
-			"type": "object",
-					    "required": ["identifier"],
-			"properties": {
-			    "identifier": {
-				"$ref": "#/definitions/item_identifier"
-			    }
-			}
-		    },
-		    "default": {},
-		    "examples": [{
-			"https://hydrillabugs.koszko.org/***": {
-			    "identifier": "helloapple"
-			},
-			"https://*.koszko.org/***": {
-			    "identifier": "hello-potato"
-			}
-		    }]
-		}
-	    }
-	}
     }
 }