docs: service property type and map and refactor ServiceBlock type na…

…me to ServiceMap
walt-id · Sep 17, 2024 · 2184c58 · 2184c58
1 parent 1bce223
commit 2184c58
Show file tree

Hide file tree

Showing 6 changed files with 48 additions and 32 deletions.
diff --git a/...d/src/commonMain/kotlin/id/walt/did/dids/document/models/service/RegisteredServiceType.kt b/...d/src/commonMain/kotlin/id/walt/did/dids/document/models/service/RegisteredServiceType.kt
@@ -4,7 +4,9 @@ import kotlinx.serialization.Serializable
 import kotlin.js.ExperimentalJsExport
 import kotlin.js.JsExport
 
-//as defined in https://www.w3.org/TR/2024/NOTE-did-spec-registries-20240830/#service-types
+/**
+ * Enumerated type representing service types that are registered in the [Decentralized Identifier Extensions](https://www.w3.org/TR/2024/NOTE-did-spec-registries-20240830/#service-types) parameter registry.
+ */
 @OptIn(ExperimentalJsExport::class)
 @JsExport
 @Serializable

diff --git a/...ries/waltid-did/src/commonMain/kotlin/id/walt/did/dids/document/models/service/Service.kt b/...ries/waltid-did/src/commonMain/kotlin/id/walt/did/dids/document/models/service/Service.kt
@@ -10,26 +10,31 @@ import kotlinx.serialization.json.*
 import kotlin.js.ExperimentalJsExport
 import kotlin.js.JsExport
 
+/**
+ * Class for representing the service property of a DID document according to the respective section of the [DID Core](https://www.w3.org/TR/did-core/#services) specification
+ * @param serviceMaps A set of [ServiceMap] object instances.
+ * @see ServiceMap
+ */
 @OptIn(ExperimentalJsExport::class)
 @JsExport
 @Serializable(with = ServiceSerializer::class)
-data class Service(val serviceBlocks: Set<ServiceBlock>)
+data class Service(val serviceMaps: Set<ServiceMap>)
 
 object ServiceSerializer : KSerializer<Service> {
-    private val internalSerializer = SetSerializer(ServiceBlock.serializer())
+    private val internalSerializer = SetSerializer(ServiceMap.serializer())
     override val descriptor: SerialDescriptor = internalSerializer.descriptor
 
     override fun serialize(encoder: Encoder, value: Service) =
         encoder.encodeSerializableValue(
-            SetSerializer(ServiceBlock.serializer()),
-            value.serviceBlocks,
+            SetSerializer(ServiceMap.serializer()),
+            value.serviceMaps,
         )
 
 
     override fun deserialize(decoder: Decoder): Service =
         Service(
             decoder.decodeSerializableValue(
-                SetSerializer(ServiceBlock.serializer()),
+                SetSerializer(ServiceMap.serializer()),
             )
         )
 }
@@ -40,10 +45,19 @@ private val reservedKeys = listOf(
     "serviceEndpoint",
 )
 
+/**
+ * Class for representing a service map of a DID Document's service property according to the respective section of the [DID Core](https://www.w3.org/TR/did-core/#services:~:text=is%20described%20below%3A-,service,-The%20service%20property) specification
+ * @param id The identifier of this [ServiceMap] instance
+ * @param type A set of strings that reflect the type(s) of this [ServiceMap]. Use of the [RegisteredServiceType] entries is recommended for the sake of interoperability, however, users are free to introduce their own custom types.
+ * @param serviceEndpoint A set of [ServiceEndpoint] instances with which this [ServiceMap] instance is associated.
+ * @param customProperties Optional user-defined custom properties that can be included in this [ServiceMap] instance.
+ * @see ServiceEndpoint
+ * @see RegisteredServiceType
+ */
 @OptIn(ExperimentalJsExport::class)
 @JsExport
 @Serializable(with = ServiceBlockSerializer::class)
-data class ServiceBlock(
+data class ServiceMap(
     val id: String,
     val type: Set<String>,
     val serviceEndpoint: Set<ServiceEndpoint>,
@@ -60,15 +74,15 @@ data class ServiceBlock(
     }
 }
 
-object ServiceBlockSerializer : KSerializer<ServiceBlock> {
+object ServiceBlockSerializer : KSerializer<ServiceMap> {
     override val descriptor = JsonObject.serializer().descriptor
 
-    override fun deserialize(decoder: Decoder): ServiceBlock {
+    override fun deserialize(decoder: Decoder): ServiceMap {
         val jsonObject = decoder.decodeSerializableValue(JsonObject.serializer())
         reservedKeys.forEach {
             require(jsonObject.contains(it))
         }
-        return ServiceBlock(
+        return ServiceMap(
             id = Json.decodeFromJsonElement(jsonObject["id"]!!),
             type = jsonObject["type"]!!.let { element ->
                 when {
@@ -99,7 +113,7 @@ object ServiceBlockSerializer : KSerializer<ServiceBlock> {
         )
     }
 
-    override fun serialize(encoder: Encoder, value: ServiceBlock) {
+    override fun serialize(encoder: Encoder, value: ServiceMap) {
         encoder.encodeSerializableValue(
             JsonObject.serializer(),
             buildJsonObject {

diff --git a/...tid-did/src/commonMain/kotlin/id/walt/did/dids/document/models/service/ServiceEndpoint.kt b/...tid-did/src/commonMain/kotlin/id/walt/did/dids/document/models/service/ServiceEndpoint.kt
@@ -9,7 +9,7 @@ import kotlin.js.ExperimentalJsExport
 import kotlin.js.JsExport
 
 /**
- * Base class for representing a service endpoint according to the DID Core specification.
+ * Base class for representing a service endpoint according to the respective section of the [DID Core](https://www.w3.org/TR/did-core/#dfn-serviceendpoint) specification.
  * This can be either a URL (refer to [ServiceEndpointURL] ) or an arbitrary JSON object (refer to [ServiceEndpointObject]).
  * @see ServiceEndpointURL
  * @see ServiceEndpointObject

diff --git a/...ibraries/waltid-did/src/commonMain/kotlin/id/walt/did/dids/registrar/dids/DidDocConfig.kt b/...ibraries/waltid-did/src/commonMain/kotlin/id/walt/did/dids/registrar/dids/DidDocConfig.kt
@@ -5,7 +5,7 @@ import id.walt.crypto.keys.KeyType
 import id.walt.did.dids.DidUtils
 import id.walt.did.dids.document.DidDocument
 import id.walt.did.dids.document.models.service.Service
-import id.walt.did.dids.document.models.service.ServiceBlock
+import id.walt.did.dids.document.models.service.ServiceMap
 import id.walt.did.dids.document.models.service.ServiceEndpoint
 import id.walt.did.dids.document.models.verification.method.VerificationMaterialType
 import id.walt.did.dids.document.models.verification.method.VerificationMethod
@@ -161,7 +161,7 @@ data class DidDocConfig(
 
         val service = serviceConfigurationSet
             .map {
-                ServiceBlock(
+                ServiceMap(
                     id = "$did#${randomUUID()}",
                     type = setOf(it.type),
                     serviceEndpoint = it.serviceEndpoint,
@@ -180,7 +180,7 @@ data class DidDocConfig(
                     put(verRelType.toString(), Json.encodeToJsonElement(verRelValue))
                 }
             }
-            if (service.serviceBlocks.isNotEmpty()) put("service", Json.encodeToJsonElement(service))
+            if (service.serviceMaps.isNotEmpty()) put("service", Json.encodeToJsonElement(service))
             rootCustomProperties?.forEach {
                 put(it.key, it.value)
             }

diff --git a/...raries/waltid-did/src/commonTest/kotlin/id/walt/did/serialize/service/ServiceBlockTest.kt b/...raries/waltid-did/src/commonTest/kotlin/id/walt/did/serialize/service/ServiceBlockTest.kt
@@ -1,7 +1,7 @@
 package id.walt.did.serialize.service
 
 import id.walt.crypto.utils.JsonUtils.toJsonElement
-import id.walt.did.dids.document.models.service.ServiceBlock
+import id.walt.did.dids.document.models.service.ServiceMap
 import id.walt.did.dids.document.models.service.ServiceEndpointObject
 import id.walt.did.dids.document.models.service.ServiceEndpointURL
 import id.walt.did.dids.document.models.service.RegisteredServiceType
@@ -23,7 +23,7 @@ class ServiceBlockTest {
     @Test
     fun testServiceBlockEndpointURLSerialization() = runTest {
         //with URL endpoint block and no custom properties
-        val svcBlockWithURLEndpointNoCustom = ServiceBlock(
+        val svcBlockWithURLEndpointNoCustom = ServiceMap(
             id = "some-id",
             type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
             serviceEndpoint = setOf(ServiceEndpointURL("some-url"))
@@ -53,7 +53,7 @@ class ServiceBlockTest {
             actual = Json.decodeFromString(svcBlockWithURLEndpointNoCustomListJsonEncodedString)
         )
         //with URL endpoint block and custom properties
-        val svcBlockWithURLEndpointCustom = ServiceBlock(
+        val svcBlockWithURLEndpointCustom = ServiceMap(
             id = "some-id",
             type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
             serviceEndpoint = setOf(ServiceEndpointURL("some-url")),
@@ -88,7 +88,7 @@ class ServiceBlockTest {
     @Test
     fun testServiceBlockEndpointObjectSerialization() = runTest {
         //with object endpoint block and no custom properties
-        val svcBlockWithObjectEndpointNoCustom = ServiceBlock(
+        val svcBlockWithObjectEndpointNoCustom = ServiceMap(
             id = "some-id",
             type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
             serviceEndpoint = setOf(
@@ -125,7 +125,7 @@ class ServiceBlockTest {
             actual = Json.decodeFromString(svcBlockWithObjectEndpointNoCustomListJsonEncodedString),
         )
         //with object endpoint block and custom properties
-        val svcBlockWithObjectEndpointCustom = ServiceBlock(
+        val svcBlockWithObjectEndpointCustom = ServiceMap(
             id = "some-id",
             type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
             serviceEndpoint = setOf(
@@ -166,7 +166,7 @@ class ServiceBlockTest {
 
     @Test
     fun testServiceBlockWithSameEndpoints() = runTest {
-        val svcBlockWithURLEndpoints = ServiceBlock(
+        val svcBlockWithURLEndpoints = ServiceMap(
             id = "some-id",
             type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
             serviceEndpoint = setOf(
@@ -187,7 +187,7 @@ class ServiceBlockTest {
             expected = svcBlockWithURLEndpoints,
             actual = Json.decodeFromString(svcBlockWithURLEndpointsJsonEncodedString)
         )
-        val svcBlockWithObjectEndpoints = ServiceBlock(
+        val svcBlockWithObjectEndpoints = ServiceMap(
             id = "some-id",
             type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
             serviceEndpoint = setOf(
@@ -222,7 +222,7 @@ class ServiceBlockTest {
 
     @Test
     fun testServiceBlockWithMixEndpoints() = runTest {
-        val svcBlock = ServiceBlock(
+        val svcBlock = ServiceMap(
             id = "some-id",
             type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
             serviceEndpoint = setOf(
@@ -252,7 +252,7 @@ class ServiceBlockTest {
 
     @Test
     fun testServiceBlockMultipleTypes() = runTest {
-        val svcBlock = ServiceBlock(
+        val svcBlock = ServiceMap(
             id = "some-id",
             type = setOf(
                 RegisteredServiceType.DIDCommMessaging.toString(),

diff --git a/...d-libraries/waltid-did/src/commonTest/kotlin/id/walt/did/serialize/service/ServiceTest.kt b/...d-libraries/waltid-did/src/commonTest/kotlin/id/walt/did/serialize/service/ServiceTest.kt
@@ -16,20 +16,20 @@ class ServiceTest {
         "tit" to "tat".toJsonElement(),
     )
 
-    private val svcBlockSingleURLNoCustom = ServiceBlock(
+    private val svcBlockSingleURLNoCustom = ServiceMap(
         id = "some-id",
         type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
         serviceEndpoint = setOf(ServiceEndpointURL("some-url")),
     )
 
-    private val svcBlockSingleURLCustom = ServiceBlock(
+    private val svcBlockSingleURLCustom = ServiceMap(
         id = "some-id",
         type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
         serviceEndpoint = setOf(ServiceEndpointURL("some-url")),
         customProperties = customProperties,
     )
 
-    private val svcBlockMultipleURLNoCustom = ServiceBlock(
+    private val svcBlockMultipleURLNoCustom = ServiceMap(
         id = "some-id",
         type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
         serviceEndpoint = setOf(
@@ -38,7 +38,7 @@ class ServiceTest {
         ),
     )
 
-    private val svcBlockMultipleURLCustom = ServiceBlock(
+    private val svcBlockMultipleURLCustom = ServiceMap(
         id = "some-id",
         type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
         serviceEndpoint = setOf(
@@ -48,7 +48,7 @@ class ServiceTest {
         customProperties = customProperties,
     )
 
-    private val svcBlockSingleObjectNoCustom = ServiceBlock(
+    private val svcBlockSingleObjectNoCustom = ServiceMap(
         id = "some-id",
         type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
         serviceEndpoint = setOf(
@@ -61,7 +61,7 @@ class ServiceTest {
         ),
     )
 
-    private val svcBlockSingleObjectCustom = ServiceBlock(
+    private val svcBlockSingleObjectCustom = ServiceMap(
         id = "some-id",
         type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
         serviceEndpoint = setOf(
@@ -75,7 +75,7 @@ class ServiceTest {
         customProperties = customProperties,
     )
 
-    private val svcBlockMultipleObjectNoCustom = ServiceBlock(
+    private val svcBlockMultipleObjectNoCustom = ServiceMap(
         id = "some-id",
         type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
         serviceEndpoint = setOf(
@@ -94,7 +94,7 @@ class ServiceTest {
         ),
     )
 
-    private val svcBlockMultipleObjectCustom = ServiceBlock(
+    private val svcBlockMultipleObjectCustom = ServiceMap(
         id = "some-id",
         type = setOf(RegisteredServiceType.DIDCommMessaging.toString()),
         serviceEndpoint = setOf(