From e4b336560e87881f5868450dea5ac00d98c666d3 Mon Sep 17 00:00:00 2001 From: Arjan Lamers <> Date: Fri, 21 Jun 2019 09:54:16 +0200 Subject: [PATCH 1/5] some documentation on how to use the standard --- README.md | 13 ++++++++++--- Using the standard.md | 24 ++++++++++++++++++++++++ 2 files changed, 34 insertions(+), 3 deletions(-) create mode 100644 Using the standard.md diff --git a/README.md b/README.md index 5db6593..b590f49 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,13 @@ # ICAR ADE JSON draft This repository contains the ICAR ADE work-in-progress JSON standard. +This page describes the principles driving this standard. If you want to use the ICAR ADE standard in your application, there are tips and +tricks in the "Using the standard.md" file. For a quick start, open the +[exampleUrlScheme.yaml](https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.yaml) file in +your favorite OpenAPI Specification editor, or use the following URL to have a preview in the free Redoc tool: [view +exampleUrlScheme.yaml](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.yaml) + + Approach ======== @@ -54,7 +61,7 @@ It is not always easy to determine which data belong to a message and which data then is if the fields b should get their own message B. The main discussion points are: * Granularity of permission: does it make sense to allow some fields a to be shared with a party and fields b not? If so, make them separate messages. -* Isolated usage: is there a use case where the fields b are useable by themselves without a? If so, make them separate messages. Be considerate of chattiness: too fragmented messages lead to a chatty converstation without any use. +* Isolated usage: is there a use case where the fields b are useable by themselves without a? If so, make them separate messages. Be considerate of chattiness: too fragmented messages lead to a chatty conversation without any use. * Vendor support: is this a specific feature that can be supported or not by a vendor. The preference is to have availability of endpoints as an indication of availability of features. However, if this is simply a more detailed extension to a message, it may be simply modeled as some optional field(s). If in doubt, consider making it a dedicated message B first. This allows for an easier upgrade path than combining them first and then splitting them up. An application developer can always keep using the additional @@ -64,12 +71,12 @@ On using abstract base types ============================ Many events (by example) share similar fields such as an id or timestamp. From a maintenance point of view, it is convenient to extract them to a base type from which concrete events can be derived. In JSON Schema -however, there is no convenient support for this. The closest way of doing it is to have an embedded type. This leads to having the nesting feel a bit ackward if some of these common fields are related to others. +however, there is no convenient support for this. The closest way of doing it is to have an embedded type. This leads to having the nesting feel a bit akward if some of these common fields are related to others. E.g., in a milking visit we would have the timestamp of the visit in the base type structure, while the duration is part of the concrete data type. As such, the working group decided to not use base types for this in the technical definition; however we do specify it 'on paper' so that we keep it consistent and predictable. We anticipate that if these base types become available, we can change the maintenance of the standard without impacting the message definitions themselves. -We do consider the existance of meta-data as a separate type. +We do consider the existence of meta-data as a separate type. TODO: define the fields that should be in the base type event. diff --git a/Using the standard.md b/Using the standard.md new file mode 100644 index 0000000..054c53a --- /dev/null +++ b/Using the standard.md @@ -0,0 +1,24 @@ +# Using the ICAR ADE Standard + +The ADE standard is meant to be an open standard. As such, you are free to start using it, whether to consume or to produce messages. We'll provide tips and tricks on this page to make it as easy as possible for you to start adopting this standard. + +## Scope of the Standard +The standard currently focuses on JSON messages defined in JSON Schema. These messages can be transported via REST or via any other channel. We are also working on a recommended URL scheme if you want to use REST. For now, you can find an example URL scheme to help you navigate and decide how to use the standard. This scheme is defined in the OpenAPI Specification v3. + +## Getting Started +Most developers should be familiar with REST and JSON files. To simply view the standard, you can open the [exampleUrlScheme.yaml](https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.yaml) file in your favorite OpenAPI Specification editor. + +Or, for convenience, use the following URL to have a preview in the free Redoc tool: +[view exampleUrlScheme.yaml](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.yaml) + +## Customizing the Standard +The standard aims to cover most cases in a generic way. However, there will always be regional differences or vendor specific fields that may be required to be part of a message. You are free to simply add more fields to your messages than described in the standard. When doing so, please take note of the following recommendations: +- Consider if your field is potentially standardizable. If other regions or vendors may require something similar, define it in such a way that it may become part of the standard at one time. By doing this, no technical changes may be required by the time a new version comes out which includes this field. +- If your field is not potentially standardizable, then make sure that the name you choose does not potentially conflict with future fields. E.g., use a prefix for your region or company name. + +## Forward and Backward Compatibility + +To ensure forward and backward compatibility for as far as we can, the standard prescribes a few guidelines. +Any consumer must use a _tolerant reader pattern_: if you encounter fields that you do not recognize (as part of the standard), you should simply ignore them. (They may be part of a newer standard, or be regional or vendor specific fields). + + From 2fc0cebe8f7fd78c3b7bd3ec2a85ce432618187a Mon Sep 17 00:00:00 2001 From: Arjan Lamers <> Date: Fri, 21 Jun 2019 09:58:32 +0200 Subject: [PATCH 2/5] fixed spelling error --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b590f49..b873170 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,7 @@ On using abstract base types ============================ Many events (by example) share similar fields such as an id or timestamp. From a maintenance point of view, it is convenient to extract them to a base type from which concrete events can be derived. In JSON Schema -however, there is no convenient support for this. The closest way of doing it is to have an embedded type. This leads to having the nesting feel a bit akward if some of these common fields are related to others. +however, there is no convenient support for this. The closest way of doing it is to have an embedded type. This leads to having the nesting feel a bit awkward if some of these common fields are related to others. E.g., in a milking visit we would have the timestamp of the visit in the base type structure, while the duration is part of the concrete data type. As such, the working group decided to not use base types for this in the technical definition; however we do specify it 'on paper' so that we keep it consistent and predictable. We anticipate that if these base types become available, we can change the maintenance of the standard without impacting the message definitions themselves. From 4430cb8db6532062003591004c2b8b6e7067c8f1 Mon Sep 17 00:00:00 2001 From: Arjan Lamers <> Date: Fri, 21 Jun 2019 10:05:35 +0200 Subject: [PATCH 3/5] converted example url scheme to be a better example, removed superfluous tags for now --- Release Candidate Messages/exampleUrlScheme.yaml | 11 +++-------- 1 file changed, 3 insertions(+), 8 deletions(-) diff --git a/Release Candidate Messages/exampleUrlScheme.yaml b/Release Candidate Messages/exampleUrlScheme.yaml index d43ab30..1f470f2 100644 --- a/Release Candidate Messages/exampleUrlScheme.yaml +++ b/Release Candidate Messages/exampleUrlScheme.yaml @@ -6,15 +6,9 @@ info: version: '1.0' servers: - url: / -tags: - - name: ICAR approval ready - description: | - (almost) exact copy of existing ICAR-ADE standard message, ready for approval paths: '/locations/{location-scheme}/{location-id}/milking-visits': get: - tags: - - ICAR approval ready summary: Get the data for milking visits description: | # Purpose @@ -27,8 +21,9 @@ paths: schema: type: string enum: - - nl-v1 - - be-v1 + - nl.ubn + - de.farmid + - be.pen - name: location-id in: path description: The unique identifier for the location. From 389a6a81ce363d9322b7ee93ef3a809f46ec831b Mon Sep 17 00:00:00 2001 From: Arjan Lamers <> Date: Fri, 21 Jun 2019 10:07:56 +0200 Subject: [PATCH 4/5] linking to the using the standard file --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index b873170..b43f7cc 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ This repository contains the ICAR ADE work-in-progress JSON standard. This page describes the principles driving this standard. If you want to use the ICAR ADE standard in your application, there are tips and -tricks in the "Using the standard.md" file. For a quick start, open the +tricks in the [Using the standard](https://github.com/adewg/ICAR/blob/master/Using%20the%20standard.md) file. For a quick start, open the [exampleUrlScheme.yaml](https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.yaml) file in your favorite OpenAPI Specification editor, or use the following URL to have a preview in the free Redoc tool: [view exampleUrlScheme.yaml](https://redocly.github.io/redoc/?url=https://raw.githubusercontent.com/adewg/ICAR/master/Release%20Candidate%20Messages/exampleUrlScheme.yaml) From fd5839a7f94100ac9671a96a61805c31a529b757 Mon Sep 17 00:00:00 2001 From: Arjan Lamers <> Date: Fri, 21 Jun 2019 10:09:58 +0200 Subject: [PATCH 5/5] removed bit about inheritence since the work has already been done --- README.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/README.md b/README.md index b43f7cc..9d02ef6 100644 --- a/README.md +++ b/README.md @@ -67,17 +67,3 @@ then is if the fields b should get their own message B. The main discussion poin If in doubt, consider making it a dedicated message B first. This allows for an easier upgrade path than combining them first and then splitting them up. An application developer can always keep using the additional endpoint for B and switch to the embedded fields b in the message A later. The new fields b in message A are not a problem due to the tolerant reader pattern. -On using abstract base types -============================ - -Many events (by example) share similar fields such as an id or timestamp. From a maintenance point of view, it is convenient to extract them to a base type from which concrete events can be derived. In JSON Schema -however, there is no convenient support for this. The closest way of doing it is to have an embedded type. This leads to having the nesting feel a bit awkward if some of these common fields are related to others. -E.g., in a milking visit we would have the timestamp of the visit in the base type structure, while the duration is part of the concrete data type. As such, the working group decided to not use base types for this -in the technical definition; however we do specify it 'on paper' so that we keep it consistent and predictable. We anticipate that if these base types become available, we can change the maintenance of the standard -without impacting the message definitions themselves. - -We do consider the existence of meta-data as a separate type. - -TODO: define the fields that should be in the base type event. - -TODO: define the meta-data type.