Template documentation update (#1333)

Author: Joshua Coffey

docs/reference/other/openid.md

@@ -118,16 +118,17 @@ Some credential template fields may be intended for URLs which resolve to images
 
 By default, these will display to the holders in the OIDC flow as simple text fields containing the raw URL. However, the template can be configured to display these URLs as either inline embedded images, or convenient links to download the linked data.
 
-When creating a Template:
-
-- Choose the `Uri` type for any Fields which are intended to contain URIs.
-- Set the `trinsic/web.display_method` annotation on the Field
- - If the field is intended to contain an image, use the value `inline`.
- - Otherwise, use the value `download`.
-- Set the `trinsic/file.content_type` annotation on the Field
- - Use the value `image` if the field is intended to contain a link to an image
- - Otherwise, the value should be the expected MIME Type of the data
- - If you are unsure, use `application/octet-stream` as a catch-all
+When creating or updating a Template:
+
+- Choose the `URI` type for any Fields which are intended to contain URIs.
+- Configure the `UriData` object on the Field
+ - Set the `RenderMethod` property
+ - If the field is intended to contain an image, use the value `INLINE_IMAGE`.
+ - Otherwise, use `LINK` for a clickable link, or `TEXT` to display the URI in raw form.
+ - Set the `MimeType` property
+ - Use the value `image` if the field is intended to contain a link to an image
+ - Otherwise, the value should be the expected MIME Type of the data
+ - If you are unsure, use `application/octet-stream` as a catch-all
 
 ## Sample
 

docs/reference/services/template-service.md

@@ -4,23 +4,17 @@
 The Template Service allows you to manage and search [Credential Templates](/learn/concepts/templates).
 
 
-!!! info "Templates are optional"
- Templates are designed to be a helpful abstraction over the complexities of producing valid [JSON-LD Verifiable Credentials](https://www.w3.org/TR/vc-data-model/).
-
- You aren't required to use templates; if you produce valid JSON-LD VCs yourself, they can be issued through Trinsic.
-
 ---
 
 ## Create Template
 
-!!! info "Field Annotations"
- When defining the Fields of a Template, the `annotations` object can be used to set arbitrary key-value metadata on a Field.
+Creates a new credential template.
 
- Trinsic defines certain annotations that dictate how a credential field containing a URI will render during the verification flow.
+The `name` of a template must be unique within your ecosystem, and cannot be changed -- it is used to derive the URI of the template itself.
 
- [Click here](../../reference/other/openid.md) for more information on this use case.
+The `title` and `description` parameters (for the template itself, as well as for any of its fields) should be human-readable strings. They should describe the credentials issued by the template, not the template itself (for example, a good title for a medical license template would simply be "Medical License", not "Medical License Template").
 
-Creates a new credential template.
+`field_ordering` may be used to specify the order in which fields are rendered when displaying a credential, and to categorize fields into logical sections. This is used for display only, and has no bearing on working with credentials as an issuer or verifier.
 
 {{ proto_sample_start() }}
  === "Trinsic CLI"
@@ -31,7 +25,7 @@ Creates a new credential template.
  === "TypeScript"
   <!--codeinclude-->
   ```typescript
-  [CreateTemplate](../../../web/test/CredentialTemplateShared.ts) inside_block:defineTemplate
+  [CreateTemplate](../../../web/test/CredentialTemplates.test.ts) inside_block:createTemplate
   ```
   <!--/codeinclude-->
 
@@ -67,14 +61,67 @@ Creates a new credential template.
 
 ---
 
+## Update Template
+
+Updates a template's display metadata, such as its human-readable title/description.
+
+This call cannot be used to update templates in a way that might invalidate previously-issued credentials: fields cannot be added, removed, or renamed, but their `title` and `description` properties may be updated.
+
+In order to leave a property unchanged (for example, if you wish to change `description` but not `title`), simply leave it unspecified (_don't_ set it to an empty string/object). This applies to fields as well: any field not specified in `fields` will remain unchanged.
+
+{{ proto_sample_start() }}
+ === "Trinsic CLI"
+ ```bash
+ Not yet supported
+ ```
+
+ === "TypeScript"
+  <!--codeinclude-->
+  ```typescript
+  [UpdateTemplate](../../../web/test/CredentialTemplates.spec.ts) inside_block:updateTemplate
+  ```
+  <!--/codeinclude-->
+
+ === "C#"
+  <!--codeinclude-->
+  ```csharp
+  [UpdateTemplate](../../../dotnet/Tests/Tests.cs) inside_block:updateTemplate
+  ```
+  <!--/codeinclude-->
+
+ === "Python"
+  <!--codeinclude-->
+  ```python
+  [UpdateTemplate](../../../python/samples/templates_demo.py) inside_block:updateTemplate
+  ```
+  <!--/codeinclude-->
+
+ === "Go"
+  <!--codeinclude-->
+  ```golang
+  [UpdateTemplate](../../../go/services/template_service_test.go) inside_block:updateTemplate
+  ```
+  <!--/codeinclude-->
+
+ === "Java"
+  <!--codeinclude-->
+  ```java
+  [UpdateTemplate](../../../java/src/test/java/trinsic/TemplatesDemo.java) inside_block:updateTemplate
+  ```
+  <!--/codeinclude-->
+
+{{ proto_method_tabs("services.verifiablecredentials.templates.v1.CredentialTemplates.Update") }}
+
+---
+
 ## Get Template
 
 Fetches a template definition by `id`.
 
 {{ proto_sample_start() }}
 
  === "Trinsic CLI"
-  ```bash
+  ```
   trinsic template get --id <TEMPLATE_ID>
   ```
   
@@ -124,7 +171,7 @@ Deletes a credential template by `id`.
 {{ proto_sample_start() }}
  === "Trinsic CLI"
  ```bash
- trinsic tamplate delete --id <TEMPLATE_ID>
+ trinsic template delete --id <TEMPLATE_ID>
  ```
 
  === "C#"

docs/walkthroughs/vaccination.md

@@ -271,14 +271,6 @@ Templates are simply a list of the fields that a credential can have.
  ```
  <!--/codeinclude-->
 
-!!! info "Templates are Optional"
-
- Templates are an optional helpful abstraction which removes the need to work directly with complex data formats such as JSON-LD.
-
- When a template is used to issue a credential, the result is a valid, interoperable JSON-LD Verifiable Credential.
-
- Trinsic's SDKs support issuing JSON-LD credentials that you create yourself, should you choose not to use templates.
-
 !!! abstract "Further Reading: Templates"
 
  - Learn more about [Templates](/learn/concepts/templates){target=_blank}

dotnet/Tests/Tests.cs

@@ -409,15 +409,33 @@ public async Task DemoTemplatesWithIssuance() {
 
  // create example template
  // createTemplate() {
- CreateCredentialTemplateRequest templateRequest = new() {
+ CreateCredentialTemplateRequest createRequest = new()
+ {
  Name = "An Example Credential",
- AllowAdditionalFields = false
+ Title = "Example Credential",
+ Description = "A credential for Trinsic's SDK samples",
+ AllowAdditionalFields = false,
+ Fields =
+ {
+ { "firstName", new() { Title = "First Name", Description = "Given name of holder" } },
+ { "lastName", new() { Title = "Last Name", Description = "Surname of holder", Optional = true } },
+ { "age", new() { Title = "Age", Description = "Age in years of holder", Type = FieldType.Number } }
+ },
+ FieldOrdering =
+ {
+ { "firstName", new() { Order = 0, Section = "Name" } },
+ { "lastName", new() { Order = 1, Section = "Name" } },
+ { "age", new() { Order = 2, Section = "Miscellanous" } }
+ },
+ AppleWalletOptions = new()
+ {
+ PrimaryField = "firstName",
+ SecondaryFields = { "lastName" },
+ AuxiliaryFields = { "age" }
+ }
  };
- templateRequest.Fields.Add("firstName", new() { Description = "Given name" });
- templateRequest.Fields.Add("lastName", new());
- templateRequest.Fields.Add("age", new() { Optional = true }); // TODO - use FieldType.NUMBER once schema validation is fixed.
 
- var template = await trinsic.Template.CreateAsync(templateRequest);
+ var template = await trinsic.Template.CreateAsync(createRequest);
  // }
 
  template.Should().NotBeNull();
@@ -426,12 +444,40 @@ public async Task DemoTemplatesWithIssuance() {
  template.Data.SchemaUri.Should().NotBeNull();
 
  var templateId = template.Data.Id;
+ 
+ // update template
+ // updateTemplate() {
+ UpdateCredentialTemplateRequest updateRequest = new() {
+ Id = templateId,
+ Title = "New Title",
+ Description = "New Description",
+ Fields = {
+ { "firstName", new() { Title = "New title for firstName" } },
+ { "lastName", new() { Description = "New description for lastName" } }
+ },
+ FieldOrdering =
+ {
+ { "age", new() { Order = 0, Section = "Misc" } },
+ { "firstName", new() { Order = 1, Section = "Full Name" } },
+ { "lastName", new() { Order = 2, Section = "Full Name" } },
+ },
+ AppleWalletOptions = new()
+ {
+ PrimaryField = "age",
+ SecondaryFields = { "firstName", "lastName" }
+ }
+ };
+
+ var updatedTemplate = await trinsic.Template.UpdateAsync(updateRequest);
+ // }
+
+ updatedTemplate.UpdatedTemplate.Title.Should().Be(updateRequest.Title);
 
  // issue credential from this template
  var values = JsonSerializer.Serialize(new {
  firstName = "Jane",
  lastName = "Doe",
- age = "42"
+ age = 42
  });
 
  // issueFromTemplate() {

go/services/template_service_test.go

@@ -3,12 +3,9 @@ package services
 import (
 "context"
 "encoding/json"
-"fmt"
-"github.com/google/uuid"
 "github.com/stretchr/testify/assert"
 "github.com/trinsic-id/sdk/go/proto/services/verifiablecredentials/templates/v1/template"
 "github.com/trinsic-id/sdk/go/proto/services/verifiablecredentials/v1/credential"
-
 "testing"
 )
 
@@ -21,10 +18,38 @@ func TestTemplatesDemo(t *testing.T) {
 
 // create example template
 // createTemplate() {
-templateRequest := &template.CreateCredentialTemplateRequest{Name: fmt.Sprintf("Example Template - %s", uuid.New()), AllowAdditionalFields: false, Fields: make(map[string]*template.TemplateField)}
-templateRequest.Fields["firstName"] = &template.TemplateField{Description: "Given name"}
-templateRequest.Fields["lastName"] = &template.TemplateField{}
-templateRequest.Fields["age"] = &template.TemplateField{Type: template.FieldType_NUMBER, Optional: true}
+templateRequest := &template.CreateCredentialTemplateRequest{
+Name: "An Example Credential",
+Title: "Example Credential",
+Description: "A credential for Trinsic's SDK samples",
+AllowAdditionalFields: false,
+Fields: map[string]*template.TemplateField{
+"firstName": {
+Title: "First Name",
+Description: "Given name of holder",
+},
+"lastName": {
+Title: "Last Name",
+Description: "Surname of holder",
+Optional: true,
+},
+"age": {
+Title: "Age",
+Description: "Age in years of holder",
+Type: template.FieldType_NUMBER,
+},
+},
+FieldOrdering: map[string]*template.FieldOrdering{
+"firstName": {Order: 0, Section: "Name"},
+"lastName": {Order: 1, Section: "Name"},
+"age": {Order: 2, Section: "Miscellaneous"},
+},
+AppleWalletOptions: &template.AppleWalletOptions{
+PrimaryField: "firstName",
+SecondaryFields: []string{"lastName"},
+AuxiliaryFields: []string{"age"},
+},
+}
 
 templateResponse, err := trinsic.Template().Create(context.Background(), templateRequest)
 // }
@@ -35,6 +60,40 @@ func TestTemplatesDemo(t *testing.T) {
 assert2.NotNil(templateResponse.Data.Id)
 assert2.NotNil(templateResponse.Data.SchemaUri)
 
+templateId := templateResponse.Data.Id
+
+// updateTemplate() {
+var newTemplateTitle = "New Title"
+var newTemplateDescription = "New Description"
+var newFirstNameTitle = "New title for firstName"
+var newLastNameDescription = "New description for lastName"
+
+updateRequest := &template.UpdateCredentialTemplateRequest{
+Id: templateId,
+Title: &newTemplateTitle,
+Description: &newTemplateDescription,
+Fields: map[string]*template.TemplateFieldPatch{
+"firstName": {Title: &newFirstNameTitle},
+"lastName": {Description: &newLastNameDescription},
+},
+FieldOrdering: map[string]*template.FieldOrdering{
+"age": {Order: 0, Section: "Misc"},
+"firstName": {Order: 1, Section: "Full Name"},
+"lastName": {Order: 2, Section: "Full Name"},
+},
+AppleWalletOptions: &template.AppleWalletOptions{
+PrimaryField: "age",
+SecondaryFields: []string{"firstName", "lastName"},
+},
+}
+
+updateResponse, err := trinsic.Template().Update(context.Background(), updateRequest)
+// }
+
+if !assert2.Nil(err) && !assert2.NotNil(updateResponse) {
+return
+}
+
 // issue credential from this template
 values := struct {
 FirstName string
@@ -93,9 +152,9 @@ func TestTemplatesDemo(t *testing.T) {
 }
 
 // updateCredentialStatus() {
-updateResponse, err := trinsic.Credential().UpdateStatus(context.Background(), &credential.UpdateStatusRequest{CredentialStatusId: "", Revoked: true})
+updateStatusResponse, err := trinsic.Credential().UpdateStatus(context.Background(), &credential.UpdateStatusRequest{CredentialStatusId: "", Revoked: true})
 // }
-if updateResponse != nil {
+if updateStatusResponse != nil {
 }
 
 }