From 0c458ac30ab9d8ce731507d0fecf8dc0fa3aa7d5 Mon Sep 17 00:00:00 2001 From: Pablo M Date: Wed, 3 Jul 2024 10:52:21 +0100 Subject: [PATCH] Add Swagger support for V3 declarations --- public/api/docs/v1/swagger.yaml | 11 + public/api/docs/v2/swagger.yaml | 202 +++----- public/api/docs/v3/swagger.yaml | 487 ++++++++++-------- .../requests/api/docs/v3/declarations_spec.rb | 60 ++- .../filters/list_participant_declarations.rb | 14 +- .../models/participant_declaration.rb | 329 +++++++++--- 6 files changed, 673 insertions(+), 430 deletions(-) diff --git a/public/api/docs/v1/swagger.yaml b/public/api/docs/v1/swagger.yaml index 3b2b0db68d..169800aeab 100644 --- a/public/api/docs/v1/swagger.yaml +++ b/public/api/docs/v1/swagger.yaml @@ -1708,8 +1708,19 @@ components: "$ref": "#/components/schemas/IDAttribute" type: type: string + enum: + - participant-declaration example: participant-declaration attributes: + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - eligible_for_payment + - voided + - state + - updated_at properties: participant_id: description: The unique identifier of this participant declaration record diff --git a/public/api/docs/v2/swagger.yaml b/public/api/docs/v2/swagger.yaml index bebbe5706a..f6349b0323 100644 --- a/public/api/docs/v2/swagger.yaml +++ b/public/api/docs/v2/swagger.yaml @@ -367,22 +367,15 @@ paths: value: data: id: d0b4a32e-a272-489e-b30a-cb17131457fc - type: npq-participant + type: participant-declaration attributes: - email: isabelle.macdonald2@some-school.example.com - full_name: Isabelle MacDonald - teacher_reference_number: '1234567' + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2022-04-30' + course_identifier: npq-leading-teaching + state: submitted updated_at: '2021-05-31T02:22:32.000Z' - npq_enrolments: - - course_identifier: npq-leading-teaching - schedule_identifier: npq-leadership-spring - cohort: '2022' - eligible_for_funding: true - npq_application_id: db3a7848-7308-4879-942a-c4a70ced400a - training_status: active - school_urn: '106286' - targeted_delivery_funding_eligibility: true - funded_place: true + has_passed: true schema: "$ref": "#/components/schemas/ParticipantDeclarationResponse" '401': @@ -1916,8 +1909,7 @@ components: - expected-commitment-unclear - other ParticipantDeclaration: - description: The details of an NPQ Participant - type: object + description: The data attributes associated with a participant declaration response required: - id - type @@ -1926,132 +1918,88 @@ components: id: "$ref": "#/components/schemas/IDAttribute" type: - description: The data type type: string - example: npq-participant enum: - - npq-participant + - participant-declaration + example: participant-declaration attributes: + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - state + - updated_at properties: - email: - description: The email address registered for this NPQ participant + participant_id: + description: The unique identifier of this participant declaration record type: string + format: uuid nullable: false - example: isabelle.macdonald2@some-school.example.com - full_name: - description: The full name of this NPQ participant + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type type: string nullable: false - example: Isabelle MacDonald - teacher_reference_number: - description: The Teacher Reference Number (TRN) for this NPQ participant + example: started + enum: + - started + - retained-1 + - retained-2 + - retained-3 + - retained-4 + - completed + - extended-1 + - extended-2 + - extended-3 + declaration_date: + description: The event declaration date type: string - example: '1234567' + nullable: false + example: '2022-04-30' + course_identifier: + description: The NPQ course this NPQ application relates to + type: string + nullable: false + example: npq-leading-teaching + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + - npq-senco + state: + description: Indicates the state of this payment declaration + type: string + nullable: false + example: submitted + enum: + - submitted + - eligible + - payable + - paid + - voided + - ineligible + - awaiting-clawback + - clawed-back updated_at: description: The date the application was last updated type: string nullable: false format: date-time example: '2021-05-31T02:22:32.000Z' - npq_enrolments: - description: Information about the course(s) the participant is enroled - in - type: array - items: - description: The details of an NPQ Participant enrolment - type: object - required: - - course_identifier - - npq_application_id - - eligible_for_funding - - training_status - - targeted_delivery_funding_eligibility - properties: - course_identifier: - description: The NPQ course this NPQ application relates to - type: string - nullable: false - example: npq-leading-teaching - enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - - npq-senior-leadership - - npq-headship - - npq-executive-leadership - - npq-early-years-leadership - - npq-additional-support-offer - - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - - npq-senco - schedule_identifier: - description: The new schedule of the participant - nullable: true - type: string - example: npq-leadership-spring - enum: - - npq-aso-march - - npq-aso-june - - npq-aso-november - - npq-aso-december - - npq-ehco-march - - npq-ehco-june - - npq-ehco-november - - npq-ehco-december - - npq-leadership-autumn - - npq-leadership-spring - - npq-specialist-autumn - - npq-specialist-spring - cohort: - description: Indicates which call-off contract would fund this - participant's training. 2021 indicates a participant that has - started, or will start, their training in the 2021/22 academic - year. Once a provider accepts an application, they may change - a participant's cohort up until the point of submitting a started - declaration. - type: string - nullable: true - example: '2022' - eligible_for_funding: - description: Indicates whether this NPQ participant would be eligible - for funding from the DfE - type: boolean - nullable: false - example: true - npq_application_id: - description: The ID of the NPQ application that was accepted to - create this enrolment - type: string - format: uuid - nullable: false - example: db3a7848-7308-4879-942a-c4a70ced400a - training_status: - description: The training status of the NPQ participant - type: string - enum: - - active - - deferred - - withdrawn - example: active - school_urn: - description: The Unique Reference Number (URN) of the school where - this NPQ participant is employed - type: string - nullable: true - example: '106286' - targeted_delivery_funding_eligibility: - description: Whether or not this application is eligible for Targeted - Delivery Funding uplift - nullable: false - type: boolean - example: true - funded_place: - description: Indicates whether this NPQ participant is funded - by DfE - nullable: true - type: boolean - example: true + has_passed: + description: The date the declaration was last updated + type: string + nullable: true + example: true ParticipantDeclarationRequest: description: A participant declaration data request type: object diff --git a/public/api/docs/v3/swagger.yaml b/public/api/docs/v3/swagger.yaml index 30466f2c5e..3bc7ee561d 100644 --- a/public/api/docs/v3/swagger.yaml +++ b/public/api/docs/v3/swagger.yaml @@ -280,6 +280,163 @@ paths: schema: "$ref": "#/components/schemas/ApplicationChangeFundedPlaceRequest" required: true + "/api/v3/participant-declarations": + get: + summary: Retrieve multiple Participant declarations + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: filter + in: query + required: false + schema: + "$ref": "#/components/schemas/ListParticipantDeclarationsFilter" + - name: page + in: query + required: false + schema: + "$ref": "#/components/schemas/PaginationFilter" + - name: sort + in: query + required: false + schema: + "$ref": "#/components/schemas/SortingOptions" + responses: + '200': + description: A list of Participant declarations + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationsResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + post: + summary: Declare a participant has reached a milestone + tags: + - Participant declarations + security: + - api_key: [] + parameters: [] + responses: + '200': + description: The participant declaration being created + content: + application/json: + examples: + success: + value: + data: + id: d0b4a32e-a272-489e-b30a-cb17131457fc + type: participant-declaration + attributes: + participant_id: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: started + declaration_date: '2021-05-31T02:21:32.000Z' + course_identifier: npq-leading-teaching + state: submitted + updated_at: '2021-05-31T02:22:32.000Z' + created_at: '2021-05-31T02:22:32.000Z' + statement_id: cd3a12347-7308-4879-942a-c4a70ced400a + clawback_statement_id: cd3a12347-7308-4879-942a-c4a70ced400a + ineligible_for_funding_reason: duplicate_declaration + uplift_paid: true + has_passed: true + lead_provider_name: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '400': + description: Bad request + content: + application/json: + schema: + "$ref": "#/components/schemas/BadRequestResponse" + '422': + description: Unprocessable entity + content: + application/json: + schema: + "$ref": "#/components/schemas/UnprocessableEntityResponse" + requestBody: + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationRequest" + "/api/v3/participant-declarations/{id}": + get: + summary: Retrieve a single Participant declarations + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: id + in: path + required: true + schema: + "$ref": "#/components/schemas/IDAttribute" + responses: + '200': + description: A single Participant declarations + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '404': + description: Not found + content: + application/json: + schema: + "$ref": "#/components/schemas/NotFoundResponse" + "/api/v3/participant-declarations/{id}/void": + put: + summary: Void a declaration + tags: + - Participant declarations + security: + - api_key: [] + parameters: + - name: id + in: path + required: true + schema: + "$ref": "#/components/schemas/IDAttribute" + responses: + '200': + description: The participant declaration being voided + content: + application/json: + schema: + "$ref": "#/components/schemas/ParticipantDeclarationResponse" + '401': + description: Unauthorized + content: + application/json: + schema: + "$ref": "#/components/schemas/UnauthorisedResponse" + '404': + description: Not found + content: + application/json: + schema: + "$ref": "#/components/schemas/NotFoundResponse" "/api/v3/participants/npq": get: summary: Retrieve multiple NPQ participants @@ -728,6 +885,17 @@ components: and time (ISO 8601 date format). type: string example: '2021-05-13T11:21:55Z' + cohort: + description: Return participant declarations associated to the specified + cohort or cohorts. This is a comma delimited string of years. + type: string + example: '2021,2022' + delivery_partner_id: + description: Return participant declarations associated to the specified + delivery partner or delivery partners. This is a comma delimited string + of delivery partner IDs. + type: string + example: 7e5bcdbf-c818-4961-8da5-439cab1984e0 ListStatementsFilter: description: Filter statements to return more specific results type: object @@ -1624,7 +1792,7 @@ components: - updated_at - "-updated_at" ParticipantDeclaration: - description: The details of an NPQ Participant + description: The data attributes associated with a participant declaration response type: object required: - id @@ -1634,231 +1802,118 @@ components: id: "$ref": "#/components/schemas/IDAttribute" type: - description: The data type type: string - example: npq-participant enum: - - npq-participant + - participant-declaration + example: participant-declaration attributes: + required: + - participant_id + - declaration_type + - declaration_date + - course_identifier + - state + - updated_at + - lead_provider_name properties: - full_name: - description: The full name of this NPQ participant + participant_id: + description: The unique id of the participant type: string - nullable: false - example: Isabelle MacDonald - teacher_reference_number: - description: The Teacher Reference Number (TRN) for this NPQ participant + format: uuid + example: db3a7848-7308-4879-942a-c4a70ced400a + declaration_type: + description: The event declaration type type: string - example: '1234567' + enum: + - started + - retained-1 + - retained-2 + - retained-3 + - retained-4 + - completed + - extended-1 + - extended-2 + - extended-3 + example: started + declaration_date: + description: The event declaration date + type: string + format: date-time + example: '2021-05-31T02:21:32.000Z' + course_identifier: + description: The type of course the participant is enrolled in + type: string + enum: + - npq-leading-teaching + - npq-leading-behaviour-culture + - npq-leading-teaching-development + - npq-leading-literacy + - npq-senior-leadership + - npq-headship + - npq-executive-leadership + - npq-early-years-leadership + - npq-additional-support-offer + - npq-early-headship-coaching-offer + - npq-leading-primary-mathematics + example: npq-leading-teaching + state: + description: Indicates the state of this payment declaration + type: string + enum: + - submitted + - eligible + - payable + - paid + - voided + - ineligible + - awaiting-clawback + - clawed-back + example: submitted updated_at: - description: The date the application was last updated + description: The date the declaration was last updated type: string - nullable: false format: date-time example: '2021-05-31T02:22:32.000Z' - npq_enrolments: - description: Information about the course(s) the participant is enroled - in - type: array - items: - description: The details of an NPQ Participant enrolment - type: object - required: - - email - - course_identifier - - npq_application_id - - eligible_for_funding - - training_status - - targeted_delivery_funding_eligibility - properties: - email: - description: The email address registered for this NPQ participant - type: string - nullable: false - example: isabelle.macdonald2@some-school.example.com - course_identifier: - description: The NPQ course this NPQ application relates to - type: string - nullable: false - example: npq-leading-teaching - enum: - - npq-leading-teaching - - npq-leading-behaviour-culture - - npq-leading-teaching-development - - npq-leading-literacy - - npq-senior-leadership - - npq-headship - - npq-executive-leadership - - npq-early-years-leadership - - npq-additional-support-offer - - npq-early-headship-coaching-offer - - npq-leading-primary-mathematics - - npq-senco - schedule_identifier: - description: The new schedule of the participant - nullable: true - type: string - example: npq-leadership-spring - enum: - - npq-aso-march - - npq-aso-june - - npq-aso-november - - npq-aso-december - - npq-ehco-march - - npq-ehco-june - - npq-ehco-november - - npq-ehco-december - - npq-leadership-autumn - - npq-leadership-spring - - npq-specialist-autumn - - npq-specialist-spring - cohort: - description: Indicates which call-off contract would fund this - participant's training. 2021 indicates a participant that has - started, or will start, their training in the 2021/22 academic - year. Once a provider accepts an application, they may change - a participant's cohort up until the point of submitting a started - declaration. - type: string - nullable: true - example: '2022' - eligible_for_funding: - description: Indicates whether this NPQ participant would be eligible - for funding from the DfE - type: boolean - nullable: false - example: true - npq_application_id: - description: The ID of the NPQ application that was accepted to - create this enrolment - type: string - format: uuid - nullable: false - example: db3a7848-7308-4879-942a-c4a70ced400a - training_status: - description: The training status of the NPQ participant - type: string - enum: - - active - - deferred - - withdrawn - example: active - school_urn: - description: The Unique Reference Number (URN) of the school where - this NPQ participant is employed - type: string - nullable: true - example: '106286' - targeted_delivery_funding_eligibility: - description: Whether or not this application is eligible for Targeted - Delivery Funding uplift - nullable: false - type: boolean - example: true - withdrawal: - description: The details of an NPQ Participant withdrawal - type: object - nullable: true - required: - - reason - - date - example: - properties: - reason: - description: The reason a participant was withdrawn - type: string - nullable: false - example: personal-reason-moving-school - enum: - - insufficient-capacity-to-undertake-programme - - personal-reason-health-or-pregnancy-related - - personal-reason-moving-school - - personal-reason-other - - insufficient-capacity - - change-in-developmental-or-personal-priorities - - change-in-school-circumstances - - change-in-school-leadership - - quality-of-programme-structure-not-suitable. - - quality-of-programme-content-not-suitable - - quality-of-programme-facilitation-not-effective - - quality-of-programme-accessibility - - quality-of-programme-other - - programme-not-appropriate-for-role-and-cpd-needs - - started-in-error - - expected-commitment-unclear - - other - date: - description: The date and time the participant was withdrawn - type: string - nullable: false - format: date-time - example: '2021-05-31T02:22:32.000Z' - deferral: - description: The details of an NPQ Participant deferral - type: object - nullable: true - required: - - reason - - date - example: - properties: - reason: - description: The reason a participant was deferred - type: string - nullable: false - example: career-break - enum: - - bereavement - - long-term-sickness - - parental-leave - - career-break - - other - date: - description: The date and time the participant was deferred - type: string - nullable: false - format: date-time - example: '2021-05-31T02:22:32.000Z' - created_at: - description: The date the application was created - type: string - nullable: false - format: date-time - example: '2021-05-31T02:21:32.000Z' - funded_place: - description: Indicates whether this NPQ participant is funded - by DfE - nullable: true - type: boolean - example: true - participant_id_changes: - description: Information about the Participant ID changes - type: array - items: - description: The details of an Participant ID change - type: object - required: - - from_participant_id - - to_participant_id - - changed_at - properties: - from_participant_id: - description: The unique identifier of the changed from participant - training record. - type: string - format: uuid - example: 23dd8d66-e11f-4139-9001-86b4f9abcb02 - to_participant_id: - description: The unique identifier of the changed to participant - training record. - type: string - format: uuid - example: ac3d1243-7308-4879-942a-c4a70ced400a - changed_at: - description: The date and time the Participant ID change - type: string - format: date-time - example: '2021-05-31T02:22:32.000Z' + created_at: + description: The date the declaration was created + type: string + format: date-time + example: '2021-05-31T02:22:32.000Z' + statement_id: + description: Unique ID of the statement the declaration will be paid + as part of + type: string + format: uuid + example: cd3a12347-7308-4879-942a-c4a70ced400a + nullable: true + clawback_statement_id: + description: Unique id of the statement to which the declaration will + be clawed back on, if any + type: string + format: uuid + example: cd3a12347-7308-4879-942a-c4a70ced400a + nullable: true + ineligible_for_funding_reason: + description: If the declaration is ineligible, the reason why + type: string + enum: + - duplicate_declaration + nullable: true + example: duplicate_declaration + uplift_paid: + description: If participant is eligible for uplift, whether it has been + paid as part of this declaration + type: boolean + example: true + has_passed: + description: Whether the participant has failed or passed + type: string + example: true + nullable: true + lead_provider_name: + description: The name of the provider that submitted the declaration + type: string + nullable: false ParticipantDeclarationRequest: description: A participant declaration data request type: object diff --git a/spec/requests/api/docs/v3/declarations_spec.rb b/spec/requests/api/docs/v3/declarations_spec.rb index 1c9da8ed9c..f499b7e731 100644 --- a/spec/requests/api/docs/v3/declarations_spec.rb +++ b/spec/requests/api/docs/v3/declarations_spec.rb @@ -1,6 +1,64 @@ require "rails_helper" require "swagger_helper" -RSpec.describe "Participant Declarations endpoint", type: :request, openapi_spec: "v1/swagger.yaml" do +RSpec.describe "Participant Declarations endpoint", type: :request, openapi_spec: "v3/swagger.yaml" do include_context "with authorization for api doc request" + + it_behaves_like "an API index endpoint documentation", + "/api/v3/participant-declarations", + "Participant declarations", + "Participant declarations", + "#/components/schemas/ListParticipantDeclarationsFilter", + "#/components/schemas/ParticipantDeclarationsResponse" + + describe "single declarations" do + let(:lead_provider) { create(:lead_provider) } + let(:type) { "participant-declaration" } # check + let(:application) { create(:application, :accepted, :with_declaration, lead_provider:) } + let(:resource) { application.declarations.first } + + it_behaves_like "an API show endpoint documentation", + "/api/v3/participant-declarations/{id}", + "Participant declarations", + "Participant declarations", + "#/components/schemas/ParticipantDeclarationResponse" + + it_behaves_like "an API update endpoint documentation", + "/api/v3/participant-declarations/{id}/void", + "Participant declarations", + "Void a declaration", + "The participant declaration being voided", + "#/components/schemas/ParticipantDeclarationResponse" + end + + describe "create declarations" do + let(:lead_provider) { create(:lead_provider) } + let(:type) { "participant-declaration" } # check + let(:cohort) { create(:cohort, :current) } + let(:course_group) { CourseGroup.find_by(name: "leadership") } + let(:course) { create(:course, :sl, course_group:) } + let!(:schedule) { create(:schedule, :npq_leadership_autumn, course_group:, cohort:) } + let(:application) { create(:application, :accepted, cohort:, course:, lead_provider:) } + let(:declaration_date) { schedule.applies_from + 1.day } + let(:response_example) do + extract_swagger_example(schema: "#/components/schemas/ParticipantDeclarationResponse", version: :v3) + end + let(:invalid_attributes) { { participant_id: "invalid" } } + let(:attributes) do + { + participant_id: application.user.ecf_id, + declaration_type: "started", + declaration_date: application.schedule.applies_from.rfc3339, + course_identifier: course.identifier, + } + end + + it_behaves_like "an API create on resource endpoint documentation", + "/api/v3/participant-declarations", + "Participant declarations", + "Declare a participant has reached a milestone", + "The participant declaration being created", + "#/components/schemas/ParticipantDeclarationResponse", + "#/components/schemas/ParticipantDeclarationRequest" + end end diff --git a/spec/swagger_schemas/filters/list_participant_declarations.rb b/spec/swagger_schemas/filters/list_participant_declarations.rb index fe99df9951..e5c94c577a 100644 --- a/spec/swagger_schemas/filters/list_participant_declarations.rb +++ b/spec/swagger_schemas/filters/list_participant_declarations.rb @@ -17,5 +17,17 @@ }, }.tap { |h| h[:v2] = h[:v1] - h[:v3] = h[:v1] + h[:v3] = h[:v1].deep_dup + h[:v3][:properties].merge!({ + cohort: { + description: "Return participant declarations associated to the specified cohort or cohorts. This is a comma delimited string of years.", + type: :string, + example: "2021,2022", + }, + delivery_partner_id: { + description: "Return participant declarations associated to the specified delivery partner or delivery partners. This is a comma delimited string of delivery partner IDs.", + type: :string, + example: "7e5bcdbf-c818-4961-8da5-439cab1984e0", + }, + }) }.freeze diff --git a/spec/swagger_schemas/models/participant_declaration.rb b/spec/swagger_schemas/models/participant_declaration.rb index dd94a41359..7a34af43a3 100644 --- a/spec/swagger_schemas/models/participant_declaration.rb +++ b/spec/swagger_schemas/models/participant_declaration.rb @@ -8,10 +8,23 @@ "$ref": "#/components/schemas/IDAttribute", }, type: { - description: "The data type", type: :string, + enum: %w[ + participant-declaration + ], + example: "participant-declaration", }, attributes: { + required: %w[ + participant_id + declaration_type + declaration_date + course_identifier + eligible_for_payment + voided + state + updated_at + ], properties: { participant_id: { description: "The unique identifier of this participant declaration record", @@ -110,93 +123,113 @@ }, v2: { description: "The data attributes associated with a participant declaration response", - type: :object, required: %i[id type attributes], - id: { - "$ref": "#/components/schemas/IDAttribute", - }, - type: { - description: "The data type", - type: :string, - }, - attributes: { - properties: { - participant_id: { - description: "The unique id of the participant", - type: :string, - format: :uuid, - example: "db3a7848-7308-4879-942a-c4a70ced400a", - }, - declaration_type: { - description: "The event declaration type", - type: :string, - enum: %w[ - started - retained-1 - retained-2 - retained-3 - retained-4 - completed - extended-1 - extended-2 - extended-3 - ], - example: "started", - }, - declaration_date: { - description: "The event declaration date", - type: :string, - format: "date-time", - example: "2021-05-31T02:21:32.000Z", - }, - course_identifier: { - description: "The type of course the participant is enrolled in", - type: :string, - enum: %w[ - npq-leading-teaching - npq-leading-behaviour-culture - npq-leading-teaching-development - npq-leading-literacy - npq-senior-leadership - npq-headship - npq-executive-leadership - npq-early-years-leadership - npq-additional-support-offer - npq-early-headship-coaching-offer - npq-leading-primary-mathematics - ], - example: "ecf-induction", - }, - state: { - description: "Indicates the state of this payment declaration", - type: :string, - enum: %w[ - submitted - eligible - payable - paid - voided - ineligible - ], - example: "submitted", - }, - updated_at: { - description: "The date the declaration was last updated", - type: :string, - format: "date-time", - example: "2021-05-31T02:22:32.000Z", - }, - has_passed: { - description: "Whether the participant has failed or passed", - type: :boolean, - example: true, - nullable: true, + properties: { + id: { + "$ref": "#/components/schemas/IDAttribute", + }, + type: { + type: :string, + enum: %w[ + participant-declaration + ], + example: "participant-declaration", + }, + attributes: { + required: %w[ + participant_id + declaration_type + declaration_date + course_identifier + state + updated_at + ], + properties: { + participant_id: { + description: "The unique identifier of this participant declaration record", + type: :string, + format: :uuid, + nullable: false, + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: :string, + nullable: false, + example: "started", + enum: %w[ + started + retained-1 + retained-2 + retained-3 + retained-4 + completed + extended-1 + extended-2 + extended-3 + ], + }, + declaration_date: { + description: "The event declaration date", + type: :string, + nullable: false, + example: "2022-04-30", + }, + course_identifier: { + description: "The NPQ course this NPQ application relates to", + type: :string, + nullable: false, + example: "npq-leading-teaching", + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + npq-senco + ], + }, + state: { + description: "Indicates the state of this payment declaration", + type: :string, + nullable: false, + example: "submitted", + enum: %w[ + submitted + eligible + payable + paid + voided + ineligible + awaiting-clawback + clawed-back + ], + }, + updated_at: { + description: "The date the application was last updated", + type: :string, + nullable: false, + format: :"date-time", + example: "2021-05-31T02:22:32.000Z", + }, + has_passed: { + description: "The date the declaration was last updated", + type: :string, + nullable: true, + example: true, + }, }, }, }, }, v3: { - description: "The details of a participant declaration", + description: "The data attributes associated with a participant declaration response", type: :object, required: %i[id type attributes], properties: { @@ -204,11 +237,137 @@ "$ref": "#/components/schemas/IDAttribute", }, type: { - description: "The data type", type: :string, + enum: %w[ + participant-declaration + ], + example: "participant-declaration", }, attributes: { - - } + required: %w[ + participant_id + declaration_type + declaration_date + course_identifier + state + updated_at + lead_provider_name + ], + properties: { + participant_id: { + description: "The unique id of the participant", + type: "string", + format: "uuid", + example: "db3a7848-7308-4879-942a-c4a70ced400a", + }, + declaration_type: { + description: "The event declaration type", + type: "string", + enum: %w[ + started + retained-1 + retained-2 + retained-3 + retained-4 + completed + extended-1 + extended-2 + extended-3 + ], + example: "started", + }, + declaration_date: { + description: "The event declaration date", + type: "string", + format: "date-time", + example: "2021-05-31T02:21:32.000Z", + }, + course_identifier: { + description: "The type of course the participant is enrolled in", + type: "string", + enum: %w[ + npq-leading-teaching + npq-leading-behaviour-culture + npq-leading-teaching-development + npq-leading-literacy + npq-senior-leadership + npq-headship + npq-executive-leadership + npq-early-years-leadership + npq-additional-support-offer + npq-early-headship-coaching-offer + npq-leading-primary-mathematics + ], + example: "npq-leading-teaching", + }, + state: { + description: "Indicates the state of this payment declaration", + type: "string", + enum: %w[ + submitted + eligible + payable + paid + voided + ineligible + awaiting-clawback + clawed-back + ], + example: "submitted", + }, + updated_at: { + description: "The date the declaration was last updated", + type: "string", + format: "date-time", + example: "2021-05-31T02:22:32.000Z", + }, + created_at: { + description: "The date the declaration was created", + type: "string", + format: "date-time", + example: "2021-05-31T02:22:32.000Z", + }, + statement_id: { + description: "Unique ID of the statement the declaration will be paid as part of", + type: "string", + format: "uuid", + example: "cd3a12347-7308-4879-942a-c4a70ced400a", + nullable: true, + }, + clawback_statement_id: { + description: "Unique id of the statement to which the declaration will be clawed back on, if any", + type: "string", + format: "uuid", + example: "cd3a12347-7308-4879-942a-c4a70ced400a", + nullable: true, + }, + ineligible_for_funding_reason: { + description: "If the declaration is ineligible, the reason why", + type: "string", + enum: %w[ + duplicate_declaration + ], + nullable: true, + example: "duplicate_declaration", + }, + uplift_paid: { + description: "If participant is eligible for uplift, whether it has been paid as part of this declaration", + type: "boolean", + example: true, + }, + has_passed: { + description: "Whether the participant has failed or passed", + type: "string", # Need update when completed + example: true, + nullable: true, + }, + lead_provider_name: { + description: "The name of the provider that submitted the declaration", + type: "string", + nullable: false, + }, + }, + }, + }, }, }.freeze