diff --git a/collections/icarObservationSummaryCollection.json b/collections/icarObservationSummaryCollection.json new file mode 100644 index 0000000..a92e8f9 --- /dev/null +++ b/collections/icarObservationSummaryCollection.json @@ -0,0 +1,21 @@ +{ + "description": "Represents a collection of observation summary statistics. Based on icarResourceCollection to provide paging etc.", + + "allOf": [{ + "$ref": "../collections/icarResourceCollection.json" + }, + { + "type": "object", + + "properties": { + "member": { + "type": "array", + "items": { + "$ref": "../resources/icarObservationSummaryResource.json" + }, + "description": "As per JSON-LD Hydra syntax, member provides the array of objects, in this case observation summary statistics." + } + } + } + ] +} \ No newline at end of file diff --git a/enums/icarAggregationType.json b/enums/icarAggregationType.json index e223aa3..5b4d30f 100644 --- a/enums/icarAggregationType.json +++ b/enums/icarAggregationType.json @@ -1,5 +1,5 @@ { - "description": "The type of aggregation.", + "description": "The type of aggregation. In addition to obvious statistical terms, Range is the difference between min and max, and index is a computed index value.", "type": "string", @@ -9,7 +9,9 @@ "StDev", "Min", "Max", - "Count" + "Count", + "Range", + "Index" ] } diff --git a/enums/icarDurationType.json b/enums/icarDurationType.json new file mode 100644 index 0000000..8e86fee --- /dev/null +++ b/enums/icarDurationType.json @@ -0,0 +1,15 @@ +{ + "description": "ISO8601/RFC3339 durations used in various types of aggregations. D=Day, M=Month, W=Week, Y=Year, H=Hour, M=Min.", + + "type": "string", + + "enum": [ + "1D", + "1H", + "24H", + "96H", + "1W", + "1M" + ] +} + diff --git a/resources/icarObservationSummaryResource.json b/resources/icarObservationSummaryResource.json new file mode 100644 index 0000000..9f047e0 --- /dev/null +++ b/resources/icarObservationSummaryResource.json @@ -0,0 +1,28 @@ +{ + "description": "This resource (not an event) is delivered on request to summarise observations for an animal over a time period.", + + "allOf": [ + { + "$ref": "../resources/icarResource.json" + }, + { + "type": "object", + + "required": ["animal"], + + "properties": { + "animal": { + "$ref": "../types/icarAnimalIdentifierType.json", + "description": "Unique animal scheme and identifier combination." + }, + "statistics": { + "description": "The summary statistics for this animal. Likely to be summarised on demand based on query parameters.", + "type": "array", + "items": { + "$ref": "../types/icarObservationStatisticsType.json" + } + } + } + } + ] + } \ No newline at end of file diff --git a/types/icarObservationStatisticsType.json b/types/icarObservationStatisticsType.json new file mode 100644 index 0000000..e7aa4e0 --- /dev/null +++ b/types/icarObservationStatisticsType.json @@ -0,0 +1,30 @@ +{ + "description": "Aggregated statistics for a animal behaviour or similar observation over a time period.", + + "allOf": [ + { + "type": "object", + + "required": ["startDateTime", "duration"], + + "properties": { + "startDateTime": { + "$ref": "../types/icarDateTimeType.json", + "description": "The start date/time of the aggregation period for this particular statistic." + }, + "duration": { + "$ref": "../enums/icarDurationType.json", + "description": "The type of period duration (e.g. 1D, 24H, 1W). A call may return statistics with different durations." + }, + "isIncomplete": { + "type": "boolean", + "description": "This flag is present with the value true, when there is insufficient or incomplete data in the duration." + } + } + + }, + { + "$ref": "../types/icarStatisticsType.json" + } + ] + } \ No newline at end of file diff --git a/url-schemes/exampleUrlScheme.json b/url-schemes/exampleUrlScheme.json index 4667c8a..52edb44 100644 --- a/url-schemes/exampleUrlScheme.json +++ b/url-schemes/exampleUrlScheme.json @@ -2631,7 +2631,67 @@ } } } - } + }, + "/locations/{location-scheme}/{location-id}/observation-summary-metrics": { + "get": { + "operationId": "get-animal-observation-summary-metrics", + "summary": "Get summary statistics for individual animal observations.", + "description": "# Purpose\nProvides the collection of animal observation summary statistics for animals at the specified location.\n", + "tags": [ + "ADE-1.4-management" + ], + "parameters": [ + { + "$ref": "#/components/parameters/location-scheme" + }, + { + "$ref": "#/components/parameters/location-id" + }, + { + "$ref": "#/components/parameters/date-from" + }, + { + "$ref": "#/components/parameters/date-to" + }, + { + "$ref": "#/components/parameters/animal-scheme" + }, + { + "$ref": "#/components/parameters/animal-id" + }, + { + "$ref": "#/components/parameters/metric-scheme" + }, + { + "$ref": "#/components/parameters/metric-id" + }, + { + "$ref": "#/components/parameters/duration" + }, + { + "$ref": "#/components/parameters/meta-modified-from" + }, + { + "$ref": "#/components/parameters/meta-modified-to" + } + ], + "responses": { + "200": { + "description": "Successful. The response contains the animal observation summary resources for the given location.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icarObservationSummaryCollection" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } + } }, "components": { "schemas": { @@ -2820,6 +2880,9 @@ }, "icarGroupPositionObservationEventCollection": { "$ref": "../collections/icarGroupPositionObservationEventCollection.json" + }, + "icarObservationSummaryCollection": { + "$ref": "../collections/icarObservationSummaryCollection.json" } }, "parameters": { @@ -2971,6 +3034,33 @@ "schema": { "type": "string" } + }, + "metric-scheme": { + "name": "metric-scheme", + "in": "query", + "description": "The scheme for a metric.", + "required": false, + "schema": { + "type": "string" + } + }, + "metric-id": { + "name": "metric-id", + "in": "query", + "description": "The unique metric within a scheme.", + "required": false, + "schema": { + "type": "string" + } + }, + "duration": { + "name": "duration", + "in": "query", + "description": "The duration for aggregations (e.g. 1D, 1H, 24H, 96H).", + "required": true, + "schema": { + "type": "string" + } } }, "responses": { diff --git a/url-schemes/managementURLScheme.json b/url-schemes/managementURLScheme.json index e5cd894..d44d4ad 100644 --- a/url-schemes/managementURLScheme.json +++ b/url-schemes/managementURLScheme.json @@ -465,7 +465,7 @@ }, { "$ref": "#/components/parameters/purpose" - } + } ], "responses": { "200": { @@ -485,160 +485,160 @@ } }, "/locations/{location-scheme}/{location-id}/inventory-transactions": { - "get": { - "operationId": "get-inventory-transactions", - "summary": "Get the inventory transactions that relate to a certain location", - "description": "# Purpose\nProvides the inventory transactions relating to a location\n", - "tags": [ - "ADE-1.4-management" - ], - "parameters": [ - { - "$ref": "#/components/parameters/location-scheme" - }, - { - "$ref": "#/components/parameters/location-id" - }, - { - "$ref": "#/components/parameters/date-from" - }, - { - "$ref": "#/components/parameters/date-to" - }, - { - "$ref": "#/components/parameters/family" - }, - { - "$ref": "#/components/parameters/identifier-scheme" - }, - { - "$ref": "#/components/parameters/identifier-id" - }, - { - "$ref": "#/components/parameters/meta-modified-from" - }, - { - "$ref": "#/components/parameters/meta-modified-to" - } - ], - "responses": { - "200": { - "description": "Successful. The response contains the inventory transactions for the given location.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/icarInventoryTransactionCollection" - } - } - } - }, - "default": { - "$ref": "#/components/responses/default" - } - } - } + "get": { + "operationId": "get-inventory-transactions", + "summary": "Get the inventory transactions that relate to a certain location", + "description": "# Purpose\nProvides the inventory transactions relating to a location\n", + "tags": [ + "ADE-1.4-management" + ], + "parameters": [ + { + "$ref": "#/components/parameters/location-scheme" + }, + { + "$ref": "#/components/parameters/location-id" + }, + { + "$ref": "#/components/parameters/date-from" + }, + { + "$ref": "#/components/parameters/date-to" + }, + { + "$ref": "#/components/parameters/family" + }, + { + "$ref": "#/components/parameters/identifier-scheme" + }, + { + "$ref": "#/components/parameters/identifier-id" + }, + { + "$ref": "#/components/parameters/meta-modified-from" + }, + { + "$ref": "#/components/parameters/meta-modified-to" + } + ], + "responses": { + "200": { + "description": "Successful. The response contains the inventory transactions for the given location.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icarInventoryTransactionCollection" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } }, "/locations/{location-scheme}/{location-id}/feed-inventory-transactions": { - "get": { - "operationId": "get-feed-inventory-transactions", - "summary": "Get the feed inventory transactions that relate to a certain location", - "description": "# Purpose\nProvides the feed inventory transactions relating to a location\n", - "tags": [ - "ADE-1.4-management" - ], - "parameters": [ - { - "$ref": "#/components/parameters/location-scheme" - }, - { - "$ref": "#/components/parameters/location-id" - }, - { - "$ref": "#/components/parameters/date-from" - }, - { - "$ref": "#/components/parameters/date-to" - }, - { - "$ref": "#/components/parameters/identifier-scheme" - }, - { - "$ref": "#/components/parameters/identifier-id" - }, - { - "$ref": "#/components/parameters/meta-modified-from" - }, - { - "$ref": "#/components/parameters/meta-modified-to" - } - ], - "responses": { - "200": { - "description": "Successful. The response contains the feed inventory transactions for the given location.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/icarFeedTransactionCollection" - } - } - } - }, - "default": { - "$ref": "#/components/responses/default" - } - } - } + "get": { + "operationId": "get-feed-inventory-transactions", + "summary": "Get the feed inventory transactions that relate to a certain location", + "description": "# Purpose\nProvides the feed inventory transactions relating to a location\n", + "tags": [ + "ADE-1.4-management" + ], + "parameters": [ + { + "$ref": "#/components/parameters/location-scheme" + }, + { + "$ref": "#/components/parameters/location-id" + }, + { + "$ref": "#/components/parameters/date-from" + }, + { + "$ref": "#/components/parameters/date-to" + }, + { + "$ref": "#/components/parameters/identifier-scheme" + }, + { + "$ref": "#/components/parameters/identifier-id" + }, + { + "$ref": "#/components/parameters/meta-modified-from" + }, + { + "$ref": "#/components/parameters/meta-modified-to" + } + ], + "responses": { + "200": { + "description": "Successful. The response contains the feed inventory transactions for the given location.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icarFeedTransactionCollection" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } }, "/locations/{location-scheme}/{location-id}/medicine-inventory-transactions": { - "get": { - "operationId": "get-medicine-inventory-transactions", - "summary": "Get the medicine inventory transactions that relate to a certain location", - "description": "# Purpose\nProvides the medicine inventory transactions relating to a location\n", - "tags": [ - "ADE-1.4-management" - ], - "parameters": [ - { - "$ref": "#/components/parameters/location-scheme" - }, - { - "$ref": "#/components/parameters/location-id" - }, - { - "$ref": "#/components/parameters/date-from" - }, - { - "$ref": "#/components/parameters/date-to" - }, - { - "$ref": "#/components/parameters/identifier-scheme" - }, - { - "$ref": "#/components/parameters/identifier-id" - }, - { - "$ref": "#/components/parameters/meta-modified-from" - }, - { - "$ref": "#/components/parameters/meta-modified-to" - } - ], - "responses": { - "200": { - "description": "Successful. The response contains the medicine inventory transactions for the given location.", - "content": { - "application/json": { - "schema": { - "$ref": "#/components/schemas/icarMedicineTransactionCollection" - } - } - } - }, - "default": { - "$ref": "#/components/responses/default" - } - } - } + "get": { + "operationId": "get-medicine-inventory-transactions", + "summary": "Get the medicine inventory transactions that relate to a certain location", + "description": "# Purpose\nProvides the medicine inventory transactions relating to a location\n", + "tags": [ + "ADE-1.4-management" + ], + "parameters": [ + { + "$ref": "#/components/parameters/location-scheme" + }, + { + "$ref": "#/components/parameters/location-id" + }, + { + "$ref": "#/components/parameters/date-from" + }, + { + "$ref": "#/components/parameters/date-to" + }, + { + "$ref": "#/components/parameters/identifier-scheme" + }, + { + "$ref": "#/components/parameters/identifier-id" + }, + { + "$ref": "#/components/parameters/meta-modified-from" + }, + { + "$ref": "#/components/parameters/meta-modified-to" + } + ], + "responses": { + "200": { + "description": "Successful. The response contains the medicine inventory transactions for the given location.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icarMedicineTransactionCollection" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } }, "/locations/{location-scheme}/{location-id}/position-observations": { "get": { @@ -656,16 +656,16 @@ "$ref": "#/components/parameters/location-id" }, { - "$ref": "#/components/parameters/date-from" + "$ref": "#/components/parameters/date-from" }, { "$ref": "#/components/parameters/date-to" }, { - "$ref": "#/components/parameters/identifier-scheme" + "$ref": "#/components/parameters/identifier-scheme" }, { - "$ref": "#/components/parameters/identifier-id" + "$ref": "#/components/parameters/identifier-id" }, { "$ref": "#/components/parameters/meta-modified-from" @@ -756,7 +756,7 @@ } } } - }, + }, "/locations/{location-scheme}/{location-id}/group-position-observations": { "get": { "operationId": "get-group-position-observations", @@ -773,16 +773,16 @@ "$ref": "#/components/parameters/location-id" }, { - "$ref": "#/components/parameters/date-from" + "$ref": "#/components/parameters/date-from" }, { "$ref": "#/components/parameters/date-to" }, { - "$ref": "#/components/parameters/identifier-scheme" + "$ref": "#/components/parameters/identifier-scheme" }, { - "$ref": "#/components/parameters/identifier-id" + "$ref": "#/components/parameters/identifier-id" }, { "$ref": "#/components/parameters/meta-modified-from" @@ -873,8 +873,67 @@ } } } - - }, + }, + "/locations/{location-scheme}/{location-id}/observation-summary-metrics": { + "get": { + "operationId": "get-animal-observation-summary-metrics", + "summary": "Get summary statistics for individual animal observations.", + "description": "# Purpose\nProvides the collection of animal observation summary statistics for animals at the specified location.\n", + "tags": [ + "ADE-1.4-management" + ], + "parameters": [ + { + "$ref": "#/components/parameters/location-scheme" + }, + { + "$ref": "#/components/parameters/location-id" + }, + { + "$ref": "#/components/parameters/date-from" + }, + { + "$ref": "#/components/parameters/date-to" + }, + { + "$ref": "#/components/parameters/animal-scheme" + }, + { + "$ref": "#/components/parameters/animal-id" + }, + { + "$ref": "#/components/parameters/metric-scheme" + }, + { + "$ref": "#/components/parameters/metric-id" + }, + { + "$ref": "#/components/parameters/duration" + }, + { + "$ref": "#/components/parameters/meta-modified-from" + }, + { + "$ref": "#/components/parameters/meta-modified-to" + } + ], + "responses": { + "200": { + "description": "Successful. The response contains the animal observation summary resources for the given location.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/icarObservationSummaryCollection" + } + } + } + }, + "default": { + "$ref": "#/components/responses/default" + } + } + } + }, "/batches/locations/{location-scheme}/{location-id}/animal-sets": { "post": { "operationId": "post-batch-animal-sets", @@ -1614,7 +1673,7 @@ "$ref": "../resources/icarInventoryTransactionResource.json" }, "icarInventoryTransactionCollection": { - "$ref": "../collections/icarInventoryTransactionCollection.json" + "$ref": "../collections/icarInventoryTransactionCollection.json" }, "icarInventoryTransactionArray": { "type": "array", @@ -1626,7 +1685,7 @@ "$ref": "../resources/icarFeedTransactionResource.json" }, "icarFeedTransactionCollection": { - "$ref": "../collections/icarFeedTransactionCollection.json" + "$ref": "../collections/icarFeedTransactionCollection.json" }, "icarFeedTransactionArray": { "type": "array", @@ -1638,7 +1697,7 @@ "$ref": "../resources/icarMedicineTransactionResource.json" }, "icarMedicineTransactionCollection": { - "$ref": "../collections/icarMedicineTransactionCollection.json" + "$ref": "../collections/icarMedicineTransactionCollection.json" }, "icarMedicineTransactionArray": { "type": "array", @@ -1650,7 +1709,7 @@ "$ref": "../resources/icarGroupPositionObservationEventResource.json" }, "icarGroupPositionObservationEventCollection": { - "$ref": "../collections/icarGroupPositionObservationEventCollection.json" + "$ref": "../collections/icarGroupPositionObservationEventCollection.json" }, "icarGroupPositionObservationEventArray": { "type": "array", @@ -1662,13 +1721,16 @@ "$ref": "../resources/icarPositionObservationEventResource.json" }, "icarPositionObservationEventCollection": { - "$ref": "../collections/icarPositionObservationEventCollection.json" + "$ref": "../collections/icarPositionObservationEventCollection.json" }, "icarPositionObservationEventArray": { "type": "array", "items": { "$ref": "#/components/schemas/icarPositionObservationEventResource" } + }, + "icarObservationSummaryCollection": { + "$ref": "../collections/icarObservationSummaryCollection.json" } }, "parameters": { @@ -1732,48 +1794,93 @@ "description": "The purpose of the statistics.", "required": false, "schema": { - "$ref": "../enums/icarStatisticsPurposeType.json" + "$ref": "../enums/icarStatisticsPurposeType.json" } }, "family": { - "name": "family", - "in": "query", - "description": "The family of products.", - "required": false, - "schema": { - "$ref": "../enums/icarProductFamilyType.json" - } + "name": "family", + "in": "query", + "description": "The family of products.", + "required": false, + "schema": { + "$ref": "../enums/icarProductFamilyType.json" + } }, "identifier-scheme": { - "name": "identifier-scheme", - "in": "query", - "description": "The scheme for an identifier.", - "required": false, - "schema": { - "type": "string" - } + "name": "identifier-scheme", + "in": "query", + "description": "The scheme for an identifier.", + "required": false, + "schema": { + "type": "string" + } }, "identifier-id": { - "name": "identifier-id", - "in": "query", - "description": "The unique identifier within a scheme.", - "required": false, - "schema": { - "type": "string" - } + "name": "identifier-id", + "in": "query", + "description": "The unique identifier within a scheme.", + "required": false, + "schema": { + "type": "string" + } + }, + "animal-scheme": { + "name": "animal-scheme", + "in": "query", + "description": "The scheme id for the animal identifier.", + "required": false, + "schema": { + "type": "string" + } + }, + "animal-id": { + "name": "animal-id", + "in": "query", + "description": "The unique identifier for the animal.", + "required": false, + "schema": { + "type": "string" + } + }, + "metric-scheme": { + "name": "metric-scheme", + "in": "query", + "description": "The scheme for a metric.", + "required": false, + "schema": { + "type": "string" + } + }, + "metric-id": { + "name": "metric-id", + "in": "query", + "description": "The unique metric within a scheme.", + "required": false, + "schema": { + "type": "string" + } + }, + "duration": { + "name": "duration", + "in": "query", + "description": "The duration for aggregations (e.g. 1D, 1H, 24H, 96H).", + "required": true, + "schema": { + "type": "string" + } } }, "responses": { - "default": { - "description": "An error has occured while handling the request. Check the content of the message for the error details.", - "content": { - "application/json": { - "schema": { - "$ref": "../collections/icarErrorCollection.json" + "default": { + "description": "An error has occured while handling the request. Check the content of the message for the error details.", + "content": { + "application/json": { + "schema": { + "$ref": "../collections/icarErrorCollection.json" + } + } } - } } - } } } -} +} \ No newline at end of file diff --git a/well-known/icarMetricTypeIdentifier.md b/well-known/icarMetricTypeIdentifier.md index 8c08484..1658f03 100644 --- a/well-known/icarMetricTypeIdentifier.md +++ b/well-known/icarMetricTypeIdentifier.md @@ -4,3 +4,4 @@ | --- | --- | --- | --- | --- | | icar.org | | ICAR defined metrics - is there something available from ICAR | Milk weight | | | crv.nl | | CRV defined metrics - need to setup a webpage for this ... | Milk weight | | +| org.icar.activities | [icarObservationSummaryMetrics](icarObservationSummaryMetrics.md) | Observation summary metrics defined by the ICAR ADE group. | RuminationTime, StandingTime | Values as specified in the linked markdown. | diff --git a/well-known/icarObservationSummaryMetrics.md b/well-known/icarObservationSummaryMetrics.md new file mode 100644 index 0000000..887c4a7 --- /dev/null +++ b/well-known/icarObservationSummaryMetrics.md @@ -0,0 +1,18 @@ +# Predefined metrics that can be used for animal activity measurement +Add more metrics when required (check for duplicates first) and submit with a Pull Request. + +| Metric name | Units | Description | +| --- | --- | --- | +| DrinkingTime | MIN | Time spent drinking, measured over a time period. | +| EatingTime | MIN | Time spent prehending, chewing, and swallowing feed, measured over a time period. | +| InactiveTime | MIN | Time when an animal is not actively moving, which can occur in either standing or lying positions. Measured over a time period. | +| LyingTime | MIN | Time spent lying down, measured over a time period. | +| RestingTime | MIN | Time spent resting (standing, lying, but not walking or eating), measured over a time period. | +| RuminationTime | MIN | Time spent ruminating (regurgiating and re-chewing food), measured over a time period. | +| StandingTime | MIN | Time spent standing, measured over a time period. | +| StepCount | ACT | Number of steps measured with a pedometer or activity device. ACT is the UN/CEFACT unit for a count of an action. | +| WalkingTime | MIN | Time spent walking measured over a time period. | +| MilkingVisitCount | ACT | Number of milking visits observed in a time period. | +| RumenPHRange | - | Range or Amplitude difference between minimum and maximum pH over a period. | + +