openapi: 3.0.3
info:
  title: Catena - OpenAPI 3.0
  description: Service that allows a client application to manage work declarations.
  version: 0.1.0
  contact:
    name: Smals

servers:
  - url: http://localhost:8888/REST/enterpriseWorkContractChain/v1
    description: Development environment
  - url: https://services-test.socialsecurity.be/REST/enterpriseWorkContractChain/v1
    description: Test environment
  - url: https://services-int.socialsecurity.be/REST/enterpriseWorkContractChain/v1
    description: Integration environment
  - url: https://services-acpt.socialsecurity.be/REST/enterpriseWorkContractChain/v1
    description: Acceptation environment
  - url: https://services.socialsecurity.be/REST/enterpriseWorkContractChain/v1
    description: Production environment

security:
  - Oauth:
      - "scope:rsz-onss:management:catena:enterprise"
      - "scope:rsz-onss:management:catena:professional-system-consult"
      - "scope:rsz-onss:management:catena:professional-system-create"
      - "scope:rsz-onss:management:catena:professional-system-update"
      - "scope:rsz-onss:management:catena:professional-system-delete"
      - "scope:rsz-onss:management:catena:monitoring"
x-oauth2-required-scopes: any

tags:
  - name: Declarations
    description: Create and retrieve declarations
  - name: Contracts
    description: Create and retrieve contracts
  - name: Subcontracting Relationships
    description: Create and retrieve subcontracting relationships
  - name: Remarks
    description: Retrieve remarks
  - name: RefData
    description: Retrieve referential data
  - name: Monitoring
    description: Monitoring endpoints

paths:
  /health:
    get:
      tags:
        - Monitoring
      summary: Check health of the service
      description: This resource is only available to supervision users
      operationId: checkHealth
      externalDocs:
        url: "https://www.belgif.be/specification/rest/api-guide/#health"
      responses:
        "200":
          "$ref": "#/components/responses/HealthUpOrDegradedResponse"
        "503":
          "$ref": "#/components/responses/HealthDownResponse"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:monitoring"

  /declarations:
    post:
      tags:
        - Declarations
      summary: Create a new declaration along with a new contract and its corresponding subcontracting relationship
      description: Create a new declaration, generate a new contract and a new subcontracting relationship, then establish a link between them.
      operationId: createDeclaration
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/DeclarationCreation"
      responses:
        201:
          description: Results of the declaration creation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeclarationCreation"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-create"
      x-oauth2-required-scopes: any

  /declarations/{declarationId}/contracts:
    post:
      tags:
        - Contracts
      summary: Create a new contract and its corresponding subcontracting relationship
      operationId: createContract
      parameters:
        - name: declarationId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/DeclarationReference"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractCreation"
      responses:
        201:
          description: Results of the contract creation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contract"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-create"
      x-oauth2-required-scopes: any

  /contracts/{contractId}:
    put:
      tags:
        - Contracts
      summary: Update a contract
      operationId: updateContract
      parameters:
        - name: contractId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ContractReference"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractUpdate"
      responses:
        200:
          description: Results of the contract update
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Contract"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-update"
      x-oauth2-required-scopes: any

  /contracts/search:
    post:
      tags:
        - Contracts
      summary: Search contracts
      description: Search contracts based on criteria passed in the request body.
      operationId: searchContracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ContractSearch"
      parameters:
        - $ref: "#/components/parameters/PageParameter"
        - $ref: "#/components/parameters/PageSizeParameter"
      responses:
        200:
          description: A page of the contract search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ContractPage"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-consult"
      x-oauth2-required-scopes: any

  /contracts/{contractId}/subcontractingRelationships:
    post:
      tags:
        - Subcontracting Relationships
      summary: Create a new subcontracting relationship
      operationId: createSubcontractingRelationship
      parameters:
        - name: contractId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ContractReference"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubcontractingRelationshipCreation"
      responses:
        201:
          description: Results of the subcontracting relationship creation
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubcontractingRelationship"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-create"
      x-oauth2-required-scopes: any

  /contracts/{contractId}/remarks:
    get:
      tags:
        - Remarks
      summary: Get remarks of a contract
      operationId: getRemarksByContract
      parameters:
        - name: contractId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/ContractReference"
      responses:
        200:
          description: List of remarks of a contract
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemarkList"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-consult"
      x-oauth2-required-scopes: any

  /subcontractingRelationships/{subcontractingRelationshipId}/remarks:
    get:
      tags:
        - Remarks
      summary: Get remarks of a subcontracting relationship
      operationId: getRemarksBySubcontractingRelationship
      parameters:
        - name: subcontractingRelationshipId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/SubcontractingRelationshipReference"
      responses:
        200:
          description: List of remarks of a subcontracting relationship
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemarkList"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-consult"
      x-oauth2-required-scopes: any

  /subcontractingRelationships/{subcontractingRelationshipId}:
    put:
      tags:
        - Subcontracting Relationships
      summary: Update a subcontracting relationship
      operationId: updateSubcontractingRelationship
      parameters:
        - name: subcontractingRelationshipId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/SubcontractingRelationshipReference"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubcontractingRelationshipUpdate"
      responses:
        200:
          description: Results of the subcontracting relationship update
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubcontractingRelationship"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-update"
      x-oauth2-required-scopes: any
    delete:
      tags:
        - Subcontracting Relationships
      summary: Delete a subcontracting relationship
      operationId: deleteSubcontractingRelationship
      parameters:
        - name: subcontractingRelationshipId
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/SubcontractingRelationshipReference"
      responses:
        204:
          description: Removal was successful.
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-delete"
      x-oauth2-required-scopes: any

  /subcontractingRelationships/search:
    post:
      tags:
        - Subcontracting Relationships
      summary: Search subcontracting relationships
      description: Search subcontracting relationships based on criteria passed in the request body.
      operationId: searchSubcontractingRelationships
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SubcontractingRelationshipSearch"
      parameters:
        - $ref: "#/components/parameters/PageParameter"
        - $ref: "#/components/parameters/PageSizeParameter"
      responses:
        200:
          description: A page of the subcontracting relationship search results
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SubcontractingRelationshipPage"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-consult"
      x-oauth2-required-scopes: any

  /refData/declarationContexts:
    get:
      tags:
        - RefData
      summary: Retrieve all declaration context codes & labels
      description: Retrieve all context codes & their i18n labels (FR/NL/DE/EN)
      operationId: getAllContextDetails
      responses:
        200:
          description: List of available declaration contexts
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeclarationContextList"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-consult"
            - "scope:rsz-onss:management:catena:professional-system-create"
            - "scope:rsz-onss:management:catena:professional-system-update"
            - "scope:rsz-onss:management:catena:professional-system-delete"
      x-oauth2-required-scopes: any

  /refData/declarationContexts/{declarationContextCode}:
    get:
      tags:
        - RefData
      summary: Return a declaration context by its code.
      description: Retrieve a context detail (code & i18n labels) by its code.
      operationId: getContextDetails
      parameters:
        - in: path
          name: declarationContextCode
          description: The code of the context
          example: delivery
          required: true
          schema:
            type: string
      responses:
        200:
          description: Declaration context details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DeclarationContext"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-consult"
            - "scope:rsz-onss:management:catena:professional-system-create"
            - "scope:rsz-onss:management:catena:professional-system-update"
            - "scope:rsz-onss:management:catena:professional-system-delete"
      x-oauth2-required-scopes: any

  /refData/remarks:
    get:
      tags:
        - RefData
      summary: Retrieve all remarks codes & descriptions
      description: Retrieve all remarks codes & their i18n descriptions (FR/NL/DE/EN)
      operationId: getAllRemarkDetails
      responses:
        200:
          description: List of available remarks
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemarkRefList"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-consult"
            - "scope:rsz-onss:management:catena:professional-system-create"
            - "scope:rsz-onss:management:catena:professional-system-update"
            - "scope:rsz-onss:management:catena:professional-system-delete"
      x-oauth2-required-scopes: any

  /refData/remarks/{remarkCode}:
    get:
      tags:
        - RefData
      summary: Return a remark by its code.
      description: Retrieve a remark detail (code, i18n description & i18n resolution) by its code.
      operationId: getRemarkDetails
      parameters:
        - in: path
          name: remarkCode
          description: The code of the remark
          example: actor_bankruptcy
          required: true
          schema:
            $ref: "#/components/schemas/RemarkRefCode"
      responses:
        200:
          description: Remark details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RemarkDetailRef"
        default:
          $ref: "#/components/responses/ProblemResponse"
      security:
        - Oauth:
            - "scope:rsz-onss:management:catena:enterprise"
            - "scope:rsz-onss:management:catena:professional-system-consult"
            - "scope:rsz-onss:management:catena:professional-system-create"
            - "scope:rsz-onss:management:catena:professional-system-update"
            - "scope:rsz-onss:management:catena:professional-system-delete"
      x-oauth2-required-scopes: any

components:
  parameters:
    PageParameter:
      name: page
      in: query
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1

    PageSizeParameter:
      name: pageSize
      in: query
      required: false
      schema:
        type: integer
        default: 50
        minimum: 1
        maximum: 50

  responses:
    HealthUpOrDegradedResponse:
      description: The service is UP or DEGRADED
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HealthStatus"
          examples:
            responseUp:
              description: API is available
              value: { "status": "UP" }
            responseDegraded:
              description: API is available, but with reduced functionality
              value: { "status": "DEGRADED" }

    HealthDownResponse:
      description: The service is DOWN
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/HealthStatus"
          examples:
            responseDown:
              value: { "status": "DOWN" }

    ProblemResponse:
      content:
        application/problem+json:
          schema:
            $ref: "#/components/schemas/Problem"
      description: A problem

  schemas:
    HealthStatus:
      type: object
      description: Response message for the API health
      properties:
        status:
          description: "Level indicating the health status of the service: UP (functioning as expected), DOWN (suffering unexpected failures), DEGRADED (partly unavailable but service can be continued with reduced functionality), or a custom status value"
          type: string
      required:
        - status

    DeclarationReference:
      type: string
      description: Reference of a particular declaration ; must contain 13 characters (digits or letters (no 'i' and 'o')).
      pattern: "^[A-HJ-NP-Z0-9]{13}$"
      example: 1Y1012345678P

    Declaration:
      type: object
      description: |
        Representation of a declaration. \
        A declaration of works is a concept that summarizes the common characteristics of the related contracts and connects the owner with contractors.
      required:
        - context
        - purpose
      properties:
        id:
          $ref: "#/components/schemas/DeclarationReference"
        context:
          $ref: "#/components/schemas/DeclarationContextCode"
        purpose:
          $ref: "#/components/schemas/Purpose"
    
    DeclarationCreation:
      type: object
      description: Data required to create a declaration along with a new contract and its corresponding subcontracting relationship
      required:
        - declaration
        - contract
      properties:
        declaration:
          allOf:
            - $ref: "#/components/schemas/Declaration"
            - properties:
                id:
                  type: string
                  readOnly: true
        contract:
          allOf:
            - $ref: "#/components/schemas/ContractCreation"
            - properties:
                declarationId:
                  allOf:
                    - $ref: "#/components/schemas/DeclarationReference"
                    - readOnly: true

    DeclarationSearchCriteria:
      type: object
      description: Criteria to search declaration
      properties:
        id:
          $ref: "#/components/schemas/DeclarationReference"
        context:
          type: array
          items:
            $ref: "#/components/schemas/DeclarationContextCode"
        purpose:
          $ref: "#/components/schemas/Purpose"

    DeclarationContextList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/DeclarationContext"

    DeclarationContext:
      type: object
      description: Ref data ; code & its i18n labels (FR/NL/DE/EN)
      properties:
        code:
          $ref: "#/components/schemas/DeclarationContextCode"
        label:
          $ref: "#/components/schemas/LocalizedString"

    DeclarationContextCode:
      type: string
      description: Code of the RefData, all accepted values can be fetched by /refData/declarationContexts request
      example: "delivery"
      pattern: "^[A-Za-z0-9]{1,50}$"

    RemarkRefList:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: "#/components/schemas/RemarkRef"

    RemarkRef:
      type: object
      description: Ref data ; code & its i18n description (FR/NL/DE/EN)
      properties:
        code:
          $ref: "#/components/schemas/RemarkRefCode"
        description:
          $ref: "#/components/schemas/LocalizedString"

    RemarkDetailRef:
      type: object
      description: Ref data ; code, its i18n description & its i18n resolution (FR/NL/DE/EN)
      allOf:
        - $ref: "#/components/schemas/RemarkRef"
        - type: object
          properties:
            resolution:
              $ref: "#/components/schemas/LocalizedString"

    RemarkRefCode:
      type: string
      description: Code of the RefData, all accepted values can be fetched by /refData/remarks request
      example: "actor_bankruptcy"
      pattern: "^(?=.{1,50}$)([a-z0-9][a-z0-9_]*)$"
    
    Remark:
      type: object
      description: Representation of a remark
      properties:
        code:
          type: string
          description: Reference of a remark
          example: unknown_enterprise
        description:
          type: string
          description: |
            Description of the remark. \
            Translated according to the Accept-Language HTTP header, with French as the default locale.
          example: "The enterprise does not exist in the CBE."
        resolution:
          type: string
          description: |
            A suggested course of action that can help address the issue. This field may be empty. This field contains HTML content.\
            Translated according to the Accept-Language HTTP header, with French as the default locale.
          example: '<a href="https://example.com/how-to-change-enterprise">Change the enterprise responsible for this subcontracting relationship</a>'

    RemarkList:
      type: object
      description: List of remarks
      properties:
        remarks:
          type: array
          items:
            $ref: "#/components/schemas/Remark"

    Purpose:
      type: string
      description: Type of purpose
      example: continuous
      enum:
        - specific
        - continuous

    ContractReference:
      type: string
      description: Reference of a contract (starts the same way as the declaration's suffixed with an incremental index)
      pattern: '^[A-HJ-NP-Z0-9]{13}/\d+$'
      example: 1Y1012345678P/1

    Contract:
      type: object
      description: |
        Representation of a work contract.
        Specific work portion assigned to a company within the larger project.
      properties:
        id:
          $ref: "#/components/schemas/ContractReference"
        subcontractingRelationshipId:
          allOf:
            - $ref: "#/components/schemas/SubcontractingRelationshipReference"
            - readOnly: true
        contractor:
          $ref: "#/components/schemas/Actor"
        contact:
          $ref: "#/components/schemas/Contact"
        declaration:
          $ref: "#/components/schemas/Declaration"
        comment:
          type: string
          description: Comment of the contract. Only used by NSSO applications (will be ignored for enterprise users)
          example: "Comment of the contract"

    ContractCreation:
      type: object
      description: Data required to create a contract and its corresponding subcontracting relationship
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/ContractReference"
            - readOnly: true
        subcontractingRelationshipId:
          allOf:
            - $ref: "#/components/schemas/SubcontractingRelationshipReference"
            - readOnly: true
        contractor:
          allOf:
            - $ref: "#/components/schemas/Actor"
            - description: |
                This field is used (and required) only by NSSO applications \
                Attempting to add another enterprise number while being connected as an enterprise will result in an error
        contact:
          allOf:
            - $ref: "#/components/schemas/Contact"
            - description: |
                Contact details of a person such as names, email and phone number. \
                If configured as such in the parameters, this field may be mandatory.
        comment:
          type: string
          description: Comment of the contract. Only used by NSSO applications (will be ignored for enterprise users)
          example: "Comment of the contract"

    ContractUpdate:
      type: object
      description: Data required to update a contract
      properties:
        contact:
          allOf:
            - $ref: "#/components/schemas/Contact"
            - description: |
                Contact details of a person such as names, email and phone number. \
                If configured as such in the parameters, this field may be mandatory.
        comment:
          type: string
          description: Comment of the contract. Only used by NSSO applications (will be ignored for enterprise users)
          example: "Comment of the contract"

    ContractSearch:
      type: object
      description: Search criteria for a contract
      required:
        - criteria
      properties:
        criteria:
          $ref: "#/components/schemas/ContractSearchCriteria"
        sort:
          $ref: "#/components/schemas/ContractSort"

    ContractSearchCriteria:
      type: object
      description: Criteria to search contracts
      properties:
        id:
          $ref: "#/components/schemas/ContractReference"
        enterpriseNumber:
          allOf:
            - $ref: "#/components/schemas/EnterpriseNumber"
            - description: |
                Identifier issued by CBE for a registered organization (must be valid) \
                https://economie.fgov.be/fr/themes/entreprises/banque-carrefour-des/actualites/structure-du-numero \
                Search results are filtered according to the user's access rights.
        declaration:
          $ref: "#/components/schemas/DeclarationSearchCriteria"

    ContractSort:
      type: object
      required:
        - property
      properties:
        direction:
          type: string
          enum:
            - asc
            - desc
          default: asc
        property:
          type: string
          enum:
            - id
          #                - these values below are not active now but will be in a near future
          #                - startDate
          #                - endDate
          default: id

    ContractPage:
      type: object
      allOf:
        - $ref: "#/components/schemas/SearchResultPage"
        - description: List of contracts paginated
        - properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/Contract"
            sort:
              $ref: "#/components/schemas/ContractSort"

    SubcontractingRelationshipReference:
      type: string
      description: Reference of a subcontracting relationship
      pattern: "^[a-z0-9]+(\\.[a-z0-9]+)*$"
      example: "wbqyn68.pm9vk"

    SubcontractingRelationshipBase:
      type: object
      properties:
        parent:
          $ref: "#/components/schemas/SubcontractingRelationshipParent"
        startDate:
          type: string
          description: |
            The start date must fall within the intervention period of the parent relationship (if any). \
            Can be in the past, but must respect the date rule above.
          format: date
        endDate:
          type: string
          description: |
            Mandatory if the purpose of the declaration is "specific". \
            The end date must fall within the intervention period of the parent relationship (if any). \
            Cannot be before the start date.
          format: date

    SubcontractingRelationship:
      type: object
      description: |
        Representation of a subcontracting relationship.
        Represents the relation between two enterprises: a subcontractor and the enterprise that hires it.
      allOf:
        - $ref: "#/components/schemas/SubcontractingRelationshipBase"
        - properties:
            id:
              $ref: "#/components/schemas/SubcontractingRelationshipReference"
            subContractor:
              allOf:
                - $ref: "#/components/schemas/Actor"
                - description: If the parent is empty, the subContractor represents the contractor linked to the main contract.

    SubcontractingRelationshipParent:
      type: object
      description: The parent id must be linked to a company other than the one concerned by this relationship.
      required:
        - id
      properties:
        id:
          $ref: "#/components/schemas/SubcontractingRelationshipReference"
        subContractor:
          allOf:
            - $ref: "#/components/schemas/Actor"
            - readOnly: true

    SubcontractingRelationshipCreation:
      description: Data required to create a subcontracting relationship
      allOf:
        - $ref: "#/components/schemas/SubcontractingRelationshipBase"
        - type: object
          required:
            - parent
            - subContractor
            - startDate
          properties:
            subContractor:
              $ref: "#/components/schemas/Actor"

    SubcontractingRelationshipUpdate:
      type: object
      description: Data required to update a subcontracting relationship
      allOf:
        - $ref: "#/components/schemas/SubcontractingRelationshipBase"
        - type: object
          required:
            - parent
            - startDate
          properties:
            subContractor:
              allOf:
                - $ref: "#/components/schemas/Actor"
                - readOnly: true

    SubcontractingRelationshipSearch:
      type: object
      description: Search criteria for a subcontracting relationship
      required:
        - criteria
      properties:
        criteria:
          $ref: "#/components/schemas/SubcontractingRelationshipSearchCriteria"

    SubcontractingRelationshipSearchCriteria:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/SubcontractingRelationshipReference"
        declaration:
          $ref: "#/components/schemas/DeclarationSearchCriteria"
        contractId:
          $ref: "#/components/schemas/ContractReference"
        parent:
          $ref: "#/components/schemas/SubcontractingRelationshipParent"
        subContractor:
          $ref: "#/components/schemas/Actor"

    SubcontractingRelationshipPage:
      type: object
      allOf:
        - $ref: "#/components/schemas/SearchResultPage"
        - description: List of subcontracting relationships paginated
        - properties:
            items:
              type: array
              items:
                $ref: "#/components/schemas/SubcontractingRelationship"

    SearchResultPage:
      type: object
      properties:
        first:
          description: Absolute URI to the first page
          type: string
          format: uri
          readOnly: true
        last:
          description: Absolute URI to the last page
          type: string
          format: uri
          readOnly: true
        prev:
          description: Absolute URI to the previous page
          type: string
          format: uri
          readOnly: true
        next:
          description: Absolute URI to the next page
          type: string
          format: uri
          readOnly: true
        page:
          type: integer
          description: Current page number
          format: int32
        pageSize:
          type: integer
          description: (Maximum) Number of elements in a single page
          format: int32
        total:
          type: integer
          description: Total number of results
          format: int64
        totalPages:
          type: integer
          description: Total number of pages
          format: int32

    Actor:
      type: object
      description: Represent an entity in the service supply chain, either as a service provider, a subordinate or a subcontractor.
      required:
        - enterpriseNumber
      properties:
        enterpriseNumber:
          $ref: "#/components/schemas/EnterpriseNumber"
        name:
          type: string
          readOnly: true
          description: | 
            The name of the enterprise (if available). \
            Translated according to the Accept-Language HTTP header, with French as the default locale.

    Contact:
      type: object
      description: Contact details of a person such as names, email and phone number
      properties:
        givenName:
          type: string
          description: Most important of the given names of the person (given name aka first name).
          example: "John"
        familyName:
          type: string
          description: A family name is usually shared by members of a family.
          example: "Doe"
        telephone:
          type: string
          description: Telephone number.
          example: "+32 475 12 34 56"
        email:
          type: string
          description: E-mail address.
          example: "johnDoe@outlook.com"

    EnterpriseNumber:
      type: string
      description: |
        Identifier issued by CBE for a registered organization (must be valid) \
        https://economie.fgov.be/fr/themes/entreprises/banque-carrefour-des/actualites/structure-du-numero
      example: "0406798006"
      pattern: '^[0-1]\d{9}$'

    LocalizedString:
      type: object
      description: A description specified in multiple languages
      properties:
        nl:
          type: string
        fr:
          type: string
        de:
          type: string
        en:
          type: string

    Problem:
      type: object
      description: A Problem Details object (RFC 7807)
      properties:
        type:
          type: string
          format: uri
          description: An absolute URI that identifies the problem type
          default: about:blank # kept for backwards-compatibility, type will be mandatory in problem-v2
        href:
          type: string
          format: uri
          description: An absolute URI that, when dereferenced, provides human-readable documentation for the problem type (e.g. using HTML).
        title:
          type: string
          description: A short summary of the problem type. Written in English and readable for engineers (usually not suited for non technical stakeholders and not localized).
          example: Service Unavailable
        status:
          type: integer
          format: int32
          description: The HTTP status code generated by the origin server for this occurrence of the problem.
          minimum: 400
          maximum: 600
          exclusiveMaximum: true
          example: 503
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of the problem
        instance:
          type: string
          format: uri
          description: An absolute URI that identifies the specific occurrence of the problem. It may or may not yield further information if dereferenced.
        issues:
          type: array
          description: An array of all issues encountered with the request
          items:
            type: object
            description: An issue object that gives more information about the issue
            properties:
              in:
                type: string
                description: Where is the issue located in the request
                example: "body"
              detail:
                type: string
                description: Description of the issue
                example: '[Path ''/items/0/actor''] ECMA 262 regex "^[A-HJ-NP-Z0-9]{13}$" does not match input string "1Y1-A123456-7L-Z"'
              name:
                type: string
                description: The path of the value that causes an issue
                example: "/items/0/actor"
              value:
                type: string
                description: The value sent that is not valid
                example: "1Y1-A123456-7L-Z"
      example: {
          "type": "urn:problem-type:belgif:payloadTooLarge",
          "href": "https://www.belgif.be/specification/rest/api-guide/problems/payloadTooLarge.html", # location of linked doc will change in the future to recommended URI structure
          "title": "Payload Too Large",
          "status": 413,
          "detail": "Request message must not be larger than 10 MB",
          "instance": "urn:uuid:123e4567-e89b-12d3-a456-426614174000",
          "limit": 10485760, # additional properties specific to the problem type are allowed
          "issues":
            [
              {
                "in": "body",
                "detail": '[Path ''/items/0/actor''] ECMA 262 regex "^[A-HJ-NP-Z0-9]{13}$" does not match input string "1Y1-A123456-7L-Z"',
                "name": "/items/0/actor",
                "value": "1Y1-A123456-7L-Z",
              },
            ],
        }

  securitySchemes:
    Oauth:
      type: oauth2
      description: This API uses OAuth 2 with the clientCredentials grant flow.
      flows:
        clientCredentials:
          tokenUrl: "https://privateservices-int.socialsecurity.be/REST/oauth/v5/token"
          scopes:
            "scope:rsz-onss:management:catena:enterprise": this scope allows enterprise to use the web-services
            "scope:rsz-onss:management:catena:professional-system-consult": This scope allows ONSS applications acting as professionals to consult data via the web services
            "scope:rsz-onss:management:catena:professional-system-create": This scope allows ONSS applications acting as professionals to create data via the web services
            "scope:rsz-onss:management:catena:professional-system-update": This scope allows ONSS applications acting as professionals to update data via the web services
            "scope:rsz-onss:management:catena:professional-system-delete": This scope allows ONSS applications acting as professionals to delete data via the web services
            "scope:rsz-onss:management:catena:monitoring": this scope allows monitoring to check the system health
