diff --git a/src/openapi/customers/SE-customers.yaml b/src/openapi/customers/SE-customers.yaml index 0f75322..c982add 100644 --- a/src/openapi/customers/SE-customers.yaml +++ b/src/openapi/customers/SE-customers.yaml @@ -166,10 +166,10 @@ paths: "detail": "Meer dan 1 klantprofiel gevonden. Verfijn je zoekcriteria.", "instance": "555d00b5-bc3f-4591-949b-479e76d49ea7", } - post: + post: tags: - Customers - parameters: + parameters: - name: X-HTM-ROLE-HEADER in: header schema: @@ -178,7 +178,7 @@ paths: required: false description: The role of the HTM employee in the case of the SMP, in this case the call can only be done through the SMP summary: Create a customer profile. - description: Create a customer profile in the ABT database with status ACTIVE and debtorStatus Inactive with a start date based on the timestamp of this post call. + description: Create a customer profile in the ABT database with status ACTIVE and debtorStatus Inactive with a start date based on the timestamp of this post call. requestBody: content: application/json: @@ -187,73 +187,71 @@ paths: examples: minimalCustomerProfile: value: - { - "person": { - "emailAddress": "j.jansen@hatseflats.nl" - } - } + { "person": { "emailAddress": "j.jansen@hatseflats.nl" } } fullCustomerProfile: value: { - "customerPreference": { - "languageId": 1 - }, - "person": { - "birthname": "Jan", - "surname": "Jansen", - "prefix": "dhr", - "suffix": "jr", - "dateOfBirth": "1970-01-01", - "emailAddress": "j.jansen@hatseflats.nl", - "addresses": [ - { - "street": "Laan van Meerdervoort", - "houseNumber": 5, - "houseNumberSuffix": "B", - "postalCode": "2500AA", - "city": "Den Haag", - "country": "NL", - "isPreferred": true, - "addressTypeId": 1 - }, - { - "street": "Beeklaan", - "houseNumber": 30, - "houseNumberSuffix": "B", - "postalCode": "2500AA", - "city": "Den Haag", - "country": "NL", - "isPreferred": false, - "addressTypeId": 2 - } - ], - "phones": [ - { - "number": "6123456789", - "countryCode": "0031", - "phoneTypeId": 1, - "isPreferred": true - }, - { - "number": "7012345678", - "countryCode": "0031", - "phoneTypeId": 2, - "isPreferred": false - } - ], - "devices": [ - { - "externalDeviceId": "123e4567-e89b-12d3-a456-426614174000", - "alias": "My iPhone", - }, - { - "externalDeviceId": "987e6543-e21b-12d3-a456-426614174999", - "alias": "My iPad", - } - ] - } + "customerPreference": { "languageId": 1 }, + "person": + { + "birthname": "Jan", + "surname": "Jansen", + "prefix": "dhr", + "suffix": "jr", + "dateOfBirth": "1970-01-01", + "emailAddress": "j.jansen@hatseflats.nl", + "addresses": + [ + { + "street": "Laan van Meerdervoort", + "houseNumber": 5, + "houseNumberSuffix": "B", + "postalCode": "2500AA", + "city": "Den Haag", + "country": "NL", + "isPreferred": true, + "addressTypeId": 1, + }, + { + "street": "Beeklaan", + "houseNumber": 30, + "houseNumberSuffix": "B", + "postalCode": "2500AA", + "city": "Den Haag", + "country": "NL", + "isPreferred": false, + "addressTypeId": 2, + }, + ], + "phones": + [ + { + "number": "6123456789", + "countryCode": "0031", + "phoneTypeId": 1, + "isPreferred": true, + }, + { + "number": "7012345678", + "countryCode": "0031", + "phoneTypeId": 2, + "isPreferred": false, + }, + ], + "devices": + [ + { + "externalDeviceId": "123e4567-e89b-12d3-a456-426614174000", + "alias": "My iPhone", + }, + { + "externalDeviceId": "987e6543-e21b-12d3-a456-426614174999", + "alias": "My iPad", + }, + ], + }, } - responses: + responses: "201": description: Created content: @@ -287,7 +285,7 @@ paths: description: The role of the HTM employee in the case of the SMP summary: Update a customer profile description: Update a customer profile based on the sub from the JWT, or customerProfileId in case of SMP - requestBody: + requestBody: content: application/json: schema: @@ -296,70 +294,74 @@ paths: patchCustomer: value: { - "person": { - "birthname": "Jan", - "surname": "Jansen", - "prefix": "dhr", - "suffix": "jr", - "dateOfBirth": "1970-01-01", - "addresses": [ - { - "addressId": 2, - "street": "Laan van Meerdervoort", - "houseNumber": 5, - "postalCode": "2500AA", - "city": "Den Haag", - "country": "NL" - }, - { - "addressId": 1, - "street": "Beeklaan", - "houseNumber": 30, - "houseNumberSuffix": "B", - "postalCode": "2500AA", - "city": "Den Haag", - "country": "NL", - "addressTypeId": 2 - } - ], - "phones": [ - { - "phoneId": 1, - "number": "6123456789", - "countryCode": "0031", - "phoneTypeId": 1, - "isPreferred": true - }, - { - "phoneId": 2, - "number": "7012345678", - "countryCode": "0031", - "phoneTypeId": 2, - "isPreferred": false - } - ], - "devices": [ - { - "deviceId": "813afdd8-bf8c-4e26-bfda-4da79552bd38", - "externalDeviceId": "123e4567-e89b-12d3-a456-426614174000", - "alias": "My iPhone", - }, - { - "deviceId": "4f4249a2-ac6c-44f9-b740-66e66b6f3c28", - "externalDeviceId": "987e6543-e21b-12d3-a456-426614174999", - "alias": "My iPad", - } - ] - } - } - responses: + "person": + { + "birthname": "Jan", + "surname": "Jansen", + "prefix": "dhr", + "suffix": "jr", + "dateOfBirth": "1970-01-01", + "addresses": + [ + { + "addressId": 2, + "street": "Laan van Meerdervoort", + "houseNumber": 5, + "postalCode": "2500AA", + "city": "Den Haag", + "country": "NL", + }, + { + "addressId": 1, + "street": "Beeklaan", + "houseNumber": 30, + "houseNumberSuffix": "B", + "postalCode": "2500AA", + "city": "Den Haag", + "country": "NL", + "addressTypeId": 2, + }, + ], + "phones": + [ + { + "phoneId": 1, + "number": "6123456789", + "countryCode": "0031", + "phoneTypeId": 1, + "isPreferred": true, + }, + { + "phoneId": 2, + "number": "7012345678", + "countryCode": "0031", + "phoneTypeId": 2, + "isPreferred": false, + }, + ], + "devices": + [ + { + "deviceId": "813afdd8-bf8c-4e26-bfda-4da79552bd38", + "externalDeviceId": "123e4567-e89b-12d3-a456-426614174000", + "alias": "My iPhone", + }, + { + "deviceId": "4f4249a2-ac6c-44f9-b740-66e66b6f3c28", + "externalDeviceId": "987e6543-e21b-12d3-a456-426614174999", + "alias": "My iPad", + }, + ], + }, + } + responses: "200": description: OK content: application/json: schema: $ref: "#/components/schemas/CustomersResponse" - + /customers/tokens: get: tags: @@ -585,7 +587,7 @@ paths: "name": null, "birthdate": null, "photo": null, - }, + }, "gboAgeProfile": null, "_links": { @@ -707,7 +709,7 @@ paths: "gboAgeProfileId": 1, "name": "Kind (4 t/m 11 jaar)", "ageFromInclusive": 4, - "ageToInclusive": 11 + "ageToInclusive": 11, }, "_links": { @@ -804,7 +806,7 @@ paths: "gboAgeProfileId": 1, "name": "Kind (4 t/m 11 jaar)", "ageFromInclusive": 4, - "ageToInclusive": 11 + "ageToInclusive": 11, }, "_links": { @@ -914,12 +916,12 @@ paths: "lastChangeDate": "2024-08-24T14:15:22Z", }, }, - "gboAgeProfile": + "gboAgeProfile": { "gboAgeProfileId": 1, "name": "Kind (4 t/m 11 jaar)", "ageFromInclusive": 4, - "ageToInclusive": 11 + "ageToInclusive": 11, }, "_links": { @@ -1037,7 +1039,7 @@ paths: "birthdate": null, "photo": null, }, - "gboAgeProfile": null + "gboAgeProfile": null, }, { "customerProfileId": 132, @@ -1058,7 +1060,7 @@ paths: "birthdate": null, "photo": null, }, - "gboAgeProfile": null + "gboAgeProfile": null, }, { "customerProfileId": 166, @@ -1082,7 +1084,7 @@ paths: "birthdate": null, "photo": null, }, - "gboAgeProfile": null + "gboAgeProfile": null, }, { "customerProfileId": 166, @@ -1103,7 +1105,7 @@ paths: "birthdate": null, "photo": null, }, - "gboAgeProfile": null + "gboAgeProfile": null, }, { "customerProfileId": 1, @@ -1124,7 +1126,7 @@ paths: "birthdate": null, "photo": null, }, - "gboAgeProfile": null + "gboAgeProfile": null, }, ], _links: @@ -2369,7 +2371,7 @@ paths: "ePurse": null, "personalAccountData": { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null + "gboAgeProfile": null, }, "newOvPayToken": { @@ -2386,7 +2388,7 @@ paths: "ePurse": null, "personalAccountData": { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null + "gboAgeProfile": null, }, "isTransferable": true, "transferableObjects": @@ -2399,7 +2401,7 @@ paths: "ePurse": true, "personalAccountData": { "name": true, "birthdate": true, "photo": true }, - "gboAgeProfile": true + "gboAgeProfile": true, }, "_links": { @@ -2423,50 +2425,57 @@ paths: "tokenStatus": { "tokenStatusId": 2, "name": "Active" }, "expirationDate": "2028-02-01", - "productInstances": [ - { - "productId": 1, - "name": "HTM 90% Korting EMV", - "status": "Active", - "isRenewable": true, - "productCategory": { - "productCategoryId": 1, - "name": "Kortingsabonnement" + "productInstances": + [ + { + "productId": 1, + "name": "HTM 90% Korting EMV", + "status": "Active", + "isRenewable": true, + "productCategory": + { + "productCategoryId": 1, + "name": "Kortingsabonnement", + }, + "fromInclusive": "2025-11-25T13:25:00+01:00", + "untilInclusive": "2025-12-25T03:59:59+01:00", + "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", + "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", + "contractId": "56B17EF-C436-9043-B76C-481797WEB464F", + "_links": + { + "self": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/1/productinstances/1", + "method": "GET", + }, + "get_order": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", + "method": "GET", + }, + "get_contract": + { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F", + "method": "GET", + }, + }, }, - "fromInclusive": "2025-11-25T13:25:00+01:00", - "untilInclusive": "2025-12-25T03:59:59+01:00", - "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", - "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "contractId": "56B17EF-C436-9043-B76C-481797WEB464F", - "_links": { - "self": { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens/1/productinstances/1", - "method": "GET" - }, - "get_order": { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", - "method": "GET" - }, - "get_contract": { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F", - "method": "GET" - } - } - } - ], + ], "replacedByTokenId": null, "autoReloadRegistration": null, "ePurse": null, "personalAccountData": { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null + "gboAgeProfile": null, }, "newOvPayToken": { "customerProfileId": null, "ovPayTokenId": null, "xTat": "32089cc8-d187-47ff-a3a9-5c2558def811", - "tokenType": { "tokenTypeId": 2, "name": "OV-pas physical" }, + "tokenType": + { "tokenTypeId": 2, "name": "OV-pas physical" }, "alias": null, "tokenStatus": null, "expirationDate": "2028-02-01", @@ -2476,7 +2485,7 @@ paths: "ePurse": null, "personalAccountData": { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null + "gboAgeProfile": null, }, "isTransferable": false, "transferableObjects": @@ -2513,7 +2522,7 @@ paths: "ePurse": null, "personalAccountData": { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null + "gboAgeProfile": null, }, "newOvPayToken": { @@ -2530,7 +2539,7 @@ paths: "ePurse": null, "personalAccountData": { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null + "gboAgeProfile": null, }, "isTransferable": false, "transferableObjects": @@ -2602,8 +2611,8 @@ paths: "gboAgeProfileId": 1, "name": "Kind (4 t/m 11 jaar)", "ageFromInclusive": 4, - "ageToInclusive": 11 - } + "ageToInclusive": 11, + }, }, "newOvPayToken": { @@ -2620,7 +2629,7 @@ paths: "ePurse": null, "personalAccountData": { "name": null, "birthdate": null, "photo": null }, - "gboAgeProfile": null + "gboAgeProfile": null, }, "isTransferable": false, "transferableObjects": @@ -2674,12 +2683,12 @@ paths: "photo": null, }, "gboAgeProfile": - { - "gboAgeProfileId": 1, - "name": "Kind (4 t/m 11 jaar)", - "ageFromInclusive": 4, - "ageToInclusive": 11 - } + { + "gboAgeProfileId": 1, + "name": "Kind (4 t/m 11 jaar)", + "ageFromInclusive": 4, + "ageToInclusive": 11, + }, }, "newOvPayToken": { @@ -2709,13 +2718,13 @@ paths: }, "photo": null, }, - "gboAgeProfile": - { - "gboAgeProfileId": 4, - "name": "Kind (19 t/m 65 jaar)", - "ageFromInclusive": 19, - "ageToInclusive": 65 - } + "gboAgeProfile": + { + "gboAgeProfileId": 4, + "name": "Kind (19 t/m 65 jaar)", + "ageFromInclusive": 19, + "ageToInclusive": 65, + }, }, "isTransferable": false, "transferableObjects": @@ -3075,10 +3084,10 @@ paths: }, "gboAgeProfile": { - "gboAgeProfileId": 1, - "name": "Kind (4 t/m 11 jaar)", - "ageFromInclusive": 4, - "ageToInclusive": 11 + "gboAgeProfileId": 1, + "name": "Kind (4 t/m 11 jaar)", + "ageFromInclusive": 4, + "ageToInclusive": 11, }, "_links": { @@ -3119,60 +3128,22 @@ paths: }, }, } + "202": + description: Accepted + content: + application/json: + schema: + $ref: "#/components/schemas/unavailable" + examples: Token transfer in progress: description: | The transfer of the token is still in progress. The response body shows the details of the processing status. value: { - "properties": - { - "waitEndTime": "2025-06-04T09:29:21.9641991Z", - "startTime": "2025-06-04T09:29:21.9641991Z", - "status": "Running", - "correlation": - { - "clientTrackingId": "08584525775244808022011782750CU00", - }, - "workflow": - { - "id": "/workflows/9cd96b77c0b94b31832778569f8ef2f9/versions/08584532480062676349", - "name": "08584532480062676349", - "type": "workflows/versions", - }, - "trigger": - { - "name": "token_transfer", - "inputsLink": - { - "uri": "https://htm-abt-logicapp-acc.azurewebsites.net:443/runtime/webhooks/workflow/scaleUnits/prod-00/workflows/9cd96b77c0b94b31832778569f8ef2f9/runs/08584525775235278538475939776CU00/contents/TriggerInputs?api-version=2022-05-01&code=C6PDQGl3MGwt8KyA9BjWDdQbzBwm-01gEmZaTp-hPJ5UAzFuPU-thg%3d%3d&se=2025-06-04T13%3A00%3A00.0000000Z&sp=%2Fruns%2F08584525775235278538475939776CU00%2Fcontents%2FTriggerInputs%2Fread&sv=1.0&sig=6Uxs33K7cQ7jONWzhv9XFPzx4RRHZ6smzfM6wNPk5Mc", - "contentSize": 298, - }, - "outputsLink": - { - "uri": "https://htm-abt-logicapp-acc.azurewebsites.net:443/runtime/webhooks/workflow/scaleUnits/prod-00/workflows/9cd96b77c0b94b31832778569f8ef2f9/runs/08584525775235278538475939776CU00/contents/TriggerOutputs?api-version=2022-05-01&code=C6PDQGl3MGwt8KyA9BjWDdQbzBwm-01gEmZaTp-hPJ5UAzFuPU-thg%3d%3d&se=2025-06-04T13%3A00%3A00.0000000Z&sp=%2Fruns%2F08584525775235278538475939776CU00%2Fcontents%2FTriggerOutputs%2Fread&sv=1.0&sig=vJ6pmCsmz2aP7f73MVOmCTes3YvC1e2w0ZLqdypLXrM", - "contentSize": 6110, - }, - "startTime": "2025-06-04T09:29:21.9497457Z", - "endTime": "2025-06-04T09:29:21.9497457Z", - "originHistoryName": "08584525775235278538475939776CU00", - "correlation": - { - "clientTrackingId": "08584525775244808022011782750CU00", - }, - "status": "Succeeded", - }, - "outputs": {}, - "response": - { - "startTime": "2025-06-04T09:29:21.9642901Z", - "correlation": {}, - "status": "Waiting", - }, - }, - "id": "/workflows/9cd96b77c0b94b31832778569f8ef2f9/runs/08584525775235278538475939776CU00", - "name": "08584525775235278538475939776CU00", - "type": "workflows/runs", + "startTime": "2025-02-14T05:32:47.067Z", + "status": "Running", + "clientTrackingId": "08584620957189579629541919368CU00", } "404": description: Not found @@ -3371,10 +3342,7 @@ paths: $ref: "#/components/schemas/unavailable" examples: Update alias of a device: - value: - { - "alias": "My old iPhone 13", - } + value: { "alias": "My old iPhone 13" } responses: "200": description: OK @@ -3484,209 +3452,209 @@ components: CustomersResponseList: type: object properties: - customers: + customers: type: array items: - $ref: "#/components/schemas/CustomersResponse" - CustomersResponse: + $ref: "#/components/schemas/CustomersResponse" + CustomersResponse: type: object properties: - customerProfileId: - type: integer - example: 1 - customerNumber: - type: integer - example: 1000001 - customerStatus: - type: object - properties: - customerStatusId: - type: integer - example: 1 - name: - type: string - example: Active - debtorNumber: - type: string - example: DB100001 - debtorStatus: - type: object - properties: - debtorStatusId: - type: integer - example: 1 - name: - type: string - example: Active - person: - type: object - properties: - prefix: - type: string - example: Mr - birthname: - type: string - example: John - surname: - type: string - example: Doe - suffix: - type: string - example: Jr. - dateOfBirth: - type: string - format: date - example: "2023-02-01" - emailAddress: - type: string - format: email - example: 4j2dD@example.com - addresses: - type: array - items: - type: object - properties: - addressId: - type: integer - example: 1 - addressType: - type: object - properties: - addressTypeId: - type: integer - example: 1 - name: - type: string - example: Shipping - street: - type: string - example: Appelstraat - houseNumber: - type: integer - example: 1 - houseNumberSuffix: - type: string - example: BS - postalCode: - type: string - example: 1234AB - city: - type: string - example: Den Haag - country: - type: string - example: NL - phones: - type: array - items: - type: object - properties: - phoneId: - type: integer - example: 1 - isPreferred: - type: boolean - example: true - phoneType: - type: object - properties: - phoneTypeId: - type: integer - example: 1 - name: - type: string - example: Home - number: - type: string - example: "0123456789" - countryCode: - type: string - example: "0031" - devices: - type: array - items: - type: object - properties: - deviceId: - type: string - format: uuid - example: 1 - externalDeviceId: - type: string - format: uuid - example: dee7d80e-9288-4508-a3ed-c067e619179f - alias: - type: string - example: My iPhone 13 - _links: - type: object - properties: - add_device: - type: object - properties: - href: - type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/devices - method: - type: string - example: POST - edit_device: - type: object - properties: - href: - type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/devices/1 - method: - type: string - example: PATCH - delete_device: - type: object - properties: - href: - type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/devices/1 - method: - type: string - example: DELETE - _links: - type: object - properties: - self: + customerProfileId: + type: integer + example: 1 + customerNumber: + type: integer + example: 1000001 + customerStatus: + type: object + properties: + customerStatusId: + type: integer + example: 1 + name: + type: string + example: Active + debtorNumber: + type: string + example: DB100001 + debtorStatus: + type: object + properties: + debtorStatusId: + type: integer + example: 1 + name: + type: string + example: Active + person: + type: object + properties: + prefix: + type: string + example: Mr + birthname: + type: string + example: John + surname: + type: string + example: Doe + suffix: + type: string + example: Jr. + dateOfBirth: + type: string + format: date + example: "2023-02-01" + emailAddress: + type: string + format: email + example: 4j2dD@example.com + addresses: + type: array + items: type: object properties: - href: + addressId: + type: integer + example: 1 + addressType: + type: object + properties: + addressTypeId: + type: integer + example: 1 + name: + type: string + example: Shipping + street: type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers - method: + example: Appelstraat + houseNumber: + type: integer + example: 1 + houseNumberSuffix: type: string - example: GET - partial_edit: + example: BS + postalCode: + type: string + example: 1234AB + city: + type: string + example: Den Haag + country: + type: string + example: NL + phones: + type: array + items: type: object properties: - href: + phoneId: + type: integer + example: 1 + isPreferred: + type: boolean + example: true + phoneType: + type: object + properties: + phoneTypeId: + type: integer + example: 1 + name: + type: string + example: Home + number: type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers - method: + example: "0123456789" + countryCode: type: string - example: PATCH - get_tokens: + example: "0031" + devices: + type: array + items: type: object properties: - href: + deviceId: type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens - method: + format: uuid + example: 1 + externalDeviceId: type: string - example: GET - create_token: - type: object - properties: - href: + format: uuid + example: dee7d80e-9288-4508-a3ed-c067e619179f + alias: type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens - method: - type: string - example: POST + example: My iPhone 13 + _links: + type: object + properties: + add_device: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/devices + method: + type: string + example: POST + edit_device: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/devices/1 + method: + type: string + example: PATCH + delete_device: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/devices/1 + method: + type: string + example: DELETE + _links: + type: object + properties: + self: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers + method: + type: string + example: GET + partial_edit: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers + method: + type: string + example: PATCH + get_tokens: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens + method: + type: string + example: GET + create_token: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/tokens + method: + type: string + example: POST OvPayTokensResponse: type: object required: