diff --git a/mkdocs/docs/protocol/claim-schema.md b/mkdocs/docs/protocol/claim-schema.md index 3f8bee8..5889ce6 100644 --- a/mkdocs/docs/protocol/claim-schema.md +++ b/mkdocs/docs/protocol/claim-schema.md @@ -6,7 +6,7 @@ Schemas are described via JSON-LD documents. A claim issuer could reuse existing ## Example: KYCAgeCredential Schema -- [Github Document](https://github.com/iden3/claim-schema-vocab/blob/main/schemas/json-ld/kyc-v3.json-ld) +- [Github Document](https://github.com/iden3/claim-schema-vocab/blob/main/schemas/json-ld/kyc-v4.jsonld) ```json { @@ -17,7 +17,7 @@ Schemas are described via JSON-LD documents. A claim issuer could reuse existing "id": "@id", "type": "@type", "KYCAgeCredential": { - "@id": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld#KYCAgeCredential", + "@id": "https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v4.jsonld#KYCAgeCredential", "@context": { "@version": 1.1, "@protected": true, @@ -34,7 +34,7 @@ Schemas are described via JSON-LD documents. A claim issuer could reuse existing "@type": "xsd:integer" } } - }, + } } ] } @@ -47,16 +47,14 @@ The last part of the document contains a reference to the value types `birthday` ## Schema Hash -The Schema Hash is a unique identifier for a Claim Schema. It is derived by hashing the string that represents unique identifier `@id` of the Claim Schema type. In the previous example, the hash pre-image is the string `https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld#KYCAgeCredential`. - +The Schema Hash is a unique identifier for a Claim Schema. It is derived by hashing the string that represents unique identifier `@id` of the Claim Schema type. In the previous example, the hash pre-image is the string `https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v4.jsonld#KYCAgeCredential`. +` For example, in the case of the Auth Claim the schema hash would be ```golang var sHash core.SchemaHash -h := Keccak256([]byte("https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v3.json-ld#KYCAgeCredential")) +h := Keccak256([]byte("https://raw.githubusercontent.com/iden3/claim-schema-vocab/main/schemas/json-ld/kyc-v4.jsonld#KYCAgeCredential")) copy(sHash[:], h[len(h)-16:]) sHashHex, _ := sHash.MarshalText() - fmt.Println(string(sHashHex)) -// f21e8faf5c95292b6bfbc53f8143a9d4 -``` \ No newline at end of file +``` diff --git a/mkdocs/docs/protocol/non-merklized.md b/mkdocs/docs/protocol/non-merklized.md new file mode 100644 index 0000000..a5f81ef --- /dev/null +++ b/mkdocs/docs/protocol/non-merklized.md @@ -0,0 +1,143 @@ +# Non-merklized credentials + +## Motivation + +While Iden3 protocol allows to "merklize" the whole JSON-LD document (transform the document into key-value pairs and put them into a sparse merkle tree for later proving of credential field value in the tree), which removes limits on amount and structure of the credential data, there's still a need to issue a core claim with the data itself. This is particularly useful for onchain issuers, which can’t work with json-ld schemas in smart contracts (for many reasons), and also for use cases when the actual data must be saved for cheaper access inside circuits (e.g. Auth BJJ credential public key representation). + +**Core Concept** + +Non-merklized credentials now can be created relying on JSON-LD schemas. + +Example of such context: `https://schema.iden3.io/core/jsonld/auth.jsonld` + +```json +{ + "@context": [{ + "@version": 1.1, + "@protected": true, + "id": "@id", + "type": "@type", + "AuthBJJCredential": { + "@id": "https://schema.iden3.io/core/jsonld/auth.jsonld#AuthBJJCredential", + "@context": { + "@version": 1.1, + "@protected": true, + "id": "@id", + "type": "@type", + "iden3_serialization": "iden3:v1:slotIndexA=x&slotIndexB=y", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "auth-vocab": "https://schema.iden3.io/core/vocab/auth.md#", + "x": { + "@id": "auth-vocab:x", + "@type": "xsd:positiveInteger" + }, + "y": { + "@id": "auth-vocab:y", + "@type": "xsd:positiveInteger" + } + } + } + }] +} +``` + +Schema is defined as a schema for non-merklized credentials by utilizing `iden3_serialization` attribute. + +It contains a map string represented mapping, where: + +`iden3:v1` - version of protocol serialization, constant. + +`slotIndexA=x` slotIndexA is index data slot A with index 2 for path to field `x` in credential + +`slotIndexB=y` slotIndexB is index data slot B with index 3 for path to field `y` in credential + +other possible values: + +`slotValueA` slotIndexB is value data slot with index 6 + +`slotValueB` slotValueB is value data slot with index 7 + +See more information regarding data slot indexes [here](https://www.notion.so/Identity-Core-77fe2f04c8ad4e0296e2b90400d7ae3a?pvs=21). When user creates schema he should choose the slot to put the field. + +Nested structures are supported and path is created using concatenation with `.` e.g for birthday field in the Index Data Slot A mapping entry looks like that: + +`"iden3:v1:slotIndexA=passportInfo.birthday"` + +```json +{ + "@context": [ + { + "@version": 1.1, + "@protected": true, + "id": "@id", + "type": "@type", + "Passport": { + "@id": "uuid:urn:229a9afc-4aad-48e4-b113-bf2ca6f3a98f", + "@context": { + "@version": 1.1, + "@protected": true, + "id": "@id", + "type": "@type", + "kyc-vocab": "https://github.com/iden3/claim-schema-vocab/blob/main/credentials/kyc.md#", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "passportInfo": { + "@id": "kyc-vocab:passportInfo", + "@context": { + "@version": 1.1, + "@protected": true, + "kyc-vocab": "https://github.com/iden3/claim-schema-vocab/blob/main/credentials/kyc.md#", + "xsd": "http://www.w3.org/2001/XMLSchema#", + "id": "@id", + "type": "@type", + "birthday": { + "@type": "xsd:integer", + "@id": "kyc-vocab:birthday" + } + } + } + } + } + } + ] +} +``` + +**Important**: + +1. Fields in index slots make influence on the uniqueness of the claim in the clams tree of issuer, data in the value slots - don’t. +2. Data Slots number is 4, so there is a restriction to have only 4 fields for non-merklized credentials. + +Meanwhile `@type` filed for each field must contain one of the supported primitive types, so value can be written according to the data type. + +List of supported data types: + +```json +XSD namespace { + Boolean = 'http://www.w3.org/2001/XMLSchema#boolean', + Integer = 'http://www.w3.org/2001/XMLSchema#integer', + NonNegativeInteger = 'http://www.w3.org/2001/XMLSchema#nonNegativeInteger', + NonPositiveInteger = 'http://www.w3.org/2001/XMLSchema#nonPositiveInteger', + NegativeInteger = 'http://www.w3.org/2001/XMLSchema#negativeInteger', + PositiveInteger = 'http://www.w3.org/2001/XMLSchema#positiveInteger', + DateTime = 'http://www.w3.org/2001/XMLSchema#dateTime', + Double = 'http://www.w3.org/2001/XMLSchema#double' +} +``` + +Libraries that support non-merklized credentials: +https://github.com/iden3/go-schema-processor/releases/tag/v2.0.1 +https://github.com/0xPolygonID/js-sdk/releases/tag/v1.1.0 + +To create non-merklized credential in go-schema-processor / JS-sdk merklized Root Position must be set to None (default value) and ld context must contain `iden3_serialization` attribute. + +```golang +processor.CoreClaimOptions{ + .., + MerklizedRootPosition: verifiable.CredentialMerklizedRootPositionNone, + ... + } +``` + +If context contains serialization attribute but MerklizedRootPosition is set to Index / Value error will be thrown. + +In case context doesn’t contain serialization attribute and MerklizedRootPosition is set to Index / Value. Merkle root will be written to corresponding position. If the MerklizedRootPosition is set to None Merkle root will be written to Index. diff --git a/mkdocs/mkdocs.yml b/mkdocs/mkdocs.yml index 81b4d57..ac5f3b6 100644 --- a/mkdocs/mkdocs.yml +++ b/mkdocs/mkdocs.yml @@ -84,6 +84,7 @@ nav: # - Libraries: "services/libraries.md" - Login protocol: "protocol/zklogin.md" - Proof Query language: "protocol/querylanguage.md" + - Non-merklized credentials: "protocol/non-merklized.md" - JSON-LD merklization: "w3c/merklization.md" - Reverse hash service: "services/rhs.md" - On-chain credential status: "protocol/onchain-credential-status.md"