From 55c8a436ed833e5e26444b6739dcc6c922928f5b Mon Sep 17 00:00:00 2001 From: dkoeni <116151702+dkoeni@users.noreply.github.com> Date: Mon, 15 Jul 2024 19:15:58 +0200 Subject: [PATCH] Update descriptions (#34) * update yaml multiline indicators * break lines according to yaml lint rules --- pensionAPI.yaml | 169 ++++++++++++++++++++++++++---------------------- 1 file changed, 90 insertions(+), 79 deletions(-) diff --git a/pensionAPI.yaml b/pensionAPI.yaml index 7b38367..e9702b9 100644 --- a/pensionAPI.yaml +++ b/pensionAPI.yaml @@ -3,6 +3,7 @@ info: version: 1.0.0 title: Pension # yamllint disable rule:indentiation + # yamllint disable rule:line-length description: | # Pension-API (Deutsch) @@ -402,6 +403,7 @@ info: - **Risk contribution**: Risikobeitrag (Beitrag für Leistungen bei Invalidität und Tod) - **Vested benefits**: Freizügigkeitsleistungen # yamllint enable rule:indentiation + # yamllint enable rule:line-length contact: email: info@common-api.ch @@ -438,7 +440,7 @@ paths: /insured-persons/{personId}: get: summary: Get details of an insured person - description: | + description: > Provides the details of the insured person, including name, address and additional data relevant in the Swiss social security system (birth date, sex etc.) operationId: getInsuredPerson @@ -466,7 +468,7 @@ paths: /insured-persons/{personId}/statements: post: summary: Get pension statement(s) data - description: | + description: > Provides the pension statement(s) representing the state of the policy/policies for the specified date (or most recent regular/official statement(s) when date not given) as structured data. @@ -509,7 +511,7 @@ paths: /statements/{pensionStatementId}/documents: get: summary: Get the pension statement document for the specified id - description: | + description: > Provides the pension statement for the specified id as a PDF document in the insured person's preferred language. @@ -713,7 +715,7 @@ paths: $ref: '#/components/schemas/BalanceMandatoryEndCurrentYear' prb: type: array - description: | + description: > Projected retirement benefits for a series of retirement ages. The list contains projections for each integer retirement age from 58 to the regular retirement age. For persons of 58 or older, the list is restricted @@ -775,28 +777,28 @@ paths: - 5.500 iree: $ref: '#/components/schemas/InterestRate' - description: | + description: > Enveloping interest rate for combined mandatory and supplementary coverage (in percent), used specifically in purchase calculations. examples: - 6.300 irmp: $ref: '#/components/schemas/InterestRate' - description: | + description: > Projection rate for mandatory coverage (in percent), used specifically for calculating projected future values. examples: - 6.800 irsp: $ref: '#/components/schemas/InterestRate' - description: | + description: > Projection rate for supplementary coverage (in percent), used specifically for calculating projected future values. examples: - 5.500 irep: $ref: '#/components/schemas/InterestRate' - description: | + description: > Projection enveloping interest rate for combined mandatory and supplementary coverage (in percent), used specifically for calculating projected future values. examples: @@ -854,7 +856,7 @@ paths: /policies/{policyId}: get: summary: Get details of a pension fund policy - description: | + description: > Provides extensive details about the insurance policy including current retirement capital, prospective pension benefits for different retirement ages, contributions to financing the insurance etc. @@ -883,7 +885,7 @@ paths: /policies/{policyId}/salary-change-simulation: post: summary: Simulate effects of salary and employment level change - description: | + description: > Simulates the effects of a salaray and/or employment level change on contributions and prospective retirement benefits. Prospective retirements benefits are calculated for retirement at the regular age as well as for multiple early retirement ages. @@ -967,7 +969,7 @@ paths: /policies/{policyId}/purchases/template: get: summary: Retrieves a purchase request template - description: | + description: > The template purchase request serves to retrieve the configuration and intial values for a new purchase request. operationId: getTemplatePurchaseRequest @@ -995,7 +997,7 @@ paths: /policies/{policyId}/purchases: get: summary: Query all purchase requests - description: | + description: > Returns a list of all current and past purchase requests. operationId: listPurchaseRequest tags: @@ -1065,7 +1067,7 @@ paths: /policies/{policyId}/purchases/{purchaseRequestId}: get: summary: Get purchase request - description: | + description: > Retrieves the current state of the specified purchase request. operationId: getPurchaseRequest tags: @@ -1085,7 +1087,7 @@ paths: description: Purchase Request ID. responses: '200': - description: Vvoluntary purchase request + description: Voluntary purchase request content: application/json: schema: @@ -1141,7 +1143,7 @@ paths: /policies/{policyId}/payment-methods: get: summary: Retrieves the available payment methods - description: | + description: > Returns the list of methods available to make payments for a voluntary purchase of pension benefits. operationId: getPaymentMethods @@ -1307,7 +1309,7 @@ components: format: int32 minimum: 0 maximum: 100 - description: | + description: > Degree (percent) of disability according to OASI (AHV/IV). If not specified, 0 is assumed. examples: @@ -1504,7 +1506,7 @@ components: $ref: '#/components/schemas/PensionPlan' isInVestedBenefitFoundation: type: boolean - description: | + description: > Indicates if policy is part of a vested benefit foundation (as opposed to a regular pension fund with payments from an employer). If the field is not set, a regular pension fund is assumed. @@ -1527,7 +1529,7 @@ components: PensionPlan: type: object - description: | + description: > The pension plan defines various conditions for the occupational pension provision of the insured employees, incl. the contributions and insured benefits. required: @@ -1665,7 +1667,7 @@ components: $ref: '#/components/schemas/BalanceMandatoryEndCurrentYear' projectedRetirementBenefits: type: array - description: | + description: > Projected retirement benefits for a series of retirement ages. The list contains projections for each integer retirement age from 58 to the regular retirement age. For persons of 58 or older, the list is restricted @@ -1719,7 +1721,7 @@ components: RetirementBenefits: type: object - description: | + description: > Retirement benefits for retirement at the specified age. The conversion rate is mandatory: either the pair for mandatory and supplementary coverage is provided, or the enveloping conversion rate. @@ -1772,7 +1774,7 @@ components: CapitalBalanceNoInterest: type: number format: double - description: | + description: > Retirement capital balance assuming no interest on assets (mandatory and supplementary coverage) examples: @@ -1781,7 +1783,7 @@ components: CapitalBalanceNoInterestMandatory: type: number format: double - description: | + description: > Retirement capital balance assuming no interest on assets (mandatory coverage only) examples: - 248862.65 @@ -1818,7 +1820,7 @@ components: InterestRates: type: object - description: | + description: > A set of interest rates applicable/applied to the retirement capital, including actual rates for mandatory and supplementary coverage. Rates for saving/purchase and projection rates for future value calculations. @@ -1850,28 +1852,28 @@ components: - 5.500 interestRateEnvelopingPurchase: $ref: '#/components/schemas/InterestRate' - description: | + description: > Enveloping interest rate for combined mandatory and supplementary coverage (in percent), used specifically in purchase calculations. examples: - 6.300 interestRateMandatoryProjection: $ref: '#/components/schemas/InterestRate' - description: | + description: > Projection rate for mandatory coverage (in percent), used specifically for calculating projected future values. examples: - 6.800 interestRateSupplementaryProjection: $ref: '#/components/schemas/InterestRate' - description: | + description: > Projection rate for supplementary coverage (in percent), used specifically for calculating projected future values. examples: - 5.500 interestRateEnvelopingProjection: $ref: '#/components/schemas/InterestRate' - description: | + description: > Projection enveloping interest rate for combined mandatory and supplementary coverage (in percent), used specifically for calculating projected future values. examples: @@ -1938,7 +1940,7 @@ components: MinimalLumpSumWithPensionBenefits: type: number format: double - description: | + description: > Guaranteed, minimal one-off payment in case of death where other benefits are paid out. examples: - 74383.00 @@ -2015,7 +2017,7 @@ components: capitalAt50: type: number format: double - description: | + description: > The insured person's retirement capital when he/she was 50 (mandatory and supplementary). Empty for persons younger than 50. examples: @@ -2023,7 +2025,7 @@ components: capitalAt50Mandatory: type: number format: double - description: | + description: > The insured person's retirement capital when he/she was 50 (mandatory part only). Empty for persons younger than 50. examples: @@ -2036,6 +2038,7 @@ components: a registered partnership (mandatory and supplementary). Relevant is the last marriage or registered partnership (the marriage/partnership date is part of the insured person object.) + Empty for persons who are not married or in a registered partnership. examples: - 28483.35 @@ -2047,27 +2050,28 @@ components: a registered partnership (mandatory part only). Relevant is the last marriage or registered partnership (the marriage/partnership date is part of the insured person object.) + Empty for persons who are not married or in a registered partnership. examples: - 23863.15 capitalFirstCommunicated: type: number format: double - description: | + description: > Vested benefit capital that has been initially communicated or had become due after January 1, 1995 (for insured persons having married before January 1, 1995). examples: - 0.00 capitalFirstCommunicatedDate: $ref: '#/components/schemas/Date' - description: | + description: > Date when vested benefit capital has been initially communicated or had become due after January 1, 1995 (for insured persons having married before January 1, 1995). voluntaryPurchases: type: array items: $ref: '#/components/schemas/CapitalTransaction' - description: | + description: > List of voluntary purchases of additional pension benefits made in the past. At least the purchases of the last 3 years must be included. They can be aggregated by calendar year. @@ -2075,24 +2079,24 @@ components: type: array items: $ref: '#/components/schemas/CapitalTransaction' - description: | + description: > List of withdrawls and refunds for home ownership promotion made in the past. divorceWithdrawals: type: array items: $ref: '#/components/schemas/CapitalTransaction' - description: | + description: > List of withdrawls and refunds due to divorce made in the past. pledges: type: array items: $ref: '#/components/schemas/Pledge' - description: | + description: > List of pledges of parts of the retirement capital. CapitalTransaction: type: object - description: | + description: > Capital transaction made by the insured persons. It includes volunatry purchases, withdrawals for and refunds of home ownerhsip promotion, withdrawals or refunds due to divorce. required: @@ -2106,7 +2110,7 @@ components: amount: type: number format: double - description: | + description: > Total transaction amount for mandatory and supplementary part. The amount is positive for payments towards the capital, and negative for withdrawals. examples: @@ -2123,7 +2127,7 @@ components: RegularPurchaseMaxAmount: type: number format: double - description: | + description: > The maximum amount the insured person is permitted to contribute to their pension plan as an ordinary purchase. examples: @@ -2132,14 +2136,15 @@ components: HomeOwnershipAvailableForWithdrawal: type: number format: double - description: | - The total amount available for the insured person to withdraw or borrow against from their retirement capital for the purpose of financing home ownership. + description: > + The total amount available for the insured person to withdraw or borrow against from their retirement capital + for the purpose of financing home ownership. examples: - 31000.00 HealthReservation: type: object - description: | + description: > Period of health reservation. required: - startDate @@ -2149,26 +2154,26 @@ components: description: Start date of health reservation. endDate: $ref: '#/components/schemas/Date' - description: | + description: > End date of health reservation. If no end date is specified, the health reservation is currently still in force. Pledge: type: object - description: | + description: > Details about pledged capital. properties: amount: type: number format: double - description: | + description: > Amount of retirement capital used for pledging (mandatory and supplementary). examples: - 20000.00 amountMandatory: type: number format: double - description: | + description: > Amount of retirement capital used for pledging (mandatory part only). examples: - 20000.00 @@ -2291,7 +2296,7 @@ components: - 80 effectiveDate: $ref: '#/components/schemas/Date' - description: | + description: > Date when the salary change takes effect. If omitted: tomorrow. @@ -2307,7 +2312,7 @@ components: $ref: '#/components/schemas/SalaryData' projectedRetirementBenefits: type: array - description: | + description: > Projected retirement benefits for a series of retirement ages. The list contains projections for each integer retirement age from 58 to the regular retirement age. For persons of 58 or older, the list is restricted @@ -2325,26 +2330,26 @@ components: properties: totalAmount: type: number - description: | + description: > Purchase amount in CHF. For periodic purchases, the sum of all payments. examples: - 10000.00 retirementAge: type: integer - description: | + description: > Planned retirement age (in month since birth). If omitted, the regular payment age is assumed. examples: - 780 date: $ref: '#/components/schemas/Date' - description: | + description: > Date of the (first) payments. If omitted: tomorrow. paymentSize: type: number - description: | + description: > The size of individual periodic payments. If omitted, 0 or equal to 'amount', a one-time payment is assumed. examples: @@ -2484,108 +2489,114 @@ components: type: number format: double minimum: 1 - description: | + description: > Answer to question 1a: Requested purchase amount in CHF. examples: - 10000.00 hasVestedBenefits: type: boolean - description: | - Answer to question 2a: Indicates if the insured person has pillar 2 vested benefits outside the pension fund (`true`) or not (`false`) + description: > + Answer to question 2a: Indicates if the insured person has pillar 2 vested benefits outside the pension fund (`true`) + or not (`false`) examples: - false hasMadeSelfEmployedContributions: type: boolean - description: | - Answer to question 3a: Indicates if the insured person has made pillar 3a contributions while being self-employed (`true`) or not (`false`) + description: > + Answer to question 3a: Indicates if the insured person has made pillar 3a contributions while being self-employed (`true`) + or not (`false`) examples: - false selfEmployedContributionCredit: type: number format: double minimum: 1 - description: | + description: > Answer to question 3b: Balance of pillar 3a credit as of the end of last year. examples: - 35000.00 hasNotRepaidEarlyWithdrawal: type: boolean - description: | - Answer to question 4a: Indicates if the insured person has made an early withdrawal of savings to fund the purchase of residential property and has not repaid it fully (`true`) or not (`false`). + description: > + Answer to question 4a: Indicates if the insured person has made an early withdrawal of savings to fund the purchase + of residential property and has not repaid it fully (`true`) or not (`false`). examples: - false hasMovedFromAbroad: type: boolean - description: | - Answer to question 5a: Indicates if the insured person has moved to Switzerland from abroad during the last 5 years (`true`) or not (`false`). + description: > + Answer to question 5a: Indicates if the insured person has moved to Switzerland from abroad during the last 5 years (`true`) + or not (`false`). examples: - false moveFromAbroadDate: $ref: '#/components/schemas/Date' - description: | + description: > Answert to question 5b: Date of move from another country to Switzerland. hasBeenInsuredBefore: type: boolean - description: | + description: > Answer to question 5c: Indicates if the person has been insured in the Swiss pension system before (`true`) or not (`false`). examples: - false firstInsuranceDate: $ref: '#/components/schemas/Date' - description: | + description: > Answert to question 5d: First entry date into the Swiss pension system. isDrawingPensionBenefits: type: boolean - description: | - Answer to question 6a: Indicates if the insured person is already drawing or has ever drawn retirement benefits under another pension plan (`true`) or not (`false`). + description: > + Answer to question 6a: Indicates if the insured person is already drawing or has ever drawn retirement benefits + under another pension plan (`true`) or not (`false`). examples: - false isInAnotherPensionPlan: type: boolean - description: | + description: > Answer to question 7a: Indicates if the person is insured in another pension plan (`true`) or not (`false`). examples: - false isFullyAbleToWork: type: boolean - description: | + description: > Answer to question 7b: Indicates if the person is fully able to work (`true`) or not (`false`). examples: - true isPurchaseAfterDivorce: type: boolean - description: | - Answer to question 7c: Indicates if the purchase is to make up for the pension savings surrender due to a divorce (`true`) or not (`false`). + description: > + Answer to question 7c: Indicates if the purchase is to make up for the pension savings surrender due to a divorce (`true`) + or not (`false`). examples: - false isPurchaseWithPillar3aSavings: type: boolean - description: | + description: > Answer to question 7d: Indicates if the purchase is made with funds from a pillar 3a pension plan (`true`) or not (`false`). examples: - false isAddressUpToDate: type: boolean - description: | + description: > Answer to question 8a: Indicates if the postal address is up-to-date (`true`) or not (`false`). examples: - true phoneContact: type: string - description: | + description: > Answer to question 8b: Phone number to contact the insured person regarding the purchase request. examples: - 0041 79 123 45 67 emailContact: type: string - description: | + description: > Answer to question 8c: Email address to contact the insured person regarding the purchase request. examples: - johndoe@gmail.com RequiredPurchaseDetails: type: object - description: | + description: > Provides the configuration regarding which questions should be displayed/asked and additional data required for the questions. properties: askForSelfEmployedContributionCredit: @@ -2686,7 +2697,7 @@ components: paymentSize: type: number format: double - description: | + description: > Size (in CHF) of individual regular payments. examples: - 500.00 @@ -2698,7 +2709,7 @@ components: PaymentInstructions: type: object - description: | + description: > Payment instructions for to insured person to make the payment. This information will only be provided if the request has the state `approved` and a QR bill related payment methode has been chosen (`paymentMethod` = `singlePaymentQrBill` or `paymentMethod` = `irreularPaymentQrBill`). @@ -2860,7 +2871,7 @@ components: - 10000.00 reason: type: string - description: | + description: > A human-readable description of the transaction reason, in the insured person's preferred language. examples: