app/src/docs/v1.api-spec.yaml
---
openapi: 3.0.3
info:
version: 1.0.0
title: Common Forms Toolkit API
description: >-
An API for a Forms application. This API supports an extensive set of Form
Management features, ranging from the validation and capture of form data
to Administrative actions such as form submission Status changes, assigning
users or adding Notes. The toolkit also offers Team access management,
Notifications, Document Generation and Reporting.
license:
name: Apache 2.0
url: 'https://www.apache.org/licenses/LICENSE-2.0.html'
contact:
name: NR Common Service Showcase
email: NR.CommonServiceShowcase@gov.bc.ca
externalDocs:
description: Project Readmes
url: 'https://bcgov.github.io/common-forms-toolkit/'
servers:
- url: /api/v1
description: This Server
security:
- BearerAuth: []
OpenID: []
paths:
/forms:
get:
summary: Form Meta-data
operationId: search
tags:
- Forms
parameters:
- in: query
name: slug
schema:
type: string
description: short name for the form
example: parkingsurvey
- in: query
name: public
schema:
type: boolean
description: is the form public or only accessible to authenticated users
- in: query
name: active
schema:
type: boolean
description: Is the form active?
- in: query
name: name
schema:
type: string
description: A title for the form
- in: query
name: keyword
schema:
type: string
description: Keywords used to describe the form
responses:
'200':
description: Form(s) found
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Form'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/current':
get:
summary: Current Form Definition
operationId: current
tags:
- Forms
parameters:
- in: path
name: slug
required: true
schema:
type: string
description: short name for the form
responses:
'200':
description: Form found
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/FormDefinition'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
summary: Update Form Definition
tags:
- Forms
security:
- OpenID:
- admin
operationId: update
parameters:
- in: path
name: slug
required: true
schema:
type: string
description: short name for the form
requestBody:
description: the updated form definition
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ChangedFormDefinition'
responses:
'200':
description: The updated Form Definition
content:
application/json:
schema:
$ref: '#/components/schemas/FormDefinition'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/settings':
get:
summary: All Form Settings
operationId: allSettings
security:
- OpenID:
- viewer
tags:
- Settings
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
responses:
'200':
description: Successful operation
content:
application/json:
schema:
minItems: 3
$ref: '#/components/schemas/Settings'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/settings/{settingName}':
parameters:
- in: path
name: settingName
schema:
type: string
required: true
description: The Setting name
get:
summary: Single Form setting
operationId: readSettings
security:
- OpenID:
- viewer
tags:
- Settings
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Setting'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/schemas/NotFound'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
summary: Update a Form Setting
operationId: updateSettings
security:
- OpenID:
- admin
tags:
- Settings
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
responses:
'201':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Setting'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/team/users/{userId}':
get:
summary: A User and their role
operationId: readUser
security:
- OpenID:
- admin
tags:
- Teams
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: userId
schema:
type: string
required: true
description: a Keycloak user ID
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserWithRoles'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/schemas/NotFound'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/team/users':
get:
summary: 'Members of the Team, and their roles'
operationId: readUsers
security:
- OpenID:
- admin
tags:
- Teams
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: query
name: roles
schema:
type: boolean
required: false
description: return composite roles set up in Keycloak for each user
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
type: object
oneOf:
- $ref: '#/components/schemas/UserWithRoles'
- $ref: '#/components/schemas/User'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/team/roles':
get:
summary: All roles
operationId: readRoles
security:
- OpenID:
- admin
tags:
- Teams
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: query
name: users
schema:
type: boolean
required: false
description: return users that have this role
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
type: object
oneOf:
- $ref: '#/components/schemas/RoleWithUsers'
- $ref: '#/components/schemas/Role'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/team/roles/{roleId}':
get:
summary: Details of a role and users in the Team that have it
operationId: readRole
security:
- OpenID:
- admin
tags:
- Teams
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: roleId
schema:
type: string
required: true
description: a role ID
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
oneOf:
- $ref: '#/components/schemas/RoleWithUsers'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/schemas/NotFound'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/team/roles/{roleId}/users':
get:
summary: Users that have a role
operationId: readRoleUsers
security:
- OpenID:
- admin
tags:
- Teams
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: roleId
schema:
type: string
required: true
description: a role ID
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/User'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/schemas/NotFound'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
summary: Update all users with this role
operationId: updateRoleUsers
security:
- OpenID:
- admin
tags:
- Teams
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: roleId
required: true
schema:
type: string
description: a role ID
responses:
'200':
description: Access requested
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/UserWithRoles'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/schemas/NotFound'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/team/users/{userId}/roles':
put:
summary: Reset user to a specific role
operationId: updateUserRoles
security:
- OpenID:
- admin
tags:
- Teams
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: userId
schema:
type: string
required: true
description: the ID of a user
responses:
'200':
description: User's role was reset
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Role'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/schemas/NotFound'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/team/access':
post:
summary: Request Access for a user
operationId: processAccessRequest
security:
- OpenID:
- admin
tags:
- Teams
parameters:
- in: path
name: slug
required: true
schema:
type: string
description: a short name for the Form
responses:
'201':
description: Access requested
content:
application/json:
schema:
$ref: '#/components/schemas/UserWithRoles'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/submissions':
get:
summary: Get all form submissions that match the query parameters
operationId: searchSubmissions
security:
- OpenID:
- viewer
tags:
- Submissions
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: query
name: version
schema:
type: string
description: the form version
required: false
- in: query
name: tiny
schema:
type: boolean
default: true
description: should only a more slimmed-down subset of the results be returned
required: false
- in: query
name: deleted
schema:
type: boolean
default: false
description: only return deleted submissions
required: false
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Submission'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
tags:
- Submissions
summary: Add a Submission
operationId: createSubmission
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
requestBody:
description: The form's data sent when the form is submitted by the user
required: true
content:
application/json:
example:
FormFieldOne: Ms
FormFieldTwo: Jane
FormFieldThree: Smith
responses:
'201':
description: Submission created
content:
application/json:
schema:
$ref: '#/components/schemas/Submission'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/submissions/{submissionId}':
get:
summary: Get a form submission by ID
operationId: readSubmissionPublic
tags:
- Submissions
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Submission'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
put:
summary: Update a form Submission
security:
- OpenID:
- editor
tags:
- Submissions
operationId: updateSubmission
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
requestBody:
description: The form's data sent when the form is edited by a user
required: true
content:
application/json:
example:
FormFieldOne: Mrs
FormFieldTwo: Jane
FormFieldThree: Smith
responses:
'201':
description: Submission updated
content:
application/json:
schema:
$ref: '#/components/schemas/Submission'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
security:
- OpenID:
- editor
tags:
- Submissions
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
summary: Soft-deletes the submission with the specified ID.
responses:
'200':
description: Submission was deleted.
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/submissions/{submissionId}/pdf':
get:
summary: Generate a form submission as a PDF document
operationId: generateSubmissionPdf
tags:
- Submissions
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
responses:
'201':
description: PDF file generated with the CDOGS API
content:
application/pdf:
schema:
type: string
format: binary
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/submissions/email':
post:
summary: Send Email notification to Admin
description: >-
Uses BC Gov Email Messaging API: <br />
https://ches.nrs.gov.bc.ca/api/v1/docs/#operation/postMerge
operationId: sendSubmissionEmail
tags:
- Submissions
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
requestBody:
description: A Submission object
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Submission'
responses:
'200':
description: Returns an array of message correspondence ids
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/submissions/{submissionId}/statuses':
get:
summary: Get the related status history and notes for a form submission
operationId: getStatuses
security:
- OpenID:
- viewer
tags:
- Status
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Statuses'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary: Add Status Change (with Notes)
security:
- OpenID:
- reviewer
tags:
- Status
operationId: createSubmissionStatus
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
requestBody:
description: The Status choosen and related data
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/StatusPost'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Statuses'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/current/statusCodes':
put:
summary: Update Status Codes for a form
security:
- OpenID:
- reviewer
tags:
- Status
operationId: updateCurrentStatusCodes
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
requestBody:
description: >-
All Status types, display names, allowed status transitions,
associated classifications
required: true
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StatusCodePost'
responses:
'201':
description: Status codes updated
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/StatusCode'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/submissions/{submissionId}/statuses/{submissionStatusId}/notes':
get:
summary: Get Status Notes
description: Get Notes that have been added to a Status update
operationId: readSubmissionStatusNotes
security:
- OpenID:
- viewer
tags:
- Notes
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
- in: path
name: submissionStatusId
schema:
type: string
format: uuid
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Note'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary: Add Status Note
description: Add a new Note related to a Status update
security:
- OpenID:
- reviewer
tags:
- Notes
operationId: createSubmissionStatusNote
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
- in: path
name: submissionStatusId
schema:
type: string
format: uuid
required: true
requestBody:
description: A Note associated with a status update
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotePost'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Note'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'/{slug}/submissions/{submissionId}/notes':
get:
summary: Get Submission Notes
description: Get Notes that have been added to a Submission
operationId: getNotes
security:
- OpenID:
- viewer
tags:
- Notes
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Note'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
summary: Add Submission Note
description: Add a new Note related to a Submission
security:
- OpenID:
- reviewer
tags:
- Notes
operationId: createSubmissionNote
parameters:
- in: path
name: slug
schema:
type: string
required: true
description: a short name for the Form
- in: path
name: submissionId
schema:
type: string
format: uuid
required: true
requestBody:
description: A Note associated with a Submission
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/NotePost'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/Note'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/Forbidden'
'422':
$ref: '#/components/responses/UnprocessableEntity'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
OpenID:
type: openIdConnect
openIdConnectUrl: 'https://example.com/.well-known/openid-configuration'
schemas:
TimeStampUserData:
type: object
properties:
createdBy:
type: string
example: migration-011
createdAt:
type: string
example: 2020-06-04T18:49:20.672Z
updatedBy:
type: string
example: jsmith
updatedAt:
type: string
example: 2020-06-04T18:49:20.672Z
Form:
allOf:
- type: object
properties:
formId:
type: string
example: aeb3b705-1de5-4f4e-a4e6-0716b7671034
name:
type: string
example: Business Form One
slug:
type: string
example: businessformone
public:
type: boolean
active:
type: boolean
keywords:
type: array
example:
- contact
- business
- form
items:
type: string
prefix:
type: string
example: bus_os
- $ref: '#/components/schemas/TimeStampUserData'
FormDefinition:
allOf:
- type: object
properties:
formId:
type: string
example: d6944dd9-1c0c-4915-971d-542dda14eb7f
description:
type: string
example: This is a form for your business
metadata:
$ref: '#/components/schemas/Form'
versions:
type: array
items:
$ref: '#/components/schemas/FormVersion'
- $ref: '#/components/schemas/TimeStampUserData'
FormVersion:
allOf:
- type: object
properties:
formVersionId:
type: string
example: 1
formId:
type: string
example: d6944dd9-1c0c-4915-971d-542dda14eb7f
changes:
type: string
example: null
statusCodes:
type: array
items:
$ref: '#/components/schemas/StatusCode'
- $ref: '#/components/schemas/TimeStampUserData'
ChangedFormDefinition:
allOf:
- type: object
description: Form definition updated
properties:
formId:
type: string
example: d6944dd9-1c0c-4915-971d-542dda14eb7f
description:
type: string
example: This is an updated form for your business
metadata:
$ref: '#/components/schemas/Form'
versions:
type: array
items:
$ref: '#/components/schemas/FormChanges'
- $ref: '#/components/schemas/TimeStampUserData'
FormChanges:
type: object
properties:
formVersionId:
type: string
example: 1
formId:
type: string
example: d6944dd9-1c0c-4915-971d-542dda14eb7f
changes:
type: string
example: this is a new version
statusCodes:
type: array
items:
$ref: '#/components/schemas/StatusCode'
StatusCode:
allOf:
- type: object
properties:
code:
type: string
example: SUBMITTED
display:
type: string
example: Submitted
enabled:
type: boolean
example: true
nextCodes:
type: array
items:
type: string
example:
- ASSIGNED
- COMPLETED
allowedClassifications:
type: array
items:
type: string
example: []
- $ref: '#/components/schemas/TimeStampUserData'
StatusPost:
type: object
properties:
code:
type: string
example: ASSIGNED
assignedTo:
type: string
example: John Smith
assignedToEmail:
type: string
example: jsmith@aol.com
actionDate:
type: string
format: date
pattern: YYYY-MM-DD
example: '2020-06-01'
notes:
type: array
items:
type: object
properties:
note:
type: string
example: This Client is ready for a phone call
classification:
type: string
example: Pass or fail
NotePost:
type: object
properties:
note:
type: string
example: This Client is ready for a phone call
Settings:
type: array
items:
$ref: '#/components/schemas/Setting'
Setting:
allOf:
- type: object
properties:
name:
type: string
description: setting name
example: confirmationEmail
enabled:
type: boolean
description: Is this setting enabled?
example: true
config:
type: object
example:
to: parking-staff@example.com
from: the-application@example.com
title: Parking Form Accepted
subject: Parking Form Accepted
priority: normal
template: confirmation-number-email.html
messageLinkUrl: 'https://form-url/app/parking/admin/submission'
messageLinkText: Please login to view the details of this submission
- $ref: '#/components/schemas/TimeStampUserData'
Statuses:
type: array
items:
allOf:
- type: object
properties:
submissionStatusId:
example: 2
submissionId:
example: 1ea77ee7-2234-44f8-8543-967674dcb825
code:
example: ASSIGNED
assignedTo:
example: John Smith
assignedToEmail:
example: jsmith@email.com
actionDate:
type: string
format: date
pattern: YYYY-MM-DD
example: '2020-06-01'
classification:
type: string
example: pass
notes:
type: array
items:
$ref: '#/components/schemas/Note'
- $ref: '#/components/schemas/TimeStampUserData'
StatusCodePost:
type: object
properties:
code:
type: string
example: SUBMITTED
display:
type: string
example: Submitted
enabled:
type: boolean
example: true
nextCodes:
type: array
items:
example:
- ASSIGNED
- COMPLETED
allowedClassifications:
type: array
items:
example:
- Pass
- Fail
User:
type: object
description: A user as represented by Keycloak
properties:
id:
type: string
description: ID of the user
example: 5dad1ec9-d3c0-4b0f-8ead-cb4d9fa98987
username:
type: string
description: Username of this user
example: jsmith@idir
firstName:
type: string
example: Jane
lastName:
type: string
example: Smith
email:
type: string
example: jsmith@gov.bc.ca
UserWithRoles:
allOf:
- $ref: '#/components/schemas/User'
- type: object
properties:
roles:
type: array
items:
$ref: '#/components/schemas/Role'
Role:
type: object
description: The composite roles granted to the user
properties:
id:
type: string
example: b19be52b-1939-45a3-95dc-7958080cdc04
name:
type: string
description: The role name
example: reviewer
description:
type: string
example: >-
Form Reviewers have all the permissions of Form Viewer. Elevated
permissions include adding notes and assignments to a submission.
composite:
type: boolean
default: true
clientRole:
type: boolean
default: true
containerId:
type: string
example: 8baa6eaf-d1bf-4a85-b807-a4de5e9214ec
RoleWithUsers:
allOf:
- $ref: '#/components/schemas/Role'
- type: object
properties:
users:
type: array
items:
$ref: '#/components/schemas/User'
Submission:
allOf:
- type: object
description: Submission details
properties:
submissionId:
type: string
format: uuid
description: The Submission ID
example: 1ea77ee7-2234-44f8-8543-967674dcb825
formVersionId:
type: string
description: Form version
example: 1
deleted:
type: boolean
description: If this submission has been soft-deleted
formData:
$ref: '#/components/schemas/FormData'
- $ref: '#/components/schemas/TimeStampUserData'
FormData:
type: object
description: Your Form data
Note:
allOf:
- type: object
description: Note attached to a form submission
properties:
noteId:
type: integer
description: Primary key of the note
example: 1
submissionId:
type: string
format: uuid
description: The Submission ID
example: 1ea77ee7-2234-44f8-8543-967674dcb825
note:
type: string
example: This form submission was processed!
- $ref: '#/components/schemas/TimeStampUserData'
BadRequest:
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
properties:
status:
example: 400
title:
example: Bad Request
type:
example: 'https://httpstatuses.com/400'
Conflict:
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
properties:
status:
example: 409
title:
example: Conflict
type:
example: 'https://httpstatuses.com/409'
Error:
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
properties:
status:
example: 500
title:
example: Internal Server Error
type:
example: 'https://httpstatuses.com/500'
NotFound:
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
properties:
status:
example: 404
title:
example: Not Found
type:
example: 'https://httpstatuses.com/404'
Problem:
required:
- type
- title
- status
- detail
properties:
type:
type: string
description: 'What type of problem, link to explanation of problem'
title:
type: string
description: 'Title of problem, generally the Http Status Code description'
status:
type: string
description: The Http Status code
detail:
type: string
description: short description of why this problem was raised.
ValidationError:
allOf:
- $ref: '#/components/schemas/Problem'
- type: object
required:
- errors
properties:
errors:
type: array
items:
type: object
required:
- message
properties:
value:
type: object
description: Contents of the field that was in error.
example: utf-8x
message:
type: string
description: The error message for the field.
example: Invalid value `encoding`.
status:
example: 422
title:
example: Unprocessable Entity
type:
example: 'https://httpstatuses.com/422'
responses:
Accepted:
description: Accepted
BadRequest:
description: Request is missing content or is malformed
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequest'
Conflict:
description: Request conflicts with server state
content:
application/json:
schema:
$ref: '#/components/schemas/Conflict'
Error:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Lack required role to perform action
NoContent:
description: Accepted and no content
NotFound:
description: Not found
content:
application/json:
schema:
$ref: '#/components/schemas/NotFound'
UnauthorizedError:
description: Access token is missing or invalid
UnprocessableEntity:
description: >-
The server was unable to process the contained instructions. Generally
validation error(s).
content:
application/json:
schema:
$ref: '#/components/schemas/ValidationError'