CIP-0072 | Fold inline schemas into links to companion files (#529)

rphair · KtorZ · web-flow · commit defdde35cca4 · 2023-07-04T11:45:45.000+02:00
* collapsed inline schemas into links to respective files

* Update CIP-0072/README.md

---------

Co-authored-by: Matthias Benkort &lt;5680256+KtorZ@users.noreply.github.com&gt;
diff --git a/CIP-0072/README.md b/CIP-0072/README.md
@@ -89,153 +89,13 @@ The on-chain dApp registration certificate MUST follow canonical JSON and be ser
 
 *`signature`*: The signature of the certificate. The publishers generate the signature is by first turning on-chain JSON into a canonical form (RFC 8765), hashing it with blake2b-256 and generating a signature of the hash. Stores / clients can verify the signature by repeating the process, they can use the public key to verify the signature of the certificate. Fields used for canonical JSON: ["subject", "rootHash", "metadata","type"]. Please note that a signature should be generated of blake2b-256 hash as a byte array, not as a hex represented string(!).
 
-### On chain CDDL for registration / de-registration
+### On-chain Schemas
 
-```
-string = bstr .size (1..64) ; tstr / string from 1 up to 64 chars only
-
-sig_256 = bstr .size (64..64) ; 256 bytes signature (256 / 64 = 4 bytes)
-
-transaction_metadata = {
-  1667: on-chain_metadata
-}
-
-on-chain_metadata = {
-  subject: string,
-  rootHash: sig_256,
-  metadata: [+ string] / [+ string / [+ string]],
-  type: registration / de-registration,
-  signature: signature,
-}
+[On-chain CDDL for registration / de-registration (Version 1)](./version_1_onchain.cddl)
 
-registration = {
-  action: "REGISTER",
-  ? comment: string,
-}
+which also can be expressed using JSON schema:
 
-de-registration = {
-  action: "DE_REGISTER",
-  ? comment: string,
-}
-
-signature = {
-  r: string,
-  s: string,
-  algo: text .regexp "Ed25519-EdDSA",
-  pub: string,
-}
-```
-
-which can be expressed using JSON schema.
-
-### dApp on-chain certificate JSON Schema
-
-```json
-{
-    "$schema":"https://json-schema.org/draft/2020-12/schema",
-    "$id":"https://example.com/dApp.schema.json",
-    "title": "Cardano dApp Claim",
-    "description": "Registration of Cardano dApp claim.",
-    "type":"object",
-    "properties":{
-       "subject":{
-          "type":"string",
-                "minLength": 1,
-                "maxLength": 64,
-                "pattern":"^[0-9a-fA-F]{1,64}$",
-                "description":"Identifier of the claim subject (dApp). A UTF-8 encoded string, must be max 64 chars. Typically it is randomly generated hash by the dApp developer."
-       },
-       "rootHash":{
-          "type":"string",
-                "minLength": 64,
-                "maxLength": 64,
-                "pattern":"^[0-9a-fA-F]{64}$",
-               "description":"blake2b-256 hash of the metadata describing the off-chain part of the dApp."
-       },
-       "metadata": {
-         "type": "array",
-         "description": "An array of valid URLs pointing to off-chain CIP-72 compatible metadata document. If an individual URL is longer than 64 characters, it must be expressed as an array of strings (where each string may contain at most 64 characters).",
-         "items": {
-           "anyOf": [{
-             "type": "string",
-               "minLength": 1,
-               "maxLength": 64
-             }, {
-             "type": "array",
-             "items": {
-               "type": "string",
-               "minLength": 1,
-               "maxLength": 64
-             }
-           }],
-           "examples": ["https://raw.githubusercontent.com/org/repo/offchain.json", ["https://raw.githubusercontent.com/long-org-name/", "long-repo-name/offchain.json"], "ipfs://QmbQDvKJeo2NgGcGdnUiUFibTzuKNK5Uij7jzmK8ZccmWp", ["ipfs://QmbQDvKJeo2NgGcGdnUiaAdADA", "UFibTzuKNKc0jA390alDAD5Uij7jzmK8ZccmWp"]]
-         }
-       },
-       "type":{
-          "type":"object",
-          "description":"Describes the releases, if they are new or an updates.",
-          "properties":{
-             "action":{
-               "type":"string",
-               "enum":["REGISTER", "DE_REGISTER"],
-               "description":"Describes the action this certificate is claiming; i.e 'REGISTER', for a new dApp or an update, DE_REGISTER for asserting that the dApp's development is stopped, and it is deprecated. So, no further dApp's on-chain update is to be expected."
-             },
-             "comment": {
-                "type": "string",
-                "minLength": 1,
-                "maxLength": 64,
-                "description": "A free text field to provide details about this particular changes (64 chars limited)."
-             }
-          },
-          "required":[
-             "action"
-          ]
-       },
-       "signature":{
-          "description":"Signature of the blake2b-256 hash of whole canonical (RFC 8785) JSON document (except signature property).",
-          "type":"object",
-          "properties":{
-             "r":{
-                "type":"string",
-                "description":"A hex representation of the R component of the signature.",
-                "minLength": 64,
-                "maxLength": 64,
-                "pattern":"^[0-9a-fA-F]{64}$"
-             },
-             "s":{
-                "type":"string",
-                "description":"A hex representation of the S component of the signature.",
-                "minLength": 64,
-                "maxLength": 64,
-                "pattern":"^[0-9a-fA-F]{64}$"
-             },
-             "algo":{
-               "const":"Ed25519-EdDSA"
-             },
-             "pub":{
-                "type":"string",
-                "description":"A hex representation of the public key.",
-                "minLength": 64,
-                "maxLength": 64,
-                "pattern":"^[0-9a-fA-F]{64}$"
-             }
-          },
-          "required":[
-             "r",
-             "s",
-             "algo",
-             "pub"
-          ]
-       }
-    },
-    "required":[
-       "subject",
-       "rootHash",
-       "type",
-       "signature"
-    ]
- }
- ```
+[dApp on-chain certificate JSON Schema (Version 1)](./version_1_onchain.json)
 
 ### Metadata Label
 
@@ -247,214 +107,7 @@ When submitting the transaction metadata pick the following value for `transacti
 
 The dApp Registration certificate itself doesn't enforce a particular structure to the metadata you might fetch off-chain. However, we recommend that you use the following structure:
 
-```json
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "type":"object",
-    "properties": {
-      "subject": {
-        "type":"string",
-        "minLength": 1,
-        "maxLength": 64,
-        "pattern":"^[0-9a-fA-F]{1,64}$",
-        "description": "A subject, it must match with subject stored on chain data. A UTF-8 encoded string, 1 - 64 chars."
-      },
-      "projectName": {
-        "type":"string",
-        "description": "A project name, e.g. My dApp."
-      },
-      "link": {
-        "type":"string",
-        "description": "Website presenting a dApp.",
-        "pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
-      },      
-      "logo": {
-        "type":"string",
-        "description": "URL to the logo or the base64 encoded image."
-      },
-      "categories": {
-        "type":"array",
-        "items": {
-          "type": "string",
-          "enum":["Games", "DeFi", "Gambling", "Exchanges", "Collectibles", "Marketplaces", "Social", "Other"]
-        },
-        "description": "One or more categories. Category MUST be one of the following schema definition."
-      },
-      "social": {
-        "type":"object",
-        "properties": {
-          "website": {
-            "type":"string",
-            "description": "dApps website link.",
-            "pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
-          },
-          "twitter": {
-            "type":"string",
-            "description": "An optional Twitter link.",
-            "pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
-          },
-          "github": {
-            "type":"string",
-            "description": "An optional Github link.",
-            "pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
-          },
-          "discord": {
-            "type":"string",
-            "description": "An optional Discord link.",
-            "pattern": "(https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|www\\.[a-zA-Z0-9][a-zA-Z0-9-]+[a-zA-Z0-9]\\.[^\\s]{2,}|https?:\/\/(?:www\\.|(?!www))[a-zA-Z0-9]+\\.[^\\s]{2,}|www\\.[a-zA-Z0-9]+\\.[^\\s]{2,})"
-          }
-        },
-        "required": ["website"]
-      },
-      "description": {
-        "type": "object",
-        "properties": {
-          "short": {
-            "type": "string",
-            "description": "Short dApp description (no less than 40 and no longer than 168 characters).",
-            "minLength": 40,
-            "maxLength": 168
-          },
-          "long": {
-            "type": "string",
-            "description": "An optional long dApp description (no less than 40 and no longer than 1008 characters).",
-            "minLength": 40,
-            "maxLength": 1008
-          }
-        },
-        "required": [
-          "short"
-        ]
-      },
-      "releases": {
-        "type": "array",
-        "items": [
-          {
-            "type": "object",
-            "properties": {
-              "releaseNumber": {
-                "type": "string",
-                "pattern": "^(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)\\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\\+([0-9a-zA-Z-]+(\\.[0-9a-zA-Z-]+)*))?$",
-                "description": "Semver compatible release number (major.minor.patch) or (major.minor.patch-some_text) e.g. 1.2.3 or 1.1.1-alpha"
-              },
-              "releaseName": {
-                "type": "string",
-                "description": "An optional human readable release name, e.g. V1"
-              },
-              "securityVulnerability": {
-                "type": "boolean",
-                "description": "Indicates that a given version has a security vulnerability."
-              },
-              "comment": {
-                "type": "string",
-                "description": "A free text field to provide comment about this particular release, e.g. new features it brings, etc."
-              },
-              "scripts": {
-                "type": "array",
-                "items": [
-                  {
-                    "type": "object",
-                    "properties": {
-                      "id": {
-                        "type": "string"
-                      },
-                      "version": {
-                        "type": "integer"
-                      }
-                    },
-                    "required": [
-                      "id",
-                      "version"
-                    ]
-                  }
-                ]
-              }
-            },
-            "required": [
-              "releaseNumber"
-            ]
-          }
-        ]
-      },
-      "scripts": {
-        "type": "array",
-        "items": [
-          {
-            "type": "object",
-            "properties":{
-              "id": {
-                "type":"string",
-                "description": "Unique Script ID (across all scripts from this dApp)."
-              },
-              "name":{
-                "type":"string",
-                "description": "An optional script name usually related to it's function."
-              },
-              "purposes":{
-                "type":"array",
-                "items": {
-                    "type": "string",
-                      "enum":["SPEND", "MINT"]
-                },
-                "description": "Purposes of the script, SPEND or MINT (notice it can be both for some modern Cardano languages)."
-              },
-              "type":{
-                "enum":["PLUTUS", "NATIVE"],
-                "description": "Script Type. PLUTUS refers to the typical PlutusV1 or PlutusV2 scripts, where as NATIVE means there has been no Plutus directly used by this is a native script."
-              },
-              "versions":{
-                "type":"array",
-                "items":[
-                  {
-                    "type":"object",
-                    "properties":{
-                      "version":{
-                        "type":"integer",
-                        "description":"Script version, monotonically increasing."
-                      },
-                      "plutusVersion":{
-                        "type":"integer",
-                        "enum":[1, 2]
-                      },
-                      "scriptHash":{
-                        "type":"string",
-                        "description":"Full on-chain script hash (hex).",
-                        "pattern":"[0-9a-fA-F]+"
-                      },
-                      "contractAddress": {
-                        "type":"string",
-                        "description":"An optional Bech32 contract address matching script's hash."
-                      }
-                    },
-                    "required": [
-                      "version",
-                      "plutusVersion",
-                      "scriptHash"
-                    ]
-                  }
-                ]
-              }
-            },
-            "required": [
-              "id",
-              "purposes",
-              "type",
-              "versions"
-            ]
-          }
-        ]
-      }
-    },
-    "required": [
-      "subject",
-      "projectName",
-      "link",
-      "social",
-      "categories",
-      "description"
-    ]
-  }
-  ```
+[Off-chain dApp Registration certificate schema (Version 1)](./version_1_offchain.json)
 
 This schema describes the minimum required fields for a store to be able to display and validate your dApp. You can add any other fields you want to the metadata, but we recommend that you use at least the ones described above.
 
