Documentation for group events

Preview of documentation (much more to be done)
- Explanation of animal sets and groups (resolves adewg#272)
- Start of ADE information model documentation (adewg#300)

docs/README.md

@@ -0,0 +1,13 @@
+# ICAR Animal Data Exchange (ADE) documentation
+
+This folder contains documentation that may change and be updated with each version release of the ADE specifications.
+
+Current Version: ADE 1.3
+
+## Documentation Topics
+
+1. [Choosing between location-based and generic data synchronisation APIs](location-or-data-exchange-api.md)
+2. [Location-based API specification](location-based-api.md)
+3. [Generic data synchronisation API specification](generic-data-exchange-api.md)
+4. [Understanding animal sets and group events](understanding-animal-groups.md)
+

docs/images/README.md

@@ -0,0 +1 @@
+Images in this folder (PNG, JPG, SVG) are referenced in the other documentation markdown files.

docs/resources/README.md

@@ -0,0 +1 @@
+Create markdown files in this folder for each resource, describing how it should be used and its properties.

docs/resources/icarAnimalSetResource.md

@@ -0,0 +1,23 @@
+# Schema Resource : icarAnimalSetResource
+
+This is a resource that represents groups or sets of known individual animals.
+These sets of animals may be short lived (for instance, a "Session" of animals handled together on the same day and activity), or long lived (for instance, animals grouped for lactation management, health, or reporting and comparisons).
+
+The `icarAnimalSetResource` itself defines its current membership, but the individual animal events [icarAnimalSetJoinEventResource](../resources/icarAnimalSetJoinEventResource.md) and [icarAnimalSetLeaveEventResource](../resources/icarAnimalSetLeaveEventResource.md) represent the addition and removal of animals in the set, and may reflect a changing membership over time. 
+
+Management of animal sets and their representation over time is implementation dependent and not specified by this data exchange specification.
+
+## Properties
+
+Contains all the properties defined in [icarResource](../resources/icarResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| id | string | Yes | Unique identifier in the source system for this animal set. |
+| name | string | - | Human readable name of the set. |
+| purpose | [icarSetPurposeType](../../enums/icarSetPurposeType.json) | - | The purpose of the animal set. |
+| member | array of [icarAnimalIdentifierType](../types/icarAnimalIdentifierType.md) | Yes | Zero or more animal identifiers for the animals currently in the set. |
+
+
+
+

docs/resources/icarEventCoreResource.md

@@ -0,0 +1,22 @@
+# Schema Resource : icarEventCoreResource
+
+This is a resource that represents an event observation that may be recorded on an entity. Extensions to this resource will define the type of entity (for example, an animal, group, or location), and the actual event being observed.
+
+
+## Properties
+
+Contains all the properties defined in [icarResource](../resources/icarResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| id | string | Yes | Unique identifier in the source system for this event. |
+| eventDateTime | [icarDateTimeType](../types/icarDateTimeType.md) | Yes - in concrete classes | RFC3339 UTC date and time (see https://ijmacd.github.io/rfc3339-iso8601/). |
+| traitLabel | [icarTraitLabelIdentifierType](../../types/icarTraitLabelIdentifierType.md) | - | If the event represents a formal trait, identifies the recording system (scheme) and trait (id). |
+| responsible | string | - | Use if an observation is manually recorded, or an event is carried out or authorised by a person. |
+| contemporaryGroup | string | - | For manually recorded events, record any contemporary group code that would affect statistical analysis. |
+| remark | string | - | A comment or remark field for additional user-specified information about the event. |
+
+
+
+
+

docs/resources/icarGroupEventCoreResource.md

@@ -0,0 +1,17 @@
+# Schema Resource : icarGroupEventCoreResource
+
+This is a resource that represents an event observation that may be recorded on a group of animals. Extensions to this resource will define actual event being observed.
+
+## Properties
+
+Contains all the properties defined in [icarEventCoreResource](../resources/icarEventCoreResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| groupMethod | [icarGroupEventMethodType](../../enums/icarGroupEventMethodType.md) | Yes | Indicates whether the event references an existing animal set, has an embedded animal set, or an inventory classification. |
+| countObserved | integer | - | Summarises the number of animals observed in the event. Generally the number of animals in the group, but sometimes a sample. |
+| inventoryClassification | [icarInventoryClassificationType](../../types/icarInventoryClassificationType.md) | - | Describe the group of animals by their characteristics rather than animal identifiers. |
+| embeddedAnimalSet | [icarAnimalSetResource](../resources/icarAnimalSetResource.md) | - | Specifies the set of animals as a list of member animal identifiers. |
+| animalSetReference | [icarAnimalSetReferenceType](../types/icarAnimalSetReferenceType.md)] | - | Reference an existing animal set by ID and optionally URI. Suitable for long-lived animal sets that have a mechanism to manage changes to membership. |
+
+

docs/resources/icarGroupMovementArrivalEventResource.md

@@ -0,0 +1,12 @@
+# Schema Resource : icarGroupMovementArrivalEventResource
+
+This is a resource that represents an an observation of a group of animals arriving on farm.
+
+## Properties
+
+Contains all the properties defined in [icarGroupEventCoreResource](../resources/icarGroupEventCoreResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| arrivalReason | [icarArrivalReasonType](../../enums/icarArrivalReasonType.json) | Yes | Specifies why the animals are being brought onto the location. |
+| consignment | [icarConsignmentType](../types/icarConsignmentType.md) | - | Provides consignment level information about origin, destination, and movement documents. |

docs/resources/icarGroupMovementBirthEventResource.md

@@ -0,0 +1,13 @@
+# Schema Resource : icarGroupMovementBirthEventResource
+
+This is a resource that represents an an observation of a group of animals being registered at a location.
+NOTE: This event has "birth" in its name for compatibility with the individual animal `icarMovementBirthEventResource` which records the registration of a new animal born and tagged on the location. However, it implies tagging and first recording rather than actual birth of animals.
+
+## Properties
+
+Contains all the properties defined in [icarGroupEventCoreResource](../resources/icarGroupEventCoreResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| registrationReason | [icarRegistrationReasonType](../../enums/icarRegistrationReasonType.json) | Yes | Specifies why the animals are being registered. |
+

docs/resources/icarGroupMovementDepartureEventResource.md

@@ -0,0 +1,13 @@
+# Schema Resource : icarGroupMovementDepartureEventResource
+
+This is a resource that represents an an observation of a group of animals leaving the location.
+
+## Properties
+
+Contains all the properties defined in [icarGroupEventCoreResource](../resources/icarGroupEventCoreResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| departureKind | [icarDepartureKindType](../../enums/icarDepartureKindType.json) | Yes | Coded description of the type of departure (e.g. sale, agistment, other). |
+| departureReason | [icarDepartureReasonType](../../enums/icarDepartureReasonType.json) | - | Coded description of the reason why the animals are departing. |
+| consignment | [icarConsignmentType](../types/icarConsignmentType.md) | - | Provides consignment level information about origin, destination, and transport. |

docs/resources/icarGroupTreatmentEventResource.md

@@ -0,0 +1,18 @@
+# Schema Resource : icarGroupTreatmentEventResource
+
+This resource represents a treatment carried out on a group of animals, for instance a drench against parasites, or a vaccination.
+
+## Properties
+
+Contains all the properties defined in [icarGroupEventCoreResource](../resources/icarGroupEventCoreResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| medicine | [icarMedicineReferenceType](../types/icarMedicineReferenceType.md) | - | A reference to the medicine used (where applicable). |
+| procedure | string | - | Medicine application method or a non-medicine procedure. |
+| batches | array of [icarMedicineBatchType](../types/icarMedicineBatchType.md) | - | Batches and expiry details for the medicine administered. |
+| withdrawals | array of [icarMedicineWithdrawalType](../types/icarMedicineWithdrawalType.md) | - | Withholding details for the treatment administered. |
+| dosePerAnimal | [icarMedicineDoseType](../types/icarMedicineDoseType.md) | - | The actual or average medicine dose administered per animal. |
+| totalMedicineUsed | [icarMedicineDoseType](../types/icarMedicineDoseType.md) | - | The total amount of medicine used. |
+| site | string | - | Body site where the treatment was administered. |
+| positions | array of [icarPositionType](../types/icarPositionType.md) | - | The body positions treated. |

docs/resources/icarGroupWeightEventResource.md

@@ -0,0 +1,18 @@
+# Schema Resource : icarGroupWeightEventResource
+
+This resource represents a live weight observed on a group of animals, for instance an average or sample weighing.
+
+## Properties
+
+Contains all the properties defined in [icarGroupEventCoreResource](../resources/icarGroupEventCoreResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| units | [uncefactMassUnitsType](../../enums/uncefactMassUnitsType.json) | - | Units specified in UN/CEFACT 3-letter form. Default if not specified is KGM. |
+| method | [icarWeightMethodType](../../enums/icarWeightMethodType.json) | - | The method of observation. Loadcell is the default if not specified. |
+| resolution | number | - | The smallest measurement difference that can be discriminated given the current device settings. Specified in Units, for instance 0.5 (kilograms). |
+| animalWeights | array of [icarIndividualWeightType](../types/icarIndividualWeightType.md) | - | Array of animal id and weight pairs for animals in the event. |
+| statistics | array of [icarStatisticsType](../types/icarStatisticsType.md) | - | Array of weight statistics, namely average, sum, min, max, count, stdev. |
+| device | [icarDeviceReferenceType](../types/icarDeviceReferenceType.md) | - | Optional information about the device used for the measurement. |
+| timeOffFeed | number | - | Hours of curfew or withholding feed prior to weighing to standardise gut fill. |
+

docs/resources/icarMovementDeathEventResource.md

@@ -0,0 +1,21 @@
+# Schema Resource : icarGroupMovementDeathEventResource
+
+This is a resource that represents an an observation of a group of animals that have died or been euthanised.
+
+## Properties
+
+Contains all the properties defined in [icarGroupEventCoreResource](../resources/icarGroupEventCoreResource.md).
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| deathReason | [icarDeathReasonType](../../enums/icarDeathReasonType.json) | - | Coded reason for death - this is the CAUSE, compared to the MEANS. |
+| explanation | string | - | Free text explanation of the reason for death. |
+| disposalMethod | [icarDeathDisposalMethodType](../../enums/icarDeathDisposalMethodType.json) | - | Coded disposal methods including approved service, consumption by humans or animals, etc. |
+| disposalOperator | string | - | Disposal operator official name (should really be schema.org/organization). |
+| disposalReference | string | - | Reference (receipt, docket, or ID) for disposal. |
+| consignment | [icarConsignmentType](../types/icarConsignmentType.md) | - | Where disposal is by transport, a consignment record may be required. |
+| deathMethod | [icarDeathMethodType](../../enums/icarDeathMethodType.json) | Yes | Defines the MEANS of death, including an accident, natural causes, or euthanised. |
+
+
+
+

docs/resources/icarResource.md

@@ -0,0 +1,15 @@
+# Schema Resource : icarResource
+
+All resources that can be independently fetched through a GET method (or equivalent) in the ICAR specifications include the properties of `icarResource`. It is effectively an *abstract base class* (although this is not a concept in JSON Schema).
+
+## Properties
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| resourceType | string | Yes | A **discriminator** property that uniquely identifies the type of resource - for instance `icarWeightEventResource` or `icarAnimalSetResource`. Discriminators are used for deserialisation and serialisation of JSON in some languages, but can also help identify the concrete resource type used in generalised contexts (such as a synchronisation API or a link to a related resource). |
+| @self | string - uri | Recommended | Uniform resource identifier (URI) of the resource (rel=self). Compliant with JSON-LD.  |
+| meta | [icarMetaDataType](../types/icarMetaDataType.md) | Recommended | Meta data for the resource, including source identity and date/time modified. This is essential for synchronisation of data between systems. |
+| location | [icarLocationIdentifierType](../types/icarLocationIdentifierType.md) | Recommended | A scheme and identifier combination that identifies the current location to which the resource relates. |
+
+
+

docs/types/README.md

@@ -0,0 +1 @@
+Create markdown files in this folder for each significant JSON schema "type" in the \types folder, providing instructions for use and a list of properties.

docs/types/icarAnimalIdentifierType.md

@@ -0,0 +1,6 @@
+# Schema Type: icarAnimalIdentifierType
+
+The animal identifier type is a special case of an [icarIdentifierType](../types/icarIdentifierType.md).
+It does not define any additional properties, and is only defined to make it clear to human readers of the JSON schema that the expected value is to represent an animal.
+
+Some software may reduce this type to its base type of `icarIdentifierType`. This is fine.

docs/types/icarBreedIdentifierType.md

@@ -0,0 +1,6 @@
+# Schema Type: icarBreedIdentifierType
+
+The breed identifier type is a special case of an [icarIdentifierType](../types/icarIdentifierType.md).
+It does not define any additional properties, and is only defined to make it clear to human readers of the JSON schema that the expected value is to represent a breed, defined by the managing authority of the breed list (scheme) and a unique value (id).
+
+Some software may reduce this type to its base type of `icarIdentifierType`. This is fine.

docs/types/icarDateTimeType.md

@@ -0,0 +1,12 @@
+# Schema Type: icarDateTimeType
+
+An ICAR date time type is a string, formatted and validated using the RFC3339 subset of the ISO 8601 specification.
+There is more documentation for this format at https://ijmacd.github.io/
+
+For ICAR data exchange purposes, this should be a string in the format YYYY-MM-DDTHH:MM:SS.XXXZ - that is, it should be a complete date and time in UTC (the Z specifier at the end indicates UTC or Zulu time). You SHOULD convert from local time to UTC time.
+
+If local time is used instead (allowed but not recommended), the Z should be left off and a +HH appended to represent the time offset of local time from UTC. For instance, a local time in East Australian winter time would have +10 at the end.
+
+## Examples
+
+* 2021-11-26T15:30:00.000Z  - 3:30pm UTC time on the 26th November 2021.

docs/types/icarIdentifierType.md

@@ -0,0 +1,28 @@
+# Schema Type: icarIdentifierType
+
+Many entities in the ICAR Animal Data Exchange have a unique identification that is controlled or managed by an issuing body or scheme.
+For instance:
+- An animal identifier may be issued by and conform with the rules of a national animal identification scheme.
+- A location identifier may by issued by and conform to the requirements of a national business idenfification scheme.
+- A livestock breed may be one of the valid values in a list maintained by an animal recording service or society.
+
+## Properties
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| scheme | string | Yes | The identifier (in reverse domain format) of an official scheme that manages unique identifiers. |
+| id | string | Yes | A unique identification for the resource issued under the auspices of the scheme. |
+
+## Well-known Schemes
+Some identifier schemes for various types of identifier are listed in the `well-known` folder in the ICAR Animal Data Exchange GitHub repository:
+* [icarAnimalIdentifierType](../../well-known/icarAnimalIdentifierType.md)
+* [icarBreedIdentifierType](../../well-known/icarBreedIdentifierType.md)
+* [icarDiagnosisIdentifierType](../../well-known/icarDiagnosisIdentifierType.md)
+* [icarFeedIdentifierType](../../well-known/icarFeedIdentifierType.md)
+* [icarLocationIdentifierType](../../well-known/icarLocationIdentifierType.md)
+* [icarMedicineIdentifierType](../../well-known/icarMedicineIdentifierType.md)
+* [icarPropertyIdentifierType](../../well-known/icarPropertyIdentifierType.md)
+* [icarTraitLabelIdentifierType](../../well-known/icarTraitLabelIdentifierType.md)
+
+
+

docs/types/icarInventoryClassificationType.md

@@ -0,0 +1,34 @@
+# Schema Type: icarInventoryClassificationType
+
+This type is used to very flexibly define a group of animals within a location. At the very least the group of animals will have a name and species, but the group may have other defining attributes that allows software systems to interpret the data.
+
+`icarInventoryClassificationType` is most commonly used in group event observations, and is a member of `icarGroupEventCoreResource`.
+
+## Properties
+
+| Name | Type | Required | Description and notes |
+| --- | --- | --- | --- |
+| name | string | Yes | Human-readable name for this inventory grouping. |
+| species | [icarAnimalSpecieType](../../enums/icarAnimalSpecieType.json) | Yes | The species of animals. |
+| count | number | - | The count or number of animals in this inventory classification. Where the inventory classification is referenced or defined in an event, the number of animals involved in the event may be smaller than this `count` of the animals in the inventory classification (for instance, if only a sample are involved in the event). |
+| sex | [icarAnimalGenderType](../../enums/icarAnimalGenderType.json) | - | The sex of animals in this classification. |
+| primaryBreed | [icarBreedIdentifierType](../types/icarBreedIdentifierType.md) | - | Primary breed defined using an identifier and scheme. |
+| birthPeriod | string | - | The range of birth dates. Use YYYY (all one year), YYYY-MM (one month), or two RFC3339 dates separated by / to represent a range (e.g., YYYY-MM-DD/YYYY-MM-DD). This field may be null. |
+| reproductiveStatus | [icarAnimalReproductionStatusType](../../enums/icarAnimalReproductionStatusType.json) | - | The reproductive/pregnancy status of animals (if all animals in the inventory classification have the same status). |
+| lactationStatus | [icarAnimalLactationStatusType](../../enums/icarAnimalLactationStatusType.json) | - | The lactation status of animals (if all the animals in the inventory classification have the same status). |
+| productionPurposes | array of [icarProductionPurposeType](../../enums/icarProductionPurposeType.json) | - | A list of production purposes shared by the animals in the inventory classification (see the enumeration values). |
+
+## Examples
+
+1. A group with just a name and species:
+```
+{ "name" : "Some Cows", "species" : "Cattle", "count": 23 }
+```
+
+2. A group of pregnant ewes born in August to October 2021
+
+```
+{ "name" : "In-lamb Ewes", "species" : "Sheep", "count": 200,
+  "sex": "Female", "birthPeriod": "2021-08-01/2021-10-31", "reproductiveStatus" : "Pregnant" }
+```
+

docs/types/icarLocationIdentifierType.md

@@ -0,0 +1,6 @@
+# Schema Type: icarLocationIdentifierType
+
+The location identifier type is a special case of an [icarIdentifierType](../types/icarIdentifierType.md).
+It does not define any additional properties, and is only defined to make it clear to human readers of the JSON schema that the expected value is to represent a location.
+
+Some software may reduce this type to its base type of `icarIdentifierType`. This is fine.