issue 11: have a readable version of the spec

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](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)
+
+
 Approach
 ========
 
@@ -54,23 +61,9 @@ 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 
 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 ackward 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. 
-
-TODO: define the fields that should be in the base type event.
-
-TODO: define the meta-data type.

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.

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).
+
+