From 58ca9326dcfc86f28f0be61dca7d5b537bf64202 Mon Sep 17 00:00:00 2001 From: Max Martens Date: Thu, 26 Mar 2026 18:45:32 +0100 Subject: [PATCH] Rework of purchasedproducts endpoints, including JSON Schema and documentation and examples, especially for activation logic using validityStart and validityEnd (which is in line with how TapConnect populates those same fields) --- src/openapi/customers/SE-customers.yaml | 634 ++++++++++++++++-------- 1 file changed, 426 insertions(+), 208 deletions(-) diff --git a/src/openapi/customers/SE-customers.yaml b/src/openapi/customers/SE-customers.yaml index e3d828f..414655f 100644 --- a/src/openapi/customers/SE-customers.yaml +++ b/src/openapi/customers/SE-customers.yaml @@ -2220,7 +2220,7 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/ProductInstancesResponse" + $ref: "#/components/schemas/OvPayTokenProductInstancesResponse" examples: getEmptyProductInstances: summary: No product-instances found on token @@ -2233,7 +2233,6 @@ paths: "productInstances": [ { - "productInstanceId": "26d41861-f77e-4666-9cde-2c5c66ace0a2", "productId": 1, "name": "HTM 90% Korting", "status": "Active", @@ -3404,7 +3403,7 @@ paths: responses: "200": description: OK - /productinstances: + /purchasedproducts: parameters: - name: X-HTM-JWT-AUTH-HEADER in: header @@ -3412,7 +3411,7 @@ paths: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c required: false - description: The JWT of a customer in case of touchpoint were customer logs in themselves + description: The JWT of a customer in case of a touchpoint where customer logs in themselves - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER in: header schema: @@ -3428,56 +3427,61 @@ paths: required: false - name: deviceId in: query - description: Id of the device you want to get the instantiated HTM products for. + description: Id of the device you want to get the purchased HTM products for. schema: type: string format: uuid - name: externalDeviceId in: query - description: Id of the device you want to get the instantiated HTM products for. + description: External id of the device you want to get the purchased HTM products for. schema: type: string - name: ovpayTokenId in: query - description: Id of the ovpay token you want to get the instantiated HTM products for. + description: Id of the OVpay-token you want to get the purchased HTM products for. schema: type: string format: uuid get: - summary: Get a list of all HTM products for a specific customer, device or token, at least one should be filled in + summary: Get a list of all purchased HTM products for a specific device or token of the given customer. At least one of the query parameters should be filled in. description: |- - Get a list of all HTM products instantiated for a specific customer, device or token, at least one of the query params should be filled in. + Get a list of all purchased HTM products for a specific device or token of the given customer. At least one of the query parametersshould be filled in. Only HTM products are returned. - Where relevant, operations to be performed are returned as HATEOAS links per product-instance. + Where relevant, operations to be performed are returned as HATEOAS links per purchased product. tags: - - ProductInstances + - Purchased Products responses: "200": description: OK content: application/json: schema: - $ref: "#/components/schemas/ProductInstancesResponse" + $ref: "#/components/schemas/PurchasedProductsResponse" examples: - getEmptyProductInstances: - summary: No product-instances found + getEmptyPurchasedProducts: + summary: No purchased products found value: - productInstances: { + purchasedProducts: { "ovPayProducts":[], "barcodeTickets": [], "vouchers":[] } - getSingleBarcodeProductInstanceForDevice: - summary: One BarcodeTicket product-instance + getTwoBarcodePurchasedProductsForDevice: + summary: Two BarcodeTicket purchased products, one PendingActivation and one Active + description: |- + The first ticket (PendingActivation) shows the 30-day range in which the ticket can be activated + (using the PATCH endpoint) in the validityStart and validityEnd fields. The second ticket (Active) + shows the actual validity period of the ticket after activation. value: { - "productInstances":{ + "purchasedProducts":{ "ovPayProducts":[], "barcodeTickets":[ { - "productInstanceId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", - "productId": 13, - "name": "HTM dagkaart", + "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", + "productId": 14, + "name": "HTM 2 uurskaart", + "status": "PendingActivation", "productCategory": { "productCategoryId": 5, @@ -3485,40 +3489,67 @@ paths: }, "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "status": "Active", - "ticketReference": "KJj43nejhbTxhr897287", - "issuedAt": "2020-03-21T00:00:00", + "ticketReference": "KJj43nejhbTxhrfef287", + "serviceId": "DEF-4321-7654-7659", + "issuedAt": "2026-03-21T09:01:35", "activatedAt": null, "blocked": false, "cancelledAt": null, - "fraudDetected": false, + "validityStart": "2026-03-21T09:01:35", + "validityEnd": "2026-04-21T23:59:59", "barcode": "barcodeBytes", - "deviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", - "_links": - { - "get_order": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", - "method": "GET", - }, - "patch_productinstance": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/productinstances/0f0981bf-6d60-4b06-bc55-de1ba325f366", - "method": "PATCH", - }, + "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", + "_links": { + "get_order": { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", + "method": "GET" }, + "patch_purchasedproduct": { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/purchasedproducts/0f0981bf-6d60-4b06-bc55-de1ba325f366", + "method": "PATCH" + } + } }, + { + "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", + "productId": 14, + "name": "HTM 2 uurskaart", + "status": "Active", + "productCategory": + { + "productCategoryId": 5, + "name": "Barcode", + }, + "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", + "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", + "ticketReference": "KJj43nejhbTxhr897287", + "serviceId": "ABC-1234-7654-8945", + "issuedAt": "2026-03-21T10:01:12", + "activatedAt": "2026-03-21T12:45:01", + "blocked": false, + "cancelledAt": null, + "validityStart": "2026-03-21T12:45:01", + "validityEnd": "2026-03-21T14:45:01", + "barcode": "barcodeBytes", + "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", + "_links": { + "get_order": { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", + "method": "GET" + } + } + } ], "vouchers":[] } } - getSingleOvpayProductInstanceForSpecificOvPayToken: - summary: One Ovpay product-instance + getSingleOvpayPurchasedProductForSpecificOvPayToken: + summary: One Ovpay purchased product value: { - "productInstances":{ + "purchasedProducts":{ "ovPayProducts":[ { - "productInstanceId": "26d41861-f77e-4666-9cde-2c5c66ace0a2", + "purchasedProductId": "26d41861-f77e-4666-9cde-2c5c66ace0a2", "productId": 1, "name": "HTM 90% Korting", "status": "Active", @@ -3534,7 +3565,6 @@ paths: "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", "contractId": "56B17EF-C436-9043-B76C-481797WEB464F", "ovPayTokenId": 42, - "deviceId": null, "_links": { "get_order": @@ -3554,95 +3584,18 @@ paths: "vouchers":[] } } - getMultipleProductInstancesForCustomer: - summary: Multiple product-instances for a customer + getSingleVoucherPurchasedProductForCustomer: + summary: One voucher purchased product value: { - "productInstances":{ - "ovPayProducts":[ { - "productInstanceId": "26d41861-f77e-4666-9cde-2c5c66ace0a2", - "productId": 1, - "name": "HTM 90% Korting", - "isRenewable": true, - "productCategory": - { - "productCategoryId": 1, - "name": "Kortingsabonnement", - }, - "fromInclusive": "2024-11-25T13:25:00+01:00", - "untilInclusive": "2024-12-25T03:59:59+01:00", - "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", - "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "contractId": "56B17EF-C436-9043-B76C-481797WEB464F", - "ovPayTokenId": 42, - "deviceId": null, - "_links": - { - "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", - }, - }, - }, - ], - "barcodeTickets": - [ - { - "productInstanceId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", - "productId": 13, - "name": "HTM dagkaart", - "productCategory": - { - "productCategoryId": 5, - "name": "Barcode", - }, - "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", - "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "status": "Active", - "ticketReference": "KJj43nejhbTxhr897287", - "issuedAt": "2020-03-21T00:00:00", - "activatedAt": null, - "blocked": false, - "cancelledAt": null, - "fraudDetected": false, - "barcode": "barcodeBytes", - "deviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", - "_links": - { - "get_order": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", - "method": "GET", - }, - "patch_productinstance": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/productinstances/0f0981bf-6d60-4b06-bc55-de1ba325f366", - "method": "PATCH", - }, - }, - }, - ], - "vouchers":[] - } - } - getSingleVoucherProductInstanceForCustomer: - summary: One voucher product-instance - value: - { - "productInstances":{ + "purchasedProducts":{ "ovPayProducts":[], "barcodeTickets":[], "vouchers":[ { - "productInstanceId": "07a55d42-ea42-4f5c-896a-b340ab084309", + "purchasedProductId": "07a55d42-ea42-4f5c-896a-b340ab084309", "productId": 81, - "name": "HTM ooivaarspas voucher ", + "name": "HTM ooivaarspas voucher", "productCategory": { "productCategoryId": 9, @@ -3650,7 +3603,7 @@ paths: }, "voucherCode": "HTM45253", "fromInclusive": "2026-01-01T00:00:00", - "untillInclusive": "2026-12-31T23:59:99", + "untilInclusive": "2026-12-31T23:59:99", "voucherStatus": { "voucherStatusId": 2, "name": "issued" @@ -3667,11 +3620,10 @@ paths: }, ] } - ] } } - /productinstances/{productInstanceId}: + /purchasedproducts/{purchasedProductId}: parameters: - name: X-HTM-JWT-AUTH-HEADER in: header @@ -3679,7 +3631,7 @@ paths: type: string example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c required: false - description: The JWT of a customer in case of touchpoint were customer logs in themselves + description: The JWT of a customer in case of a touchpoint where customer logs in themselves - name: X-HTM-CUSTOMER-PROFILE-ID-HEADER in: header schema: @@ -3693,28 +3645,28 @@ paths: type: string example: Customer required: false - - name: productInstanceId + - name: purchasedProductId in: path required: true style: simple - description: Id of the product instance you want to change + description: Id of the purchased product you want to change schema: type: string format: uuid example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 patch: - summary: Update a productInstance + summary: Update a purchased product description: |- - Update the status of the give productInstance. + Update the given purchased product. Currently only used to activate a barcode ticket. tags: - - ProductInstances + - Purchased Products requestBody: content: application/json: schema: $ref: "#/components/schemas/unavailable" examples: - Update a productInstance status to active: + Activate a TapConnect purchased product: value: { "status": "Active" @@ -3725,55 +3677,46 @@ paths: content: application/json: schema: - $ref: "#/components/schemas/unavailable" + $ref: "#/components/schemas/PurchasedProductsResponse" examples: - Update a productInstance status to active: - summary: Update a productInstance status to active + Activate a TapConnect purchased product: + summary: Activate a TapConnect purchased product value: { - "productInstances": - [ + "purchasedProducts": { + "ovPayProducts": [], + "barcodeTickets": [ { - "productInstanceId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", - "productId": 13, - "name": "HTM dagkaart", - "purchasedProductType": "TapConnect", + "purchasedProductId": "0f0981bf-6d60-4b06-bc55-de1ba325f366", + "productId": 14, + "name": "HTM 2 uurskaart", "status": "Active", - "isRenewable": false, - "productCategory": - { - "productCategoryId": 2, - "name": "Afgekocht reisrecht", - }, - "fromInclusive": "2024-11-25T13:25:00+01:00", - "untilInclusive": null, + "productCategory": { + "productCategoryId": 5, + "name": "Barcode" + }, "orderId": "501B17EF-36C4-4039-B92C-6517969B464E", "orderLineId": "38B17EF-36C4-4039-B92C-4817969B464E", - "contractId": null, - "content": { - "ticketReference": "KJj43nejhbTxhr897287", - "issuedAt": "2020-03-21T00:00:00", - "activatedAt": "2020-03-21T00:00:00", - "blocked": false, - "cancelledAt": null, - "fraudDetected": false, - "barcode": "barcodeBytes" - }, - "_links": - { - "get_order": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", - "method": "GET", - }, - "patch_productinstance": - { - "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/customers/productinstances/0f0981bf-6d60-4b06-bc55-de1ba325f366", - "method": "PATCH", - }, - }, - }, + "ticketReference": "KJj43nejhbTxhr897287", + "serviceId": "ABC-1234-7654-8945", + "issuedAt": "2026-03-21T10:01:12", + "activatedAt": "2026-03-21T12:45:01", + "blocked": false, + "cancelledAt": null, + "validityStart": "2026-03-21T12:45:01", + "validityEnd": "2026-03-21T14:45:01", + "barcode": "barcodeBytes", + "externalDeviceId": "e2be51ae-2701-4803-a2d7-97d4b714482d", + "_links": { + "get_order": { + "href": "https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E", + "method": "GET" + } + } + } ], + "vouchers": [] + } } components: schemas: @@ -4163,39 +4106,20 @@ components: method: type: string example: GET - ProductInstancesResponse: + OvPayTokenProductInstancesResponse: type: object - required: - - productInstances properties: productInstances: type: array items: type: object - required: - - productInstanceId - - productId - - name - - status - - purchasedProductType - - isRenewable - - productCategory - - _links properties: - productInstanceId: - type: string - format: uuid - example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 productId: type: integer example: 1 name: type: string example: HTM 90% Korting - purchasedProductType: - type: string - description: The type of product instance (e.g. GBO, TapConnect, physical, etc.) - example: GBO status: type: string enum: ["Active", "Ended", "Refunded"] @@ -4236,10 +4160,6 @@ components: format: uuid example: 56B17EF-C436-9043-B76C-481797WEB464F description: Only present for subscriptions/contracts - content: - type: object - description: Custom data for the product-instance, depending on the purchasedProductType - example: null _links: type: object properties: @@ -4254,31 +4174,329 @@ components: example: GET get_order: type: object - description: Always present for any HTM product-instance properties: href: type: string + description: Always present for any HTM product-instance example: https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E method: type: string example: GET get_contract: type: object - description: Only present for subscriptions/contracts properties: href: type: string + description: Only present for subscriptions/contracts example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F method: type: string example: GET - patch_productinstance: + PurchasedProductsResponse: + type: object + required: + - purchasedProducts + properties: + purchasedProducts: + type: object + required: + - ovPayProducts + - barcodeTickets + - vouchers + properties: + ovPayProducts: + type: array + items: + type: object + required: + - purchasedProductId + - productId + - name + - status + - isRenewable + - productCategory + - fromInclusive + - orderId + - orderLineId + - _links + properties: + purchasedProductId: + type: string + format: uuid + example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 + productId: + type: integer + example: 1 + name: + type: string + example: HTM 90% Korting + status: + type: string + enum: ["Active", "Ended", "Refunded"] + example: Active + isRenewable: + type: boolean + example: true + productCategory: type: object - description: Only present for TapConnect product-instances that need to be activated + description: The category of the originating HTM product definition properties: - href: + productCategoryId: + type: integer + example: 1 + name: type: string - example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/productinstances/0f0981bf-6d60-4b06-bc55-de1ba325f366 - method: + example: Kortingsabonnement + fromInclusive: + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + untilInclusive: + type: string + format: date-time-offset + description: >- + If not present, this purchased product represents a subscription/contract without a real end date. If present, it can be either the natural end date or the refund timestamp. + example: "2024-12-25T03:59:59+01:00" + orderId: + type: string + format: uuid + example: 501B17EF-36C4-4039-B92C-6517969B464E + orderLineId: + type: string + format: uuid + example: 38B17EF-36C4-4039-B92C-4817969B464E + contractId: + type: string + format: uuid + example: 56B17EF-C436-9043-B76C-481797WEB464F + description: Only present for subscriptions/contracts + _links: + type: object + properties: + self: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts + method: + type: string + example: GET + get_order: + type: object + properties: + href: + type: string + description: Always present for any HTM purchased product + example: https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E + method: + type: string + example: GET + get_contract: + type: object + properties: + href: + type: string + description: Only present for subscriptions/contracts + example: https://api.integratielaag.nl/abt/touchpoint/1.0/customers/contracts/56B17EF-C436-9043-B76C-481797WEB464F + method: + type: string + example: GET + barcodeTickets: + type: array + items: + type: object + required: + - purchasedProductId + - productId + - name + - status + - productCategory + - orderId + - orderLineId + - ticketReference + - serviceId + - issuedAt + - blocked + - validityStart + - validityEnd + - _links + properties: + purchasedProductId: + type: string + format: uuid + example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 + productId: + type: integer + example: 1 + name: + type: string + example: HTM 2 uurskaart + status: + type: string + enum: ["PendingActivation", "Active", "Ended", "Blocked", "Refunded"] + example: Active + productCategory: + type: object + description: The category of the originating HTM product definition + properties: + productCategoryId: + type: integer + example: 5 + name: type: string - example: PATCH + example: Barcode + orderId: + type: string + format: uuid + example: 501B17EF-36C4-4039-B92C-6517969B464E + orderLineId: + type: string + format: uuid + example: 38B17EF-36C4-4039-B92C-4817969B464E + ticketReference: + type: string + example: KJj43nejhbTxhr897287 + serviceId: + type: string + example: ABC-1234-7654-8945 + issuedAt: + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + activatedAt: + type: string + format: date-time-offset + description: Only present for active and ended barcode tickets + example: "2024-11-25T13:25:00+01:00" + blocked: + type: boolean + example: false + cancelledAt: + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + validityStart: + description: |- + The date-time at which the ticket will become valid for traveling. The ticket will not be valid before this date. + For tickets that require activation: Before activation this field will show the lower bound of the range in which + a ticket can be activated, after activation the value of this field is updated to the final start of the validity + range. For example: a 1 hour product that has to be activated within 7 days. Before ticket activation (activatedAt + field returns null) this value (together with validityEnd) will return the 7 day range, after activation (activatedAt + field returns a date-time) the value will show the start of the final 1 hour validity range. + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + validityEnd: + description: |- + The date-time at which the ticket will become valid for traveling. The ticket will not be valid before this date. + For tickets that require activation: Before activation this field will show the upper bound of the range in which + a ticket can be activated, after activation the value of this field is updated to the final end of the validity + range. For example: a 1 hour product that has to be activated within 7 days. Before ticket activation (activatedAt + field returns null) this value (together with validityStart) will return the 7 day range, after activation (activatedAt + field returns a date-time) the value will show the end of the final 1 hour validity range. + type: string + format: date-time-offset + example: "2024-11-25T15:25:00+01:00" + barcode: + type: string + example: barcodeBytes + externalDeviceId: + type: string + example: e2be51ae-2701-4803-a2d7-97d4b714482d + _links: + type: object + properties: + self: + type: object + properties: + href: + type: string + example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts + method: + type: string + example: GET + get_order: + type: object + properties: + href: + type: string + description: Always present for any HTM purchased product + example: https://api.integratielaag.nl/abt/touchpoint/1.0/orders/501B17EF-36C4-4039-B92C-6517969B464E + method: + type: string + example: GET + patch_purchasedproduct: + type: object + properties: + href: + type: string + description: Only present for purchased products that are PATCHable + example: https://api.integratielaag.nl/abt/touchpoint/1.0/purchasedproducts/56B17EF-C436-9043-B76C-481797WEB464F + method: + type: string + example: PATCH + vouchers: + type: array + items: + type: object + required: + - purchasedProductId + - productId + - name + - productCategory + - voucherCode + - fromInclusive + - voucherStatus + properties: + purchasedProductId: + type: string + format: uuid + example: 0f0981bf-6d60-4b06-bc55-de1ba325f366 + productId: + type: integer + example: 81 + name: + type: string + example: HTM ooivaarspas voucher + productCategory: + type: object + description: The category of the originating HTM product definition + properties: + productCategoryId: + type: integer + example: 6 + name: + type: string + example: Voucher + voucherCode: + type: string + example: HKV-A7J-128-PYT + fromInclusive: + type: string + format: date-time-offset + example: "2024-11-25T13:25:00+01:00" + untilInclusive: + type: string + format: date-time-offset + example: "2024-12-25T03:59:59+01:00" + voucherStatus: + type: object + properties: + voucherStatusId: + type: integer + example: 2 + name: + type: string + example: issued + mandatoryCustomerDataItems: + type: array + items: + type: object + properties: + mandatoryCustomerDataItemId: + type: integer + example: 4 + customerDataItem: + type: string + example: emailAddress