components:
  schemas:
    # should go to main
    Date:
      type: object
      properties:
        datetime:
          type: string
          format: date-time
    Scope:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - scope
        name:
          type: object
          additionalProperties:
            type: string
          example:
            fr: Social
    ScopeById:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - scope
      required:
        - id
        - scope

    # ok to stay here
    Person:
      type: object
      properties:
        id:
          type: integer
          readOnly: true
        type:
          type: string
          enum:
            - "person"
        firstName:
          type: string
        lastName:
          type: string
        text:
          type: string
          description: a canonical representation for the person name
          readOnly: true
        birthdate:
          $ref: "#/components/schemas/Date"
        deathdate:
          $ref: "#/components/schemas/Date"
        phonenumber:
          type: string
        mobilenumber:
          type: string
        gender:
          type: string
          enum:
            - man
            - woman
            - both
        gender_numeric:
          type: integer
          description: a numerical representation of gender
          readOnly: true
    PersonById:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "person"
      required:
        - id
        - type
    # should go to third party
    ThirdParty:
      type: object
      properties:
        text:
          type: string
    ThirdPartyById:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "thirdparty"
      required:
        - id
        - type

    # ok to stay here
    AccompanyingPeriod:
      type: object
      properties:
        type:
          type: string
          enum:
            - accompanying_period
        id:
          type: integer
        requestorAnonymous:
          type: boolean
    Resource:
      type: object
      properties:
        type:
          type: string
          enum:
            - "accompanying_period_resource"
          readOnly: true
        id:
          type: integer
          readOnly: true
        resource:
          anyOf:
            - $ref: "#/components/schemas/PersonById"
            - $ref: "#/components/schemas/ThirdPartyById"
    ResourceById:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "accompanying_period_resource"
      required:
        - id
        - type
    Comment:
      type: object
      properties:
        type:
          type: string
          enum:
            - "accompanying_period_comment"
          readOnly: true
        id:
          type: integer
          readOnly: true
        content:
          type: string
    CommentById:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "accompanying_period_comment"
      required:
        - id
        - type
    SocialIssue:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "social_issue"
        parent_id:
          type: integer
          readOnly: true
        children_ids:
          type: array
          items:
            type: integer
          readOnly: true
        title:
          type: object
          additionalProperties:
            type: string
          example:
            fr: Accompagnement Social Adulte
          readOnly: true
        text:
          type: string
          readOnly: true
    Household:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "household"
    HouseholdPosition:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "household_position"
    AccompanyingCourseWork:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "accompanying_period_work"
        note:
          type: string
        privateComment:
          type: string
        startDate:
          $ref: "#/components/schemas/Date"
        endDate:
          $ref: "#/components/schemas/Date"
        handlingThirdParty:
          $ref: "#/components/schemas/ThirdPartyById"
        goals:
          type: array
          items:
            $ref: "#/components/schemas/AccompanyingCourseWorkGoal"
        results:
          type: array
          items:
            $ref: "#/components/schemas/SocialWorkResultById"
    AccompanyingCourseWorkGoal:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "accompanying_period_work_goal"
        note:
          type: string
        goal:
          $ref: "#/components/schemas/SocialWorkGoalById"
        results:
          type: array
          items:
            $ref: "#/components/schemas/SocialWorkGoalById"

    SocialWorkResultById:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "social_work_result"
    SocialWorkGoalById:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "social_work_goal"

    RelationById:
      type: object
      properties:
        id:
          type: integer
        type:
          type: string
          enum:
            - "relation"
      required:
        - id
        - type
    Relationship:
      type: object
      properties:
        type:
          type: string
          enum:
            - "relationship"
        id:
          type: integer
          readOnly: true
        fromPerson:
          anyOf:
            - $ref: "#/components/schemas/PersonById"
        toPerson:
          anyOf:
            - $ref: "#/components/schemas/PersonById"
        relation:
          anyOf:
            - $ref: "#/components/schemas/RelationById"
        reverse:
          type: boolean


paths:
  /1.0/person/person/{id}.json:
    get:
      tags:
        - person
      summary: Get a single person
      parameters:
        - name: id
          in: path
          required: true
          description: The person's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
        403:
          description: "Unauthorized"
    patch:
      tags:
        - person
      summary: "Alter a person"
      parameters:
        - name: id
          in: path
          required: true
          description: The person's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A person"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Person"
            examples:
              Update a person:
                value:
                  type: "person"
                  firstName: "string"
                  lastName: "string"
                  birthdate:
                    datetime: "2016-06-01T00:00:00+02:00"
                  deathdate:
                    datetime: "2021-06-01T00:00:00+02:00"
                  phonenumber: "string"
                  mobilenumber: "string"
                  gender: "male"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "Object with validation errors"

  /1.0/person/person.json:
    post:
      tags:
        - person
      summary: Create a single person
      requestBody:
        description: "A person"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Person"
            examples:
              Create a new person:
                value:
                  type: "person"
                  firstName: "string"
                  lastName: "string"
                  birthdate:
                    datetime: "2016-06-01T00:00:00+02:00"
                  deathdate:
                    datetime: "2021-06-01T00:00:00+02:00"
                  phonenumber: "string"
                  mobilenumber: "string"
                  gender: "male"
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Person"
        403:
          description: "Unauthorized"
        422:
          description: "Invalid data: the data is a valid json, could be deserialized, but does not pass validation"

  /1.0/person/person/{id}/address.json:
    post:
      tags:
        - person
      summary: post an address to a person
      parameters:
        - name: id
          in: path
          required: true
          description: The person id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: The address id to attach to the person
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "Unprocessable entity (validation errors)"

  /1.0/person/address/suggest/by-person/{id}.json:
    get:
      tags:
        - address
      summary: get a list of suggested address for a person
      description: >
        The address are computed from various source. Currently:

        - the address of course to which the person is participating

        The current person's address is always ignored.
      parameters:
        - name: id
          in: path
          required: true
          description: The person id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"

  /1.0/person/address/suggest/by-household/{id}.json:
    get:
      tags:
        - address
      summary: get a list of suggested address for a household
      description: >
        The address are computed from various source. Currently:

        - the address of course to which the members is participating

        The current household address is always ignored.
      parameters:
        - name: id
          in: path
          required: true
          description: The household id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"

  /1.0/person/accompanying-course/{id}.json:
    get:
      tags:
        - accompanying-course
      summary: "Return the description for an accompanying course (accompanying period)"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
    patch:
      tags:
        - person
      summary: "Alter an accompanying course (accompanying period)"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "An accompanying period"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccompanyingPeriod"
            examples:
              Set the requestor as anonymous:
                value:
                  type: accompanying_period
                  id: 12345
                  requestorAnonymous: true
              Adding an initial comment:
                value:
                  type: accompanying_period
                  id: 2668,
                  pinnedComment:
                    type: accompanying_period_comment
                    content: >
                      This is my an initial comment.

                      Say hello to the new "parcours"!
              Setting person with id 8405 as locator:
                value:
                  type: accompanying_period
                  id: 0
                  personLocation:
                    type: person
                    id: 8405
              Removing person location for both person and address:
                value:
                  type: accompanying_period
                  id: 0
                  personLocation: null
                  addressLocation: null
              Adding address with id 7960 as temporarily address:
                value:
                  type: accompanying_period
                  id: 0
                  personLocation: null
                  addressLocation:
                    id: 7960
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/{id}/requestor.json:
    post:
      tags:
        - accompanying-course
      summary: "Add a requestor to the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A person or thirdparty"
        required: true
        content:
          application/json:
            schema:
              oneOf:
                - $ref: "#/components/schemas/PersonById"
                - $ref: "#/components/schemas/ThirdPartyById"
            examples:
              add person with id 50:
                summary: "a person with id 50"
                value:
                  type: person
                  id: 50
              add thirdparty with id 100:
                summary: "a third party with id 100"
                value:
                  type: thirdparty
                  id: 100
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"
    delete:
      tags:
        - accompanying-course
      summary: "Remove the requestor for the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/{id}/participation.json:
    post:
      tags:
        - accompanying-course
      summary: "Add a participant to the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A person"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PersonById"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"
    delete:
      tags:
        - accompanying-course
      summary: "Remove the participant for the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A person"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PersonById"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/{id}/resource.json:
    post:
      tags:
        - accompanying-course
      summary: "Add a resource to the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A resource"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Resource"
            examples:
              add person with id 50:
                summary: "a person with id 50"
                value:
                  type: accompanying_period_resource
                  resource:
                    type: person
                    id: 50
              add thirdparty with id 100:
                summary: "a third party with id 100"
                value:
                  type: accompanying_period_resource
                  resource:
                    type: thirdparty
                    id: 100
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"
    delete:
      tags:
        - accompanying-course
      summary: "Remove the resource"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A resource"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResourceById"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/{id}/comment.json:
    post:
      tags:
        - accompanying-course
      summary: "Add a comment to the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A comment"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Comment"
            examples:
              a single comment:
                summary: "a simple comment"
                value:
                  type: accompanying_period_comment
                  content: |
                    This is a funny comment I would like to share with you.

                    Thank you for reading this !
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"
    delete:
      tags:
        - accompanying-course
      summary: "Remove the comment"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A comment"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CommentById"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/{id}/scope.json:
    post:
      tags:
        - accompanying-course
      summary: "Add a scope to the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A comment"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Scope"
            examples:
              add a scope:
                value:
                  type: scope
                  id: 5
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"
    delete:
      tags:
        - accompanying-course
      summary: "Remove the scope"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A scope with his id"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ScopeById"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/{id}/socialissue.json:
    post:
      tags:
        - accompanying-course
      summary: "Add a social issue to the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A social issue by id"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SocialIssue"
            examples:
              add a social issue:
                value:
                  type: social_issue
                  id: 5
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"
    delete:
      tags:
        - accompanying-course
      summary: "Remove the social issue"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A social issue with his id"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SocialIssue"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"
  /1.0/person/accompanying-course/{id}/referrers-suggested.json:
    get:
      tags:
        - accompanying-course
      summary: "get a list of available referral for a given accompanying cours"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"

  /1.0/person/accompanying-course/{id}/works.json:
    get:
      tags:
        - accompanying-course
      summary: List of accompanying period works for an accompanying period
      description: Gets a list of accompanying period works for an accompanying period
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"

  /1.0/person/accompanying-course/{id}/work.json:
    post:
      tags:
        - accompanying-course-work
      summary: "Add a work (AccompanyingPeriodwork) to the accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A new work"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - "accompanying_period_work"
                startDate:
                  $ref: "#/components/schemas/Date"
                endDate:
                  $ref: "#/components/schemas/Date"
            examples:
              create a work:
                value:
                  type: accompanying_period_work
                  social_action:
                    id: 0
                    type: social_work_social_action
                  startDate:
                    datetime: 2021-06-20T15:00:00+0200
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/work/{id}.json:
    get:
      tags:
        - accompanying-course-work
      summary: edit an existing accompanying course work
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying course social work's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

    put:
      tags:
        - accompanying-course-work
      summary: edit an existing accompanying course work
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying course social work's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/AccompanyingCourseWork"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "Unprocessable entity (validation errors)"
        400:
          description: "Bad Request"

  /1.0/person/accompanying-course/{id}/confirm.json:
    post:
      tags:
        - person
      summary: confirm an accompanying course
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "transition cannot be applied"

  /1.0/person/accompanying-course/{id}/confidential.json:
    post:
      tags:
        - person
      summary: "Toggle confidentiality of accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "Confidentiality toggle"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - "accompanying_period"
                confidential:
                  type: boolean
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/{id}/intensity.json:
    post:
      tags:
        - person
      summary: "Toggle intensity status of accompanying course"
      parameters:
        - name: id
          in: path
          required: true
          description: The accompanying period's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "Intensity toggle"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - "accompanying_period"
                intensity:
                  type: string
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/accompanying-course/by-person/{person_id}.json:
    get:
      tags:
        - accompanying period
      summary: get a list of accompanying periods for a person
      description: Returns a list of the current accompanying periods for a person
      parameters:
        - name: person_id
          in: path
          required: true
          description: The person id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"

  /1.0/person/accompanying-period/origin.json:
    get:
      tags:
        - person
      summary: Return a list of all origins
      responses:
        200:
          description: "ok"

  /1.0/person/accompanying-period/origin/{id}.json:
    get:
      tags:
        - person
      summary: Return an origin by id
      parameters:
        - name: id
          in: path
          required: true
          description: The origin id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        200:
          description: "ok"
        400:
          description: "Bad Request"
        401:
          description: "Unauthorized"
        404:
          description: "Not found"

  /1.0/person/accompanying-period/resource/{id}.json:
    patch:
      tags:
        - accompanying-course-resource
      summary: "Alter the resource"
      parameters:
        - name: id
          in: path
          required: true
          description: The resource's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A resource"
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum:
                    - "accompanying_period_resource"
                #id:
                #  type: integer
                comment:
                  type: string
              required:
                - type
            examples:
              Set the resource comment:
                value:
                  type: accompanying_period_resource
                  #id: 0
                  comment: my judicious comment
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"

  /1.0/person/household.json:
    get:
      tags:
        - household
      summary: Return a list of all household
      responses:
        200:
          description: "ok"
    post:
      tags:
        - household
      requestBody:
        description: "A household"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Household"
      summary: Post a new household
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "Unprocessable entity (validation errors)"
        400:
          description: "transition cannot be applied"

  /1.0/person/household/{id}.json:
    get:
      tags:
        - household
      summary: Return a household by id
      parameters:
        - name: id
          in: path
          required: true
          description: The household id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        200:
          description: "ok"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Household"
        404:
          description: "not found"
        401:
          description: "Unauthorized"

  /1.0/person/household/by-address-reference/{address_id}.json:
    get:
      tags:
        - household
      summary: Return a list of household which are sharing the same address reference
      parameters:
        - name: address_id
          in: path
          required: true
          description: the address reference id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        200:
          description: "ok"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Household"
        404:
          description: "not found"
        401:
          description: "Unauthorized"

  /1.0/person/household/suggest/by-person/{person_id}/through-accompanying-period-participation.json:
    get:
      tags:
        - household
      summary: Return households associated with the given person through accompanying periods
      description: |
        Return households associated with the given person throught accompanying periods participation.

        The current household of the given person is excluded.
      parameters:
        - name: person_id
          in: path
          required: true
          description: The person's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        200:
          description: "ok"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Household"
        404:
          description: "not found"
        401:
          description: "Unauthorized"

  /1.0/person/household/members/move.json:
    post:
      tags:
        - household
      summary: move one or multiple person from a household to another
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                concerned:
                  type: array
                  items:
                    type: object
                    properties:
                      person:
                        $ref: "#/components/schemas/PersonById"
                      start_date:
                        $ref: "#/components/schemas/Date"
                      position:
                        $ref: "#/components/schemas/HouseholdPosition"
                      holder:
                        type: boolean
                      comment:
                        type: string
                destination:
                  $ref: "#/components/schemas/Household"
            examples:
              Moving person to a new household:
                value:
                  concerned:
                    - person:
                        id: 0
                        type: person
                      position:
                        type: household_position
                        id: 1
                      start_date:
                        datetime: "2021-06-01T00:00:00+02:00"
                      comment: "This is my comment for moving"
                      holder: false
                  destination:
                    type: household
              Moving person to a new household and set an address to this household:
                value:
                  concerned:
                    - person:
                        id: 0
                        type: person
                      position:
                        type: household_position
                        id: 1
                      start_date:
                        datetime: "2021-06-01T00:00:00+02:00"
                      comment: "This is my comment for moving"
                      holder: false
                  destination:
                    type: household
                    forceAddress:
                      id: 0
              Moving person to an existing household:
                value:
                  concerned:
                    - person:
                        id: 0
                        type: person
                      position:
                        type: household_position
                        id: 1
                      start_date:
                        datetime: 2021-06-01T00:00:00+02:00
                      comment: "This is my comment for moving"
                      holder: false
                  destination:
                    type: household
                    id: 54
              Removing a person from any household:
                value:
                  concerned:
                    - person:
                        id: 0
                        type: person
                      start_date:
                        datetime: 2021-06-01T00:00:00+02:00
                  destination: null
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "Unprocessable entity (validation errors)"
        400:
          description: "transition cannot be applied"

  /1.0/person/household/{id}/address.json:
    post:
      tags:
        - household
      summary: post an address to a household
      parameters:
        - name: id
          in: path
          required: true
          description: The household id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  type: integer
                  description: The address id to attach to the household
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "Unprocessable entity (validation errors)"
        400:
          description: "transition cannot be applied"

  /1.0/person/social/social-action.json:
    get:
      tags:
        - social-work-social-action
      summary: get a list of social action
      responses:
        401:
          description: "Unauthorized"
        200:
          description: "OK"

  /1.0/person/social/social-action/{id}.json:
    get:
      tags:
        - social-work-social-action
      parameters:
        - name: id
          in: path
          required: true
          description: The social action's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

  /1.0/person/social/social-action/by-social-issue/{id}.json:
    get:
      tags:
        - social-work-social-action
      parameters:
        - name: id
          in: path
          required: true
          description: The social action's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

  /1.0/person/social-work/evaluation/by-social-action/{social_action_id}.json:
    get:
      tags:
        - social-work-evaluation
      summary: return a list of evaluation which are available for a given social action
      parameters:
        - name: social_action_id
          in: path
          required: true
          description: The social action's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        200:
          description: ok
        404:
          description: not found

  /1.0/person/social-work/social-issue.json:
    get:
      tags:
        - social-issue
      summary: Return a list of social work
      responses:
        200:
          description: "ok"

  /1.0/person/social-work/social-issue/{id}.json:
    get:
      tags:
        - social-issue
      summary: Return a social issue by id
      parameters:
        - name: id
          in: path
          required: true
          description: The social issue's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        200:
          description: "ok"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SocialIssue"
        404:
          description: "not found"
        401:
          description: "Unauthorized"

  /1.0/person/social-work/result.json:
    get:
      tags:
        - accompanying-course-work
      summary: get a list of social work result
      responses:
        401:
          description: "Unauthorized"
        200:
          description: "OK"

  /1.0/person/social-work/result/{id}.json:
    get:
      tags:
        - accompanying-course-work
      parameters:
        - name: id
          in: path
          required: true
          description: The result's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

  /1.0/person/social-work/result/by-goal/{id}.json:
    get:
      tags:
        - accompanying-course-work
      parameters:
        - name: id
          in: path
          required: true
          description: The goal's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

  /1.0/person/social-work/result/by-social-action/{id}.json:
    get:
      tags:
        - accompanying-course-work
      parameters:
        - name: id
          in: path
          required: true
          description: The social action's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

  /1.0/person/social-work/goal.json:
    get:
      tags:
        - accompanying-course-work
      summary: get a list of social work goal
      responses:
        401:
          description: "Unauthorized"
        200:
          description: "OK"

  /1.0/person/social-work/goal/{id}.json:
    get:
      tags:
        - accompanying-course-work
      parameters:
        - name: id
          in: path
          required: true
          description: The goal's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

  /1.0/person/social-work/goal/by-social-action/{id}.json:
    get:
      tags:
        - accompanying-course-work
      parameters:
        - name: id
          in: path
          required: true
          description: The social action's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

  /1.0/relations/relationship/by-person/{id}.json:
    get:
      tags:
        - relationships
      parameters:
        - name: id
          in: path
          required: true
          description: The person's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        400:
          description: "Bad Request"

  /1.0/relations/relationship.json:
    post:
      tags:
        - relationships
      summary: Create a new relationship
      requestBody:
        description: "A relationship"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Relationship"
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Relationship"
        403:
          description: "Unauthorized"
        422:
          description: "Invalid data: the data is a valid json, could be deserialized, but does not pass validation"

  /1.0/relations/relationship/{id}.json:
    patch:
      tags:
        - relationships
      summary: "Alter a relationship"
      parameters:
        - name: id
          in: path
          required: true
          description: The relationship's id
          schema:
            type: integer
            format: integer
            minimum: 1
      requestBody:
        description: "A relationship"
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/Relationship"
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "Object with validation errors"
    delete:
      tags:
        - relationships
      summary: "Remove the relationship"
      parameters:
        - name: id
          in: path
          required: true
          description: The relationship's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        401:
          description: "Unauthorized"
        404:
          description: "Not found"
        200:
          description: "OK"
        422:
          description: "object with validation errors"


  /1.0/relations/relation.json:
    get:
      tags:
        - relations
      summary: get a list of relations
      responses:
        401:
          description: "Unauthorized"
        200:
          description: "OK"

  /1.0/person/config/alt_names.json:
    get:
      tags:
        - person
      summary: Return a list of possible altNames that are defined in the config
      responses:
        200:
          description: "OK"

  /1.0/person/creation/authorized-centers:
    get:
      tags:
        - person
        - permissions
      summary: Return a list of possible centers for person creation
      responses:
        200:
          description: "OK"

  /1.0/person/accompanying-course-work-evaluation-document/{id}/duplicate:
    post:
      tags:
        - accompanying-course-work-evaluation-document
      summary: Dupliate an an accompanying period work evaluation document
      parameters:
        - in: path
          name: id
          required: true
          description: The document's id
          schema:
            type: integer
            format: integer
            minimum: 1
      responses:
        200:
          description: "OK"
          content:
            application/json:
              schema:
                type: object
