From eb75f71688eea2ca44066bdaf48437ac75f8e0d1 Mon Sep 17 00:00:00 2001 From: Max Kurapov Date: Fri, 21 Oct 2022 16:12:51 +0200 Subject: [PATCH] chore: update shared schema spec for consistency --- openapi/AS/IdP/openapi.yaml | 2 +- openapi/AS/RS/openapi.yaml | 8 +- openapi/AS/client/openapi.yaml | 6 +- openapi/RS/openapi.yaml | 35 +-- openapi/shared/schemas.yaml | 523 +++++++++++++++++---------------- 5 files changed, 294 insertions(+), 280 deletions(-) diff --git a/openapi/AS/IdP/openapi.yaml b/openapi/AS/IdP/openapi.yaml index 243f85bc..21813b5e 100644 --- a/openapi/AS/IdP/openapi.yaml +++ b/openapi/AS/IdP/openapi.yaml @@ -94,7 +94,7 @@ paths: type: object properties: access: - $ref: ../../shared/schemas.yaml#/access + $ref: ../../shared/schemas.yaml#/components/schemas/access '404': description: Not Found operationId: get-grant diff --git a/openapi/AS/RS/openapi.yaml b/openapi/AS/RS/openapi.yaml index 58f6c1e6..614c6440 100644 --- a/openapi/AS/RS/openapi.yaml +++ b/openapi/AS/RS/openapi.yaml @@ -33,9 +33,9 @@ paths: grant: type: string access: - $ref: ../../shared/schemas.yaml#/access + $ref: ../../shared/schemas.yaml#/components/schemas/access key: - $ref: ../../shared/schemas.yaml#/key + $ref: ../../shared/schemas.yaml#/components/schemas/key client_id: type: string description: Opaque client identifier. @@ -86,11 +86,11 @@ paths: description: The proofing method used by the client instance to bind the token to the RS request. resource_server: oneOf: - - $ref: ../../shared/schemas.yaml#/key + - $ref: ../../shared/schemas.yaml#/components/schemas/key - type: string description: 'The identification used to authenticate the resource server making this call, either by value or by reference.' access: - $ref: ../../shared/schemas.yaml#/access + $ref: ../../shared/schemas.yaml#/components/schemas/access required: - access_token - resource_server diff --git a/openapi/AS/client/openapi.yaml b/openapi/AS/client/openapi.yaml index baccb8cf..a21867be 100644 --- a/openapi/AS/client/openapi.yaml +++ b/openapi/AS/client/openapi.yaml @@ -87,7 +87,7 @@ paths: - access properties: access: - $ref: ../../shared/schemas.yaml#/access + $ref: ../../shared/schemas.yaml#/components/schemas/access client: $ref: '#/components/schemas/client' interact: @@ -337,7 +337,7 @@ components: description: An identifier string that the AS can use to identify the client software comprising this client instance. key: oneOf: - - $ref: ../../shared/schemas.yaml#/key + - $ref: ../../shared/schemas.yaml#/components/schemas/key - type: string description: The public key of the client instance to be used in this request or a reference to a key. interact-request: @@ -427,7 +427,7 @@ components: type: integer description: The number of seconds in which the access will expire. The client instance MUST NOT use the access token past this time. An RS MUST NOT accept an access token past this time. access: - $ref: ../../shared/schemas.yaml#/access + $ref: ../../shared/schemas.yaml#/components/schemas/access required: - value - manage diff --git a/openapi/RS/openapi.yaml b/openapi/RS/openapi.yaml index e870a57b..79bdf05f 100644 --- a/openapi/RS/openapi.yaml +++ b/openapi/RS/openapi.yaml @@ -188,7 +188,7 @@ paths: properties: incomingAmount: description: The maximum amount that should be paid into the payment pointer under this incoming payment. - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount expiresAt: type: string description: The date and time when payments into the incoming payment must no longer be accepted. @@ -588,11 +588,12 @@ paths: additionalProperties: false properties: receiver: - $ref: ../shared/schemas.yaml#/receiver + in: path + $ref: ../shared/schemas.yaml#/components/schemas/receiver receiveAmount: - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount sendAmount: - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount required: - receiver description: |- @@ -816,9 +817,9 @@ components: description: A public name for the account. This should be set by the account holder with their provider to provide a hint to counterparties as to the identity of the account holder. readOnly: true assetCode: - $ref: ../shared/schemas.yaml#/assetCode + $ref: ../shared/schemas.yaml#/components/schemas/assetCode assetScale: - $ref: ../shared/schemas.yaml#/assetScale + $ref: ../shared/schemas.yaml#/components/schemas/assetScale authServer: type: string format: uri @@ -876,9 +877,9 @@ components: description: The base64 url-encoded shared secret to use when establishing a STREAM connection. readOnly: true assetCode: - $ref: ../shared/schemas.yaml#/assetCode + $ref: ../shared/schemas.yaml#/components/schemas/assetCode assetScale: - $ref: ../shared/schemas.yaml#/assetScale + $ref: ../shared/schemas.yaml#/components/schemas/assetScale required: - id - ilpAddress @@ -936,10 +937,10 @@ components: default: false incomingAmount: description: The maximum amount that should be paid into the payment pointer under this incoming payment. - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount receivedAmount: description: The total amount that has been paid into the payment pointer under this incoming payment. - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount expiresAt: type: string description: The date and time when payments under this incoming payment will no longer be accepted. @@ -1089,16 +1090,16 @@ components: default: false receiver: description: The URL of the incoming payment or ILP STREAM Connection that is being paid. - $ref: ../shared/schemas.yaml#/receiver + $ref: ../shared/schemas.yaml#/components/schemas/receiver receiveAmount: description: The total amount that should be received by the receiver when this outgoing payment has been paid. - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount sendAmount: description: The total amount that should be sent when this outgoing payment has been paid. - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount sentAmount: description: The total amount that has been sent under this outgoing payment. - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount description: type: string description: Human readable description of the outgoing payment that will be visible to the account holder and shared with the receiver. @@ -1167,11 +1168,11 @@ components: description: The URL of the payment pointer from which this quote's payment would be sent. readOnly: true receiver: - $ref: ../shared/schemas.yaml#/receiver + $ref: ../shared/schemas.yaml#/components/schemas/receiver receiveAmount: - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount sendAmount: - $ref: ../shared/schemas.yaml#/amount + $ref: ../shared/schemas.yaml#/components/schemas/amount expiresAt: type: string description: The date and time when the calculated `sendAmount` is no longer valid. diff --git a/openapi/shared/schemas.yaml b/openapi/shared/schemas.yaml index a3bcfb14..b37067a4 100644 --- a/openapi/shared/schemas.yaml +++ b/openapi/shared/schemas.yaml @@ -1,282 +1,295 @@ -access: - type: array - description: A description of the rights associated with this access token. - items: - $ref: '#/access-item' - allOf: - - contains: - properties: - type: - const: incoming-payment - minContains: 0 - maxContains: 1 - - contains: - properties: - type: - const: outgoing-payment - minContains: 0 - maxContains: 1 - - contains: - properties: - type: - const: quote - minContains: 0 - maxContains: 1 -access-item: - discriminator: - propertyName: type - mapping: - incoming-payment: '#/access-incoming' - outgoing-payment: '#/access-outgoing' - quote: '#/access-quote' - oneOf: - - $ref: '#/access-incoming' - - $ref: '#/access-outgoing' - - $ref: '#/access-quote' - description: The access associated with the access token is described using objects that each contain multiple dimensions of access. - unevaluatedProperties: false -access-incoming: - title: access-incoming - type: object - properties: - type: - type: string - enum: - - incoming-payment - description: The type of resource request as a string. This field defines which other fields are allowed in the request object. - actions: +openapi: 3.1.0 +info: + title: Open Payments - Shared schemas + version: '1.0' + license: + name: Apache 2.0 + identifier: Apache-2.0 + summary: Open Payments - Shared schemas + description: 'Shared schemas used across Open Payments APIs' + contact: + email: tech@interledger.org +components: + schemas: + access: type: array - description: The types of actions the client instance will take at the RS as an array of strings. + description: A description of the rights associated with this access token. items: - type: string - enum: - - create - - complete - - read - - read-all - - list - - list-all + $ref: '#/components/schemas/access-item' allOf: - contains: - $ref: '#/read-actions' + properties: + type: + const: incoming-payment minContains: 0 maxContains: 1 - contains: - $ref: '#/list-actions' + properties: + type: + const: outgoing-payment minContains: 0 maxContains: 1 - uniqueItems: true - identifier: - type: string - format: uri - description: A string identifier indicating a specific resource at the RS. - required: - - type - - actions -access-outgoing: - title: access-outgoing - type: object - properties: - type: - type: string - enum: - - outgoing-payment - description: The type of resource request as a string. This field defines which other fields are allowed in the request object. - actions: - type: array - description: The types of actions the client instance will take at the RS as an array of strings. - items: - type: string - enum: - - create - - read - - read-all - - list - - list-all - allOf: - contains: - $ref: '#/read-actions' + properties: + type: + const: quote minContains: 0 maxContains: 1 - - contains: - $ref: '#/list-actions' - minContains: 0 - maxContains: 1 - uniqueItems: true - identifier: - type: string - format: uri - description: A string identifier indicating a specific resource at the RS. - limits: - $ref: '#/limits-outgoing' - required: - - type - - actions - - identifier -access-quote: - title: access-quote - type: object - properties: - type: - type: string - enum: - - quote - description: The type of resource request as a string. This field defines which other fields are allowed in the request object. - actions: - type: array - description: The types of actions the client instance will take at the RS as an array of strings. - items: - type: string - enum: - - create - - read - - read-all - allOf: - - contains: - $ref: '#/read-actions' - minContains: 0 - maxContains: 1 - uniqueItems: true - required: - - type - - actions -amount: - title: amount - type: object - description: 'All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.' - properties: - value: - type: string - format: uint64 - description: 'The value is an unsigned 64-bit integer amount, represented as a string.' - assetCode: - $ref: '#/assetCode' - assetScale: - $ref: '#/assetScale' - required: - - value - - assetCode - - assetScale -assetCode: - title: Asset code - type: string - description: The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code. -assetScale: - title: Asset scale - type: integer - minimum: 0 - maximum: 255 - description: The scale of amounts denoted in the corresponding asset code. -interval: - title: Interval - type: string - description: '[ISO8601 repeating interval](https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals)' - examples: - - 'R11/2022-08-24T14:15:22Z/P1M' - - 'R/2017-03-01T13:00:00Z/2018-05-11T15:30:00Z' - - 'R-1/P1Y2M10DT2H30M/2022-05-11T15:30:00Z' -key: - title: key - type: object - description: A key presented by value MUST be a public key. - properties: - proof: - type: string - enum: - - httpsig - description: The form of proof that the client instance will use when presenting the key. - jwk: + access-item: + discriminator: + propertyName: type + mapping: + incoming-payment: '#/components/schemas/access-incoming' + outgoing-payment: '#/components/schemas/access-outgoing' + quote: '#/components/schemas/access-quote' + oneOf: + - $ref: '#/components/schemas/access-incoming' + - $ref: '#/components/schemas/access-outgoing' + - $ref: '#/components/schemas/access-quote' + description: The access associated with the access token is described using objects that each contain multiple dimensions of access. + unevaluatedProperties: false + access-incoming: + title: access-incoming type: object - description: 'The public key and its properties represented as a JSON Web Key [[RFC7517](https://datatracker.ietf.org/doc/html/rfc7517)].' - additionalProperties: false - required: - - alg - - kid - - kty - - crv - - x properties: - alg: + type: type: string - description: 'The cryptographic algorithm family used with the key. The only allowed value is `EdDSA`. ' enum: - - EdDSA - kid: + - incoming-payment + description: The type of resource request as a string. This field defines which other fields are allowed in the request object. + actions: + type: array + description: The types of actions the client instance will take at the RS as an array of strings. + items: + type: string + enum: + - create + - complete + - read + - read-all + - list + - list-all + allOf: + - contains: + $ref: '#/components/schemas/read-actions' + minContains: 0 + maxContains: 1 + - contains: + $ref: '#/components/schemas/list-actions' + minContains: 0 + maxContains: 1 + uniqueItems: true + identifier: type: string - description: A Key ID can be used to match a specific key. - kty: + format: uri + description: A string identifier indicating a specific resource at the RS. + required: + - type + - actions + access-outgoing: + title: access-outgoing + type: object + properties: + type: type: string enum: - - OKP - description: 'The Key Type. The only allowed value is `OKP`. ' - use: + - outgoing-payment + description: The type of resource request as a string. This field defines which other fields are allowed in the request object. + actions: + type: array + description: The types of actions the client instance will take at the RS as an array of strings. + items: + type: string + enum: + - create + - read + - read-all + - list + - list-all + allOf: + - contains: + $ref: '#/components/schemas/read-actions' + minContains: 0 + maxContains: 1 + - contains: + $ref: '#/components/schemas/list-actions' + minContains: 0 + maxContains: 1 + uniqueItems: true + identifier: type: string - enum: - - sig - description: The intended use of the key. - crv: + format: uri + description: A string identifier indicating a specific resource at the RS. + limits: + $ref: '#/components/schemas/limits-outgoing' + required: + - type + - actions + - identifier + access-quote: + title: access-quote + type: object + properties: + type: type: string enum: - - Ed25519 - description: 'The cryptographic curve used with the key. The only allowed value is `Ed25519`. ' - x: - type: string - description: Public key encoded using the `base64url` encoding. - key_ops: + - quote + description: The type of resource request as a string. This field defines which other fields are allowed in the request object. + actions: type: array - description: Array of allowed operations this key may be used for. + description: The types of actions the client instance will take at the RS as an array of strings. items: type: string enum: - - sign - - verify - nbf: - type: integer - description: UNIX timestamp indicating the earliest this key may be used. - exp: - type: integer - description: UNIX timestamp indicating the latest this key may be used. - revoked: - type: boolean - description: The revocation status of the key. - required: - - proof - - jwk -limits-outgoing: - title: limits-outgoing - description: Open Payments specific property that defines the limits under which outgoing payments can be created. - type: object - properties: - receiver: - $ref: '#/receiver' - sendAmount: - $ref: '#/amount' - receiveAmount: - $ref: '#/amount' + - create + - read + - read-all + allOf: + - contains: + $ref: '#/components/schemas/read-actions' + minContains: 0 + maxContains: 1 + uniqueItems: true + required: + - type + - actions + amount: + title: amount + type: object + description: 'All amounts are maxima, i.e. multiple payments can be created under a grant as long as the total amounts of these payments do not exceed the maximum amount per interval as specified in the grant.' + properties: + value: + type: string + format: uint64 + description: 'The value is an unsigned 64-bit integer amount, represented as a string.' + assetCode: + $ref: '#/components/schemas/assetCode' + assetScale: + $ref: '#/components/schemas/assetScale' + required: + - value + - assetCode + - assetScale + assetCode: + title: Asset code + type: string + description: The assetCode is a code that indicates the underlying asset. This SHOULD be an ISO4217 currency code. + assetScale: + title: Asset scale + type: integer + minimum: 0 + maximum: 255 + description: The scale of amounts denoted in the corresponding asset code. interval: - $ref: '#/interval' - anyOf: - - not: - required: - - interval - - required: - - sendAmount - - required: - - receiveAmount -list-actions: - enum: - - list - - list-all -read-actions: - enum: - - read - - read-all -receiver: - title: Receiver - type: string - description: The URL of the incoming payment or ILP STREAM connection that is being paid. - format: uri - pattern: '^https://(.+)/(incoming-payments|connections)/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' - examples: - - 'https://openpayments.guide/alice/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c' - - 'https://openpayments.guide/connections/016da9d5-c9a4-4c80-a354-86b915a04ff8' + title: Interval + type: string + description: '[ISO8601 repeating interval](https://en.wikipedia.org/wiki/ISO_8601#Repeating_intervals)' + examples: + - 'R11/2022-08-24T14:15:22Z/P1M' + - 'R/2017-03-01T13:00:00Z/2018-05-11T15:30:00Z' + - 'R-1/P1Y2M10DT2H30M/2022-05-11T15:30:00Z' + key: + title: key + type: object + description: A key presented by value MUST be a public key. + properties: + proof: + type: string + enum: + - httpsig + description: The form of proof that the client instance will use when presenting the key. + jwk: + type: object + description: 'The public key and its properties represented as a JSON Web Key [[RFC7517](https://datatracker.ietf.org/doc/html/rfc7517)].' + additionalProperties: false + required: + - alg + - kid + - kty + - crv + - x + properties: + alg: + type: string + description: 'The cryptographic algorithm family used with the key. The only allowed value is `EdDSA`. ' + enum: + - EdDSA + kid: + type: string + description: A Key ID can be used to match a specific key. + kty: + type: string + enum: + - OKP + description: 'The Key Type. The only allowed value is `OKP`. ' + use: + type: string + enum: + - sig + description: The intended use of the key. + crv: + type: string + enum: + - Ed25519 + description: 'The cryptographic curve used with the key. The only allowed value is `Ed25519`. ' + x: + type: string + description: Public key encoded using the `base64url` encoding. + key_ops: + type: array + description: Array of allowed operations this key may be used for. + items: + type: string + enum: + - sign + - verify + nbf: + type: integer + description: UNIX timestamp indicating the earliest this key may be used. + exp: + type: integer + description: UNIX timestamp indicating the latest this key may be used. + revoked: + type: boolean + description: The revocation status of the key. + required: + - proof + - jwk + limits-outgoing: + title: limits-outgoing + description: Open Payments specific property that defines the limits under which outgoing payments can be created. + type: object + properties: + receiver: + $ref: '#/components/schemas/receiver' + sendAmount: + $ref: '#/components/schemas/amount' + receiveAmount: + $ref: '#/components/schemas/amount' + interval: + $ref: '#/components/schemas/interval' + anyOf: + - not: + required: + - interval + - required: + - sendAmount + - required: + - receiveAmount + list-actions: + enum: + - list + - list-all + read-actions: + enum: + - read + - read-all + receiver: + title: Receiver + type: string + description: The URL of the incoming payment or ILP STREAM connection that is being paid. + format: uri + pattern: '^https://(.+)/(incoming-payments|connections)/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$' + examples: + - 'https://openpayments.guide/alice/incoming-payments/08394f02-7b7b-45e2-b645-51d04e7c330c' + - 'https://openpayments.guide/connections/016da9d5-c9a4-4c80-a354-86b915a04ff8'