feat(prism-agent): Add OAS specification to the schema registry endpoint

prism-agent/service/api/http/pollux/schemas.yaml

@@ -8,102 +8,240 @@ components:
         - verificationMethod
         - proofPurpose
         - proofValue
+        - jws
       type: object
       properties:
         type:
           type: string
+          description: The type of cryptographic signature algorithm used to generate
+            the proof
+          example: Ed25519Signature2018
         created:
           type: string
+          description: The date and time at which the proof was created, in UTC format.<br/>This
+            field is used to ensure that the proof was generated before or at the
+            same time as the credential schema itself
           format: date-time
+          example: 2022-03-10T12:00Z
         verificationMethod:
           type: string
+          description: The verification method used to generate the proof<br/>This
+            is usually a DID and key ID combination that can be used to look up the
+            public key needed to verify the proof
+          example: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff#key-1
         proofPurpose:
           type: string
+          description: 'The purpose of the proof (for example: `assertionMethod`)<br/>This
+            indicates that the proof is being used to assert that the issuer really
+            issued this credential schema instance'
+          example: assertionMethod
         proofValue:
           type: string
+          description: The cryptographic signature value that was generated using
+            the private key associated with the verification method, and which can
+            be used to verify the proof
+          example: FiPfjknHikKmZ...
+        jws:
+          type: string
+          description: The JSON Web Signature (JWS) that contains the proof information
+          example: eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il0sImt0eSI6Ik...
         domain:
           type: string
+          description: It specifies the domain context within which the credential
+            schema and proof are being used
+          example: prims.atala.com
+      description: A digital signature over the Credential Schema for the sake of
+        asserting authorship. A piece of Metadata.
+      example: Proof(Ed25519Signature2018,2022-03-10T12:00Z,did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff#key-1,assertionMethod,FiPfjknHikKmZ...,eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il0sImt0eSI6Ik...,Some(prims.atala.com))
 
-    VerifiableCredentialSchema:
+    CredentialSchemaInput:
       required:
-        - id
         - name
         - version
-        - author
-        - authored
+        - type
+        - schema
       type: object
       properties:
-        id:
-          type: string
-          format: uuid
         name:
           type: string
+          description: A human-readable name for the credential schema. A piece of
+            Metadata.
+          example: DrivingLicense
         version:
           type: string
-        tags:
-          type: array
-          items:
-            type: string
+          description: Denotes the revision of a given Credential Schema. It should
+            follow semantic version convention to describe the impact of the schema
+            evolution
+          example: 1.0.0
         description:
           type: string
-        attributes:
+          description: A human-readable description of the credential schema
+          example: Simple credential schema for the driving licence verifiable credential.
+            This field is not a part of W3C specification
+        type:
+          type: string
+          description: This field resolves to a JSON schema with details about the
+            schema metadata that applies to the schema. A piece of Metadata.
+          example: https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json
+        schema:
+          description: |-
+            Valid JSON Schema where the Credential Schema data fields are defined
+            A piece of Metadata
+        tags:
           type: array
           items:
             type: string
-        author:
-          type: string
-        authored:
-          type: string
-          format: date-time
-        proof:
-          $ref: "#/components/schemas/Proof"
+          description: Tokens that allow to lookup and filter the credential schema
+            records. This field is not a part of W3C specification
+          examples:
+            - driving
+            - licence
+            - id
+            -
 
-    VerifiableCredentialSchemaPage:
-      allOf:
-        - $ref: "../shared/schemas.yaml#/components/schemas/Pagination"
-        - type: object
-          required: [contents]
-          properties:
-            contents:
-              type: array
-              items:
-                $ref: "#/components/schemas/VerifiableCredentialSchema"
 
-    VerificationPolicyConstraint:
+    CredentialSchemaPageResponse:
       required:
-        - schemaId
+        - kind
+        - self
+        - pageOf
       type: object
       properties:
-        schemaId:
-          type: string
-        trustedIssuers:
+        contents:
           type: array
           items:
-            type: string
+            $ref: '#/components/schemas/CredentialSchemaResponse'
+          description: A sequence of CredentialSchemaResponse objects representing
+            the list of credential schemas that the API response contains
+          examples: []
+        kind:
+          type: string
+          description: A string field indicating the type of the API response. In
+            this case, it will always be set to `CredentialSchemaPage`
+          example: CredentialSchemaPage
+        self:
+          type: string
+          description: A string field containing the URL of the current API endpoint
+          example: /prism-agent/schema-registry/schemas?skip=10&limit=10
+        pageOf:
+          type: string
+          description: A string field indicating the type of resource that the contents
+            field contains
+          example: /prism-agent/schema-registry/schemas
+        next:
+          type: string
+          description: An optional string field containing the URL of the next page
+            of results.<br/> If the API response does not contain any more pages,
+            this field should be set to None.
+          example: /prism-agent/schema-registry/schemas?skip=20&limit=10
+        previous:
+          type: string
+          description: An optional string field containing the URL of the previous
+            page of results.<br/>If the API response is the first page of results,
+            this field should be set to None.
+          example: /prism-agent/schema-registry/schemas?skip=0&limit=10
+
 
-    VerificationCredentialSchemaInput:
+    CredentialSchemaResponse:
       required:
+        - guid
+        - id
         - name
         - version
+        - description
+        - type
+        - schema
+        - author
+        - authored
+        - kind
+        - self
       type: object
       properties:
-        id:
+        guid:
           type: string
+          description: Globally unique id of the credential schema<br/>It's composed
+            from the bytes of the string that contain the `authored`, `name`, and
+            `version` values<br/>The string format looks like the resource identifier:<br/>`author`/`id`?version=`version`
           format: uuid
+          example: 0527aea1-d131-3948-a34d-03af39aba8b4
+        id:
+          type: string
+          description: A locally unique identifier to address the schema. UUID is
+            generated by the backend
+          example: 0527aea1-d131-3948-a34d-03af39aba8b5
+        longId:
+          type: string
+          description: Resource id of the credential schema. Contains the `author`'s
+            DID, `id` and `version` fields.
+          example: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff/0527aea1-d131-3948-a34d-03af39aba8b4?version=1.0.0
         name:
           type: string
+          description: A human-readable name for the credential schema. A piece of
+            Metadata.
+          example: DrivingLicense
         version:
           type: string
-        description:
-          type: string
-        attributes:
+          description: Denotes the revision of a given Credential Schema. It should
+            follow semantic version convention to describe the impact of the schema
+            evolution
+          example: 1.0.0
+        tags:
           type: array
           items:
             type: string
+          description: Tokens that allow to lookup and filter the credential schema
+            records. This field is not a part of W3C specification
+          examples:
+            - driving
+            - licence
+            - id
+        description:
+          type: string
+          description: A human-readable description of the credential schema
+          example: Simple credential schema for the driving licence verifiable credential.
+            This field is not a part of W3C specification
+        type:
+          type: string
+          description: This field resolves to a JSON schema with details about the
+            schema metadata that applies to the schema. A piece of Metadata.
+          example: https://w3c-ccg.github.io/vc-json-schemas/schema/2.0/schema.json
+        schema:
+          description: |-
+            Valid JSON Schema where the Credential Schema data fields are defined
+            A piece of Metadata
+        author:
+          type: string
+          description: DID of the identity which authored the credential schema. A
+            piece of Metadata.
+          example: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff
         authored:
           type: string
+          description: '[RFC3339](https://www.rfc-editor.org/rfc/rfc3339) date on
+            which the credential schema was created. A piece of Metadata.'
           format: date-time
-        tags:
+          example: 2022-03-10T12:00Z
+        proof:
+          $ref: '#/components/schemas/Proof'
+        kind:
+          type: string
+          description: A string that identifies the type of resource being returned
+            in the response
+          example: CredentialSchema
+        self:
+          type: string
+          description: The URL that uniquely identifies the resource being returned
+            in the response
+          example: /prism-agent/schema-registry/schemas/0527aea1-d131-3948-a34d-03af39aba8b4
+
+
+    VerificationPolicyConstraint:
+      required:
+        - schemaId
+      type: object
+      properties:
+        schemaId:
+          type: string
+        trustedIssuers:
           type: array
           items:
             type: string

prism-agent/service/api/http/prism-agent-openapi-spec.yaml

@@ -211,7 +211,8 @@ paths:
       tags:
         - Schema Registry
       summary: Lookup schemas by indexed fields
-      description: "Lookup schemas by `author`, `name`, `tags` parameters"
+      description: "Lookup schemas by `author`, `name`, `tags` parameters and control
+        the pagination by `offset` and `limit` parameters"
       parameters:
         - $ref: "./shared/parameters.yaml#/components/parameters/offset"
         - $ref: "./shared/parameters.yaml#/components/parameters/limit"
@@ -241,68 +242,68 @@ paths:
           content:
             application/json:
               schema:
-                $ref: "./pollux/schemas.yaml#/components/schemas/VerifiableCredentialSchemaPage"
+                $ref: "./pollux/schemas.yaml#/components/schemas/CredentialSchemaPageResponse"
         "400":
           $ref: "./shared/responses.yaml#/components/responses/BadRequest"
         "500":
           $ref: "./shared/responses.yaml#/components/responses/InternalServerError"
+
     post:
       operationId: createSchema
       tags:
         - Schema Registry
       summary: Publish new schema to the schema registry
       description:
-        Publish the new schema with attributes to the schema registry on
-        behalf of Cloud Agent. Schema will be signed by the keys of Cloud Agent and
-        issued by the DID that corresponds to it
+        Create the new credential schema record with metadata and internal JSON Schema on behalf of Cloud Agent
+        The credential schema will be signed by the keys of Cloud Agent and issued by the DID that corresponds to it
       requestBody:
-        description: Create schema input object with the metadata and attributes
+        description: JSON object required for the credential schema creation
         content:
           application/json:
             schema:
-              $ref: ./pollux/schemas.yaml#/components/schemas/VerificationCredentialSchemaInput
+              $ref: ./pollux/schemas.yaml#/components/schemas/CredentialSchemaInput
         required: true
       responses:
         "201":
-          description: "Schema successfully created"
+          description: "The new credential schema record is successfully created"
           content:
             application/json:
               schema:
-                $ref: ./pollux/schemas.yaml#/components/schemas/VerifiableCredentialSchema
+                $ref: ./pollux/schemas.yaml#/components/schemas/CredentialSchemaResponse
         "400":
           $ref: "./shared/responses.yaml#/components/responses/BadRequest"
         "500":
           $ref: "./shared/responses.yaml#/components/responses/InternalServerError"
-  /schema-registry/schemas/{id}:
+
+  /schema-registry/schemas/{guid}:
     get:
-      operationId: getSchemaById
       tags:
         - Schema Registry
-      summary: Fetch the schema from the registry by id
-      description:
-        Fetch the schema by the unique identifier. Verifiable Credential
-        Schema in json format is returned.
+      summary: Fetch the schema from the registry by `guid`
+      description: Fetch the credential schema by the unique identifier
+      operationId: getSchemaById
       parameters:
-        - name: id
+        - name: guid
           in: path
-          description: Get the schema by id
+          description: Globally unique identifier of the credential schema object
           required: true
           schema:
             type: string
             format: uuid
       responses:
         "200":
-          description: "Verifiable credential Schema"
+          description: ''
           content:
             application/json:
               schema:
-                $ref: ./pollux/schemas.yaml#/components/schemas/VerifiableCredentialSchema
+                $ref: './pollux/schemas.yaml#/components/schemas/CredentialSchemaResponse'
         "404":
           $ref: "./shared/responses.yaml#/components/responses/NotFound"
         "400":
           $ref: "./shared/responses.yaml#/components/responses/BadRequest"
         "500":
           $ref: "./shared/responses.yaml#/components/responses/InternalServerError"
+
   # ----------------------------------
   # Verification Policies
   # ----------------------------------