openapi: 3.0.1 info: title: Appointment Management description: > **This file forms part of Mplify 137.1** **This API implements Business Requirements described in MEF 113.** An Appointment is an arrangement to do something or meet someone at a particular time and place. It is previously made during an interaction or may be necessary to solve a customer problem or to deliver a product order item. The appointment API goal is to manage an appointment with all the necessary characteristics. List of supported use cases: - Search Appointment Timeslot - Create Appointment - Retrieve Appointment List - Retrieve Appointment by Appointment Identifier - Patch Appointment by Appointment Identifier - Cancel Appointment by Appointment Identifier - Register for Appointment Notifications Copyright 2025 Mplify Alliance and its contributors. This file includes content based on the TM Forum Appointment Management API (TMF646 v4.0.0) available at https://github.com/tmforum-apis/TMF646_AppointmentManagement, which is licensed by the TM Forum under the Apache License version 2.0. Such content has been modified by the Mplify Alliance and its contributors. version: 3.0.1 servers: - url: 'https://{serverBase}/mefApi/cantata/appointment/v3/' variables: serverBase: description: The base of Seller's URL. default: mplify.net tags: - name: appointment - name: searchTimeSlot - name: events subscription paths: /appointment: get: tags: - appointment summary: List or found Appointment objects description: > The Buyer requests a list of Appointment from the Seller based on a set of specified filter criteria. The Seller returns a summarized list of Appointments. operationId: listAppointment parameters: - name: workOrderId in: query description: A reference to a WorkOrder for which the Appointment is created. required: false schema: type: string - name: validFor.gt in: query description: >- The Date and Time the Appointment is confirmed to start and end - greater than. required: false schema: type: string format: date-time - name: validFor.lt in: query description: >- The Date and Time the Appointment is confirmed to start and end - lower than. required: false schema: type: string format: date-time - name: status in: query description: The status of the Appointment. required: false schema: $ref: '#/components/schemas/AppointmentStatusType' - name: geographicSiteId in: query description: A site identifier that is associated with the Appointment. required: false schema: type: string - name: geographicAddressId in: query description: An address identifier that is associated with the Appointment. required: false schema: type: string - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string - name: offset in: query description: >- Requested index for the start of resources to be provided in response required: false schema: type: integer - name: limit in: query description: Requested number of resources to be provided in response required: false schema: type: integer format: int32 responses: '200': description: 'OK. (https://tools.ietf.org/html/rfc7231section-6.3.1)' headers: X-Pagination-Throttled: description: > Used to indicate that the result page was throttled to maximum possible size and there are additional results that can be fetched. schema: type: boolean X-Total-Count: description: > The total number of matching records. E.g. if there are 50 matching records in total, but the request has offset=10 and limit=10, then the X-Total-Count is 50. schema: type: integer X-Result-Count: description: The number of records included in the response schema: type: integer content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Appointment_Find' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' post: tags: - appointment summary: Creates an appointment description: >- A request initiated by the Buyer to create a Appointment in the Seller's system to report an Issue experienced by the Buyer operationId: createAppointment parameters: - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string requestBody: description: The Appointment to be created content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Appointment_Create' required: true responses: '201': description: 'Created (https://tools.ietf.org/html/rfc7231section-6.3.2)' content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Appointment' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '/appointment/{id}': get: tags: - appointment summary: Retrieves an Appointment by ID description: >- The Buyer requests detailed information about a single Appointment based on the Appointment Identifier. operationId: retrieveAppointment parameters: - name: id in: path description: Unique (within the Seller domain) identifier for the Appointment. required: true schema: type: string - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string responses: '200': description: 'OK. (https://tools.ietf.org/html/rfc7231section-6.3.1)' content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Appointment' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' patch: tags: - appointment summary: Updates partially an Appointment description: >- A request by the Buyer to patch an Appointment created by the Buyer in the Seller's system. operationId: patchAppointment parameters: - name: id in: path description: Unique (within the Seller domain) identifier for the Appointment. required: true schema: type: string - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string requestBody: description: The Appointment to be updated content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Appointment_Update' required: true responses: '200': description: Updated content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Appointment' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '409': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error409' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '/appointment/{id}/cancel': post: tags: - appointment operations summary: Cancels an Appointment description: This operation sends a cancellation request. operationId: cancelAppointment parameters: - name: id in: path description: Unique (within the Seller domain) identifier for the Appointment. required: true schema: type: string - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string responses: '204': description: Cancelled '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' /searchTimeSlot: post: tags: - searchTimeSlot summary: Creates a SearchTimeSlot description: >- A request by the Buyer to find a set of available time slots for scheduling or rescheduling an Appointment for a Workorder with a Seller Technician. operationId: createSearchTimeSlot parameters: - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string requestBody: description: The Appointment to be created content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/SearchTimeSlot_Create' required: true responses: '201': description: 'Created (https://tools.ietf.org/html/rfc7231section-6.3.2)' content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/SearchTimeSlot' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' /hub: post: tags: - events subscription summary: Allows the Buyer to register to Appointment status change notifications description: The Buyer requests to subscribe to Appointment Notifications. operationId: registerListener parameters: - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string requestBody: description: Data containing the callback endpoint to deliver the information content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/EventSubscriptionInput' required: true responses: '201': description: 'Subscribed (https://tools.ietf.org/html/rfc7231section-6.3.2)' content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/EventSubscription' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '422': description: Unprocessable entity due to the business validation problems content: application/json;charset=utf-8: schema: type: array items: $ref: '#/components/schemas/Error422' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' '/hub/{id}': get: tags: - events subscription summary: Retrieves a Hub by ID description: This operation retrieves a hub entity. operationId: retrieveHub parameters: - name: id in: path description: Identifier of the Hub required: true schema: type: string - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string responses: '200': description: Success content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/EventSubscription' '400': description: Bad Request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' delete: tags: - events subscription summary: Unregister a listener description: The Buyer requests to unsubscribe from Appointment Notifications operationId: unregisterListener parameters: - name: id in: path description: The id of the EventSubscription required: true schema: type: string - name: buyerId in: query description: >- The unique identifier of the organization that is acting as the a Buyer. MUST be specified in the request only when the requester represents more than one Buyer. required: false schema: type: string - name: sellerId in: query description: >- The unique identifier of the organization that is acting as the Seller. MUST be specified in the request only when responding entity represents more than one Seller. required: false schema: type: string responses: '204': description: 'Deleted (https://tools.ietf.org/html/rfc7231section-6.3.5)' '400': description: Bad request content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error400' '401': description: Unauthorized content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error401' '403': description: Forbidden content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error403' '404': description: Not Found content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error404' '500': description: Internal Server Error content: application/json;charset=utf-8: schema: $ref: '#/components/schemas/Error500' components: schemas: Appointment: description: >- In the context of MEF 113 document, denotes an arrangement between the Buyer and Seller for a Seller Technician to meet with the Buyer at a specified time and place. type: object properties: id: description: Unique identifier of the appointment type: string href: description: Unique URI used to access to the appointment resource type: string attachment: description: >- Attachments to the Appointment, such as a file, screenshot or embedded content. type: array items: $ref: '#/components/schemas/AttachmentValue' note: description: Notes describing the purpose of and the results of the Appointment type: array items: $ref: '#/components/schemas/Note' relatedPlace: description: The location of the Appointment. $ref: '#/components/schemas/RelatedPlaceRefOrQuery' status: description: The state of the Appointment. $ref: '#/components/schemas/AppointmentStatusType' validFor: description: >- The Date and Time interval the Seller Technician is scheduled to arrive at the Appointment. $ref: '#/components/schemas/TimePeriod' relatedContactInformation: description: >- Party playing a role in this Appointment. The 'role' is to specify the type of contact as specified in MEF 113: Appointment Place Contact (role=appointmentPlaceContact) - The site contact(s) that the Seller Technician may need to contact in order to get access to the Appointment Place during the Appointment. This could be an end-user, security personnel or any authorized person Buyer Appointment Contact (role=buyerAppointmentContact)- The Buyer contact(s) assigned to and responsible for the Appointment. Seller Appointment Contact (role=sellerAppointmentContact) - The Seller contact(s) assigned to and responsible for the Appointment. type: array minItems: 1 items: $ref: '#/components/schemas/RelatedContactInformation' workOrder: description: A reference to a WorkOrder for which the Appointment is created. $ref: '#/components/schemas/WorkOrderRef' required: - id - relatedContactInformation - relatedPlace - status - validFor - workOrder AppointmentStatusType: description: | Valid values for the lifecycle status of the appointment. | status | MEF 113 name | Description | | ----------------------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `confirmed` | SCHEDULED | The Buyer has negotiated and scheduled the Appointment with the Seller. | | `inProgress` | IN_PROGRESS | The Appointment can no longer be cancelled (point of no return), this is up to the Seller's discretion. | | `cancelled` | CANCELLED | The Appointment was cancelled by the Buyer or the Seller determined that an Appointment was not required. This is a terminal state. | | `missed` | MISSED | The Appointment did not take place, because of a Seller related issue. For example, no Seller Technician was available on the date of the appointment | | `failed` | FAILED | The Appointment did not take place, because of an issue with the Buy-er. For example, Seller Technician was unable to get to the Appointment due to an incorrect location or unable to get access to the Buyer`s site. This is a terminal state | | `completed` | COMPLETED | The Appointment took place as scheduled. This is a terminal state. | type: string enum: - confirmed - inProgress - cancelled - missed - failed - completed Appointment_Create: description: >- In the context of MEF 113 document, denotes an arrangement between the Buyer and Seller for a Seller Technician to meet with the Buyer at a specified time and place.' type: object properties: attachment: description: >- Attachments to the Appointment, such as a file, screen shot or embedded content. type: array items: $ref: '#/components/schemas/AttachmentValue' note: description: Notes describing the purpose of and the results of the Appointment type: array items: $ref: '#/components/schemas/Note' relatedContactInformation: description: >- Party playing a role in this Appointment. The 'role' is to specify the type of contact as specified in MEF 113: Appointment Place Contact (role=appointmentPlaceContact) - The site contact(s) that the Seller Technician may need to contact in order to get access to the Appointment Place during the Appointment. This could be an end-user, security personnel or any authorized person Buyer Appointment Contact (role=buyerAppointmentContact)- The Buyer contact(s) assigned to and responsible for the Appointment. Seller Appointment Contact (role=sellerAppointmentContact) - The Seller contact(s) assigned to and responsible for the Appointment. type: array minItems: 1 items: $ref: '#/components/schemas/RelatedContactInformation' validFor: description: >- The Date and Time interval the Seller Technician is scheduled to arrive at the Appointment. $ref: '#/components/schemas/TimePeriod' workOrder: description: A reference to a WorkOrder for which the Appointment is created. $ref: '#/components/schemas/WorkOrderRef' required: - relatedContactInformation - validFor - workOrder Appointment_Find: description: >- In the context of MEF 113 document, denotes an arrangement between the Buyer and Seller for a Seller Technician to meet with the Buyer at a specified time and place. type: object properties: id: description: Unique identifier of the appointment type: string href: description: Unique URI used to access to the appointment resource type: string relatedPlace: description: >- Related place defines (by reference or value) the place where the appointment will take place. $ref: '#/components/schemas/RelatedPlaceRefOrQuery' status: description: The state of the Appointment. $ref: '#/components/schemas/AppointmentStatusType' validFor: description: >- The Date and Time interval the Seller Technician is scheduled to arrive at the Appointment. $ref: '#/components/schemas/TimePeriod' workOrder: description: A reference to a WorkOrder for which the Appointment is created. $ref: '#/components/schemas/WorkOrderRef' required: - id - relatedPlace - status - validFor - workOrder Appointment_Update: description: >- In the context of MEF 113 document, denotes an arrangement between the Buyer and Seller for a Seller Technician to meet with the Buyer at a specified time and place. type: object properties: attachment: description: >- Attachments to the Appointment, such as a file, screen shot or embedded content. type: array items: $ref: '#/components/schemas/AttachmentValue' note: description: Notes describing the purpose of and the results of the Appointment. type: array items: $ref: '#/components/schemas/Note' relatedPlace: description: >- Related place defines (by reference or value) the place where the appointment will take place. $ref: '#/components/schemas/RelatedPlaceRefOrQuery' relatedContactInformation: description: >- Party playing a role in this Appointment. The 'role' is to specify the type of contact as specified in MEF 113: Appointment Place Contact (role=appointmentPlaceContact) - The site contact(s) that the Seller Technician may need to contact in order to get access to the Appointment Place during the Appointment. This could be an end-user, security personnel or any authorized person Buyer Appointment Contact (role=buyerAppointmentContact)- The Buyer contact(s) assigned to and responsible for the Appointment. Seller Appointment Contact (role=sellerAppointmentContact) - The Seller contact(s) assigned to and responsible for the Appointment. type: array minItems: 1 items: $ref: '#/components/schemas/RelatedContactInformation' validFor: description: >- The Date and Time interval the Seller Technician is scheduled to arrive at the Appointment. $ref: '#/components/schemas/TimePeriod' AttachmentValue: description: >- Complements the description of an element (for instance a product) through video, pictures... type: object properties: author: description: The name of the person or organization who added the Attachment. type: string creationDate: description: The date the Attachment was added. type: string format: date-time description: description: A narrative text describing the content of the attachment type: string mimeType: description: >- Attachment mime type such as extension file for video, picture and document type: string name: description: The name of the attachment type: string size: description: The size of the attachment. $ref: '#/components/schemas/MEFByteSize' source: description: Indicates if the attachment was added by the Buyer or the Seller. $ref: '#/components/schemas/MEFBuyerSellerType' url: description: URL where the attachment is located. type: string required: - author - creationDate - name - source - url ContactInformation: description: >- Contact data for a person or organization that is involved in the product offering qualification. In a given context it is always specified by the Seller (e.g. Seller Contact Information) or by the Buyer. type: object properties: number: description: Phone number type: string emailAddress: description: Email address type: string postalAddress: description: >- Identifies the postal address of the person or office to be contacted. $ref: '#/components/schemas/FieldedAddressRepresentation' organization: description: The organization or company that the contact belongs to type: string name: description: Name of the contact type: string numberExtension: description: Phone number extension type: string required: - emailAddress - name - number DataSizeUnit: description: The unit of measure in the data size. type: string enum: - BYTES - KBYTES - MBYTES - GBYTES - TBYTES - PBYTES - EBYTES - ZBYTES - YBYTES Error: description: > Standard Class used to describe API response error Not intended to be used directly. The `code` in the HTTP header is used as a discriminator for the type of error returned in runtime. type: object properties: reason: description: >- Text that explains the reason for the error. This can be shown to a client user. type: string maxLength: 255 message: description: >- Text that provides mode details and corrective actions related to the error. This can be shown to a client user. type: string referenceError: description: URL pointing to documentation describing the error type: string format: uri required: - reason Error400: description: 'Bad Request. (https://tools.ietf.org/html/rfc7231#section-6.5.1)' allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body $ref: '#/components/schemas/Error400Code' required: - code Error400Code: description: >- One of the following error codes: - missingQueryParameter: The URI is missing a required query-string parameter - missingQueryValue: The URI is missing a required query-string parameter value - invalidQuery: The query section of the URI is invalid. - invalidBody: The request has an invalid body type: string enum: - missingQueryParameter - missingQueryValue - invalidQuery - invalidBody Error401: description: 'Unauthorized. (https://tools.ietf.org/html/rfc7235#section-3.1)' allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired $ref: '#/components/schemas/Error401Code' required: - code Error401Code: description: |- One of the following error codes: - missingCredentials: No credentials provided. - invalidCredentials: Provided credentials are invalid or expired type: string enum: - missingCredentials - invalidCredentials Error403: description: >- Forbidden. This code indicates that the server understood the request but refuses to authorize it. (https://tools.ietf.org/html/rfc7231#section-6.5.3) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users $ref: '#/components/schemas/Error403Code' required: - code Error403Code: description: |- This code indicates that the server understood the request but refuses to authorize it because of one of the following error codes: - accessDenied: Access denied - forbiddenRequester: Forbidden requester - tooManyUsers: Too many users type: string enum: - accessDenied - forbiddenRequester - tooManyUsers Error404: description: >- Resource for the requested path not found. (https://tools.ietf.org/html/rfc7231#section-6.5.4) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- The following error code: - notFound: A current representation for the target resource not found type: string enum: - notFound required: - code Error409: description: 'Conflict (https://datatracker.ietf.org/doc/html/rfc7231#section-6.5.8)' allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- The following error code: - conflict: The client has provided a value whose semantics are not appropriate for the property. type: string enum: - conflict required: - code Error422: description: >- Unprocessable entity due to a business validation problem. (https://tools.ietf.org/html/rfc4918#section-11.2) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: | One of the following error codes: - missingProperty: The property the Seller has expected is not present in the payload - invalidValue: The property has an incorrect value - invalidFormat: The property value does not comply with the expected value format - referenceNotFound: The object referenced by the property cannot be identified in the Seller system - unexpectedProperty: Additional property, not expected by the Seller has been provided - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold. - otherIssue: Other problem was identified (detailed information provided in a reason) $ref: '#/components/schemas/Error422Code' propertyPath: description: > A pointer to a particular property of the payload that caused the validation issue. It is highly recommended that this property should be used. Defined using JavaScript Object Notation (JSON) Pointer (https://tools.ietf.org/html/rfc6901). type: string required: - code Error422Code: description: | One of the following error codes: - missingProperty: The property the Seller has expected is not present in the payload - invalidValue: The property has an incorrect value - invalidFormat: The property value does not comply with the expected value format - referenceNotFound: The object referenced by the property cannot be identified in the Seller system - unexpectedProperty: Additional property, not expected by the Seller has been provided - tooManyRecords: the number of records to be provided in the response exceeds the Seller's threshold. - otherIssue: Other problem was identified (detailed information provided in a reason) type: string enum: - missingProperty - invalidValue - invalidFormat - referenceNotFound - unexpectedProperty - tooManyRecords - otherIssue Error500: description: >- Internal Server Error. (https://tools.ietf.org/html/rfc7231#section-6.6.1) allOf: - $ref: '#/components/schemas/Error' - type: object properties: code: description: >- The following error code: - internalError: Internal server error - the server encountered an unexpected condition that prevented it from fulfilling the request. type: string enum: - internalError required: - code EventSubscription: description: >- Sets the communication endpoint address the service instance must use to deliver notification information type: object properties: callback: description: >- The value provided by the Buyer in `EventSubscriptionInput` during notification registration type: string id: description: >- An identifier of the event subscription assigned by the Seller when a resource is created. type: string query: description: >- This attribute is used to define notification registration constraints. type: string required: - callback - id EventSubscriptionInput: description: This class is used to register for Notifications. type: object properties: callback: description: >- This callback value must be set to *host* property from Buyer Notification API (appointmentNotification.api.yaml). This property is appended with the base path and notification resource path specified in that API to construct an URL to which notification is sent. E.g. for "callback": "http://buyer.mef.com/listenerEndpoint", the status change event notification will be sent to: `http://buyer.mef.com/listenerEndpoint/mefApi/cantata/appointmentNotification/v3/listener/appointmentStatusChangeEvent` type: string query: description: >- This attribute is used to define to which type of events to register to. Example: "query":"eventType = AppointmentStatusChangeEvent". To subscribe for more than one event type, put the values separated by comma: `eventType=AppointmentStatusChangeEvent,AppointmentResolvedEvent`. The possible values are enumerated by the 'AppointmentEventType' in AppointmentNotification.api.yaml. An empty query is treated as specifying no filters - ending in subscription for all event types. type: string required: - callback FieldedAddressRepresentation: description: >- A type of Address that has a discrete field and value for each type of boundary or identifier down to the lowest level of detail. For example "street number" is one field, "street name" is another field, etc. type: object properties: streetNr: description: >- Number identifying a specific property on a public street. It may be combined with streetNrLast for ranged addresses. type: string streetNrSuffix: description: >- The first street number suffix (in a street number range) or the suffix for the street number if there is no range type: string streetNrLast: description: Last number in a range of street numbers allocated to an Address type: string streetNrLastSuffix: description: Last street number suffix for a ranged Address type: string streetPreDirection: description: The direction of the street that appears before the Street Name type: string streetName: description: Name of the street or other street type type: string streetType: description: >- The type of street (e.g., alley, avenue, boulevard, brae, crescent, drive, highway, lane, terrace, parade, place, tarn, way, wharf) type: string streetPostDirection: description: >- A modifier denoting a relative direction that appears after the Street Name. type: string poBox: description: Number identifying a specific location in a post office. type: string locality: description: >- An area of defined or undefined boundaries within a local authority or other legislatively defined area. type: string city: description: City in which the Address is located. type: string postcode: description: >- A descriptor for a postal delivery area used to speed and simplify the delivery of mail (also known as zip code) type: string postcodeExtension: description: >- The extension used on a postal code. Note: there are different use codes for this attribute depending upon the country. type: string stateOrProvince: description: The State or Province in which the Address is located. type: string countryCode: description: >- Country in which the Address is located, defined using two characters as defined in ISO 3166 type: string minLength: 2 maxLength: 2 subUnit: description: >- The Sub Unit represented as a list. This is a list to allow complex sub-unit information such as SUITE 42 ROOM A type: array items: $ref: '#/components/schemas/SubUnit' buildingName: description: > The well-known name of a building that is located at this Address (e.g., where there is one Address for a campus). type: string privateStreetNumber: description: Street number on a private street within the Address. type: string privateStreetName: description: >- Private streets internal to a property (e.g., a university) may have internal names that are not recorded by the land title office. type: string language: description: >- The language in which the address is expressed. It MUST use the ISO 639:2023 two letter code 639:2023 type: string minLength: 2 maxLength: 2 FormattedAddressRepresentation: description: 'A freeform text representation agreed to by the Buyer and Seller. ' type: object properties: formattedAddress: description: >- A formatted Address Representation that contains a non-fielded address. type: string language: description: >- The language in which the address is expressed. Based on ISO 639:2023 type: string minLength: 2 maxLength: 2 required: - formattedAddress GeographicAddressRef: description: > A reference to a Geographic Address resource available through Address Validation API. type: object properties: href: description: > Hyperlink to the referenced Address. Hyperlink MAY be used by the Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request. type: string id: description: >- Identifier of the referenced Geographic Address. This identifier is assigned during a successful address validation request (Geographic Address Management API) type: string '@type': description: Used to unambiguously designate the class type when using `oneOf` type: string enum: - GeographicAddressRef required: - '@type' - id GeographicAddress_Query: description: >- A list of representations being a subset of Geographic Address entity. This is to be used when providing a list of representations to validate or search for a Geographic Address type: object properties: fieldedAddressRepresentation: description: A list of Fielded Address representations type: array items: $ref: '#/components/schemas/FieldedAddressRepresentation' formattedAddressRepresentation: description: A list of Formatted Address representations type: array items: $ref: '#/components/schemas/FormattedAddressRepresentation' geographicPointRepresentation: description: A list of Geographic Point Address representations type: array items: $ref: '#/components/schemas/GeographicPointRepresentation' labelRepresentation: description: A list of Label Address representations type: array items: $ref: '#/components/schemas/LabelRepresentation' '@type': description: Used to unambiguously designate the class type when using `oneOf` type: string enum: - GeographicAddress_Query required: - '@type' minProperties: 2 GeographicPointRepresentation: description: > A GeographicPointRepresentation defines a geographic point through coordinates. type: object properties: spatialRef: description: >- The spatial reference system used to determine the coordinates. The system used and the value of this field are to be agreed during the onboarding process. type: string latitude: description: The latitude expressed in the format specified by the `spacialRef` type: string longitude: description: The longitude expressed in the format specified by the `spacialRef` type: string elevation: description: The elevation expressed in the format specified by the `spacialRef` type: string required: - latitude - longitude - spatialRef GeographicSiteRef: description: > A reference to a Geographic Site resource available through Service Site API type: object properties: href: description: > Hyperlink to the referenced Site. Hyperlink MAY be used by the Seller in responses. Hyperlink MUST be ignored by the Seller in case it is provided by the Buyer in a request. type: string id: description: Identifier of the referenced Geographic Site. type: string '@type': description: Used to unambiguously designate the class type when using `oneOf` type: string enum: - GeographicSiteRef required: - '@type' - id LabelRepresentation: description: >- A unique identifier controlled by a generally accepted independent administrative authority that specifies a fixed geographical location. type: object properties: label: description: >- The unique reference to a Geographic Address assigned by the Administrative Authority. type: string administrativeAuthority: description: >- The organization or standard from the organization that administers this Geographic Address Label ensuring it is unique within the Administrative Authority. type: string language: description: 'The language in which the label is expressed. Based on ISO 639:2023' type: string minLength: 2 maxLength: 2 required: - administrativeAuthority - label MEFBuyerSellerType: description: An enumeration with buyer and seller values. type: string enum: - buyer - seller MEFByteSize: description: A size represented by value and Byte units type: object properties: amount: description: Numeric value in a given unit type: number format: float units: description: Byte Unit $ref: '#/components/schemas/DataSizeUnit' required: - amount - units Note: description: >- Extra information about a given entity. Only useful in processes involving human interaction. Not applicable to an automated process. type: object properties: author: description: Author of the note type: string date: description: Date of the note type: string format: date-time id: description: >- Identifier of the note within its containing entity (may or may not be globally unique, depending on provider implementation) type: string source: description: Indicates if this Note was added by the Buyer or Seller. $ref: '#/components/schemas/MEFBuyerSellerType' text: description: Text of the note type: string required: - author - date - id - source - text PlaceRefOrQuery: description: >- A place described by reference to a Geographic Address, Geographic Site or by Geographic Address Representations. type: object discriminator: propertyName: '@type' mapping: GeographicAddressRef: '#/components/schemas/GeographicAddressRef' GeographicSiteRef: '#/components/schemas/GeographicSiteRef' GeographicAddress_Query: '#/components/schemas/GeographicAddress_Query' oneOf: - $ref: '#/components/schemas/GeographicAddressRef' - $ref: '#/components/schemas/GeographicSiteRef' - $ref: '#/components/schemas/GeographicAddress_Query' RelatedContactInformation: description: >- Contact data for a person or organization that is involved in the product offering qualification. In a given context it is always specified by the Seller (e.g. Seller Contact Information) or by the Buyer. type: object properties: role: description: The role of the particular contact in the request type: string number: description: Phone number type: string emailAddress: description: Email address type: string postalAddress: description: >- Identifies the postal address of the person or office to be contacted. $ref: '#/components/schemas/FieldedAddressRepresentation' organization: description: The organization or company that the contact belongs to type: string name: description: Name of the contact type: string numberExtension: description: Phone number extension type: string required: - emailAddress - name - number - role RelatedPlaceRefOrQuery: description: >- Allows pointing to a place by referring to a GeographicAddress, GeographicSite, or providing GeographicAddress by value. It also provides additional information like the `role` the place plays for given Product and `contact` needed access to this place. type: object properties: place: $ref: '#/components/schemas/PlaceRefOrQuery' role: description: >- Role of this place. The values that can be specified here are described by Product Specification (e.g. "INSTALL_LOCATION"). type: string contact: description: >- The person to call to get access to this place in case such access is required to complete the evaluation of this POQ Item. type: array items: $ref: '#/components/schemas/ContactInformation' required: - place - role SearchTimeSlot: description: >- This task resource is used to retrieve available time slots. One of this available time slot is after used to create or reschedule an appointment type: object properties: availableTimeSlot: description: >- A set of time slots with the availability of a Seller Technician returned by the Seller, which the Buyer may select for creating or rescheduling an Appointment. type: array items: $ref: '#/components/schemas/TimeSlot' requestedTimeSlot: description: >- A set of preferred time slots the Buyer is requesting the Seller to verify for availability by a Sellers Technician at the Place referenced in the Appointment Related Entity. For example Monday thru Friday, or a set of specific time slots. type: array items: $ref: '#/components/schemas/TimeSlot' workOrder: description: A reference to a WorkOrder for which the Appointment is created. $ref: '#/components/schemas/WorkOrderRef' required: - availableTimeSlot - requestedTimeSlot - workOrder SearchTimeSlot_Create: description: >- This task resource is used to retrieve available time slots. One of this available time slot is after used to create or reschedule an appointment type: object properties: requestedTimeSlot: description: >- A set of preferred time slots the Buyer is requesting the Seller to verify for availability by a Sellers Technician at the Place referenced in the Appointment Related Entity. For example Monday thru Friday, or a set of specific time slots. type: array items: $ref: '#/components/schemas/TimeSlot' workOrder: description: A reference to a WorkOrder for which the Appointment is created. $ref: '#/components/schemas/WorkOrderRef' required: - requestedTimeSlot - workOrder SubUnit: description: Allows for sub unit identification type: object properties: subUnitNumber: description: >- The discriminator used for the subunit, often just a simple number but may also be a range. type: string subUnitType: description: >- The type of subunit e.g. BERTH, FLAT, PIER, SUITE, SHOP, TOWER, UNIT, WHARF. type: string required: - subUnitNumber - subUnitType TimePeriod: description: >- A period of time, either as a deadline (endDateTime only) a startDateTime only, or both type: object properties: endDateTime: description: 'End of the time period, using IETC-RFC-3339 format' type: string format: date-time startDateTime: description: >- Start of the time period, using IETC-RFC-3339 format. If you define a start, you must also define an end type: string format: date-time required: - endDateTime - startDateTime TimeSlot: type: object properties: validFor: description: Start date and end date of the timeSlot $ref: '#/components/schemas/TimePeriod' required: - validFor WorkOrderRef: description: | A reference to an WorkOrder resource. type: object properties: href: description: | Hyperlink to the referenced WorkOrder. type: string id: description: Identifier of the referenced WorkOrder. type: string required: - id