Masterdata Sync Working Group

This repository is the home for designs and discussions related to Masterdata Sync in agrirouter.

Goal

The goal of this group is to define a standard for the exchange of agricultural master data on the basis of the agrirouter platform. The desired outcome is then a specification describing data formats, protocols and expected behaviors of the involved parties. Implementation details might be mentioned in discussions, however any such mention (f.e code snippets with SQL statements, database schemas, etc) are not supposed to be binding and would always be included as an example only.

Usage

Use issues if you want to discuss a topic, ask a question, check other already discussed issues or propose a change that you cannot make as PR. Use pull requests if you want to propose a specific change.

Structure of this repository

• ./openapi.yaml - DRAFT The OpenAPI specification for the Masterdata Sync API.
• ./specification.md - DRAFT The specification for the Masterdata Sync API, explaining the details and reasoning that are not covered by the OpenAPI specification.
• ./examples - One farm encoded both as AgmaSync and as an ADAPT 2 catalog.
• ./adapt - The pinned ADAPT release, and deviations.yaml, the deviations from it that the ADAPT-based schemas of openapi.yaml are generated from.
• ./architecture - non normative collection of architecture decision records illustrating masterdata sync concepts and flows and reasoning behind the specification.

Other:

• ./RFC.md - The RFC wrapper for the specification, used to generate the RFC page.
• tools/ - Tooling to automate routine tasks.

ADAPT-based schemas

The content schemas of openapi.yaml and the types they use are generated from ADAPT. Edit them in adapt/deviations.yaml, not in openapi.yaml, then run tools/oapi/generate.sh, which writes them before regenerating the Go bindings.

To adopt a new ADAPT release:

tools/adapt/pull.sh <tag>   # fetch it into adapt/ and pin it in adapt/adapt.lock.yaml
tools/adapt/generate.sh     # fails on changes the deviations must resolve, notes the rest

Every ADAPT property not excluded in deviations.yaml is kept, so a property a new release adds joins openapi.yaml; the generator notes each one. Exclude those that are not wanted, resolve the errors in the deviations, update "Relation to ADAPT" in specification.md, and review the resulting diff of openapi.yaml.

Visualize openapi

If you have docker, do this:

docker run --rm -p 8080:8080 \
  -e SWAGGER_JSON=/spec/openapi.yaml \
  -v $(pwd):/spec:ro \
  docker.swagger.io/swaggerapi/swagger-ui

Then open http://localhost:8080