From f3e5064a51d9b63649f8133fae0203b694f071a7 Mon Sep 17 00:00:00 2001
From: Sebastien Besson <seb.besson@gmail.com>
Date: Mon, 29 Aug 2022 09:28:09 +0100
Subject: [PATCH 1/2] Add section about JSON schemas

Described schemas location, testing & deployment as well as the
management and the testing of official JSON examples
---
 README.md | 22 +++++++++++++++++++++-
 1 file changed, 21 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 1393bf16..26c7f21e 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,26 @@ Commits on GitHub can be viewed using web services from the W3C:
 * Update changelog at the bottom of `latest/index.bs`
 * Find references to previous version and _in most cases_, bump to the current version.
 
+## JSON schemas
+
+For each top-level metadata key of the OME-NGFF specification, JSON schemas are maintained
+for each version of the specification and stored under `$VERSION/schemas/` or `latest/schemas/`.
+Tests validating these schemas must be implementing to follow principles of the
+[JSON schema test suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
+and stored under `$VERSION/tests/` or `latest/tests/` to allow their execution on each CI build.
+
+All official example snippets must also be extracted and managed as separate JSON files under
+`$VERSION/examples/` or `latest/examples/`, validated by the appropriate schema by adding a
+`.config.json` file specifying the JSON schema to use and included in the
+specification document using the
+[include-code](https://tabatkins.github.io/bikeshed/#including-code) directive.
+
+The official OME-NGFF JSON schemas are published under
+https://ngff.openmicroscopy.org/<version>/schemas/<schema_name>.schema using the
+[Spec prod](https://github.com/ome/spec-prod) GitHub action. When a new JSON schema is introduced,
+this action needs to be reviewed updated to update the deployment and allow the publication
+of the schema
+
 # Release process
 
 * copy `latest/index.bs` to `$VERSION/index.bs`
@@ -43,7 +63,7 @@ Commits on GitHub can be viewed using web services from the W3C:
   * Version in the citation block including release date
 * Update https://github.com/ome/spec-prod for the new version
 
-## Citing
+# Citing
 
 Please see https://ngff.openmicroscopy.org/latest#citing for the latest
 citation.

From 439c86c721c79cd18abf0e5da5837c8ad5512de9 Mon Sep 17 00:00:00 2001
From: Sebastien Besson <seb.besson@gmail.com>
Date: Mon, 29 Aug 2022 09:58:10 +0100
Subject: [PATCH 2/2] Address Will's comments

---
 README.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README.md b/README.md
index 26c7f21e..6b123172 100644
--- a/README.md
+++ b/README.md
@@ -33,7 +33,7 @@ Commits on GitHub can be viewed using web services from the W3C:
 
 For each top-level metadata key of the OME-NGFF specification, JSON schemas are maintained
 for each version of the specification and stored under `$VERSION/schemas/` or `latest/schemas/`.
-Tests validating these schemas must be implementing to follow principles of the
+Tests validating these schemas must be implemented to follow principles of the
 [JSON schema test suite](https://github.com/json-schema-org/JSON-Schema-Test-Suite)
 and stored under `$VERSION/tests/` or `latest/tests/` to allow their execution on each CI build.
 
@@ -46,8 +46,8 @@ specification document using the
 The official OME-NGFF JSON schemas are published under
 https://ngff.openmicroscopy.org/<version>/schemas/<schema_name>.schema using the
 [Spec prod](https://github.com/ome/spec-prod) GitHub action. When a new JSON schema is introduced,
-this action needs to be reviewed updated to update the deployment and allow the publication
-of the schema
+this action needs to be reviewed to update the deployment script and allow the publication
+of the schema.
 
 # Release process