ICAR Animal Data Exchange JSON Standards V1.5

The repository contains the JSON standard for Animal Data Exchange (ADE) produced by the International Committee for Animal Recording (ICAR).

The content of this repository is licenced using the Apache 2.0 Licence. You are encouraged to use it in your data exchanges and other applications, and also to contribute to the further development of the standard.

If you have implemented previous versions of ADE, you should read the release notes for the latest version.

Normative Sections

There are three key areas of this standard:

1. The JSON Schema for Data Types: JSON ICAR Resource Types
2. The URL Schemes and Open API for location centric applications: Application API and specification for these.
3. The Generic Data API for data exchange: Generic Data API

You can also find an explanation of how to choose between location or generic data exchange APIs and the different types of animal groups and sets supported by the standard.

Compliance

There is no formal compliance defined beyond that implied by the JSON Schema for data types and as stated in the relevant API documentation.

Documentation

You can find the documentation for this project in the Wiki.

There you will find:

• Information about ICAR and the ADE working group
• The design principles considered by the ADE working group when developing the standard
• How to understand the data model and what resources we support
• How to choose between the location based API and generic data exchange API
• Tips for implementing a client application using the standard
• Tips for implementing a service using the standard

OpenAPI Quick Start

Developers may wish to start by reading OpenAPI specification examples in the \url-schemes folder in their favourite OpenAPI specification editor. You can also view the basic example Url Scheme using the swagger editor.

Code Generation

Developers will likely take one or more of the url-schemes and generate their own code wrappers using openapi-generator or an equivalent generation tool. Version 1.5 and later of this specification has been tested with OpenAPI Generator version 7.9.0 or above and conform to the OpenAPI '3.1' specification as much as possible (and JSON Schema 2020-12). We value feedback on code generation, noting that some implementers have needed to make adjustments to get Java generation to work. Many implementers may find the bundled URL scheme a useful starting point for code generation.

Schema Bundling

This script automates the process of combining individual model files into one schema, making it easier to manage and use in code generation tasks. It ensures all necessary model files are included and prepares the schema for use with tools like Redocly CLI. The script takes a list of JSON schema files located in the url-schemes directory and bundle them into corresponding files in the bundled-schemes directory. Prerequisites:

• Node.js and npm installed.
• @redocly/cli package installed (automatically triggered via npx). Usage:
• Navigate to the directory containing the script
• Run the script: ".\schema_bundle.ps1" or "./schema_bundle.sh"
• The script will clean up the existing files in the bundled-schemes folder, then bundle the schemas listed in the script and save them in the same bundled-schemes folder.
• Once the schemes bundle operation is completed, the script will combine all bundled schemes, except for ExampleScheme, into a single file named combinedURLScheme.json, which will be placed in the bundled-schemes folder. Bundle JSON Schemas workflow:
• When changes are merged into the ADE-1 branch, the workflow will automatically trigger and bundle the schemas into the bundled-schemes folder.

Acknowledgements

Input into this standard was based on previous work of:

• The ICAR ADE working group XML standard
• DataLinker
• JoinData
• MIMIRO Open
• And many other contributors, including existing APIs and technology specifications.

Contributing

The Animal Data Exchange Working Group welcome contributions

• Read and make suggestions using the Issues List
• The default branch is set to ADE-1 which is the current release. This is to make it easier for organisations to clone and use the specifications. If you expect to contribute you will need to work on the Develop branch instead.
• Propose changes by logging an issue, then creating your own fork of the Develop branch and proposing a Pull Request that will be reviewed by the maintainers.