Document permissive_json

Author: benjeffery

c/CHANGELOG.rst

@@ -85,6 +85,8 @@
 - Add the ``tsk_tree_get_size_bound`` function which returns an upper bound on the number of nodes reachable from
   the roots of a tree. Useful for tree stack allocations (:user:`jeromekelleher`, :pr:`1704`).
 
+- Add ``MetadataSchema.permissive_json`` for an easy way to get the simplest schema.
+
 
 ----------------------
 [0.99.14] - 2021-09-03

docs/metadata.md

@@ -53,6 +53,9 @@ the keys and types of those properties are specified along with optional
 long-form names, descriptions and validations such as min/max or regex matching for
 strings, see the {ref}`sec_metadata_schema_examples` below.
 
+As a convenience the simplest, permissive JSON schema is available as
+{meth}`MetadataSchema.permissive_json()`.
+
 The {ref}`sec_tutorial_metadata` Tutorial shows how to use schemas and access metadata
 in the tskit Python API.
 

python/tskit/metadata.py

@@ -700,12 +700,12 @@ def encode_row(self, row: Any) -> bytes:
         # Set by __init__
         pass  # pragma: no cover
 
-    # Utility to make a simple permission JSON schema. Probably should be
-    # part of the documented API. See
-    # https://github.com/tskit-dev/tskit/issues/1956 for more details.
-
     @staticmethod
     def permissive_json():
+        """
+        The simplest, permissive JSON schema. Only specifies the JSON codec and has
+        no constraints on the properties.
+        """
         return MetadataSchema({"codec": "json"})