docs: Add Services section to Reference

docs/specification/reference.md

@@ -39,6 +39,16 @@ The top-level structure of a discovery document (`/.well-known/ucp`).
 
 {{ extension_schema_fields('ucp.json#/$defs/discovery_profile', 'reference') }}
 
+### Services
+Services define the API surface for a vertical (shopping, common, etc.) with
+transport bindings. Each service is keyed by its reverse-domain name
+(e.g., `dev.ucp.shopping`) in the discovery profile's `services` object.
+
+{{ extension_schema_fields('ucp.json#/$defs/services', 'reference') }}
+
+#### Service Schema
+{{ schema_fields('service_schema', 'reference') }}
+
 ### Checkout Response Metadata
 The `ucp` object included in checkout responses.
 

main.py

@@ -49,6 +49,7 @@ def define_env(env):
     "spec/schemas/",
     "spec/schemas/shopping/",
     "spec/schemas/shopping/types/",
+    "spec/services/",
   ]
 
   def _load_json_file(entity_name):

source/schemas/ucp.json

@@ -14,6 +14,11 @@
     "services": {
       "type": "object",
       "description": "Service definitions keyed by reverse-domain service name.",
+      "properties": {
+        "com.example.service": {
+          "$ref": "../services/service_schema.json"
+        }
+      },
       "additionalProperties": {"$ref": "../services/service_schema.json"}
     },
 

spec/schemas/ucp.json

@@ -12,6 +12,11 @@
     "services": {
       "type": "object",
       "description": "Service definitions keyed by reverse-domain service name.",
+      "properties": {
+        "com.example.service": {
+          "$ref": "../services/service_schema.json"
+        }
+      },
       "additionalProperties": {
         "$ref": "../services/service_schema.json"
       }