From 97f00ad1a78a4bae0eb536ac34364a32a883818d Mon Sep 17 00:00:00 2001
From: Yan Wong <yan.wong@bdi.ox.ac.uk>
Date: Mon, 7 Mar 2022 16:38:21 +0000
Subject: [PATCH] Update example to show nested objects

And also NaN for a floating point number
---
 docs/metadata.md | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/docs/metadata.md b/docs/metadata.md
index 2f9a8d6590..a9991f0cfe 100644
--- a/docs/metadata.md
+++ b/docs/metadata.md
@@ -400,6 +400,23 @@ schema = metadata.MetadataSchema(
                 "binaryFormat": "10p",
                 "pattern": "^([1-9][0-9]{3})-(1[0-2]|0[1-9])-(3[01]|0[1-9]|[12][0-9])?$",
             },
+            "phenotype": {
+                "description": "Phenotypic measurements on this individual",
+                "type": "object",
+                "properties": {
+                    "height": {
+                        "description": "Height in metres, or NaN if unknown",
+                        "type": "number",
+                        "binaryFormat": "f",
+                    },
+                    "age": {
+                        "description": "Age in years at time of sampling, or -1 if unknown",
+                        "type": "number",
+                        "binaryFormat": "h",
+                    },
+                },
+                "default": {"height": float("NaN"), "age": -1},
+            },
         },
         "required": ["accession_number", "collection_date"],
         "additionalProperties": False,
@@ -407,15 +424,17 @@ schema = metadata.MetadataSchema(
 )
 ```
 
-This schema states that the metadata for each row of the table
-is an object consisting of two properties. Property `accession_number` is a number
-(stored as a 4-byte int).
+This schema states that the metadata for each row of the table is an object consisting
+of three properties. Property `accession_number` is a number (stored as a 4-byte int).
 Property `collection_date` is a string which must satisfy a regex, which checks it is
-a valid [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) date.
-Both properties are required to be specified (this must always be done for the struct codec,
-for the JSON codec properties can be optional).
-Any other properties are not allowed (`additionalProperties` is false), this is also needed
-when using struct.
+a valid [ISO8601](https://www.iso.org/iso-8601-date-and-time-format.html) date. Property
+`phenotype` is itself an object consisting of the properties `height` (a single precision
+floating point number) and age (a 2 byte signed integer).
+Because this is a struct codec, and neither of the the first two properties have a
+default set, they must be marked as "required" (in the JSON codec if no default is given,
+unspecified properties will simply be missing in the returned metadata dictionary).
+Also because this is a struct codec, `additionalProperties` must be set to False. This
+is assumed by default in the struct codec, but has been shown above for clarity.
 
 (sec_metadata_api_overview)=