Re-home json_schema, re-imagine parsing, fix bug 🦋

Bug Fix
-------

At least one bug is fixed in this commit: the class
`EnhancedJsonSchemaGenerator` (now rechristened with the more accurate
if more unwieldy name `GenerateOmitNullableOptionalJsonSchema`) was
eliminating the `null` option on nullable fields that were required,
which subtly changed the meaning of the schema.

Where before you had:

{
  "required": ["foo"],
  "properties": {
    "foo": {
      "anyOf": [
        {"type": "string"},
        {"type": "null"}
      ]
    }
  }
}

The anyOf/null option was being removed but the required remained, which
meant changed the meaning from "you have to put something, but it can be
a string or the value `null`" to "you have to put a string". That's not
an equivalent schema.

Re-Homing of `json_schema`
--------------------------
The function `json_schema` and its entourage, the JSON Schema generator
class `EnhancedJsonSchemaGenerator`, are promoted from core to system.
This is because they are very general-purpose "George" functionality
that isn't really tied to the Overture schema per se.

Longer term, I think there's a case to be made that we should drop
`json_schema` and `GenerateOmitNullableOptionalJsonSchema` and just rely
on the existing Pydantic functionality, which is rich, along with the
`Omitable` type that's already in system. I'd like to reopen this topic.

As part of this work, I gave `GenerateOmitNullableOptionalJsonSchema`
some very thorough documentation including doctests.

Re-Imagining of Parsing
-----------------------
I killed the `parse_feature` function as I don't see what value it
brings above and beyond the native Pydantic parsing. Now that I have
fully fixed the `Feature` and `OvertureFeature` Pydantic integrations
to correctly parse the GeoJSON in all cases, its hard to see why we
need a function that "can parse an Overture feature from GeoJSON" when
the existing Pydantic functions can already do that.

I renamed the `parse` function in the overture-schema package to
`validate` and split it into two functions, `validate` and
`validate_json`, mirroring the fairly consistent way that Pydantic
likes to break it down. I used the new GeoJSON-compatible discriminated
union functionality from `Feature` (see earlier commit) and brought the
functions more into line with how Pydantic generally works. Basically
now they're "do the Pydantic thing, but with the union of all the
discovered models" functions. Also bugs are fixed, docs are added, and
the docs and code are hopefully closer to being in harmony...

Author: vcschapp

packages/overture-schema-addresses-theme/tests/test_address_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.addresses import Address
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_address_json_schema_baseline() -> None:

packages/overture-schema-annex/src/overture/schema/annex/models.py

@@ -68,6 +68,7 @@ class Dataset(BaseModel):
         str,
         Field(description="Any attribution required by this source."),
     ]
+    # FIXME: This should be a `BBox` primitive, not a `list[float]`.
     coverage_bbox: Annotated[
         list[float],
         Field(

packages/overture-schema-annex/tests/test_sources_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.annex import Sources
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_sources_json_schema_baseline() -> None:

packages/overture-schema-base-theme/tests/test_bathymetry_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.base import Bathymetry
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_bathymetry_json_schema_baseline() -> None:

packages/overture-schema-base-theme/tests/test_infrastructure_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.base import Infrastructure
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_infrastructure_json_schema_baseline() -> None:

packages/overture-schema-base-theme/tests/test_land_cover_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.base import LandCover
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_land_cover_json_schema_baseline() -> None:

packages/overture-schema-base-theme/tests/test_land_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.base import Land
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_land_json_schema_baseline() -> None:

packages/overture-schema-base-theme/tests/test_land_use_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.base import LandUse
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_land_use_json_schema_baseline() -> None:

packages/overture-schema-base-theme/tests/test_water_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.base import Water
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_water_json_schema_baseline() -> None:

packages/overture-schema-buildings-theme/tests/test_building_json_schema_baseline.py

@@ -4,7 +4,7 @@
 import os
 
 from overture.schema.buildings.building import Building
-from overture.schema.core import json_schema
+from overture.schema.system.json_schema import json_schema
 
 
 def test_building_json_schema_baseline() -> None: