openapi: 3.0.3
info:
  title: European Client Register API
  description: >-
    API for managing clients, tasks, messages, notes, products, services, and
    orders based on European standards
  version: 1.0.0
  contact:
    name: Open Register
    url: https://openregister.dev
    email: info@openregister.dev
  license:
    name: EUPL-1.2
    url: https://joinup.ec.europa.eu/collection/eupl/eupl-text-eupl-12
servers:
  - url: https://api.example.com/v1
    description: Production server
  - url: https://staging-api.example.com/v1
    description: Staging server
tags:
  - name: clients
    description: >-
      Client information based on EU Core Vocabularies, Schema.org
      Person/Organization and vCard
  - name: tasks
    description: Tasks based on iCalendar VTODO and Schema.org PlanAction
  - name: messages
    description: >-
      Client communication messages based on RFC 5322, JMAP, and Schema.org
      Message
  - name: notes
    description: Notes about clients based on Schema.org Comment and UBL Note
  - name: products
    description: Products based on UBL Item and Schema.org Product
  - name: services
    description: Services based on CPSV and Schema.org Service
  - name: orders
    description: Orders based on UBL Order and Schema.org Order
  - name: orderItems
    description: Order items based on UBL OrderLine and Schema.org OrderItem
security:
  - oauth2:
      - read
      - write
paths:
  /clients:
    get:
      summary: Retrieve a list of Client
      operationId: getClient
      tags:
        - Client
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Client'
    post:
      summary: Create a new Client
      operationId: createClient
      tags:
        - Client
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Client'
      responses:
        '201':
          description: Client created successfully
  /clients/{id}:
    get:
      summary: Retrieve a Client by ID
      operationId: getClientById
      tags:
        - Client
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Client'
        '404':
          description: Client not found
    put:
      summary: Update a Client by ID
      operationId: updateClient
      tags:
        - Client
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Client'
      responses:
        '200':
          description: Client updated successfully
        '404':
          description: Client not found
    delete:
      summary: Delete a Client by ID
      operationId: deleteClient
      tags:
        - Client
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Client deleted successfully
        '404':
          description: Client not found
  /tasks:
    get:
      summary: Retrieve a list of Task
      operationId: getTask
      tags:
        - Task
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Task'
    post:
      summary: Create a new Task
      operationId: createTask
      tags:
        - Task
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '201':
          description: Task created successfully
  /tasks/{id}:
    get:
      summary: Retrieve a Task by ID
      operationId: getTaskById
      tags:
        - Task
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
        '404':
          description: Task not found
    put:
      summary: Update a Task by ID
      operationId: updateTask
      tags:
        - Task
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Task'
      responses:
        '200':
          description: Task updated successfully
        '404':
          description: Task not found
    delete:
      summary: Delete a Task by ID
      operationId: deleteTask
      tags:
        - Task
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Task deleted successfully
        '404':
          description: Task not found
  /messages:
    get:
      summary: Retrieve a list of Message
      operationId: getMessage
      tags:
        - Message
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Message'
    post:
      summary: Create a new Message
      operationId: createMessage
      tags:
        - Message
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '201':
          description: Message created successfully
  /messages/{id}:
    get:
      summary: Retrieve a Message by ID
      operationId: getMessageById
      tags:
        - Message
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '404':
          description: Message not found
    put:
      summary: Update a Message by ID
      operationId: updateMessage
      tags:
        - Message
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Message'
      responses:
        '200':
          description: Message updated successfully
        '404':
          description: Message not found
    delete:
      summary: Delete a Message by ID
      operationId: deleteMessage
      tags:
        - Message
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Message deleted successfully
        '404':
          description: Message not found
  /notes:
    get:
      summary: Retrieve a list of Note
      operationId: getNote
      tags:
        - Note
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Note'
    post:
      summary: Create a new Note
      operationId: createNote
      tags:
        - Note
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Note'
      responses:
        '201':
          description: Note created successfully
  /notes/{id}:
    get:
      summary: Retrieve a Note by ID
      operationId: getNoteById
      tags:
        - Note
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Note'
        '404':
          description: Note not found
    put:
      summary: Update a Note by ID
      operationId: updateNote
      tags:
        - Note
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Note'
      responses:
        '200':
          description: Note updated successfully
        '404':
          description: Note not found
    delete:
      summary: Delete a Note by ID
      operationId: deleteNote
      tags:
        - Note
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '204':
          description: Note deleted successfully
        '404':
          description: Note not found
components:
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.example.com/authorize
          tokenUrl: https://auth.example.com/token
          scopes:
            read: Read access to API
            write: Write access to API
  schemas:
    Client:
      type: object
      description: >-
        Client information based on Schema.org Person/Organization and vCard
        standard
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the client
        '@type':
          type: string
          enum:
            - Person
            - Organization
          description: Schema.org type of the client
          example: Person
        name:
          type: string
          description: Full name of the client (Schema.org name, vCard FN)
          example: John Smith
        givenName:
          type: string
          description: First name (Schema.org givenName, part of vCard N)
          example: John
        familyName:
          type: string
          description: Last name (Schema.org familyName, part of vCard N)
          example: Smith
        additionalName:
          type: string
          description: Middle name (Schema.org additionalName, part of vCard N)
          example: Robert
        honorificPrefix:
          type: string
          description: Title prefix (Schema.org honorificPrefix, part of vCard N)
          example: Dr.
        honorificSuffix:
          type: string
          description: Title suffix (Schema.org honorificSuffix, part of vCard N)
          example: Jr.
        jobTitle:
          type: string
          description: Job title (Schema.org jobTitle, vCard TITLE)
          example: Director
        worksFor:
          type: string
          description: Organization the person works for (Schema.org worksFor, vCard ORG)
          example: Acme, Inc.
        department:
          type: string
          description: Department within organization (part of vCard ORG)
          example: Marketing
        image:
          type: string
          format: uri
          description: URL to client photo/avatar (Schema.org image, vCard PHOTO)
          example: https://example.com/photos/john-smith.jpg
        telephone:
          type: array
          description: Phone numbers (Schema.org telephone, vCard TEL)
          items:
            type: object
            properties:
              value:
                type: string
                example: +1-555-123-4567
              type:
                type: string
                enum:
                  - work
                  - home
                  - mobile
                  - fax
                  - other
                example: work
        email:
          type: array
          description: Email addresses (Schema.org email, vCard EMAIL)
          items:
            type: object
            properties:
              value:
                type: string
                format: email
                example: john.smith@example.com
              type:
                type: string
                enum:
                  - work
                  - home
                  - other
                example: work
        address:
          type: array
          description: Addresses (Schema.org address, vCard ADR)
          items:
            type: object
            properties:
              streetAddress:
                type: string
                description: Street address (Schema.org streetAddress)
                example: 123 Main St
              addressLocality:
                type: string
                description: City (Schema.org addressLocality)
                example: Anytown
              addressRegion:
                type: string
                description: State/province (Schema.org addressRegion)
                example: CA
              postalCode:
                type: string
                description: Postal code (Schema.org postalCode)
                example: '12345'
              addressCountry:
                type: string
                description: Country (Schema.org addressCountry)
                example: US
              type:
                type: string
                enum:
                  - work
                  - home
                  - other
                example: work
        url:
          type: array
          description: Websites (Schema.org url, vCard URL)
          items:
            type: object
            properties:
              value:
                type: string
                format: uri
                example: https://example.com
              type:
                type: string
                enum:
                  - work
                  - personal
                  - other
                example: work
        birthDate:
          type: string
          format: date
          description: Date of birth (Schema.org birthDate, vCard BDAY)
          example: '1980-01-15'
        note:
          type: string
          description: General notes about the client (Schema.org description, vCard NOTE)
          example: Prefers to be contacted by email.
        dateCreated:
          type: string
          format: date-time
          description: When the client record was created (Schema.org dateCreated)
        dateModified:
          type: string
          format: date-time
          description: When the client record was last updated (Schema.org dateModified)
      required:
        - id
        - '@type'
        - name
    Task:
      type: object
      description: Task based on Schema.org PlanAction and iCalendar VTODO
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the task
        '@type':
          type: string
          default: PlanAction
          description: Schema.org type
        name:
          type: string
          description: Task name/summary (Schema.org name, iCal SUMMARY)
          example: Prepare client proposal
        description:
          type: string
          description: Task description (Schema.org description, iCal DESCRIPTION)
          example: >-
            Create a detailed proposal for the new website project including
            timeline and budget.
        startDate:
          type: string
          format: date-time
          description: Start date/time (Schema.org startTime, iCal DTSTART)
          example: '2023-06-15T09:00:00Z'
        endDate:
          type: string
          format: date-time
          description: Due date/time (Schema.org endTime, iCal DUE)
          example: '2023-06-20T17:00:00Z'
        completedDate:
          type: string
          format: date-time
          description: Completion date/time (Schema.org endTime, iCal COMPLETED)
          example: '2023-06-19T16:30:00Z'
        actionStatus:
          type: string
          description: Task status (Schema.org actionStatus, iCal STATUS)
          enum:
            - PotentialActionStatus
            - ActiveActionStatus
            - CompletedActionStatus
            - FailedActionStatus
            - CanceledActionStatus
          example: ActiveActionStatus
        priority:
          type: integer
          description: Priority (0-9, 0=undefined, 1=highest, 9=lowest) (iCal PRIORITY)
          minimum: 0
          maximum: 9
          example: 2
        percentComplete:
          type: integer
          description: Percent complete (0-100) (iCal PERCENT-COMPLETE)
          minimum: 0
          maximum: 100
          example: 75
        category:
          type: array
          description: Categories/tags (Schema.org category, iCal CATEGORIES)
          items:
            type: string
          example:
            - proposal
            - client
            - website
        agent:
          type: object
          description: Person assigned to the task (Schema.org agent, iCal ORGANIZER)
          properties:
            id:
              type: string
              description: ID of the user in the system
              example: user-123
            name:
              type: string
              example: Jane Doe
        participant:
          type: array
          description: Other participants (Schema.org participant, iCal ATTENDEE)
          items:
            type: object
            properties:
              id:
                type: string
                description: ID of the user in the system
                example: user-456
              name:
                type: string
                example: John Smith
              role:
                type: string
                example: reviewer
        recurrenceRule:
          type: string
          description: Recurrence rule (iCal RRULE)
          example: FREQ=WEEKLY;BYDAY=MO,WE,FR
        clientId:
          type: string
          format: uuid
          description: ID of the client this task is associated with
        dateCreated:
          type: string
          format: date-time
          description: >-
            When the task record was created (Schema.org dateCreated, iCal
            CREATED)
        dateModified:
          type: string
          format: date-time
          description: >-
            When the task record was last updated (Schema.org dateModified, iCal
            LAST-MODIFIED)
      required:
        - id
        - name
        - actionStatus
        - clientId
    Message:
      type: object
      description: Message based on Schema.org Message and email standards
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the message
        '@type':
          type: string
          default: Message
          description: Schema.org type
        about:
          type: string
          description: Message subject (Schema.org about, email Subject)
          example: Website Project Proposal
        text:
          type: string
          description: Message content (Schema.org text, email Body)
          example: >-
            Dear John,


            Attached is the proposal for your website project. Please review and
            let me know if you have any questions.


            Best regards,

            Jane
        sender:
          type: object
          description: Sender information (Schema.org sender, email From)
          properties:
            name:
              type: string
              example: Jane Doe
            email:
              type: string
              format: email
              example: jane.doe@example.com
        recipient:
          type: array
          description: Recipients (Schema.org recipient, email To)
          items:
            type: object
            properties:
              name:
                type: string
                example: John Smith
              email:
                type: string
                format: email
                example: john.smith@example.com
        ccRecipient:
          type: array
          description: CC recipients (email Cc)
          items:
            type: object
            properties:
              name:
                type: string
                example: Alice Brown
              email:
                type: string
                format: email
                example: alice.brown@example.com
        bccRecipient:
          type: array
          description: BCC recipients (email Bcc)
          items:
            type: object
            properties:
              name:
                type: string
                example: Bob Green
              email:
                type: string
                format: email
                example: bob.green@example.com
        dateSent:
          type: string
          format: date-time
          description: When message was sent (Schema.org dateSent, email Date)
          example: '2023-06-10T14:30:00Z'
        dateReceived:
          type: string
          format: date-time
          description: When message was received (Schema.org dateReceived, email Received)
          example: '2023-06-10T14:31:05Z'
        dateRead:
          type: string
          format: date-time
          description: When message was read (custom extension)
          example: '2023-06-10T15:45:22Z'
        attachment:
          type: array
          description: File attachments (Schema.org attachment, email Attachments)
          items:
            type: object
            properties:
              name:
                type: string
                example: proposal.pdf
              contentUrl:
                type: string
                format: uri
                example: https://example.com/files/proposal.pdf
              encodingFormat:
                type: string
                example: application/pdf
              contentSize:
                type: string
                example: 2.4 MB
        messageId:
          type: string
          description: Unique message identifier (email Message-ID)
          example: <1234567890@mail.example.com>
        inReplyTo:
          type: string
          description: Message this is a reply to (email In-Reply-To)
          example: <0987654321@mail.example.com>
        references:
          type: array
          description: Thread references (email References)
          items:
            type: string
          example:
            - <0987654321@mail.example.com>
            - <5678901234@mail.example.com>
        channel:
          type: string
          description: Communication channel (custom extension)
          enum:
            - email
            - sms
            - chat
            - phone
            - video
            - social
          example: email
        direction:
          type: string
          description: Message direction (custom extension)
          enum:
            - inbound
            - outbound
          example: outbound
        status:
          type: string
          description: Delivery status (custom extension)
          enum:
            - draft
            - sending
            - sent
            - delivered
            - read
            - failed
          example: delivered
        clientId:
          type: string
          format: uuid
          description: ID of the client this message is associated with
        dateCreated:
          type: string
          format: date-time
          description: When the message record was created (Schema.org dateCreated)
        dateModified:
          type: string
          format: date-time
          description: When the message record was last updated (Schema.org dateModified)
      required:
        - id
        - about
        - text
        - sender
        - recipient
        - channel
        - direction
        - clientId
    Note:
      type: object
      description: Note based on Schema.org Comment and UBL Note
      properties:
        id:
          type: string
          format: uuid
          description: Unique identifier for the note
        '@type':
          type: string
          default: Comment
          description: Schema.org type
        title:
          type: string
          description: Note title (Schema.org name)
          example: Meeting Summary - June 10
        content:
          type: string
          description: Note content (Schema.org text, UBL Note)
          example: >-
            Met with client to discuss new requirements for the website project.
            They want to add an e-commerce section and integrate with their
            inventory system.
        about:
          type: string
          format: uuid
          description: ID of the entity this note is about (Schema.org about)
          example: 550e8400-e29b-41d4-a716-446655440000
        format:
          type: string
          description: Content format (Schema.org encodingFormat)
          enum:
            - text/plain
            - text/html
            - text/markdown
          example: text/markdown
        language:
          type: string
          description: Content language (Schema.org inLanguage, UBL LanguageID)
          example: en-US
        createdBy:
          type: object
          description: Author information (Schema.org author, UBL IssuerParty)
          properties:
            id:
              type: string
              description: ID of the user in the system
              example: user-123
            name:
              type: string
              example: Jane Doe
        createdAt:
          type: string
          format: date-time
          description: When the note was created (Schema.org dateCreated, UBL IssueDate)
          example: '2023-06-10T16:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: When the note was last updated (Schema.org dateModified)
          example: '2023-06-11T09:15:00Z'
        version:
          type: string
          description: Version number (Schema.org version, UBL VersionID)
          example: '1.2'
        parent:
          type: string
          description: Parent container reference (Schema.org isPartOf)
          example: folder-789
        tags:
          type: array
          description: Categorization tags (Schema.org keywords)
          items:
            type: string
          example:
            - meeting
            - requirements
            - important
        visibility:
          type: string
          description: Who can see the note (custom extension)
          enum:
            - private
            - team
            - public
          example: team
        pinned:
          type: boolean
          description: Whether note is pinned (custom extension)
          example: true
        shared:
          type: object
          description: Sharing status (custom extension)
          properties:
            type:
              type: string
              enum:
                - none
                - user
                - team
                - public
              example: team
            users:
              type: array
              items:
                type: string
              example:
                - user-456
        permissions:
          type: array
          description: Access rights (custom extension)
          items:
            type: string
            enum:
              - read
              - write
              - share
              - delete
          example:
            - read
            - write
            - share
      required:
        - id
        - content
        - about
        - createdBy
        - createdAt