fix: CType schema to include latest $schema (#259)

* fix: updating the ctype schema docs to include latest ctype schema * fix: updating the linting * feat: updating the ctypes * feat: updating domain ctype and ctypes * feat: updating the wording in the warning. " * feat: removing the future update * feat: adding missing additional props * feat: adding feedback Co-authored-by: Raphael Flechtner <[email protected]> * Update docs/concepts/05_credentials/02_ctypes.md * feat: adding required properties statements * feat: updating table * Apply suggestions from code review Co-authored-by: Raphael Flechtner <[email protected]> * feat: updating lang in the advised upgrade * feat: updating last wording --------- Co-authored-by: Raphael Flechtner <[email protected]>
KILTprotocol · Aug 1, 2023 · 57b7df4 · 57b7df4
1 parent 827222a
commit 57b7df4
Show file tree

Hide file tree

Showing 6 changed files with 57 additions and 14 deletions.
diff --git a/code_examples/sdk_examples/src/dapp/dapp/domainLinkageCtype.ts b/code_examples/sdk_examples/src/dapp/dapp/domainLinkageCtype.ts
@@ -4,14 +4,15 @@ import * as Kilt from '@kiltprotocol/sdk-js'
 export async function main(): Promise<Kilt.ICType> {
   const { creator, createdAt, ...domainLinkageCType } =
     await Kilt.CType.fetchFromChain(
-      'kilt:ctype:0x9d271c790775ee831352291f01c5d04c7979713a5896dcf5e81708184cc5c643'
+      'kilt:ctype:0xb08800a574c436831a2b9fce00fd16e9df489b2b3695e88a0895d148eca0311e'
     )
 
   console.log(JSON.stringify(domainLinkageCType, null, 2))
 
   /** Prints the following definition:
   {
-    "$schema": "http://kilt-protocol.org/draft-01/ctype#",
+    "$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/",
+    "additionalProperties": false,
     "properties": {
         "id": {
             "type": "string"
@@ -22,7 +23,7 @@ export async function main(): Promise<Kilt.ICType> {
     },
     "title": "Domain Linkage Credential",
     "type": "object",
-    "$id": "kilt:ctype:0x9d271c790775ee831352291f01c5d04c7979713a5896dcf5e81708184cc5c643"
+    "$id": "kilt:ctype:0xb08800a574c436831a2b9fce00fd16e9df489b2b3695e88a0895d148eca0311e"
   }
   */
   return domainLinkageCType

diff --git a/code_examples/sdk_examples/src/dapp/verifier/emailCtype.ts b/code_examples/sdk_examples/src/dapp/verifier/emailCtype.ts
@@ -3,14 +3,16 @@ import * as Kilt from '@kiltprotocol/sdk-js'
 
 export function main() {
   const emailCType: Kilt.ICType = {
-    $id: 'kilt:ctype:0x3291bb126e33b4862d421bfaa1d2f272e6cdfc4f96658988fbcffea8914bd9ac',
-    $schema: 'http://kilt-protocol.org/draft-01/ctype#',
+    $id: 'kilt:ctype:0xae5bc64e500eb576b7b137288cec5d532094e103be46872f1ad54641e477d9fe',
+    $schema:
+      'ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/',
     title: 'Email',
     properties: {
       Email: {
         type: 'string'
       }
     },
-    type: 'object'
+    type: 'object',
+    additionalProperties: false
   }
 }
diff --git a/docs/concepts/05_credentials/02_ctypes.md b/docs/concepts/05_credentials/02_ctypes.md
@@ -16,12 +16,48 @@ The schema defines which properties exist and what their type should be, e.g., a
 
 KILT uses [JSON Schema](https://json-schema.org/) (currently draft-07) to validate and annotate data in a strict format.
 This data format is used to define [CType models](https://github.com/KILTprotocol/sdk-js/blob/master/packages/core/src/ctype/CType.schemas.ts).
-The following are all required properties of the schema, with no additional properties allowed:
+The following are all required properties of the schema:
 
 - **Identifier**: `$id` in the format `kilt:ctype:0x{cTypeHash}`.
-- **KILT specific JSON-Schema**: Accessible at [http://kilt-protocol.org/draft-01/ctype#](http://kilt-protocol.org/draft-01/ctype#).
+- **Reference to CType metaschema (`$schema`)**: Describes what a valid CType must looks like. The latest metaschema is accessible at [ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/).
 - **Title**: Defines a user-friendly name for the CType that makes it easier for users to contextualize.
 - **Properties**: Set of fields (e.g., name, birthdate) that the CType can contain, and hence that the Claimer can have attested.
+- **Type**: Is always `"object"`,  instructing the JSON schema validator to expect an object (where each property is a claim about the Claimer in the credential).
+- **Additional properties**: In newer CTypes, *additionalProperties* must be present and must be set to `false`, restricting allowable claims in a credential to those listed in `properties`.
+
+:::warning
+Deprecation Warning: CType metaschema draft-01
+
+CTypes based on the `[http://kilt-protocol.org/draft-01/ctype#](http://kilt-protocol.org/draft-01/ctype%23%60)` metaschema are susceptible to faulty or malicious attester integrations that may introduce unexpected properties to a claim.
+Due to this vulnerability, this version of the metaschema is deprecated and its use is discouraged in the creation of new CTypes.
+For optimal security and functionality, it is recommended to use SDK version `0.33.0` or later for creating CTypes.
+This newer version defaults to using the updated metaschema available at [`ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/`](ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/%60).
+
+This also means you should update existing CTypes.
+
+While existing CTypes will continue to work in the short term, we advise to upgrade to the latest metaschema at your earliest convenience.
+
+Old Property Value:  `"$schema": "http://kilt-protocol.org/draft-01/ctype#"`
+
+New Property Value:  `"$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/"`
+
+**Migration instructions:** 
+
+Attesters are recommended to transition to issuing credentials using upgraded versions of CTypes currently in use.
+
+Using sdk version `0.33.0` or later, you can produce a copy of an existing CType `oldCType` as follows:
+
+``` js
+const newCType = CType.fromProperties(oldCType.title, oldCType.properties, 'V1')
+```
+
+The new CType will have the same title and properties as the existing one, but will be based on the new metaschema, resulting in a different hash and id.
+After [registering the new CType on the Kilt blockchain](../../develop/01_sdk/02_cookbook/04_claiming/01_ctype_creation.md), you can use the new CType as a drop-in replacement in issuing credentials.
+Depending verifiers are recommended to accept both the old and new CType during a transition period.
+Test thoroughly to ensure the correct behaviour and functionality of the new CTypes in your application.
+
+If you encounter any issues during the migration process or have questions, refer to the documentation or seek support from the relevant community.
+:::
 
 ### Properties
 
@@ -33,7 +69,7 @@ When creating a new CType schema, the following properties are required:
 - The format field is optionally:
   - *Date* format e.g., 2012-04-23T18:25:43.511Z
   - *Time* format e.g., T18:25:43.511Z
-  - *URI* format e.g., https://www.example.com
+  - *URI* format e.g., <https://www.example.com>
 
 <CodeBlock className="language-json" title="CType schema example">
   {ctypeSchema}

diff --git a/docs/develop/03_workshop/04_attester/03_ctype.md b/docs/develop/03_workshop/04_attester/03_ctype.md
@@ -47,9 +47,11 @@ Let's have a look at these attributes.
 | Key          | Value                                                                                                                                                               |
 | -------------| ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `$id`        | The KILT id of this CType. It is the most important property as it represents the **digital footprint** of the CType.                                               |
-| `$schema`    | A reference to the meta-schema describing what a CType may look like. This is the same for all CTypes.                                                              |
+| `$schema`    | A reference to the meta-schema describing what a CType may look like. There are two versions.                                                              |
 | `title`      | The title of the CType.                                                                                                                                             |
 | `properties` | The properties that a claim conforming to this CType may have.                                                                                                      |
+| `type` | Type is an object for all CTypes.                                                                                                  |
+| `additionalProperties` | The default is set to false. This restricts unwanted properties in a claim.                                                                                                      |
 
 A CType is stored on the KILT blockchain.
 

diff --git a/scripts/out/ctype-schema.json b/scripts/out/ctype-schema.json
@@ -1,6 +1,7 @@
 {
-  "$schema": "http://kilt-protocol.org/draft-01/ctype#",
+  "$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/",
   "title": "Drivers License by did:kilt:4t9FPVbcN42UMxt3Z2Y4Wx38qPL8bLduAB11gLZSwn5hVEfH",
+  "additionalProperties": false,
   "properties": {
     "name": {
       "type": "string"

diff --git a/scripts/out/ctype.json b/scripts/out/ctype.json
@@ -1,6 +1,7 @@
 {
-  "$id": "kilt:ctype:0xc22f85da01c18c1b48acf9556ac7167247ce253cc10373ea77f50fc91521d478",
-  "$schema": "http://kilt-protocol.org/draft-01/ctype#",
+  "$id": "kilt:ctype:0x4f1d68ac46daf4613181b33b16faaf10cf94879dc2246d7485dc2ccbb843641d",
+  "$schema": "ipfs://bafybeiah66wbkhqbqn7idkostj2iqyan2tstc4tpqt65udlhimd7hcxjyq/",
+  "additionalProperties": false,
   "properties": {
     "age": {
       "type": "integer"
@@ -14,4 +15,4 @@
   },
   "title": "Drivers License by did:kilt:4t9FPVbcN42UMxt3Z2Y4Wx38qPL8bLduAB11gLZSwn5hVEfH",
   "type": "object"
-}
+}