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

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

@@ -8,102 +8,333 @@ 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. 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:00:00Z"
         verificationMethod:
           type: string
+          description: The verification method used to generate the proof. 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`). 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:
+        type: Ed25519Signature2018
+        created: "2022-03-10T12:00:00Z"
+        verificationMethod: did:prism:4a5b5cf0a513e83b598bbea25cd6196746747f361a73ef77068268bc9bd732ff#key-1
+        proofPurpose: assertionMethod
+        proofValue: FiPfjknHikKmZ...
+        jws: eyJhbGciOiJFZERTQSIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il0sImt0eSI6Ik...
+        domain: 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
+          pattern: ^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$
         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:
+          type: object
+          description: |-
+            Valid JSON Schema where the Credential Schema data fields are defined
+            A piece of Metadata
+          example:
+            example:
+              $id: driving-license-1.0
+              $schema: https://json-schema.org/draft/2020-12/schema
+              description: Driving License
+              type: object
+              properties:
+                credentialSubject:
+                  type: object
+                  properties:
+                    emailAddress:
+                      type: string
+                      format: email
+                    givenName:
+                      type: string
+                    familyName:
+                      type: string
+                    dateOfIssuance:
+                      type: datetime
+                    drivingLicenseID:
+                      type: string
+                    drivingClass:
+                      type: integer
+                    required:
+                      - emailAddress
+                      - familyName
+                      - dateOfIssuance
+                      - drivingLicenseID
+                      - drivingClass
+                    additionalProperties: true
+        tags:
           type: array
           items:
             type: string
-        author:
-          type: string
-        authored:
-          type: string
-          format: date-time
-        proof:
-          $ref: "#/components/schemas/Proof"
-
-    VerifiableCredentialSchemaPage:
-      allOf:
-        - $ref: "../shared/schemas.yaml#/components/schemas/Pagination"
-        - type: object
-          required: [contents]
-          properties:
-            contents:
-              type: array
-              items:
-                $ref: "#/components/schemas/VerifiableCredentialSchema"
+          description:
+            Tokens that allow to lookup and filter the credential schema
+            records. This field is not a part of W3C specification
+          example:
+            - driving
+            - licence
+            - id
 
-    VerificationPolicyConstraint:
+    CredentialSchemaResponsePage:
       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
+        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. 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. 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. It's composed
+            from the bytes of the string that contain the `authored`, `name`, and
+            `version` values. The string format looks like the resource identifier: `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
+          example:
+            - 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:
+          type: object
+          description: |-
+            Valid JSON Schema where the Credential Schema data fields are defined
+            A piece of Metadata
+          example:
+            example:
+              $id: driving-license-1.0
+              $schema: https://json-schema.org/draft/2020-12/schema
+              description: Driving License
+              type: object
+              properties:
+                credentialSubject:
+                  type: object
+                  properties:
+                    emailAddress:
+                      type: string
+                      format: email
+                    givenName:
+                      type: string
+                    familyName:
+                      type: string
+                    dateOfIssuance:
+                      type: datetime
+                    drivingLicenseID:
+                      type: string
+                    drivingClass:
+                      type: integer
+                    required:
+                      - emailAddress
+                      - familyName
+                      - dateOfIssuance
+                      - drivingLicenseID
+                      - drivingClass
+                    additionalProperties: true
+        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:00: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