Skip to content

Pydantic Models for MicroJSON and GeoJSON

Introduction

This document describes the Pydantic models used for GeoJSON and MicroJSON objects. These models leverage Python's type hinting and Pydantic's validation mechanisms, making it robust and efficient to work with complex GeoJSON and MicroJSON objects.

Models

MicroJSON and GeoJSON models, defined manually using pydantic.

GeoJSON

Bases: RootModel

The root object of a GeoJSON file

Source code in src/microjson/model.py 
170
171
172
173
class GeoJSON(RootModel):
    """The root object of a GeoJSON file"""

    root: Union[Feature, FeatureCollection, GeometryType]  # type: ignore

MicroFeature

Bases: Feature

A MicroJSON feature, which is a GeoJSON feature with additional metadata

Parameters:

Name Type Description Default
geometry Optional[GeometryType]

Extended geometry supporting 3D types

 required
multiscale Optional[Multiscale]

The coordinate system of the feature

 required
ref Optional[Union[StrictStr, StrictInt]]

A reference to the parent feature

 required
parentId Optional[Union[StrictStr, StrictInt]]

A reference to the parent feature

 required
featureClass Optional[str]

The class of the feature

 required
Source code in src/microjson/model.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class MicroFeature(Feature):
    """A MicroJSON feature, which is a GeoJSON feature with additional
    metadata

    Args:
        geometry (Optional[GeometryType]): Extended geometry supporting 3D types
        multiscale (Optional[Multiscale]): The coordinate system of the feature
        ref (Optional[Union[StrictStr, StrictInt]]):
            A reference to the parent feature
        parentId (Optional[Union[StrictStr, StrictInt]]):
            A reference to the parent feature
        featureClass (Optional[str]): The class of the feature
    """

    # Override geometry to accept MicroJSON 3D types in addition to GeoJSON types
    geometry: Union[GeometryType, None]  # type: ignore[assignment]
    ref: Optional[Union[StrictStr, StrictInt]] = None
    # reference to the parent feature
    parentId: Optional[Union[StrictStr, StrictInt]] = None
    # for now, only string feature class is supported
    # in the future, it may be expanded with a class registry
    featureClass: Optional[str] = None
    vocabularies: Optional[Union[Dict[str, Vocabulary], str]] = None

MicroFeatureCollection

Bases: FeatureCollection

A MicroJSON feature collection, which is a GeoJSON feature collection with additional metadata.

Parameters:

Name Type Description Default
features List[MicroFeature]

Features with extended 3D geometry support

 required
properties Optional[Props]

The properties of the feature collection

 required
id Optional[Union[StrictStr, StrictInt]]

The ID of the feature coll.

 required
Source code in src/microjson/model.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
class MicroFeatureCollection(FeatureCollection):
    """A MicroJSON feature collection, which is a GeoJSON feature
    collection with additional metadata.

    Args:
        features (List[MicroFeature]): Features with extended 3D geometry support
        properties (Optional[Props]): The properties of the feature collection
        id (Optional[Union[StrictStr, StrictInt]]): The ID of the feature coll.
        provenance (Optional[Union[Workflow,
            WorkflowCollection,
            Artifact,
            ArtifactCollection]]): The provenance of the feature collection
    """

    # Override features to use MicroFeature (supports 3D geometry types)
    features: List[MicroFeature]  # type: ignore[assignment]
    properties: Optional[Dict[str, Any]] = None
    id: Optional[Union[StrictStr, StrictInt]] = None
    provenance: Optional[
        Union[Workflow, WorkflowCollection, Artifact, ArtifactCollection]
    ] = None
    vocabularies: Optional[Union[Dict[str, Vocabulary], str]] = None

MicroJSON

Bases: RootModel

The root object of a MicroJSON file

Source code in src/microjson/model.py 
225
226
227
228
class MicroJSON(RootModel):
    """The root object of a MicroJSON file"""

    root: Union[MicroFeature, MicroFeatureCollection, GeometryType]  # type: ignore

OntologyTerm

Bases: BaseModel

A reference to a formal ontology term.

Attributes:

Name Type Description
uri str

Full URI of the ontology term (e.g. "http://purl.obolibrary.org/obo/CL_0000598").
label Optional[str]

Human-readable label (e.g. "pyramidal neuron").
description Optional[str]

Optional longer description of the term.
Source code in src/microjson/model.py 
130
131
132
133
134
135
136
137
138
139
140
class OntologyTerm(BaseModel):
    """A reference to a formal ontology term.

    Attributes:
        uri: Full URI of the ontology term (e.g. "http://purl.obolibrary.org/obo/CL_0000598").
        label: Human-readable label (e.g. "pyramidal neuron").
        description: Optional longer description of the term.
    """
    uri: str
    label: Optional[str] = None
    description: Optional[str] = None

PolyhedralSurface

Bases: BaseModel

A closed surface mesh consisting of polygonal faces (ISO 19107).

Each face has the same structure as a Polygon: a list of linear rings, where each ring is a list of 3D positions.

Source code in src/microjson/model.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
class PolyhedralSurface(BaseModel):
    """A closed surface mesh consisting of polygonal faces (ISO 19107).

    Each face has the same structure as a Polygon: a list of linear rings,
    where each ring is a list of 3D positions.
    """

    type: Literal["PolyhedralSurface"]
    coordinates: List[PolygonCoords]

    @field_validator("coordinates")
    @classmethod
    def _at_least_one_face(cls, v: List[PolygonCoords]) -> List[PolygonCoords]:
        if len(v) == 0:
            raise ValueError("PolyhedralSurface must have at least one face")
        return v

    def bbox3d(self) -> Tuple[float, float, float, float, float, float]:
        return _bbox3d(self.coordinates)

    def centroid3d(self) -> Tuple[float, float, float]:
        return _centroid3d(self.coordinates)

TIN

Bases: BaseModel

A Triangulated Irregular Network — triangle mesh surface (ISO 19107).

Each face must be a single closed ring of exactly 4 positions (3 vertices + repeated first vertex).

Source code in src/microjson/model.py 
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
class TIN(BaseModel):
    """A Triangulated Irregular Network — triangle mesh surface (ISO 19107).

    Each face must be a single closed ring of exactly 4 positions
    (3 vertices + repeated first vertex).
    """

    type: Literal["TIN"]
    coordinates: List[PolygonCoords]

    @field_validator("coordinates")
    @classmethod
    def _validate_triangles(cls, v: List[PolygonCoords]) -> List[PolygonCoords]:
        if len(v) == 0:
            raise ValueError("TIN must have at least one face")
        for i, face in enumerate(v):
            if len(face) != 1:
                raise ValueError(
                    f"TIN face {i} must have exactly one ring, got {len(face)}"
                )
            ring = face[0]
            if len(ring) != 4:
                raise ValueError(
                    f"TIN face {i} ring must have exactly 4 positions "
                    f"(closed triangle), got {len(ring)}"
                )
        return v

    def bbox3d(self) -> Tuple[float, float, float, float, float, float]:
        return _bbox3d(self.coordinates)

    def centroid3d(self) -> Tuple[float, float, float]:
        return _centroid3d(self.coordinates)

Vocabulary

Bases: BaseModel

Maps property values to formal ontology terms.

Attributes:

Name Type Description
namespace Optional[str]

Common URI prefix for the ontology (e.g. "http://purl.obolibrary.org/obo/CL_").
description Optional[str]

Optional description of this vocabulary.
terms Dict[str, OntologyTerm]

Mapping from property values to ontology terms.
Source code in src/microjson/model.py 
143
144
145
146
147
148
149
150
151
152
153
class Vocabulary(BaseModel):
    """Maps property values to formal ontology terms.

    Attributes:
        namespace: Common URI prefix for the ontology (e.g. "http://purl.obolibrary.org/obo/CL_").
        description: Optional description of this vocabulary.
        terms: Mapping from property values to ontology terms.
    """
    namespace: Optional[str] = None
    description: Optional[str] = None
    terms: Dict[str, OntologyTerm]

Base Objects

Geometry Types

Uses geojson-pydantic models for GeoJSON geometry types, included here for reference. Please refer to the geojson-pydantic documentation for more information.

Point

Represents a GeoJSON Point object.

MultiPoint

Represents a GeoJSON MultiPoint object.

LineString

Represents a GeoJSON LineString object.

MultiLineString

Represents a GeoJSON MultiLineString object.

Polygon

Represents a GeoJSON Polygon object.

MultiPolygon

Represents a GeoJSON MultiPolygon object.

Compound Objects

GeometryCollection

A collection of multiple geometries. From geojson-pydantic, included here for reference.

Feature

Represents a GeoJSON feature object, from geojson-pydantic, included here for reference.

FeatureCollection

Represents a GeoJSON feature collection, from geojson-pydantic, included here for reference.

GeoJSON

The root object of a GeoJSON file.

Bases: RootModel

The root object of a GeoJSON file

Source code in src/microjson/model.py 
170
171
172
173
class GeoJSON(RootModel):
    """The root object of a GeoJSON file"""

    root: Union[Feature, FeatureCollection, GeometryType]  # type: ignore

MicroJSON Extended Models

MicroFeature

A MicroJSON feature, which is an extension of a GeoJSON feature.

Bases: Feature

A MicroJSON feature, which is a GeoJSON feature with additional metadata

Parameters:

Name Type Description Default
geometry Optional[GeometryType]

Extended geometry supporting 3D types

 required
multiscale Optional[Multiscale]

The coordinate system of the feature

 required
ref Optional[Union[StrictStr, StrictInt]]

A reference to the parent feature

 required
parentId Optional[Union[StrictStr, StrictInt]]

A reference to the parent feature

 required
featureClass Optional[str]

The class of the feature

 required
Source code in src/microjson/model.py 
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
class MicroFeature(Feature):
    """A MicroJSON feature, which is a GeoJSON feature with additional
    metadata

    Args:
        geometry (Optional[GeometryType]): Extended geometry supporting 3D types
        multiscale (Optional[Multiscale]): The coordinate system of the feature
        ref (Optional[Union[StrictStr, StrictInt]]):
            A reference to the parent feature
        parentId (Optional[Union[StrictStr, StrictInt]]):
            A reference to the parent feature
        featureClass (Optional[str]): The class of the feature
    """

    # Override geometry to accept MicroJSON 3D types in addition to GeoJSON types
    geometry: Union[GeometryType, None]  # type: ignore[assignment]
    ref: Optional[Union[StrictStr, StrictInt]] = None
    # reference to the parent feature
    parentId: Optional[Union[StrictStr, StrictInt]] = None
    # for now, only string feature class is supported
    # in the future, it may be expanded with a class registry
    featureClass: Optional[str] = None
    vocabularies: Optional[Union[Dict[str, Vocabulary], str]] = None

MicroFeatureCollection

A MicroJSON feature collection, which is an extension of a GeoJSON feature collection.

Bases: FeatureCollection

A MicroJSON feature collection, which is a GeoJSON feature collection with additional metadata.

Parameters:

Name Type Description Default
features List[MicroFeature]

Features with extended 3D geometry support

 required
properties Optional[Props]

The properties of the feature collection

 required
id Optional[Union[StrictStr, StrictInt]]

The ID of the feature coll.

 required
Source code in src/microjson/model.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
class MicroFeatureCollection(FeatureCollection):
    """A MicroJSON feature collection, which is a GeoJSON feature
    collection with additional metadata.

    Args:
        features (List[MicroFeature]): Features with extended 3D geometry support
        properties (Optional[Props]): The properties of the feature collection
        id (Optional[Union[StrictStr, StrictInt]]): The ID of the feature coll.
        provenance (Optional[Union[Workflow,
            WorkflowCollection,
            Artifact,
            ArtifactCollection]]): The provenance of the feature collection
    """

    # Override features to use MicroFeature (supports 3D geometry types)
    features: List[MicroFeature]  # type: ignore[assignment]
    properties: Optional[Dict[str, Any]] = None
    id: Optional[Union[StrictStr, StrictInt]] = None
    provenance: Optional[
        Union[Workflow, WorkflowCollection, Artifact, ArtifactCollection]
    ] = None
    vocabularies: Optional[Union[Dict[str, Vocabulary], str]] = None

MicroJSON

The root object of a MicroJSON file.

Bases: RootModel

The root object of a MicroJSON file

Source code in src/microjson/model.py 
225
226
227
228
class MicroJSON(RootModel):
    """The root object of a MicroJSON file"""

    root: Union[MicroFeature, MicroFeatureCollection, GeometryType]  # type: ignore