# HG changeset patch
# User Kim Alvefur <zash@zash.se>
# Date 1689343451 -7200
# Node ID b496ebc12aed5a4848b7c994617a5f6f9823aa17
# Parent  5ade45d9390887d88214b86c1ca72ea358ef3c77
mod_http_oauth2: Add titles and descriptions to registration schema

Since it is exposed publicly, it can serve as documentation.

diff -r 5ade45d93908 -r b496ebc12aed mod_http_oauth2/mod_http_oauth2.lua
--- a/mod_http_oauth2/mod_http_oauth2.lua	Fri Jul 14 15:44:55 2023 +0200
+++ b/mod_http_oauth2/mod_http_oauth2.lua	Fri Jul 14 16:04:11 2023 +0200
@@ -1058,6 +1058,7 @@
 end
 
 local registration_schema = {
+	title = "OAuth 2.0 Dynamic Client Registration Protocol";
 	type = "object";
 	required = {
 		-- These are shown to users in the template
@@ -1067,13 +1068,21 @@
 		"redirect_uris";
 	};
 	properties = {
-		redirect_uris = { type = "array"; minItems = 1; uniqueItems = true; items = { type = "string"; format = "uri" } };
+		redirect_uris = {
+			title = "List of Redirect URIs";
+			type = "array";
+			minItems = 1;
+			uniqueItems = true;
+			items = { title = "Redirect URI"; type = "string"; format = "uri" };
+		};
 		token_endpoint_auth_method = {
+			title = "Token Endpoint Authentication Method";
 			type = "string";
 			enum = { "none"; "client_secret_post"; "client_secret_basic" };
 			default = "client_secret_basic";
 		};
 		grant_types = {
+			title = "Grant Types";
 			type = "array";
 			minItems = 1;
 			uniqueItems = true;
@@ -1092,23 +1101,82 @@
 			};
 			default = { "authorization_code" };
 		};
-		application_type = { type = "string"; enum = { "native"; "web" }; default = "web" };
+		application_type = {
+			title = "Application Type";
+			description = "Determines which kinds of redirect URIs the client may register. \z
+			The value 'web' limits the client to https:// URLs with the same hostname as in 'client_uri' \z
+			while the value 'native' allows either loopback http:// URLs or application specific URIs.";
+			type = "string";
+			enum = { "native"; "web" };
+			default = "web";
+		};
 		response_types = {
+			title = "Response Types";
 			type = "array";
 			minItems = 1;
 			uniqueItems = true;
 			items = { type = "string"; enum = { "code"; "token" } };
 			default = { "code" };
 		};
-		client_name = { type = "string" };
-		client_uri = { type = "string"; format = "uri"; pattern = "^https:" };
-		logo_uri = { type = "string"; format = "uri"; pattern = "^https:" };
-		scope = { type = "string" };
-		contacts = { type = "array"; minItems = 1; items = { type = "string"; format = "email" } };
-		tos_uri = { type = "string"; format = "uri"; pattern = "^https:" };
-		policy_uri = { type = "string"; format = "uri"; pattern = "^https:" };
-		software_id = { type = "string"; format = "uuid" };
-		software_version = { type = "string" };
+		client_name = {
+			title = "Client Name";
+			description = "Human-readable name of the client, presented to the user in the consent dialog.";
+			type = "string";
+		};
+		client_uri = {
+			title = "Client URL";
+			description = "Should be an link to a page with information about the client.";
+			type = "string";
+			format = "uri";
+			pattern = "^https:";
+		};
+		logo_uri = {
+			title = "Logo URL";
+			description = "URL to the clients logotype (not currently used).";
+			type = "string";
+			format = "uri";
+			pattern = "^https:";
+		};
+		scope = {
+			title = "Scopes";
+			description = "Space-separated list of scopes the client promises to restrict itself to.";
+			type = "string";
+		};
+		contacts = {
+			title = "Contact Addresses";
+			description = "Addresses, typically email or URLs where the client developers can be contacted.";
+			type = "array";
+			minItems = 1;
+			items = { type = "string"; format = "email" };
+		};
+		tos_uri = {
+			title = "Terms of Service URL";
+			description = "Link to Terms of Service for the client, presented to the user in the consent dialog. \z
+			MUST be a https:// URL with hostname matching that of 'client_uri'.";
+			type = "string";
+			format = "uri";
+			pattern = "^https:";
+		};
+		policy_uri = {
+			title = "Privacy Policy URL";
+			description = "Link to a Privacy Policy for the client. MUST be a https:// URL with hostname matching that of 'client_uri'.";
+			type = "string";
+			format = "uri";
+			pattern = "^https:";
+		};
+		software_id = {
+			title = "Software ID";
+			description = "Unique identifier for the client software, common for all instances. Typically an UUID.";
+			type = "string";
+			format = "uuid";
+		};
+		software_version = {
+			title = "Software Version";
+			description = "Version of the software creating being registered. \z
+			E.g. to allow revoking all related tokens in the event of a security incident.";
+			type = "string";
+			example = "2.3.1";
+		};
 	};
 }