Fix the relationship between datastreamschema and add_insert datastream.

update related docs

Author: tipatterson-dev

docs/source/architecture/class_hierarchy.md

@@ -156,7 +156,7 @@ classDiagram
         +encoding: Encoding
         +record_schema: AnyComponent
     }
-    class JSONDatastreamRecordSchema {
+    class OMJSONDatastreamRecordSchema {
         +obs_format = "application/om+json"
         +result_schema: AnyComponent
         +parameters_schema: AnyComponent
@@ -179,7 +179,7 @@ classDiagram
     }
 
     DatastreamRecordSchema <|-- SWEDatastreamRecordSchema
-    DatastreamRecordSchema <|-- JSONDatastreamRecordSchema
+    DatastreamRecordSchema <|-- OMJSONDatastreamRecordSchema
     CommandSchema <|-- SWEJSONCommandSchema
     CommandSchema <|-- JSONCommandSchema
 ```

docs/source/architecture/construction.md

@@ -61,7 +61,7 @@ For raw CS API JSON, parse it through the resource model first:
 * - SWE+JSON schema document
   - `SWEDatastreamRecordSchema.from_swejson_dict(data)`
 * - OM+JSON schema document
-  - `JSONDatastreamRecordSchema.from_omjson_dict(data)`
+  - `OMJSONDatastreamRecordSchema.from_omjson_dict(data)`
 * - OSH logical schema (`obsFormat=logical`)
   - `LogicalDatastreamRecordSchema.from_logical_dict(data)`
 ```
@@ -160,16 +160,29 @@ cs._underlying_resource.command_schema.to_json_dict()
 
 ### "I want the schema for an existing datastream from the server"
 
-`Datastream` has three dedicated fetch methods, one per `obsFormat`
-the server supports. Each returns a typed schema model so there's no
-runtime auto-dispatch:
+For datastreams that came back from `System.discover_datastreams()`,
+the SWE+JSON schema is **already cached** on
+`_underlying_resource.record_schema`. The CS API listing endpoint
+omits the inner schema, so discovery makes a second HTTP call per
+datastream (`GET /datastreams/{id}/schema?obsFormat=application/swe+json`)
+and assigns the result onto the underlying resource. Reading
+`ds._underlying_resource.record_schema` post-discovery returns the
+populated `SWEDatastreamRecordSchema` without another network call.
+A schema fetch that fails for a single datastream is downgraded to a
+warning so it doesn't poison the rest of the discovery; that
+datastream's `record_schema` stays `None`.
+
+For datastreams built locally (no discovery), or when you need the
+OM+JSON or logical variant, `Datastream` has three dedicated fetch
+methods — one per `obsFormat` the server supports. Each returns a
+typed schema model:
 
 ```python
 ds = Datastream(parent_node=node, datastream_resource=DatastreamResource.from_csapi_dict(server_response))
 
 # Wire-format schemas (CS API spec)
 sw = ds.fetch_swejson_schema()    # -> SWEDatastreamRecordSchema (application/swe+json)
-om = ds.fetch_omjson_schema()     # -> JSONDatastreamRecordSchema (application/om+json)
+om = ds.fetch_omjson_schema()     # -> OMJSONDatastreamRecordSchema (application/om+json)
 
 # OSH-specific JSON Schema flavor
 lg = ds.fetch_logical_schema()    # -> LogicalDatastreamRecordSchema (obsFormat=logical)
@@ -181,8 +194,9 @@ Each method:
    parent `Node`'s `APIHelper` for base URL + auth.
 2. Parses the response into the corresponding pydantic model.
 3. Returns the parsed model — does *not* mutate the datastream's
-   `_underlying_resource.record_schema`. If you want to cache it, do
-   it explicitly.
+   `_underlying_resource.record_schema`. (Discovery is the one place
+   that opts into caching the SWE+JSON variant; if you want to cache
+   an OM+JSON or logical fetch, assign it yourself.)
 
 The **logical schema** is OSH-specific (not in the OGC CS API spec):
 a JSON Schema document with OGC extension keywords

docs/source/architecture/serialization.md

@@ -24,7 +24,7 @@ wrapper, route through the resource model.
   - n/a
 * - **Datastream** (`DatastreamResource`)
   - `to_csapi_dict` / `from_csapi_dict`<br/>(application/json — single shape)
-  - SWE+JSON: `SWEDatastreamRecordSchema.to_swejson_dict` / `from_swejson_dict`<br/>OM+JSON: `JSONDatastreamRecordSchema.to_omjson_dict` / `from_omjson_dict`<br/>OSH logical: `LogicalDatastreamRecordSchema.to_logical_dict` / `from_logical_dict`
+  - SWE+JSON: `SWEDatastreamRecordSchema.to_swejson_dict` / `from_swejson_dict`<br/>OM+JSON: `OMJSONDatastreamRecordSchema.to_omjson_dict` / `from_omjson_dict`<br/>OSH logical: `LogicalDatastreamRecordSchema.to_logical_dict` / `from_logical_dict`
   - OM+JSON: `ObservationResource.to_omjson_dict` / `from_omjson_dict`<br/>SWE+JSON: `ObservationResource.to_swejson_dict` / `from_swejson_dict`
 * - **ControlStream** (`ControlStreamResource`)
   - `to_csapi_dict` / `from_csapi_dict`

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "oshconnect"
-version = "0.5.1a0"
+version = "0.5.1a1"
 description = "Library for interfacing with OSH, helping guide visualization efforts, and providing a place to store configurations. Implements OGC CS API Part 3 (Pub/Sub) MQTT topic conventions including :data topics and resource event topics."
 readme = "README.md"
 authors = [

src/oshconnect/__init__.py

@@ -33,7 +33,7 @@
     QuantityRangeSchema,
     TimeRangeSchema,
 )
-from .schema_datamodels import SWEDatastreamRecordSchema, JSONDatastreamRecordSchema, JSONCommandSchema
+from .schema_datamodels import SWEDatastreamRecordSchema, OMJSONDatastreamRecordSchema, JSONCommandSchema
 
 # Event system
 from .events import EventHandler, IEventListener, CallbackListener, DefaultEventTypes, AtomicEventTypes, Event, EventBuilder
@@ -76,7 +76,7 @@
     "QuantityRangeSchema",
     "TimeRangeSchema",
     "SWEDatastreamRecordSchema",
-    "JSONDatastreamRecordSchema",
+    "OMJSONDatastreamRecordSchema",
     "JSONCommandSchema",
     # Event system
     "EventHandler",

src/oshconnect/resource_datamodels.py

@@ -209,10 +209,13 @@ class DatastreamResource(BaseModel):
     feature_of_interest_link: Link = Field(None, alias="featureOfInterest@link")
     sampling_feature_link: Link = Field(None, alias="samplingFeature@link")
     parameters: dict = Field(None)
-    phenomenon_time: TimePeriod = Field(None, alias="phenomenonTimeInterval")
+    phenomenon_time: TimePeriod = Field(None, alias="phenomenonTime")
     result_time: TimePeriod = Field(None, alias="resultTimeInterval")
     ds_type: str = Field(None, alias="type")
     result_type: str = Field(None, alias="resultType")
+    formats: List[str] = Field(default_factory=list)
+    observed_properties: List[dict] = Field(default_factory=list, alias="observedProperties")
+    system_id: str = Field(None, alias="system@id")
     links: List[Link] = Field(None)
     record_schema: SerializeAsAny[DatastreamRecordSchema] = Field(None, alias="schema")
 
@@ -236,7 +239,7 @@ def to_csapi_dict(self) -> dict:
         """Render this datastream as the CS API `application/json` resource
         body. The embedded ``schema`` field is dumped polymorphically per
         whichever variant (`SWEDatastreamRecordSchema` /
-        `JSONDatastreamRecordSchema`) it holds.
+        `OMJSONDatastreamRecordSchema`) it holds.
         """
         return self.model_dump(by_alias=True, exclude_none=True, mode='json')
 

src/oshconnect/schema_datamodels.py

@@ -155,9 +155,10 @@ def from_swejson_dict(cls, data: dict) -> "SWEDatastreamRecordSchema":
         return cls.model_validate(data, by_alias=True)
 
 
-class JSONDatastreamRecordSchema(DatastreamRecordSchema):
-    """Datastream observation schema for the JSON media types
-    (`application/json`, `application/om+json`).
+class OMJSONDatastreamRecordSchema(DatastreamRecordSchema):
+    """Datastream observation schema for the OM+JSON media type
+    (`application/om+json`, also accepts `application/json` as a synonym
+    on parse since OSH treats them equivalently for datastream schemas).
 
     Per CS API Part 2 §16.1.4, this form does not carry a SWE `encoding`
     block; structure is fully described by `resultSchema` (inline result)
@@ -182,17 +183,17 @@ def _check_obs_format(cls, v):
     @model_validator(mode="after")
     def _root_schemas_require_name(self):
         if self.result_schema is not None:
-            check_named(self.result_schema, "JSONDatastreamRecordSchema.resultSchema")
+            check_named(self.result_schema, "OMJSONDatastreamRecordSchema.resultSchema")
         if self.parameters_schema is not None:
-            check_named(self.parameters_schema, "JSONDatastreamRecordSchema.parametersSchema")
+            check_named(self.parameters_schema, "OMJSONDatastreamRecordSchema.parametersSchema")
         return self
 
     def to_omjson_dict(self) -> dict:
         """Render as an `application/om+json` datastream-schema document."""
         return _dump_csapi(self)
 
     @classmethod
-    def from_omjson_dict(cls, data: dict) -> "JSONDatastreamRecordSchema":
+    def from_omjson_dict(cls, data: dict) -> "OMJSONDatastreamRecordSchema":
         """Build from an `application/om+json` (or `application/json`)
         datastream-schema dict (e.g., a CS API ``/datastreams/{id}/schema``
         response in OM+JSON form)."""
@@ -231,7 +232,7 @@ class LogicalDatastreamRecordSchema(BaseModel):
     """Logical schema document — OSH's `obsFormat=logical` representation.
 
     Returned by ``GET /datastreams/{id}/schema?obsFormat=logical``. Distinct
-    from `SWEDatastreamRecordSchema` and `JSONDatastreamRecordSchema`:
+    from `SWEDatastreamRecordSchema` and `OMJSONDatastreamRecordSchema`:
 
     - No ``obsFormat`` envelope field
     - No ``recordSchema`` wrapper — the schema is the document