openapi: 3.0.0
info:
  title: Attribute
  version: 2.0.0
  description: >
    An **Attribute** is a custom field that records a measurable or descriptive
    detail of a resource:

    the noise level of a work environment, the load capacity of a forklift, the
    size of a PPE item.


    Each attribute carries a `name`, a `value` and a unit of measure
    (`unit_of_measure_id`), and is

    attached to a single resource through `entity_id` and `entity_type` — a
    person, a piece of

    equipment, a work environment, or a substance.


    Use this API to:

    - Record details of a resource that its standard fields do not cover

    - Find all attributes of a resource (filter by `entity_id`)

    - Update a measured value after an inspection
servers:
  - url: http://service.4hse.com/
paths:
  /v2/attribute/index:
    post:
      summary: index
      operationId: indexAttribute
      tags:
        - Attributes
      description: >
        Returns a paginated and filterable list of attributes for a given
        entity.

        Use POST to allow complex filters via JSON payload.

        The `entity_id` parameter is required and can be provided as a query
        parameter or in the request body.
      parameters:
        - name: entity_id
          in: query
          description: The ID of the entity to retrieve attributes for. Required.
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: Parameters for searching attributes
        required: false
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AttributeIndexParams"
            example:
              filter:
                name: Room Size
              per-page: 50
              page: 1
      responses:
        "200":
          description: List of attributes
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Attribute"
              example:
                attribute_id: 123e4567-e89b-12d3-a456-426655440000
                name: Room Size
                description: The room size
                entity_id: 569bc3c7-ead1-41e8-85ab-fdccf7085c5f
                entity_type: WORK_ENVIRONMENT
                unit_of_measure_id: M3
                value: "50"
          headers:
            X-Pagination-Current-Page:
              schema:
                type: integer
              description: Current page
            X-Pagination-Page-Count:
              schema:
                type: integer
              description: Total number of pages
            X-Pagination-Per-Page:
              schema:
                type: integer
              description: Number of items per page
            X-Pagination-Total-Count:
              schema:
                type: integer
              description: Total number of items
  /v2/attribute/view/{id}:
    get:
      summary: view
      operationId: viewAttribute
      tags:
        - Attributes
      description: |
        Retrieve a single attribute by its unique ID.
      parameters:
        - name: id
          in: path
          description: The ID of the attribute to retrieve
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Attribute found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attribute"
              example:
                attribute_id: 123e4567-e89b-12d3-a456-426655440000
                name: Room Size
                description: The room size
                entity_id: 569bc3c7-ead1-41e8-85ab-fdccf7085c5f
                entity_type: WORK_ENVIRONMENT
                unit_of_measure_id: M3
                value: "50"
        "404":
          description: Attribute not found
  /v2/attribute/create:
    post:
      summary: create
      operationId: createAttribute
      tags:
        - Attributes
      description: |
        Create a new attribute for an entity.
      requestBody:
        description: The attribute to create
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Attribute"
            example:
              name: Room Size
              description: The room size
              entity_id: 569bc3c7-ead1-41e8-85ab-fdccf7085c5f
              entity_type: WORK_ENVIRONMENT
              unit_of_measure_id: M3
              value: "50"
      responses:
        "201":
          description: Attribute created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attribute"
              example:
                attribute_id: 123e4567-e89b-12d3-a456-426655440000
                name: Room Size
                description: The room size
                entity_id: 569bc3c7-ead1-41e8-85ab-fdccf7085c5f
                entity_type: WORK_ENVIRONMENT
                unit_of_measure_id: M3
                value: "50"
  /v2/attribute/update/{id}:
    put:
      summary: update
      operationId: updateAttribute
      tags:
        - Attributes
      description: |
        Update an existing attribute by its unique ID.
      parameters:
        - name: id
          in: path
          description: The ID of the attribute to update
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        description: The updated attribute
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Attribute"
            example:
              name: Updated Room Size
              value: "60"
      responses:
        "200":
          description: Attribute updated successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Attribute"
              example:
                attribute_id: 123e4567-e89b-12d3-a456-426655440000
                name: Updated Room Size
                value: "60"
        "404":
          description: Attribute not found
  /v2/attribute/delete/{id}:
    delete:
      summary: delete
      operationId: deleteAttribute
      tags:
        - Attributes
      description: |
        Delete an attribute by its unique ID.  
        If force=true, all related entities will also be deleted.
      parameters:
        - name: id
          in: path
          description: The ID of the attribute to delete
          required: true
          schema:
            type: string
            format: uuid
        - name: force
          in: query
          description: Force the deletion of the entity and all related entities
          schema:
            type: boolean
            default: false
      responses:
        "204":
          description: Attribute deleted successfully
        "400":
          description: If force=false, the operation is interrupted and the list of
            connected entities that will be deleted in case of confirmation
            (force=true) is returned
components:
  schemas:
    Attribute:
      type: object
      properties:
        attribute_id:
          type: string
          format: uuid
        code:
          type: string
          maxLength: 45
        name:
          type: string
          maxLength: 255
        description:
          type: string
          maxLength: 4000
        entity_id:
          type: string
          format: uuid
          description: The ID of the entity this attribute is associated with.
        entity_type:
          type: string
          enum:
            - EQUIPMENT
            - WORK_ENVIRONMENT
            - SUBSTANCE
            - OFFICE
            - PERSON
            - MATERIAL_ITEM
            - MATERIAL
            - CUSTOMER
          description: The type of the entity this attribute is associated with.
        unit_of_measure_id:
          type: string
          maxLength: 50
        value:
          type: string
          maxLength: 250
        measure:
          type: string
          maxLength: 255
        measure_data:
          type: string
          maxLength: 4000
        tenant_id:
          type: string
          format: uuid
      required:
        - name
        - entity_id
        - entity_type
        - unit_of_measure_id
        - value
      example:
        attribute_id: 123e4567-e89b-12d3-a456-426655440000
        name: Room Size
        description: The room size
        entity_id: 569bc3c7-ead1-41e8-85ab-fdccf7085c5f
        entity_type: WORK_ENVIRONMENT
        unit_of_measure_id: M3
        value: "50"
    AttributeIndexParams:
      type: object
      properties:
        filter:
          $ref: "#/components/schemas/Attribute"
        per-page:
          type: integer
          minimum: 1
          default: 100
        page:
          type: integer
          minimum: 1
          default: 1
        sort:
          type: string
          enum:
            - name
            - code
            - entity_type
            - value
      example:
        filter:
          name: Room Size
          entity_type: WORK_ENVIRONMENT
        per-page: 50
        page: 1
        sort: name
    securitySchemes:
      OAuth2:
        type: oauth2
        flows:
          password:
            tokenUrl: https://auth.4hse.com/realms/4hse/protocol/openid-connect/token
            scopes: {}
      AccessToken:
        type: apiKey
        in: query
        name: access-token
