From a20905e93328d36f5a8ec35e2a7e7978c1914b2f Mon Sep 17 00:00:00 2001 From: wes-smith Date: Thu, 18 Apr 2024 18:22:17 -0400 Subject: [PATCH 01/16] Add Exchanges section and endpoints. --- exchanges.html | 20 +++++++ exchanges.yml | 140 +++++++++++++++++++++++++++++++++++++++++++++++++ index.html | 56 ++++++++++++++++++++ respec-oas.js | 3 ++ 4 files changed, 219 insertions(+) create mode 100644 exchanges.html create mode 100644 exchanges.yml diff --git a/exchanges.html b/exchanges.html new file mode 100644 index 0000000..38e167a --- /dev/null +++ b/exchanges.html @@ -0,0 +1,20 @@ + + + + W3C CCG - VC Verifier API + + + + + + + + + + + \ No newline at end of file diff --git a/exchanges.yml b/exchanges.yml new file mode 100644 index 0000000..58175ef --- /dev/null +++ b/exchanges.yml @@ -0,0 +1,140 @@ +paths: + /workflows: + post: + summary: Creates a new workflow and returns workflowId in the response body. + tags: + - Credentials + security: + - networkAuth: [] + - oAuth2: [] + - zCap: [] + operationId: createWorkflow + description: Creates a new workflow and returns workflowId in the response body. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateWorkflowRequest" + description: Parameters for creating a workflow. + responses: + "200": + description: Workflow successfully created! + content: + application/json: + schema: + $ref: "#/components/schemas/CreateWorkflowResponse" + "400": + description: Invalid input + "401": + description: Not Authorized + "500": + description: Internal Error + + /workflows/{workflowId}: + get: + summary: Gets the configuration of an existing workflow and returns it in the response body. + tags: + - Credentials + security: + - networkAuth: [] + - oAuth2: [] + - zCap: [] + operationId: getWorkflowConfiguration + description: Gets the configuration of an existing workflow and returns it in the response body. + responses: + "200": + description: Workflow configuration retrieved! + content: + application/json: + schema: + $ref: "#/components/schemas/GetWorkflowResponse" + "400": + description: Invalid input + "401": + description: Not Authorized + "500": + description: Internal Error + /workflows/{workflowId}/exchanges: + post: + summary: Creates a new exchange and returns workflowId in the response body. + tags: + - Credentials + security: + - networkAuth: [] + - oAuth2: [] + - zCap: [] + operationId: createWorkflow + description: Creates a new workflow and returns workflowId in the response body. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateExchangeRequest" + description: Parameters for creating a workflow. + responses: + "200": + description: Workflow successfully created! + content: + application/json: + schema: + $ref: "#/components/schemas/CreateWorkflowResponse" + "400": + description: Invalid input + "401": + description: Not Authorized + "500": + description: Internal Error + /workflows/{workflowId}/exchanges/{exchangeId}: + get: + summary: Gets the state of an existing exchange and returns it in the response body. + tags: + - Credentials + security: + - networkAuth: [] + - oAuth2: [] + - zCap: [] + operationId: getWorkflowConfiguration + description: Gets the configuration of an existing workflow and returns it in the response body. + responses: + "200": + description: Workflow configuration retrieved! + content: + application/json: + schema: + $ref: "#/components/schemas/GetExchangeResponse" + "400": + description: Invalid input + "401": + description: Not Authorized + "500": + description: Internal Error + post: + summary: Participate in an exchange by passing either a. + tags: + - Credentials + security: + - networkAuth: [] + - oAuth2: [] + - zCap: [] + operationId: createWorkflow + description: Creates a new workflow and returns workflowId in the response body. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateWorkflowRequest" + description: Parameters for creating a workflow. + responses: + "200": + description: Workflow successfully created! + content: + application/json: + schema: + $ref: "#/components/schemas/ExchangeParticipationResponse" + "400": + description: Invalid input + "401": + description: Not Authorized + "500": + description: Internal Error +components: diff --git a/index.html b/index.html index b30dfaf..473a4e2 100644 --- a/index.html +++ b/index.html @@ -775,6 +775,62 @@

Create Challenge

+
+

Workflows and Exchanges

+

+The following APIs are defined for using workflows and exchanges for credential use cases that require crossing trust boundaries: +

+ +
+ +
+

Create Workflow

+

+

+ +
+
+ +
+

Get Workflow Configuration

+

+

+ +
+
+ +
+

Create Exchange

+

+

+ +
+
+ +
+

Participate in an Exchange

+

+

+ +
+
+ +
+

Get Exchange State

+

+

+ +
+
+ +
+

Presenting

diff --git a/respec-oas.js b/respec-oas.js index ab184fb..d8ef465 100644 --- a/respec-oas.js +++ b/respec-oas.js @@ -329,6 +329,9 @@ async function injectOas(config, document) { const issuerApi = await SwaggerParser.validate('issuer.yml'); console.log('API name: %s, Version: %s', issuerApi.info.title, issuerApi.info.version); + const exchangesApi = await SwaggerParser.validate('exchanges.yml'); + console.log('API name: %s, Version: %s', + exchangesApi.info.title, exchangesApi.info.version); const verifierApi = await SwaggerParser.validate('verifier.yml'); console.log('API name: %s, Version: %s', verifierApi.info.title, verifierApi.info.version); From ec21327085c194fcd39aab4ead6345980269c785 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Sat, 20 Apr 2024 13:50:23 -0400 Subject: [PATCH 02/16] Add body definitions. --- exchanges.yml | 108 ++++++++++++++++++++++++++++++++++++++------------ respec-oas.js | 2 +- 2 files changed, 83 insertions(+), 27 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index 58175ef..b814692 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -1,7 +1,18 @@ +openapi: 3.0.0 +info: + version: "0.0.3-unstable" + title: VC Exchanges API + description: This is an Experimental Open API Specification for the [VC Data Model](https://www.w3.org/TR/vc-data-model/). + license: + name: W3C Software and Document License + url: http://www.w3.org/Consortium/Legal/copyright-software. + contact: + name: GitHub Source Code + url: https://github.com/w3c-ccg/vc-api paths: /workflows: post: - summary: Creates a new workflow and returns workflowId in the response body. + summary: Passing an empty body to this endpoint creates a new workflow and returns its information in the response body. tags: - Credentials security: @@ -10,12 +21,6 @@ paths: - zCap: [] operationId: createWorkflow description: Creates a new workflow and returns workflowId in the response body. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/CreateWorkflowRequest" - description: Parameters for creating a workflow. responses: "200": description: Workflow successfully created! @@ -29,7 +34,6 @@ paths: description: Not Authorized "500": description: Internal Error - /workflows/{workflowId}: get: summary: Gets the configuration of an existing workflow and returns it in the response body. @@ -56,28 +60,22 @@ paths: description: Internal Error /workflows/{workflowId}/exchanges: post: - summary: Creates a new exchange and returns workflowId in the response body. + summary: Passing an empty body to this endpoint creates a new exchange and returns exchangeId and time to live in the response body. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] - operationId: createWorkflow - description: Creates a new workflow and returns workflowId in the response body. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/CreateExchangeRequest" - description: Parameters for creating a workflow. + operationId: createExchange + description: Passing an empty body to this endpoint creates a new exchange and returns exchangeId and time to live in the response body. responses: "200": - description: Workflow successfully created! + description: Exchange successfully created! content: application/json: schema: - $ref: "#/components/schemas/CreateWorkflowResponse" + $ref: "#/components/schemas/CreateExchangeResponse" "400": description: Invalid input "401": @@ -109,28 +107,32 @@ paths: "500": description: Internal Error post: - summary: Participate in an exchange by passing either a. + summary: Participate in an exchange by passing either a credential to be issued or a Verifiable Presentation. tags: - Credentials security: - networkAuth: [] - oAuth2: [] - zCap: [] - operationId: createWorkflow - description: Creates a new workflow and returns workflowId in the response body. + operationId: participateInExchange + description: Participate in an exchange by passing either a credential to be issued or a Verifiable Presentation. requestBody: content: application/json: schema: - $ref: "#/components/schemas/CreateWorkflowRequest" - description: Parameters for creating a workflow. + oneOf: + - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" + - $ref: "./components/Credential.yml#/components/schemas/Credential" + description: Either responses: "200": - description: Workflow successfully created! + description: Exchange completed! content: application/json: schema: - $ref: "#/components/schemas/ExchangeParticipationResponse" + oneOf: + - $ref: "./components/IssueCredentialSuccess.yml#/components/schemas/IssueCredentialSuccess" + - $ref: "./components/VerifyPresentationResult.yml#/components/schemas/VerificationResult" "400": description: Invalid input "401": @@ -138,3 +140,57 @@ paths: "500": description: Internal Error components: + schemas: + CreateWorkflowResponse: + type: object + additionalProperties: false + description: Object containing information about a created workflow. + properties: + workflowId: + type: string + description: An identifier for the created workflow. + GetWorkflowResponse: + type: object + additionalProperties: false + description: Object containing information about a workflow. + properties: + exchanges: + type: array + description: The identifiers of the current exchanges associated with the workflow instance. + items: + type: string + authorization: + type: array + description: Metadata for the authorization mechanisms active on the workflow instance (e.g OAuth tokens, zCaps). + items: + type: string + CreateExchangeResponse: + type: object + additionalProperties: false + description: Object containing information about a created exchange. + properties: + exchangeId: + type: string + description: An identifier for the created exchange. + ttl: + type: string + description: The time to live for the created exchange. + GetExchangeResponse: + type: object + additionalProperties: false + description: Object containing information about an active exchange. + properties: + exchangeId: + type: string + description: An identifier for the exchange. + ttl: + type: string + description: The time to live for the exchange. + nextStep: + type: string + description: The interaction the exchange is expecting to happen next. + completedSteps: + type: array + description: The steps completed by the exchange previously. + items: + type: string diff --git a/respec-oas.js b/respec-oas.js index d8ef465..22eb2d9 100644 --- a/respec-oas.js +++ b/respec-oas.js @@ -338,7 +338,7 @@ async function injectOas(config, document) { const holderApi = await SwaggerParser.validate('holder.yml'); console.log('API name: %s, Version: %s', holderApi.info.title, holderApi.info.version); - const apis = [issuerApi, verifierApi, holderApi]; + const apis = [issuerApi, verifierApi, holderApi, exchangesApi]; buildApiSummaryTables({config, document, apis}); buildEndpointDetails({config, document, apis}); From c285e0eabaa93966ffdff5eb3a0734075d4960ac Mon Sep 17 00:00:00 2001 From: wes-smith Date: Sat, 20 Apr 2024 16:39:14 -0400 Subject: [PATCH 03/16] Update body and endpoint definitions. --- exchanges.yml | 45 +++++++++++++++++++++++++++++++++++++-------- 1 file changed, 37 insertions(+), 8 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index b814692..900611d 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -68,7 +68,12 @@ paths: - oAuth2: [] - zCap: [] operationId: createExchange - description: Passing an empty body to this endpoint creates a new exchange and returns exchangeId and time to live in the response body. + description: Creates a new exchange and returns exchangeId and time to live in the response body. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateExchangeRequest" responses: "200": description: Exchange successfully created! @@ -91,11 +96,11 @@ paths: - networkAuth: [] - oAuth2: [] - zCap: [] - operationId: getWorkflowConfiguration - description: Gets the configuration of an existing workflow and returns it in the response body. + operationId: getExchangeConfiguration + description: Gets the configuration of an existing exchange and returns it in the response body. responses: "200": - description: Workflow configuration retrieved! + description: Exchange configuration retrieved! content: application/json: schema: @@ -107,7 +112,7 @@ paths: "500": description: Internal Error post: - summary: Participate in an exchange by passing either a credential to be issued or a Verifiable Presentation. + summary: Participate in an exchange by passing either a credential to be issued or a Verifiable Presentation. Posting an empty body will start the exchange. tags: - Credentials security: @@ -115,7 +120,7 @@ paths: - oAuth2: [] - zCap: [] operationId: participateInExchange - description: Participate in an exchange by passing either a credential to be issued or a Verifiable Presentation. + description: Participate in an exchange by passing either a credential to be issued or a Verifiable Presentation. Posting an empty body will start the exchange. requestBody: content: application/json: @@ -164,6 +169,19 @@ components: description: Metadata for the authorization mechanisms active on the workflow instance (e.g OAuth tokens, zCaps). items: type: string + CreateExchangeRequest: + type: object + additionalProperties: false + description: Object containing information about the exchange to be created. + properties: + ttl: + type: string + description: Time to live for the exchange (ms). + variables: + type: array + description: Template variables to be used in the exchange. MAY be empty. + items: + type: object CreateExchangeResponse: type: object additionalProperties: false @@ -171,10 +189,21 @@ components: properties: exchangeId: type: string - description: An identifier for the created exchange. + description: An identifier for the created exchange . + sequence: + type: string + description: A sequence number for the exchange. Set to "0" on creation. ttl: type: string description: The time to live for the created exchange. + variables: + type: array + description: Template variables to be used in the exchange. + items: + type: object + state: + type: string + description: The status ("pending" | "complete" | "invalid") of the exchange, set to "pending" on creation. GetExchangeResponse: type: object additionalProperties: false @@ -182,7 +211,7 @@ components: properties: exchangeId: type: string - description: An identifier for the exchange. + description: An identifier for the exchange ttl: type: string description: The time to live for the exchange. From 434ed0f7a19e909913c25452b32a56d62746dbb9 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Sat, 20 Apr 2024 17:43:39 -0400 Subject: [PATCH 04/16] Update body and endpoint definitions. --- exchanges.yml | 88 ++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 77 insertions(+), 11 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index 900611d..19ff45f 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -12,7 +12,7 @@ info: paths: /workflows: post: - summary: Passing an empty body to this endpoint creates a new workflow and returns its information in the response body. + summary: Creates a new workflow and returns its information in the response body. tags: - Credentials security: @@ -21,6 +21,11 @@ paths: - zCap: [] operationId: createWorkflow description: Creates a new workflow and returns workflowId in the response body. + requestBody: + content: + application/json: + schema: + $ref: "#/components/schemas/CreateWorkflowRequest" responses: "200": description: Workflow successfully created! @@ -146,6 +151,36 @@ paths: description: Internal Error components: schemas: + CreateWorkflowRequest: + type: object + additionalProperties: false + description: Object containing information for creating a workflow. + properties: + required: + type: object + properties: + steps: + type: object + description: A set of semantically named steps to be used in exchanges created on this workflow. + items: + type: object + initialStep: + type: string + description: The step from the above set that the exchange starts on. + options: + type: object + properties: + controller: + type: string + description: The controller of the instance. + authorization: + type: object + description: Authorization scheme information (e.g. OAuth2 configuration). + credentialTemplates: + type: array + description: One or more VC templates for issuance. + items: + $ref: "#/components/schemas/VerifiableCredentialTemplate" CreateWorkflowResponse: type: object additionalProperties: false @@ -159,16 +194,36 @@ components: additionalProperties: false description: Object containing information about a workflow. properties: - exchanges: - type: array - description: The identifiers of the current exchanges associated with the workflow instance. - items: - type: string - authorization: - type: array - description: Metadata for the authorization mechanisms active on the workflow instance (e.g OAuth tokens, zCaps). - items: - type: string + required: + type: object + properties: + exchanges: + type: array + description: The identifiers of the current exchanges associated with the workflow instance. + items: + type: string + steps: + type: object + description: A set of semantically named steps to be used in exchanges created on this workflow. + items: + type: object + initialStep: + type: string + description: The step from the above set that the exchange starts on. + options: + type: object + properties: + controller: + type: string + description: The controller of the instance. + authorization: + type: object + description: Authorization scheme information (e.g. OAuth2 configuration). + credentialTemplates: + type: array + description: One or more VC templates for issuance. + items: + $ref: "#/components/schemas/VerifiableCredentialTemplate" CreateExchangeRequest: type: object additionalProperties: false @@ -223,3 +278,14 @@ components: description: The steps completed by the exchange previously. items: type: string + VerifiableCredentialTemplate: + type: object + additionalProperties: false + description: A Verifiable Credential template. + properties: + type: + type: string + description: The type of template. + template: + type: string + description: The VC template. From f23a6ff500a894bd18190e505d5bed644551199e Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 23 Apr 2024 13:48:08 -0400 Subject: [PATCH 05/16] Update endpoint, body definitions. --- exchanges.yml | 118 ++++++++++++++++++++++++++++++++++++++++++-------- index.html | 10 ++--- 2 files changed, 104 insertions(+), 24 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index 19ff45f..5b24f86 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -39,7 +39,7 @@ paths: description: Not Authorized "500": description: Internal Error - /workflows/{workflowId}: + /workflows/{localWorkflowId}: get: summary: Gets the configuration of an existing workflow and returns it in the response body. tags: @@ -63,9 +63,9 @@ paths: description: Not Authorized "500": description: Internal Error - /workflows/{workflowId}/exchanges: + /workflows/{localWorkflowId}/exchanges: post: - summary: Passing an empty body to this endpoint creates a new exchange and returns exchangeId and time to live in the response body. + summary: Creates a new exchange and returns exchangeId and time to live in the response body. tags: - Credentials security: @@ -92,7 +92,7 @@ paths: description: Not Authorized "500": description: Internal Error - /workflows/{workflowId}/exchanges/{exchangeId}: + /workflows/{localWorkflowId}/exchanges/{localExchangeId}: get: summary: Gets the state of an existing exchange and returns it in the response body. tags: @@ -117,7 +117,7 @@ paths: "500": description: Internal Error post: - summary: Participate in an exchange by passing either a credential to be issued or a Verifiable Presentation. Posting an empty body will start the exchange. + summary: Participate in an exchange. Posting an empty body will start the exchange or return what the exchange is expecting to complete the next step. tags: - Credentials security: @@ -125,7 +125,7 @@ paths: - oAuth2: [] - zCap: [] operationId: participateInExchange - description: Participate in an exchange by passing either a credential to be issued or a Verifiable Presentation. Posting an empty body will start the exchange. + description: Participate in an exchange. Posting an empty body will start the exchange or return what the exchange is expecting to complete the next step. requestBody: content: application/json: @@ -133,16 +133,14 @@ paths: oneOf: - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" - $ref: "./components/Credential.yml#/components/schemas/Credential" - description: Either + description: Either a credential to be issued or a Verifiable Presentation. responses: "200": - description: Exchange completed! + description: Exchange progressed. content: application/json: schema: - oneOf: - - $ref: "./components/IssueCredentialSuccess.yml#/components/schemas/IssueCredentialSuccess" - - $ref: "./components/VerifyPresentationResult.yml#/components/schemas/VerificationResult" + $ref: "#/components/schemas/ExchangeParticipationResponse" "400": description: Invalid input "401": @@ -180,7 +178,12 @@ components: type: array description: One or more VC templates for issuance. items: - $ref: "#/components/schemas/VerifiableCredentialTemplate" + type: object + properties: + type: + type: string + template: + type: string CreateWorkflowResponse: type: object additionalProperties: false @@ -188,7 +191,7 @@ components: properties: workflowId: type: string - description: An identifier for the created workflow. + description: The URL that uniquely identifies the created workflow. GetWorkflowResponse: type: object additionalProperties: false @@ -204,9 +207,9 @@ components: type: string steps: type: object - description: A set of semantically named steps to be used in exchanges created on this workflow. - items: - type: object + properties: + stepName: + $ref: "#/components/schemas/WorkflowStep" initialStep: type: string description: The step from the above set that the exchange starts on. @@ -223,7 +226,14 @@ components: type: array description: One or more VC templates for issuance. items: - $ref: "#/components/schemas/VerifiableCredentialTemplate" + type: object + properties: + type: + type: string + description: The type of template. + template: + type: string + description: The template itself. CreateExchangeRequest: type: object additionalProperties: false @@ -244,7 +254,7 @@ components: properties: exchangeId: type: string - description: An identifier for the created exchange . + description: The URL that uniquely identifies the exchange. sequence: type: string description: A sequence number for the exchange. Set to "0" on creation. @@ -259,6 +269,29 @@ components: state: type: string description: The status ("pending" | "complete" | "invalid") of the exchange, set to "pending" on creation. + step: + type: string + description: The semantic string ID for the current step. + ExchangeParticipationResponse: + type: object + additionalProperties: false + description: Either what the exchange is expecting next or a result of the exchange. + properties: + response: + oneOf: + - type: object + properties: + verifiablePresentationRequest: + $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" + - type: object + properties: + verifiablePresentation: + $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" + - type: object + properties: + redirectUrl: + type: string + description: The URL the exchange wishes to redirect the client to. GetExchangeResponse: type: object additionalProperties: false @@ -266,7 +299,7 @@ components: properties: exchangeId: type: string - description: An identifier for the exchange + description: The URL that uniquely identifies the exchange. ttl: type: string description: The time to live for the exchange. @@ -278,6 +311,16 @@ components: description: The steps completed by the exchange previously. items: type: string + WorkflowStep: + type: object + additionalProperties: false + description: Object containing information about a workflow step. + oneOf: + - $ref: "#/components/schemas/StepData" + - type: object + properties: + stepTemplate: + $ref: "#/components/schemas/StepTemplate" VerifiableCredentialTemplate: type: object additionalProperties: false @@ -289,3 +332,40 @@ components: template: type: string description: The VC template. + StepTemplate: + type: object + additionalProperties: false + description: A template for a workflow step. Either this must be present or the other step data must be present, but not both sets. + properties: + type: + type: string + description: The type of template. + template: + type: string + description: The step template. + StepData: + type: object + additionalProperties: false + description: Step data to be included if a template is not used. + properties: + createChallenge: + type: string + description: + verifiablePresentationRequest: + type: object + description: The VPR to send to the user in this step. + $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" + nextStep: + type: string + description: The name of the next step in the sequence. + openId: + type: object + description: Optional information to trigger OID4VP + properties: + createAuthorizationRequest: + type: string + description: If present, auto-generate the OID4VP authorization request from the VPR. Either this or authorizationRequest must be present, but not both. + authorizationRequest: + type: object + + \ No newline at end of file diff --git a/index.html b/index.html index 473a4e2..1319765 100644 --- a/index.html +++ b/index.html @@ -782,7 +782,7 @@

Workflows and Exchanges

+ data-api-path="/workflows /workflows/{localWorkflowId} /workflows/{localWorkflowId}/exchanges /workflows/{localWorkflowId}/exchanges/{localExchangeId}">

Create Workflow

@@ -799,7 +799,7 @@

Get Workflow Configuration

+ data-api-endpoint="get /workflows/{localWorkflowId}">
@@ -808,7 +808,7 @@

Create Exchange

+ data-api-endpoint="post /workflows/{localWorkflowId}/exchanges">
@@ -817,7 +817,7 @@

Participate in an Exchange

+ data-api-endpoint="post /workflows/{localWorkflowId}/exchanges/{localExchangeId}">
@@ -826,7 +826,7 @@

Get Exchange State

+ data-api-endpoint="get /workflows/{localWorkflowId}/exchanges/{localExchangeId}">
From 7d494adc5c89695ee2d833548e3a2adc3fc1df39 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 23 Apr 2024 13:51:38 -0400 Subject: [PATCH 06/16] Update CreateWorkflowResponse. --- exchanges.yml | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index 5b24f86..ff85860 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -159,9 +159,9 @@ components: properties: steps: type: object - description: A set of semantically named steps to be used in exchanges created on this workflow. - items: - type: object + properties: + stepName: + $ref: "#/components/schemas/WorkflowStep" initialStep: type: string description: The step from the above set that the exchange starts on. @@ -367,5 +367,3 @@ components: description: If present, auto-generate the OID4VP authorization request from the VPR. Either this or authorizationRequest must be present, but not both. authorizationRequest: type: object - - \ No newline at end of file From 95356a40137310de9b9ef375e62ad493f0529a91 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 23 Apr 2024 13:53:47 -0400 Subject: [PATCH 07/16] Update "step" definition. --- exchanges.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/exchanges.yml b/exchanges.yml index ff85860..e9c05ed 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -209,7 +209,10 @@ components: type: object properties: stepName: - $ref: "#/components/schemas/WorkflowStep" + type: object + properties: + step: + $ref: "#/components/schemas/WorkflowStep" initialStep: type: string description: The step from the above set that the exchange starts on. From 95aadc02e6f36efe6faf98fc15330aabe6f9a62c Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 23 Apr 2024 13:55:48 -0400 Subject: [PATCH 08/16] Update step information. --- exchanges.yml | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index e9c05ed..348f1b0 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -161,7 +161,10 @@ components: type: object properties: stepName: - $ref: "#/components/schemas/WorkflowStep" + type: object + properties: + step: + $ref: "#/components/schemas/WorkflowStep" initialStep: type: string description: The step from the above set that the exchange starts on. @@ -197,8 +200,9 @@ components: additionalProperties: false description: Object containing information about a workflow. properties: - required: + stepInformation: type: object + description: Information about the steps required for the workflow. properties: exchanges: type: array From 8b4293c65ce930f3b75ed80e43f80803cebbeb75 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 23 Apr 2024 14:20:55 -0400 Subject: [PATCH 09/16] Update ExchangeParticipationResponse. --- exchanges.yml | 43 ++++++++++++++++++++++--------------------- 1 file changed, 22 insertions(+), 21 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index 348f1b0..20c1aa3 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -273,6 +273,13 @@ components: description: Template variables to be used in the exchange. items: type: object + properties: + type: + type: string + description: The type of template. + template: + type: string + description: The template itself. state: type: string description: The status ("pending" | "complete" | "invalid") of the exchange, set to "pending" on creation. @@ -281,24 +288,21 @@ components: description: The semantic string ID for the current step. ExchangeParticipationResponse: type: object - additionalProperties: false description: Either what the exchange is expecting next or a result of the exchange. - properties: - response: - oneOf: - - type: object - properties: - verifiablePresentationRequest: - $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" - - type: object - properties: - verifiablePresentation: - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" - - type: object - properties: - redirectUrl: - type: string - description: The URL the exchange wishes to redirect the client to. + oneOf: + - type: object + properties: + verifiablePresentationRequest: + $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" + - type: object + properties: + verifiablePresentation: + $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" + - type: object + properties: + redirectUrl: + type: string + description: The URL the exchange wishes to redirect the client to. GetExchangeResponse: type: object additionalProperties: false @@ -320,7 +324,6 @@ components: type: string WorkflowStep: type: object - additionalProperties: false description: Object containing information about a workflow step. oneOf: - $ref: "#/components/schemas/StepData" @@ -357,10 +360,8 @@ components: properties: createChallenge: type: string - description: + description: An optional step directive that tells the exchange to handle challenge management via a VC API verifier service it has a zcap for. verifiablePresentationRequest: - type: object - description: The VPR to send to the user in this step. $ref: "./components/VerifiablePresentationRequest.yml#/components/schemas/VerifiablePresentationRequest" nextStep: type: string From 5e4f6296a78b723de9472706fdc082e038e09d0d Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 23 Apr 2024 14:50:03 -0400 Subject: [PATCH 10/16] Reformat CreateExchangeRequest. --- exchanges.yml | 31 ++++++++++++++++++++++--------- 1 file changed, 22 insertions(+), 9 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index 20c1aa3..72230d1 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -159,9 +159,11 @@ components: properties: steps: type: object + description: One or more steps required to complete an exchange on the workflow. properties: stepName: type: object + description: The name of the step. properties: step: $ref: "#/components/schemas/WorkflowStep" @@ -211,9 +213,11 @@ components: type: string steps: type: object + description: One or more steps required to complete an exchange on the workflow. properties: stepName: type: object + description: The name of the step. properties: step: $ref: "#/components/schemas/WorkflowStep" @@ -243,17 +247,26 @@ components: description: The template itself. CreateExchangeRequest: type: object - additionalProperties: false description: Object containing information about the exchange to be created. properties: - ttl: - type: string - description: Time to live for the exchange (ms). - variables: - type: array - description: Template variables to be used in the exchange. MAY be empty. - items: - type: object + exchangeInformation: + type: object + properties: + ttl: + type: string + description: Time to live for the exchange (ms). + variables: + type: array + description: Template variables to be used in the exchange. + items: + type: object + properties: + type: + type: string + description: The type of template. + template: + type: string + description: The template itself. CreateExchangeResponse: type: object additionalProperties: false From d576f3ff7550265a2cd00eb1fee2ad4e572f8e3c Mon Sep 17 00:00:00 2001 From: wes-smith Date: Tue, 23 Apr 2024 14:52:08 -0400 Subject: [PATCH 11/16] Update exchange participation endpoint. --- exchanges.yml | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index 72230d1..f4c1478 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -131,8 +131,14 @@ paths: application/json: schema: oneOf: - - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" - - $ref: "./components/Credential.yml#/components/schemas/Credential" + - type: object + properties: + verifiablePresentation: + $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" + - type: object + properties: + credential: + $ref: "./components/Credential.yml#/components/schemas/Credential" description: Either a credential to be issued or a Verifiable Presentation. responses: "200": From c4f4b2e550e160d2eed0237e3959a0e0cb93a083 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Mon, 29 Apr 2024 10:48:33 -0400 Subject: [PATCH 12/16] Apply grammar edits to object descriptions. Co-authored-by: Ted Thibodeau Jr --- exchanges.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index f4c1478..641e0dd 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -184,7 +184,7 @@ components: description: The controller of the instance. authorization: type: object - description: Authorization scheme information (e.g. OAuth2 configuration). + description: Authorization scheme information (e.g., OAuth2 configuration). credentialTemplates: type: array description: One or more VC templates for issuance. @@ -238,7 +238,7 @@ components: description: The controller of the instance. authorization: type: object - description: Authorization scheme information (e.g. OAuth2 configuration). + description: Authorization scheme information (e.g., OAuth2 configuration). credentialTemplates: type: array description: One or more VC templates for issuance. From f93bbce89ff08dddecb99af912a9243689f3a755 Mon Sep 17 00:00:00 2001 From: wes-smith Date: Wed, 29 May 2024 13:00:22 -0400 Subject: [PATCH 13/16] Add path parameters, remove unneeded template per code review. --- .../parameters/path/LocalExchangeId.yml | 7 +++++++ .../parameters/path/LocalWorkflowId.yml | 7 +++++++ exchanges.yml | 20 ++++++++----------- 3 files changed, 22 insertions(+), 12 deletions(-) create mode 100644 components/parameters/path/LocalExchangeId.yml create mode 100644 components/parameters/path/LocalWorkflowId.yml diff --git a/components/parameters/path/LocalExchangeId.yml b/components/parameters/path/LocalExchangeId.yml new file mode 100644 index 0000000..a478e99 --- /dev/null +++ b/components/parameters/path/LocalExchangeId.yml @@ -0,0 +1,7 @@ +name: local-exchange-id +description: A local identifier for an exchange instance. +in: path +required: true +schema: + type: string + pattern: "[a-z0-9][a-z0-9\\-]{2,}" \ No newline at end of file diff --git a/components/parameters/path/LocalWorkflowId.yml b/components/parameters/path/LocalWorkflowId.yml new file mode 100644 index 0000000..4f24915 --- /dev/null +++ b/components/parameters/path/LocalWorkflowId.yml @@ -0,0 +1,7 @@ +name: local-workflow-id +description: A local identifier for a workflow instance. +in: path +required: true +schema: + type: string + pattern: "[a-z0-9][a-z0-9\\-]{2,}" \ No newline at end of file diff --git a/exchanges.yml b/exchanges.yml index 641e0dd..1202ec2 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -1,7 +1,7 @@ openapi: 3.0.0 info: version: "0.0.3-unstable" - title: VC Exchanges API + title: VC Exchanges and Workflows API description: This is an Experimental Open API Specification for the [VC Data Model](https://www.w3.org/TR/vc-data-model/). license: name: W3C Software and Document License @@ -50,6 +50,8 @@ paths: - zCap: [] operationId: getWorkflowConfiguration description: Gets the configuration of an existing workflow and returns it in the response body. + parameters: + - $ref: "./components/parameters/path/LocalWorkflowId.yml" responses: "200": description: Workflow configuration retrieved! @@ -74,6 +76,8 @@ paths: - zCap: [] operationId: createExchange description: Creates a new exchange and returns exchangeId and time to live in the response body. + parameters: + - $ref: "./components/parameters/path/LocalWorkflowId.yml" requestBody: content: application/json: @@ -103,6 +107,9 @@ paths: - zCap: [] operationId: getExchangeConfiguration description: Gets the configuration of an existing exchange and returns it in the response body. + parameters: + - $ref: "./components/parameters/path/LocalWorkflowId.yml" + - $ref: "./components/parameters/path/LocalExchangeId.yml" responses: "200": description: Exchange configuration retrieved! @@ -350,17 +357,6 @@ components: properties: stepTemplate: $ref: "#/components/schemas/StepTemplate" - VerifiableCredentialTemplate: - type: object - additionalProperties: false - description: A Verifiable Credential template. - properties: - type: - type: string - description: The type of template. - template: - type: string - description: The VC template. StepTemplate: type: object additionalProperties: false From df8694687ce2d44b569c72bec71afb8c501d732b Mon Sep 17 00:00:00 2001 From: wes-smith Date: Wed, 29 May 2024 15:23:02 -0400 Subject: [PATCH 14/16] Update endpoint definitions. --- exchanges.yml | 83 +++++++++++++++++++++++++-------------------------- 1 file changed, 40 insertions(+), 43 deletions(-) diff --git a/exchanges.yml b/exchanges.yml index 1202ec2..144db9d 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -137,16 +137,9 @@ paths: content: application/json: schema: - oneOf: - - type: object - properties: - verifiablePresentation: - $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" - - type: object - properties: - credential: - $ref: "./components/Credential.yml#/components/schemas/Credential" - description: Either a credential to be issued or a Verifiable Presentation. + properties: + verifiablePresentation: + $ref: "./components/VerifiablePresentation.yml#/components/schemas/VerifiablePresentation" responses: "200": description: Exchange progressed. @@ -167,12 +160,14 @@ components: additionalProperties: false description: Object containing information for creating a workflow. properties: - required: + workflowData: type: object + additionalProperties: false + description: Object containing information for creating a workflow. properties: steps: type: object - description: One or more steps required to complete an exchange on the workflow. + description: One or more steps required to complete an exchange on the workflow. Passing the steps object is REQUIRED. properties: stepName: type: object @@ -182,26 +177,26 @@ components: $ref: "#/components/schemas/WorkflowStep" initialStep: type: string - description: The step from the above set that the exchange starts on. - options: - type: object - properties: + description: The step from the above set that the exchange starts on. Passing intialStep is REQUIRED. controller: type: string - description: The controller of the instance. + description: The controller of the instance. Passing controller is OPTIONAL. authorization: - type: object - description: Authorization scheme information (e.g., OAuth2 configuration). + type: string + description: Authorization scheme information (e.g., OAuth2 configuration). Passing authorization is OPTIONAL. credentialTemplates: type: array - description: One or more VC templates for issuance. + description: One or more VC templates for issuance. Passing credentialTemplates is OPTIONAL. items: type: object properties: type: type: string template: - type: string + type: string + workflowId: + type: string + description: the ID that will be used for the created workflow. workflowId is OPTIONAL. CreateWorkflowResponse: type: object additionalProperties: false @@ -215,40 +210,42 @@ components: additionalProperties: false description: Object containing information about a workflow. properties: - stepInformation: + workflowData: type: object - description: Information about the steps required for the workflow. + additionalProperties: false + description: Object containing information about a created workflow. properties: - exchanges: - type: array - description: The identifiers of the current exchanges associated with the workflow instance. - items: - type: string - steps: + stepInformation: type: object - description: One or more steps required to complete an exchange on the workflow. + description: Information about the steps required for the workflow. Returning stepInformation is REQUIRED. properties: - stepName: + exchanges: + type: array + description: The identifiers of the current exchanges associated with the workflow instance. + items: + type: string + steps: type: object - description: The name of the step. + description: One or more steps required to complete an exchange on the workflow. properties: - step: - $ref: "#/components/schemas/WorkflowStep" - initialStep: - type: string - description: The step from the above set that the exchange starts on. - options: - type: object - properties: + stepName: + type: object + description: The name of the step. + properties: + step: + $ref: "#/components/schemas/WorkflowStep" + initialStep: + type: string + description: The step from the above set that the exchange starts on. controller: type: string - description: The controller of the instance. + description: The controller of the instance. Returning controller is OPTIONAL. authorization: type: object - description: Authorization scheme information (e.g., OAuth2 configuration). + description: Authorization scheme information (e.g., OAuth2 configuration). Returning authorization is OPTIONAL. credentialTemplates: type: array - description: One or more VC templates for issuance. + description: One or more VC templates for issuance. Returning credentialTemplates is OPTIONAL. items: type: object properties: From dd6963d0d19a7cd0c942ef3bae6db9149c61444b Mon Sep 17 00:00:00 2001 From: wes-smith Date: Wed, 29 May 2024 15:36:37 -0400 Subject: [PATCH 15/16] Fix path parameter definitions. --- components/parameters/path/LocalExchangeId.yml | 2 +- components/parameters/path/LocalWorkflowId.yml | 2 +- exchanges.yml | 3 +++ 3 files changed, 5 insertions(+), 2 deletions(-) diff --git a/components/parameters/path/LocalExchangeId.yml b/components/parameters/path/LocalExchangeId.yml index a478e99..7659238 100644 --- a/components/parameters/path/LocalExchangeId.yml +++ b/components/parameters/path/LocalExchangeId.yml @@ -1,4 +1,4 @@ -name: local-exchange-id +name: localExchangeId description: A local identifier for an exchange instance. in: path required: true diff --git a/components/parameters/path/LocalWorkflowId.yml b/components/parameters/path/LocalWorkflowId.yml index 4f24915..1ddfd04 100644 --- a/components/parameters/path/LocalWorkflowId.yml +++ b/components/parameters/path/LocalWorkflowId.yml @@ -1,4 +1,4 @@ -name: local-workflow-id +name: localWorkflowId description: A local identifier for a workflow instance. in: path required: true diff --git a/exchanges.yml b/exchanges.yml index 144db9d..73058f0 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -133,6 +133,9 @@ paths: - zCap: [] operationId: participateInExchange description: Participate in an exchange. Posting an empty body will start the exchange or return what the exchange is expecting to complete the next step. + parameters: + - $ref: "./components/parameters/path/LocalWorkflowId.yml" + - $ref: "./components/parameters/path/LocalExchangeId.yml" requestBody: content: application/json: From dee75b2e92ae13cfd0554ed998ed0d3ed82c6cbe Mon Sep 17 00:00:00 2001 From: wes-smith Date: Wed, 29 May 2024 16:35:27 -0400 Subject: [PATCH 16/16] Fix linting errors. --- exchanges.yml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/exchanges.yml b/exchanges.yml index 73058f0..5c2ab26 100644 --- a/exchanges.yml +++ b/exchanges.yml @@ -1,4 +1,7 @@ openapi: 3.0.0 +servers: + - url: https://verifier.qa.veres.app/verifiers/z1A45ZhWEGMeibHrB15nv8Gk6 + description: Veres Verifier (Quality Assurance) info: version: "0.0.3-unstable" title: VC Exchanges and Workflows API @@ -157,6 +160,8 @@ paths: "500": description: Internal Error components: + securitySchemes: + $ref: "./components/SecuritySchemes.yml#/components/securitySchemes" schemas: CreateWorkflowRequest: type: object