From 08bc2c0495cd6ff2eb2487727afcb4ff818a54b2 Mon Sep 17 00:00:00 2001 From: gabe Date: Fri, 28 Jul 2023 11:54:48 -0700 Subject: [PATCH] schema how to --- doc/howto/did.md | 11 +--- doc/howto/schema.md | 105 +++++++++++++++++++++++++++++++++- pkg/service/schema/service.go | 2 - 3 files changed, 103 insertions(+), 15 deletions(-) diff --git a/doc/howto/did.md b/doc/howto/did.md index a248710bf..fbf621623 100644 --- a/doc/howto/did.md +++ b/doc/howto/did.md @@ -41,21 +41,12 @@ For now let's keep things simple and create a new `did:key` with the key type [` **Create DID Key Request** -`PUT` to `/v1/dids/key` - -```json -{ - "keyType": "Ed25519" -} -``` - -A sample CURL command is as follows: +Make a `PUT` request to `/v1/dids/key`. A sample CURL command is as follows: ```bash curl -X PUT localhost:3000/v1/dids/key -d '{"keyType": "Ed25519"}' ``` -``` If successful, you should see a response such as... ```json diff --git a/doc/howto/schema.md b/doc/howto/schema.md index 09a8a63f6..45999ce78 100644 --- a/doc/howto/schema.md +++ b/doc/howto/schema.md @@ -8,17 +8,116 @@ When constructing and processing VCs as pure JSON it is useful to have a mechani ## Intro to JSON Schema with Verifiable Credentials -Making use of the `credentialSchema` property [defined in the VC Data Model](https://www.w3.org/TR/vc-data-model/#data-schemas) TBD and other collaborators in the W3C are working on [a new specification](https://w3c.github.io/vc-json-schema/) which enables a standards-compliant path to using JSON Schema with Verifiable Crednetials. The VC JSON Schema specification defines two options for using JSON Schemas: the first, a plan JSON Schema that can apply to _any set of properties_ in a VC, and the second, a Verifiable Credential that wraps a JSON Schema. +Making use of the `credentialSchema` property [defined in the VC Data Model](https://www.w3.org/TR/vc-data-model/#data-schemas) TBD and other collaborators in the W3C are working on [a new specification](https://w3c.github.io/vc-json-schema/) which enables a standards-compliant path to using JSON Schema with Verifiable Credentials. The VC JSON Schema specification defines two options for using JSON Schemas: the first, a plan JSON Schema that can apply to _any set of properties_ in a VC, and the second, a Verifiable Credential that wraps a JSON Schema. In some cases it is useful to package a JSON Schema as a Verifiable Credential to retain information about authorship (who created the schema), when it was created, and enable other features the VC Data Model offers, such as the ability to suspend the usage of a schema with [a status](https://www.w3.org/TR/vc-data-model/#status). -An example JSON Schema using [JSON Schema Draft 2020-12]() providing an `emailAddress` property is shown below: +An example email JSON Schema using [JSON Schema Draft 2020-12](https://json-schema.org/draft/2020-12/json-schema-core.html) is provided below: ```json - +{ + "$id": "https://example.com/schemas/email.json", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "name": "Email Address", + "type": "object", + "properties": { + "emailAddress": { + "type": "string", + "format": "email" + } + }, + "required": ["emailAddress"] +} ``` +We can see that the schema defines a property `emailAddress` of JSON type `string`, and it is required. This means that any piece of JSON we apply this schema to will pass if a valid `emailAddress` property is present and fail otherwise. + +Now that we have a valid JSON Schema, we'll need to transform it so it's useful in being applied to a Verifiable Credential, not just any arbitrary JSON. We know that we want the presence of an `emailAddress` in the `credentialSubject` property of a VC and adjust the schema accordingly: + +```json +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "name": "Email Credential", + "type": "object", + "properties": { + "credentialSubject": { + "type": "object", + "properties": { + "emailAddress": { + "type": "string", + "format": "email" + } + }, + "required": ["emailAddress"] + } + } +} +``` +Now our schema, applied to a Verifiable Credential, will guarantee that the `credentialSubject` property contains a valid `emailAddress` property. ## Creating a Schema +The service exposes a set of APIs for managing schemas. To create a schema you have two options: signed or not. As mentioned earlier, the signed version of a schema is packaged as a Verifiable Credential. To create a signed schema you'll need to pass in two additional properties – the issuer DID and the ID of the verification method to use to sign the schema. We'll keep things simple for now and create an unsigned schema. + +After forming a valid JSON Schema, generate a `PUT` request to `/v1/schemas` as follows: + +```bash +curl -X PUT localhost:3000/v1/schemas -d '{ + "name": "Email Credential", + "schema": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "credentialSubject": { + "type": "object", + "properties": { + "emailAddress": { + "type": "string", + "format": "email" + } + }, + "required": ["emailAddress"] + } + } + } +}' +``` + +Upon success you'll see a response which includes the schema you passed in, with a service-generated identifier for the schema. You'll also notice a type `JsonSchema2023`, which is defined by the [VC JSON Schema specification](https://w3c.github.io/vc-json-schema/#jsonschema2023): + +```json +{ + "id": "ebeebf7b-d452-4832-b8d3-0042ec80e108", + "type": "JsonSchema2023", + "schema": { + "$id": "http://localhost:3000/v1/schemas/ebeebf7b-d452-4832-b8d3-0042ec80e108", + "$schema": "https://json-schema.org/draft/2020-12/schema", + "name": "Email Credential", + "properties": { + "credentialSubject": { + "properties": { + "emailAddress": { + "format": "email", + "type": "string" + } + }, + "required": [ + "emailAddress" + ], + "type": "object" + } + }, + "type": "object" + } +} +``` + +Now you're ready to use the schema in [creating a credential](credential.md). + +## Getting Schemas + +Once you've created multiple schemas, you can view them all by make a `GET` request to the `v1/schemas` endpoint. Future enhancements may enable filtering based on name, author, or other properties. + +You can get a specific schema by make a `GET` request to the `v1/schemas/{schemaId}` endpoint. + diff --git a/pkg/service/schema/service.go b/pkg/service/schema/service.go index 4ab277158..57b562991 100644 --- a/pkg/service/schema/service.go +++ b/pkg/service/schema/service.go @@ -164,8 +164,6 @@ func (s Service) createCredentialSchema(ctx context.Context, jsonSchema schema.J // set subject value as the schema subject := credential.CredentialSubject(jsonSchema) - // TODO(gabe) remove this after https://github.com/TBD54566975/ssi-sdk/pull/404 is merged - subject[credential.VerifiableCredentialIDProperty] = schemaURI if err := builder.SetCredentialSubject(subject); err != nil { return nil, sdkutil.LoggingErrorMsgf(err, "could not set subject: %+v", subject) }