From 40823b509a5518dfddaaa24448a687cc0ec4751d Mon Sep 17 00:00:00 2001 From: Christian Gendreau Date: Tue, 20 Jan 2026 10:57:32 -0500 Subject: [PATCH 1/6] Create Site OpenAPI specification Initial file --- schema/natural-history-collection-api.yml | 4 + schema/site.yml | 388 ++++++++++++++++++++++ 2 files changed, 392 insertions(+) create mode 100644 schema/site.yml diff --git a/schema/natural-history-collection-api.yml b/schema/natural-history-collection-api.yml index 8ae57c0..00d1b17 100644 --- a/schema/natural-history-collection-api.yml +++ b/schema/natural-history-collection-api.yml @@ -71,6 +71,10 @@ paths: $ref: 'protocol.yml#/paths/~1v1~1protocol' /v1/protocol/{Id}: $ref: 'protocol.yml#/paths/~1v1~1protocol~1{Id}' + /v1/site: + $ref: 'storageUnit.yml#/paths/~1v1~1site' + /v1/site/{Id}: + $ref: 'storageUnit.yml#/paths/~1v1~1site~1{Id}' /v1/storage-unit: $ref: 'storageUnit.yml#/paths/~1v1~1storage-unit' /v1/storage-unit/{Id}: diff --git a/schema/site.yml b/schema/site.yml new file mode 100644 index 0000000..f32f815 --- /dev/null +++ b/schema/site.yml @@ -0,0 +1,388 @@ +openapi: 3.0.0 +servers: + - description: SwaggerHub API Auto Mocking + url: https://virtserver.swaggerhub.com/AAFC/site/1.0.0 +info: + description: Site schema + version: "1.0.0" + title: Site schema + contact: + email: you@your-company.com + license: + name: Apache 2.0 + url: 'http://www.apache.org/licenses/LICENSE-2.0.html' +paths: + /v1/site: + get: + tags: + - Site + summary: Get sites + operationId: getSites + description: By passing in query string, user can get available sites authorised + parameters: + - in: query + name: filter[rsql] + description: pass an optional search string for looking up sites + schema: + type: string + - in: query + name: sort + description: optional sort order string, such as descending, denoted by "-" + schema: + type: string + - in: query + name: page[offset] + description: number of records to skip when paging + schema: + type: integer + format: int32 + - in: query + name: page[limit] + description: maximum number of records to return when paging + schema: + type: integer + format: int32 + minimum: 0 + maximum: 50 + responses: + '200': + description: sites satisfying the query restrictions + content: + application/vnd.api+json: + schema: + type: array + items: + $ref: '#/components/schemas/Site' + '404': + description: site not found + post: + tags: + - Site + summary: Add site + operationId: addSite + description: Adds a site + responses: + '201': + description: site created + '422': + description: Data integrity violation + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/NewSite' + description: Site to add + /v1/site/{Id}: + get: + tags: + - Site + summary: Find site by ID + description: Returns a single site + operationId: getSiteById + parameters: + - name: Id + in: path + description: ID of site to return + required: true + schema: + type: string + format: uuid + responses: + '200': + description: successful operation + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/Site' + '400': + description: Not a valid uuid + '404': + description: Site not found + patch: + tags: + - Site + summary: Update site + operationId: updateSite + description: update a site + parameters: + - name: Id + in: path + description: site id to patch + required: true + schema: + type: string + format: uuid + responses: + '200': + description: site updated + '400': + description: invalid input, object invalid + requestBody: + content: + application/vnd.api+json: + schema: + $ref: '#/components/schemas/Site' + description: site to update + delete: + tags: + - Site + summary: Delete site + operationId: deleteSite + description: delete a site + parameters: + - name: Id + in: path + description: site id to delete + required: true + schema: + type: string + format: uuid + responses: + '200': + description: site marked as deleted + '400': + description: Not a valid uuid + '404': + description: site not found +components: + schemas: + Site: + type: object + required: + - data + properties: + data: + type: object + required: + - id + properties: + id: + type: string + format: uuid + example: d290f1ee-6c54-4b01-90e6-d701748f0851 + description: Identifier of the object as UUID + allOf: + - $ref: '#/components/schemas/CommonSite' + + NewSite: + type: object + required: + - data + properties: + data: + type: object + allOf: + - $ref: '#/components/schemas/CommonSite' + + CommonSite: + type: object + required: + - type + - attributes + properties: + type: + enum: [site] + description: The type of data being returned. + attributes: + type: object + properties: + title: + type: string + description: The title of the site + minLength: 1 + maxLength: 255 + descriptions: + type: object + description: Description of the site in multiple languages. Key is the language code (e.g., en, fr, es), value is the description text. + nullable: true + additionalProperties: + type: string + maxLength: 2000 + createdBy: + type: string + readOnly: true + description: authenticated user who created the site + createdOn: + type: string + format: date-time + readOnly: true + description: date and time when the site was created in ISO format + example: 1985-04-12T23:20:50.52Z + code: + type: string + minLength: 1 + maxLength: 50 + nullable: true + description: Shorthand code for the site + shape: + type: object + nullable: true + description: The geometry of the site (point, circle, line, or polygon) in GeoJSON format + properties: + type: + type: string + enum: [Point, LineString, Polygon, Circle] + description: The type of geometry + coordinates: + oneOf: + - type: array + description: For Point - [longitude, latitude] + minItems: 2 + maxItems: 2 + items: + type: number + - type: array + description: For LineString - array of [longitude, latitude] pairs + items: + type: array + minItems: 2 + maxItems: 2 + items: + type: number + - type: array + description: For Polygon - array of linear rings + items: + type: array + items: + type: array + minItems: 2 + maxItems: 2 + items: + type: number + radius: + type: number + nullable: true + description: Radius in meters for Circle geometry type + minimum: 0 + establishedOn: + type: string + format: date-time + nullable: true + description: The date when the site was established, in ISO 8601 format + decommissionedOn: + type: string + format: date-time + nullable: true + description: The date when the site ended or was decommissioned, in ISO 8601 format. Must be after establishedOn if both are provided. + managedAttributes: + type: object + description: The managed attributes, map of key/value pair. Patch Strategy is SET so the entire managedAttributes needs to be resubmitted on PATCH/PUT. + nullable: true + additionalProperties: + type: string + siteHierarchyType: + type: string + nullable: true + description: The type of hierarchy this site belongs to (e.g., "Plot", "SubPlot", "Section"). Used to describe child site types in hierarchical structures. + maxLength: 100 + remarks: + type: string + nullable: true + description: remarks on the site + minLength: 0 + maxLength: 1000 + relationships: + type: object + nullable: true + properties: + parentSite: + type: object + nullable: true + description: Parent site in a hierarchical structure + properties: + data: + type: object + nullable: true + required: + - type + - id + properties: + type: + enum: [site] + id: + type: string + format: uuid + description: Unique identifier of the parent site + example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f + projects: + type: object + nullable: true + description: Projects associated with this site + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + example: project + id: + type: string + format: uuid + description: Unique identifier of the project + example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f + expeditions: + type: object + nullable: true + description: Expeditions associated with this site + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + enum: [expedition] + id: + type: string + format: uuid + description: Unique identifier of the expedition + example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f + collectingEvents: + type: object + nullable: true + description: Collecting events that occurred at this site + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + enum: [collecting-event] + id: + type: string + format: uuid + description: Unique identifier of the collecting event + example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f + attachment: + type: object + nullable: true + description: Multimedia attachments (images, documents, etc.) + properties: + data: + type: array + items: + type: object + required: + - type + - id + properties: + type: + type: string + example: metadata + id: + type: string + format: uuid + description: Unique identifier of the metadata/attachment + example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f From ffa84ae3df6c3336bdb92669d36caec4bcbbb052 Mon Sep 17 00:00:00 2001 From: Christian Gendreau Date: Fri, 30 Jan 2026 09:47:27 -0500 Subject: [PATCH 2/6] Update site.yml --- schema/site.yml | 172 +++++++----------------------------------------- 1 file changed, 22 insertions(+), 150 deletions(-) diff --git a/schema/site.yml b/schema/site.yml index f32f815..c9ee7f2 100644 --- a/schema/site.yml +++ b/schema/site.yml @@ -191,6 +191,9 @@ components: description: The title of the site minLength: 1 maxLength: 255 + group: + type: string + description: The group in which this site belongs to descriptions: type: object description: Description of the site in multiple languages. Key is the language code (e.g., en, fr, es), value is the description text. @@ -198,173 +201,42 @@ components: additionalProperties: type: string maxLength: 2000 - createdBy: - type: string - readOnly: true - description: authenticated user who created the site - createdOn: - type: string - format: date-time - readOnly: true - description: date and time when the site was created in ISO format - example: 1985-04-12T23:20:50.52Z code: type: string minLength: 1 maxLength: 50 nullable: true description: Shorthand code for the site - shape: + multilingualDescription: type: object nullable: true - description: The geometry of the site (point, circle, line, or polygon) in GeoJSON format properties: - type: - type: string - enum: [Point, LineString, Polygon, Circle] - description: The type of geometry - coordinates: - oneOf: - - type: array - description: For Point - [longitude, latitude] - minItems: 2 - maxItems: 2 - items: - type: number - - type: array - description: For LineString - array of [longitude, latitude] pairs - items: - type: array - minItems: 2 - maxItems: 2 - items: - type: number - - type: array - description: For Polygon - array of linear rings - items: - type: array - items: - type: array - minItems: 2 - maxItems: 2 - items: - type: number - radius: - type: number + descriptions: + type: array nullable: true - description: Radius in meters for Circle geometry type - minimum: 0 - establishedOn: + items: + type: object + properties: + lang: + type: string + description: language of the description + desc: + type: string + description: the description + createdBy: type: string - format: date-time - nullable: true - description: The date when the site was established, in ISO 8601 format - decommissionedOn: + readOnly: true + description: authenticated user who created the site + createdOn: type: string format: date-time - nullable: true - description: The date when the site ended or was decommissioned, in ISO 8601 format. Must be after establishedOn if both are provided. - managedAttributes: - type: object - description: The managed attributes, map of key/value pair. Patch Strategy is SET so the entire managedAttributes needs to be resubmitted on PATCH/PUT. - nullable: true - additionalProperties: - type: string - siteHierarchyType: - type: string - nullable: true - description: The type of hierarchy this site belongs to (e.g., "Plot", "SubPlot", "Section"). Used to describe child site types in hierarchical structures. - maxLength: 100 - remarks: - type: string - nullable: true - description: remarks on the site - minLength: 0 - maxLength: 1000 + readOnly: true + description: date and time when the site was created in ISO format + example: 1985-04-12T23:20:50.52Z relationships: type: object nullable: true properties: - parentSite: - type: object - nullable: true - description: Parent site in a hierarchical structure - properties: - data: - type: object - nullable: true - required: - - type - - id - properties: - type: - enum: [site] - id: - type: string - format: uuid - description: Unique identifier of the parent site - example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f - projects: - type: object - nullable: true - description: Projects associated with this site - properties: - data: - type: array - items: - type: object - required: - - type - - id - properties: - type: - type: string - example: project - id: - type: string - format: uuid - description: Unique identifier of the project - example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f - expeditions: - type: object - nullable: true - description: Expeditions associated with this site - properties: - data: - type: array - items: - type: object - required: - - type - - id - properties: - type: - enum: [expedition] - id: - type: string - format: uuid - description: Unique identifier of the expedition - example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f - collectingEvents: - type: object - nullable: true - description: Collecting events that occurred at this site - properties: - data: - type: array - items: - type: object - required: - - type - - id - properties: - type: - enum: [collecting-event] - id: - type: string - format: uuid - description: Unique identifier of the collecting event - example: 8f68a05f-937d-4d40-88b4-ed92720d9c3f attachment: type: object nullable: true From 6b9252fefe1f6b60cd251397f230301143cfbc61 Mon Sep 17 00:00:00 2001 From: Christian Gendreau Date: Fri, 30 Jan 2026 09:49:59 -0500 Subject: [PATCH 3/6] Update natural-history-collection-api.yml --- schema/natural-history-collection-api.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/schema/natural-history-collection-api.yml b/schema/natural-history-collection-api.yml index 00d1b17..252ab8f 100644 --- a/schema/natural-history-collection-api.yml +++ b/schema/natural-history-collection-api.yml @@ -72,9 +72,9 @@ paths: /v1/protocol/{Id}: $ref: 'protocol.yml#/paths/~1v1~1protocol~1{Id}' /v1/site: - $ref: 'storageUnit.yml#/paths/~1v1~1site' + $ref: 'site.yml#/paths/~1v1~1site' /v1/site/{Id}: - $ref: 'storageUnit.yml#/paths/~1v1~1site~1{Id}' + $ref: 'site.yml#/paths/~1v1~1site~1{Id}' /v1/storage-unit: $ref: 'storageUnit.yml#/paths/~1v1~1storage-unit' /v1/storage-unit/{Id}: From 7b710307351d656d2bd507aa1b92de7aff890589 Mon Sep 17 00:00:00 2001 From: Christian Gendreau Date: Mon, 2 Feb 2026 14:10:45 -0500 Subject: [PATCH 4/6] Update site.yml --- schema/site.yml | 7 ------- 1 file changed, 7 deletions(-) diff --git a/schema/site.yml b/schema/site.yml index c9ee7f2..927a86e 100644 --- a/schema/site.yml +++ b/schema/site.yml @@ -194,13 +194,6 @@ components: group: type: string description: The group in which this site belongs to - descriptions: - type: object - description: Description of the site in multiple languages. Key is the language code (e.g., en, fr, es), value is the description text. - nullable: true - additionalProperties: - type: string - maxLength: 2000 code: type: string minLength: 1 From 705c4b3af9c776ffbc8c78f4cccfbbc69beb635f Mon Sep 17 00:00:00 2001 From: Christian Gendreau Date: Wed, 4 Feb 2026 11:14:05 -0500 Subject: [PATCH 5/6] Fixed links --- schema/natural-history-collection-api.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/schema/natural-history-collection-api.yml b/schema/natural-history-collection-api.yml index 00d1b17..252ab8f 100644 --- a/schema/natural-history-collection-api.yml +++ b/schema/natural-history-collection-api.yml @@ -72,9 +72,9 @@ paths: /v1/protocol/{Id}: $ref: 'protocol.yml#/paths/~1v1~1protocol~1{Id}' /v1/site: - $ref: 'storageUnit.yml#/paths/~1v1~1site' + $ref: 'site.yml#/paths/~1v1~1site' /v1/site/{Id}: - $ref: 'storageUnit.yml#/paths/~1v1~1site~1{Id}' + $ref: 'site.yml#/paths/~1v1~1site~1{Id}' /v1/storage-unit: $ref: 'storageUnit.yml#/paths/~1v1~1storage-unit' /v1/storage-unit/{Id}: From b686ba08531b158a9b90caf084db9bf93f55585b Mon Sep 17 00:00:00 2001 From: Christian Gendreau Date: Wed, 4 Feb 2026 11:15:11 -0500 Subject: [PATCH 6/6] Renamed title to name --- schema/site.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/schema/site.yml b/schema/site.yml index 927a86e..eede4af 100644 --- a/schema/site.yml +++ b/schema/site.yml @@ -186,9 +186,9 @@ components: attributes: type: object properties: - title: + name: type: string - description: The title of the site + description: The name of the site minLength: 1 maxLength: 255 group: