pystac-ext-osc 1.0.0__py3-none-any.whl

pystac/extensions/__about__.py

@@ -0,0 +1,17 @@
+# Copyright 2026 Terradue
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Package metadata for Open Science Catalogue pystac extension."""
+
+__version__ = "1.0.0"

pystac/extensions/ogc_record.py

@@ -0,0 +1,566 @@
+# Copyright 2026 Terradue
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""OGC API Records adapter for PySTAC 1.x.x; see README for boundaries."""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any, Generic, Literal, TypeAlias, TypedDict, TypeVar
+
+from pystac.utils import datetime_to_str, str_to_datetime
+
+import pystac
+
+T = TypeVar("T")
+
+
+if TYPE_CHECKING:
+    from datetime import datetime as Datetime
+
+
+class _RequiredLanguage(TypedDict):
+    code: str
+
+
+class Language(_RequiredLanguage, total=False):
+    """Language metadata as defined by the OGC Records language.yaml schema.
+
+    ``code`` is a required RFC 5646 language tag. Optional ``name`` is the
+    untranslated language name and must be nonempty when supplied;
+    ``alternate`` names the language in another language, usually English.
+    ``dir`` defaults to ``ltr`` in the schema when omitted.
+
+    This structure provides static typing, not runtime schema validation.
+    """
+
+    name: str
+    alternate: str
+    dir: Literal["ltr", "rtl", "ttb", "btt"]
+
+
+class _RequiredThemeConcept(TypedDict):
+    id: str
+
+
+class ThemeConcept(_RequiredThemeConcept, total=False):
+    """A theme concept with a required identifier and optional descriptions.
+
+    ``url``, when supplied, must be a URI.
+    """
+
+    title: str
+    description: str
+    url: str
+
+
+class Theme(TypedDict):
+    """Theme metadata as defined by the OGC Records theme.yaml schema.
+
+    Both fields are required. ``concepts`` must contain at least one concept;
+    ``scheme`` identifies the knowledge organization system, preferably by a
+    resolvable URI. This structure provides static typing, not runtime schema
+    validation.
+    """
+
+    concepts: list[ThemeConcept]
+    scheme: str
+
+
+class _RequiredFormatName(TypedDict):
+    name: str
+
+
+class NamedFormat(_RequiredFormatName, total=False):
+    """A format identified by name, optionally including its media type."""
+
+    mediaType: str
+
+
+class _RequiredFormatMediaType(TypedDict):
+    mediaType: str
+
+
+class MediaTypeFormat(_RequiredFormatMediaType, total=False):
+    """A format identified by media type, optionally including its name."""
+
+    name: str
+
+
+# OGC format.yaml requires name or mediaType (or both). The union expresses
+# this constraint for static typing without runtime schema validation.
+Format: TypeAlias = NamedFormat | MediaTypeFormat
+
+
+class _RequiredExternalId(TypedDict):
+    value: str
+
+
+class ExternalId(_RequiredExternalId, total=False):
+    """An external identifier with a required value and optional scheme.
+
+    ``scheme`` references the authority or knowledge organization system
+    from which the identifier was obtained, preferably by a resolvable URI.
+    This structure provides static typing, not runtime schema validation.
+    """
+
+    scheme: str
+
+
+# roles.yaml requires at least one entry; length is not checked at runtime.
+Roles: TypeAlias = list[str]
+
+
+class ContactDetail(_RequiredExternalId, total=False):
+    """A phone number or email address with optional roles.
+
+    Reuses the required string value structure. Phone values must match
+    ``^\\+[1-9]{1}[0-9]{3,14}$``; email values must use email format.
+    """
+
+    roles: Roles
+
+
+class ContactAddress(TypedDict, total=False):
+    """A contact's physical address; all fields are optional."""
+
+    deliveryPoint: list[str]
+    city: str
+    administrativeArea: str
+    postalCode: str
+    country: str
+    roles: Roles
+
+
+class _RequiredContactLink(TypedDict):
+    href: str
+    type: str
+
+
+class _ContactLinkFields(_RequiredContactLink, total=False):
+    """Shared contact link fields from linkBase.yaml and link.yaml.
+
+    ``href`` must be a URI; ``created`` and ``updated`` use date-time strings.
+    """
+
+    hreflang: str
+    title: str
+    length: int
+    profile: list[str]
+    created: str
+    updated: str
+
+
+class ContactLink(_ContactLinkFields, total=False):
+    """An online contact link with required href and media type."""
+
+    rel: str
+
+
+class ContactLogo(_ContactLinkFields):
+    """A contact logo with required href, media type, and icon relation.
+
+    The media type should be an image media type.
+    """
+
+    rel: Literal["icon"]
+
+
+class _ContactFields(TypedDict, total=False):
+    identifier: str
+    position: str
+    logo: ContactLogo
+    phones: list[ContactDetail]
+    emails: list[ContactDetail]
+    addresses: list[ContactAddress]
+    links: list[ContactLink]
+    hoursOfService: str
+    contactInstructions: str
+    roles: Roles
+
+
+class _RequiredContactName(_ContactFields):
+    name: str
+
+
+class NamedContact(_RequiredContactName, total=False):
+    """A contact identified by name, optionally including an organization."""
+
+    organization: str
+
+
+class _RequiredContactOrganization(_ContactFields):
+    organization: str
+
+
+class OrganizationContact(_RequiredContactOrganization, total=False):
+    """A contact identified by organization, optionally including a name."""
+
+    name: str
+
+
+# contact.yaml requires name or organization (or both). As with Format,
+# the union provides static typing, not runtime schema validation.
+Contact: TypeAlias = NamedContact | OrganizationContact
+
+
+class MetadataField(Generic[T]):
+    """A live, optional accessor into the record properties dictionary."""
+
+    def __init__(self, key: str) -> None:
+        self.key = key
+
+    def __get__(self, instance: Any, owner: Any = None) -> Any:
+        if instance is None:
+            return self
+        return instance.properties.get(self.key)
+
+    def __set__(self, instance: Any, value: T | None) -> None:
+        if value is None:
+            instance.properties.pop(self.key, None)
+        else:
+            instance.properties[self.key] = value
+
+
+class RecordMetadataMixin:
+    """Direct recordCommonProperties accessors; dates use their JSON string form.
+
+    Nested structures remain open dictionaries, allowing future extensions.
+    These accessors do not perform JSON Schema validation.
+    """
+
+    created = MetadataField[str]("created")
+    updated = MetadataField[str]("updated")
+    type = MetadataField[str]("type")
+    title = MetadataField[str]("title")
+    description = MetadataField[str]("description")
+    keywords = MetadataField[list[str]]("keywords")
+    themes = MetadataField[list[Theme]]("themes")
+    language = MetadataField[Language]("language")
+    languages = MetadataField[list[Language]]("languages")
+    resource_languages = MetadataField[list[Language]]("resourceLanguages")
+    external_ids = MetadataField[list[ExternalId]]("externalIds")
+    formats = MetadataField[list[Format]]("formats")
+    contacts = MetadataField[list[Contact]]("contacts")
+    license = MetadataField[str]("license")
+    rights = MetadataField[str]("rights")
+
+
+class RecordCommonProperties(RecordMetadataMixin):
+    """Backward-compatible metadata view sharing the record properties."""
+
+    def __init__(self, record: OGCRecord) -> None:
+        self.record = record
+
+    @property
+    def properties(self) -> dict[str, Any]:
+        return self.record.properties
+
+    def to_dict(self) -> dict[str, Any]:
+        return deepcopy(self.properties)
+
+
+class OGCRecord(RecordMetadataMixin, pystac.Item):
+    """Item-compatible Record, with OGC serialization as the default.
+
+    Initializes STACObject directly to avoid Item's mandatory temporal extent.
+    This compatibility seam must be reviewed for future PySTAC releases.
+    `time` and STAC datetime fields are independent: no implicit conversion.
+    """
+
+    SCHEMA_URI = (
+        "https://schemas.opengis.net/ogcapi/records/part1/1.0/openapi/schemas/recordGeoJSON.yaml"
+    )
+    _RESERVED = frozenset(
+        {
+            "id",
+            "type",
+            "geometry",
+            "properties",
+            "links",
+            "assets",
+            "bbox",
+            "collection",
+            "stac_extensions",
+        }
+    )
+
+    # Preserve the positional PySTAC Item constructor API and OGC keyword options.
+    def __init__(  # noqa: PLR0917
+        self,
+        id: str | int,
+        geometry: dict[str, Any] | None = None,
+        bbox: list[float] | None = None,
+        datetime: Datetime | None = None,
+        properties: dict[str, Any] | None = None,
+        start_datetime: Datetime | None = None,
+        end_datetime: Datetime | None = None,
+        stac_extensions: list[str] | None = None,
+        href: str | None = None,
+        collection: str | pystac.Collection | None = None,
+        extra_fields: dict[str, Any] | None = None,
+        assets: dict[str, pystac.Asset] | None = None,
+        *,
+        time: dict[str, Any] | None = None,
+        conforms_to: list[str] | None = None,
+        link_templates: list[dict[str, Any]] | None = None,
+    ) -> None:
+        """Initialize a record, copying metadata and assigning asset ownership.
+
+        OGC ``time`` is independent of the STAC datetime arguments. Optional
+        OGC fields override matching entries in ``extra_fields`` when supplied.
+
+        Raises:
+            TypeError: If the identifier is not a string or integer.
+            ValueError: If extra fields override managed record fields.
+        """
+        if isinstance(id, bool) or not isinstance(id, (str, int)):
+            raise TypeError("Record id must be a string or integer")
+        pystac.STACObject.__init__(self, list(stac_extensions or []))
+        self._record_id = id
+        self.id = str(id)  # PySTAC path/layout utilities require a string.
+        self.geometry = deepcopy(geometry)
+        self.bbox = deepcopy(bbox)
+        self._null_properties = properties is None
+        self.properties = deepcopy(properties) if properties is not None else {}
+        self.extra_fields = deepcopy(extra_fields) if extra_fields else {}
+        if self._RESERVED.intersection(self.extra_fields):
+            raise ValueError("extra_fields must not override managed fields")
+        self.assets = {}
+        self.collection_id = None
+        self._stac_io = None
+        self._set_temporal_properties(datetime, start_datetime, end_datetime)
+        for field_name, field_value in (
+            ("time", time),
+            ("conformsTo", conforms_to),
+            ("linkTemplates", link_templates),
+        ):
+            if field_value is not None:
+                self.extra_fields[field_name] = deepcopy(field_value)
+        self._attach_stac_objects(collection, assets, href)
+
+    def _attach_stac_objects(
+        self,
+        collection: str | pystac.Collection | None,
+        assets: dict[str, pystac.Asset] | None,
+        href: str | None,
+    ) -> None:
+        """Set collection links, asset ownership, and the record's location."""
+        if isinstance(collection, pystac.Collection):
+            self.set_collection(collection)
+        elif collection is not None:
+            self.collection_id = collection
+        for key, asset in (assets or {}).items():
+            self.add_asset(key, asset)
+        if href is not None:
+            self.set_self_href(href)
+
+    def _set_temporal_properties(
+        self,
+        instant: Datetime | None,
+        start: Datetime | None,
+        end: Datetime | None,
+    ) -> None:
+        """Apply explicit STAC dates, retaining dates already in properties."""
+        self.datetime = instant
+        if instant is not None:
+            self.properties["datetime"] = datetime_to_str(instant)
+        elif self.properties.get("datetime") is not None:
+            self.datetime = str_to_datetime(self.properties["datetime"])
+        for field_name, value in (("start_datetime", start), ("end_datetime", end)):
+            if value is not None:
+                self.properties[field_name] = datetime_to_str(value)
+
+    @property
+    def record_id(self) -> str | int:
+        return self._record_id if str(self._record_id) == self.id else self.id
+
+    @property
+    def record_metadata(self) -> RecordCommonProperties:
+        return RecordCommonProperties(self)
+
+    @property
+    def time(self) -> dict[str, Any] | None:
+        return self.extra_fields.get("time")
+
+    @time.setter
+    def time(self, value: dict[str, Any] | None) -> None:
+        self.extra_fields["time"] = value
+
+    @property
+    def conforms_to(self) -> list[str]:
+        """The live list of conformance URIs.
+
+        Raises:
+            TypeError: If the stored value is not a list of strings.
+        """
+        conformance = self.extra_fields.setdefault("conformsTo", [])
+        if not isinstance(conformance, list) or not all(
+            isinstance(uri, str) for uri in conformance
+        ):
+            raise TypeError("conformsTo must be a list of strings")
+        return conformance
+
+    @conforms_to.setter
+    def conforms_to(self, value: list[str]) -> None:
+        self.extra_fields["conformsTo"] = value
+
+    @property
+    def link_templates(self) -> list[dict[str, Any]]:
+        """The live list of link template dictionaries.
+
+        Raises:
+            TypeError: If the stored value is not a list of dictionaries.
+        """
+        templates = self.extra_fields.setdefault("linkTemplates", [])
+        if not isinstance(templates, list) or not all(
+            isinstance(template, dict) for template in templates
+        ):
+            raise TypeError("linkTemplates must be a list of dictionaries")
+        return templates
+
+    @link_templates.setter
+    def link_templates(self, value: list[dict[str, Any]]) -> None:
+        self.extra_fields["linkTemplates"] = value
+
+    def to_dict(
+        self, include_self_link: bool = True, transform_hrefs: bool = True
+    ) -> dict[str, Any]:
+        props = deepcopy(self.properties)
+        if self.datetime is not None:
+            props["datetime"] = datetime_to_str(self.datetime)
+        doc = deepcopy(self.extra_fields)
+        doc.update(
+            type="Feature",
+            id=self.record_id,
+            geometry=deepcopy(self.geometry),
+            properties=None if self._null_properties and not props else props,
+            links=[
+                link.to_dict(transform_href=transform_hrefs)
+                for link in self.links
+                if include_self_link or link.rel != pystac.RelType.SELF
+            ],
+        )
+        if self.bbox is not None:
+            doc["bbox"] = list(self.bbox)
+        # Preserve extension declarations/assets as GeoJSON foreign members.
+        # Never substitute conformsTo for stac_extensions.
+        if self.stac_extensions:
+            doc["stac_extensions"] = list(self.stac_extensions)
+        if self.assets:
+            doc["assets"] = {key: deepcopy(asset.to_dict()) for key, asset in self.assets.items()}
+        if self.collection_id is not None:
+            doc["collection"] = self.collection_id
+        return doc
+
+    def to_record_dict(
+        self, include_self_link: bool = True, transform_hrefs: bool = True
+    ) -> dict[str, Any]:
+        return self.to_dict(include_self_link, transform_hrefs)
+
+    @classmethod
+    def matches_object_type(cls, d: dict[str, Any]) -> bool:
+        # Structural recognition only; GeoJSON/STAC overlap prevents unique dispatch.
+        return (
+            d.get("type") == "Feature"
+            and all(key in d for key in ("id", "geometry", "properties"))
+            and isinstance(d["id"], (str, int))
+            and not isinstance(d["id"], bool)
+            and (d["properties"] is None or isinstance(d["properties"], dict))
+        )
+
+    @classmethod
+    def from_dict(
+        cls,
+        d: dict[str, Any],
+        href: str | None = None,
+        root: pystac.Catalog | None = None,
+        migrate: bool = True,
+        preserve_dict: bool = True,
+    ) -> OGCRecord:
+        """Read Records; migrate is accepted for compatibility but never applied.
+
+        Always copies document metadata, even when preserve_dict=False.
+        """
+        if not cls.matches_object_type(d):
+            raise ValueError("Expected a Record GeoJSON Feature with id, geometry, properties")
+        obj = cls(
+            id=d["id"],
+            geometry=d["geometry"],
+            properties=d["properties"],
+            bbox=d.get("bbox"),
+            collection=d.get("collection"),
+            stac_extensions=d.get("stac_extensions"),
+            extra_fields={k: v for k, v in d.items() if k not in cls._RESERVED},
+            assets={k: pystac.Asset.from_dict(deepcopy(v)) for k, v in d.get("assets", {}).items()},
+        )
+        for link in d.get("links", []):
+            if href is None or link.get("rel") != "self":
+                obj.add_link(pystac.Link.from_dict(deepcopy(link)))
+        if href is not None:
+            obj.set_self_href(href)
+        if root is not None:
+            obj.set_root(root)
+        return obj
+
+    def clone(self) -> OGCRecord:
+        doc = self.to_dict(transform_hrefs=False)
+        doc["links"] = []
+        result = type(self).from_dict(doc)
+        for link in self.links:
+            result.add_link(link.clone())
+        result._stac_io = self._stac_io
+        return result
+
+    def to_stac_item(self) -> pystac.Item:
+        """Explicit export; requires a genuine STAC temporal extent.
+
+        Constructing an Item does not replace full STAC schema validation.
+        """
+        if self.datetime is None and not all(
+            self.properties.get(k) is not None for k in ("start_datetime", "end_datetime")
+        ):
+            raise ValueError("STAC export requires datetime or start_datetime/end_datetime")
+        extra = deepcopy(self.extra_fields)
+        extra.pop("stac_version", None)
+        item = pystac.Item(
+            id=self.id,
+            geometry=deepcopy(self.geometry),
+            bbox=deepcopy(self.bbox),
+            datetime=self.datetime,
+            properties=deepcopy(self.properties),
+            stac_extensions=list(self.stac_extensions),
+            collection=self.collection_id,
+            extra_fields=extra,
+            assets={k: v.clone() for k, v in self.assets.items()},
+        )
+        for link in self.links:
+            item.add_link(link.clone())
+        return item
+
+    def validate(self, validator: Any = None) -> list[Any]:
+        """Validate the OGC document with an explicitly supplied validator.
+
+        Supply an object exposing validate(document), configured for the OGC
+        OpenAPI 3.0 schema and its references. No implicit STAC validation.
+        """
+        if validator is None:
+            raise ValueError(
+                "Supply an OGC schema validator; for STAC use record.to_stac_item().validate()"
+            )
+        validator.validate(self.to_dict(transform_hrefs=False))
+        return [self.SCHEMA_URI]
+
+    def __repr__(self) -> str:
+        return f"<OGCRecord id={self.record_id!r}>"

pystac/extensions/osc.py

@@ -0,0 +1,264 @@
+# Copyright 2026 Terradue
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Implements the :stac-ext:`Open Science Catalog Extension <osc>`."""
+
+from __future__ import annotations
+
+from typing import Any, ClassVar, Generic, Literal, TypeVar, cast
+
+from pystac.extensions.base import ExtensionManagementMixin, PropertiesExtension
+from pystac.extensions.hooks import ExtensionHooks
+from pystac.utils import StringEnum
+
+import pystac
+
+#: Generalized version of :class:`~pystac.Catalog`, :class:`~pystac.Collection`,
+#: or :class:`~pystac.Item`
+T = TypeVar("T", pystac.Catalog, pystac.Collection, pystac.Item)
+
+SCHEMA_URI: str = "https://stac-extensions.github.io/osc/v1.0.0/schema.json"
+PREFIX: str = "osc:"
+
+TYPE_PROP: str = PREFIX + "type"
+STATUS_PROP: str = PREFIX + "status"
+WORKFLOWS_PROP: str = PREFIX + "workflows"
+PROJECT_PROP: str = PREFIX + "project"
+REGION_PROP: str = PREFIX + "region"
+VARIABLES_PROP: str = PREFIX + "variables"
+MISSIONS_PROP: str = PREFIX + "missions"
+EXPERIMENT_PROP: str = PREFIX + "experiment"
+
+
+class OscType(StringEnum):
+    """The supported Open Science Catalog resource types."""
+
+    PROJECT = "project"
+    PRODUCT = "product"
+
+
+class OscStatus(StringEnum):
+    """The supported lifecycle states for OSC projects and products."""
+
+    PLANNED = "planned"
+    ONGOING = "ongoing"
+    COMPLETED = "completed"
+
+
+class OscExtension(
+    Generic[T],
+    PropertiesExtension,
+    ExtensionManagementMixin[pystac.Catalog | pystac.Collection | pystac.Item],
+):
+    """The Open Science Catalog Extension for Catalogs, Collections, and Items."""
+
+    name: Literal["osc"] = "osc"
+
+    def apply_project(
+        self,
+        *,
+        status: OscStatus,
+        workflows: list[str] | None = None,
+    ) -> None:
+        """Apply the OSC project fields and remove product-only fields."""
+        self.osc_type = OscType.PROJECT
+        self.status = status
+        self.workflows = workflows
+
+        self.project = None
+        self.region = None
+        self.variables = None
+        self.missions = None
+        self.experiment = None
+
+    def apply_product(
+        self,
+        *,
+        status: OscStatus,
+        project: str,
+        region: str | None = None,
+        variables: list[str] | None = None,
+        missions: list[str] | None = None,
+        experiment: str | None = None,
+    ) -> None:
+        """Apply the OSC product fields and remove project-only fields."""
+        self.osc_type = OscType.PRODUCT
+        self.status = status
+        self.project = project
+        self.region = region
+        self.variables = variables
+        self.missions = missions
+        self.experiment = experiment
+
+        self.workflows = None
+
+    @property
+    def osc_type(self) -> OscType | None:
+        """The OSC resource type."""
+        value = self._get_property(TYPE_PROP, str)
+        return OscType(value) if value is not None else None
+
+    @osc_type.setter
+    def osc_type(self, value: OscType | None) -> None:
+        self._set_property(TYPE_PROP, value.value if value is not None else None)
+
+    @property
+    def status(self) -> OscStatus | None:
+        """The OSC lifecycle status."""
+        value = self._get_property(STATUS_PROP, str)
+        return OscStatus(value) if value is not None else None
+
+    @status.setter
+    def status(self, value: OscStatus | None) -> None:
+        self._set_property(STATUS_PROP, value.value if value is not None else None)
+
+    @property
+    def workflows(self) -> list[str] | None:
+        """The workflows created by an OSC project."""
+        return self._get_property(WORKFLOWS_PROP, list[str])
+
+    @workflows.setter
+    def workflows(self, value: list[str] | None) -> None:
+        self._set_property(WORKFLOWS_PROP, value)
+
+    @property
+    def project(self) -> str | None:
+        """The project associated with an OSC product."""
+        return self._get_property(PROJECT_PROP, str)
+
+    @project.setter
+    def project(self, value: str | None) -> None:
+        self._set_property(PROJECT_PROP, value)
+
+    @property
+    def region(self) -> str | None:
+        """The geographic region associated with an OSC product."""
+        return self._get_property(REGION_PROP, str)
+
+    @region.setter
+    def region(self, value: str | None) -> None:
+        self._set_property(REGION_PROP, value)
+
+    @property
+    def variables(self) -> list[str] | None:
+        """The variables observed by an OSC product."""
+        return self._get_property(VARIABLES_PROP, list[str])
+
+    @variables.setter
+    def variables(self, value: list[str] | None) -> None:
+        self._set_property(VARIABLES_PROP, value)
+
+    @property
+    def missions(self) -> list[str] | None:
+        """The missions providing input to an OSC product."""
+        return self._get_property(MISSIONS_PROP, list[str])
+
+    @missions.setter
+    def missions(self, value: list[str] | None) -> None:
+        self._set_property(MISSIONS_PROP, value)
+
+    @property
+    def experiment(self) -> str | None:
+        """The experiment that created an OSC product."""
+        return self._get_property(EXPERIMENT_PROP, str)
+
+    @experiment.setter
+    def experiment(self, value: str | None) -> None:
+        self._set_property(EXPERIMENT_PROP, value)
+
+    @classmethod
+    def get_schema_uri(cls) -> str:
+        """Return the supported OSC extension schema identifier."""
+        return SCHEMA_URI
+
+    @classmethod
+    def ext(cls, obj: T, add_if_missing: bool = False) -> OscExtension[T]:
+        """Wrap a Catalog, Collection, or Item with live OSC accessors.
+
+        Args:
+            obj: Object whose OSC fields will be read or modified.
+            add_if_missing: Add the schema declaration when absent.
+
+        Raises:
+            pystac.ExtensionNotImplemented: If the declaration is missing and
+                adding it was not requested.
+            pystac.ExtensionTypeError: If the object type is unsupported.
+        """
+        if isinstance(obj, pystac.Collection):
+            cls.ensure_has_extension(obj, add_if_missing)
+            return cast("OscExtension[T]", CollectionOscExtension(obj))
+        if isinstance(obj, pystac.Catalog):
+            cls.ensure_has_extension(obj, add_if_missing)
+            return cast("OscExtension[T]", CatalogOscExtension(obj))
+        if isinstance(obj, pystac.Item):
+            cls.ensure_has_extension(obj, add_if_missing)
+            return cast("OscExtension[T]", ItemOscExtension(obj))
+        raise pystac.ExtensionTypeError(cls._ext_error_message(obj))
+
+
+class CatalogOscExtension(OscExtension[pystac.Catalog]):
+    """Expose OSC fields on a PySTAC catalog."""
+
+    catalog: pystac.Catalog
+    properties: dict[str, Any]
+
+    def __init__(self, catalog: pystac.Catalog) -> None:
+        self.catalog = catalog
+        self.properties = catalog.extra_fields
+
+    def __repr__(self) -> str:
+        return f"<CatalogOscExtension Catalog id={self.catalog.id}>"
+
+
+class CollectionOscExtension(OscExtension[pystac.Collection]):
+    """Expose OSC fields on a PySTAC collection."""
+
+    collection: pystac.Collection
+    properties: dict[str, Any]
+
+    def __init__(self, collection: pystac.Collection) -> None:
+        self.collection = collection
+        self.properties = collection.extra_fields
+
+    def __repr__(self) -> str:
+        return f"<CollectionOscExtension Collection id={self.collection.id}>"
+
+
+class ItemOscExtension(OscExtension[pystac.Item]):
+    """Expose OSC fields on a PySTAC item."""
+
+    item: pystac.Item
+    properties: dict[str, Any]
+
+    def __init__(self, item: pystac.Item) -> None:
+        self.item = item
+        self.properties = item.properties
+
+    def __repr__(self) -> str:
+        return f"<ItemOscExtension Item id={self.item.id}>"
+
+
+class OscExtensionHooks(ExtensionHooks):
+    """Describe OSC schema membership for PySTAC migration hooks."""
+
+    schema_uri: str = SCHEMA_URI
+    prev_extension_ids: ClassVar[set[str]] = set()
+    stac_object_types: ClassVar[set[pystac.STACObjectType]] = {
+        pystac.STACObjectType.CATALOG,
+        pystac.STACObjectType.COLLECTION,
+        pystac.STACObjectType.ITEM,
+    }
+
+
+OSC_EXTENSION_HOOKS: ExtensionHooks = OscExtensionHooks()

pystac/extensions/py.typed

@@ -0,0 +1 @@
+

pystac_ext_osc-1.0.0.dist-info/METADATA

@@ -0,0 +1,101 @@
+Metadata-Version: 2.5
+Name: pystac-ext-osc
+Version: 1.0.0
+Summary: STAC Open Science Catalog Extension Specification pystac implementation.
+Project-URL: Documentation, https://terradue.github.io/pystac-ext-osc/
+Project-URL: Issues, https://github.com/Terradue/pystac-ext-osc/issues
+Project-URL: Source, https://github.com/Terradue/pystac-ext-osc
+Project-URL: Changelog, https://github.com/Terradue/pystac-ext-osc/blob/main/CHANGELOG.md
+Author-email: Terradue <info@terradue.com>, Simone Tripodi <simone.tripodi@terradue.com>, Fabrice Brito <fabrice.brito@terradue.com>
+License-Expression: Apache-2.0
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: pystac<2,>=1
+Provides-Extra: test
+Requires-Dist: pytest-cov<8,>=7.1.0; extra == 'test'
+Requires-Dist: pytest<10,>=9.1.1; extra == 'test'
+Description-Content-Type: text/markdown
+
+<!--
+Copyright 2026 Terradue
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+-->
+
+# Open Science Catalog PySTAC extension
+
+[![PyPI - Version](https://img.shields.io/pypi/v/pystac-ext-osc.svg)](https://pypi.org/project/pystac-ext-osc)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pystac-ext-osc.svg)](https://pypi.org/project/pystac-ext-osc)
+[![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/terradue/pystac-ext-osc/package.yaml?branch=develop&event=push&label=build&logo=githubactions)](https://github.com/terradue/pystac-ext-osc/actions/workflows/package.yaml?query=branch%3Adevelop)
+[![Code coverage](https://img.shields.io/codecov/c/github/terradue/pystac-ext-osc/develop?logo=codecov)](https://app.codecov.io/gh/terradue/pystac-ext-osc/tree/develop)
+
+PySTAC implementation of the [Open Science Catalog STAC Extension v1.0.0](https://github.com/stac-extensions/osc), with an [OGC API Records](https://ogcapi.ogc.org/records/) adapter.
+
+Use `OscExtension.ext()` for project/product metadata on Catalogs, Collections, and Items. Use `OGCRecord` for workflow and experiment records. See the [OSC tutorial](docs/tutorials/first-steps.md) and [OGC Record guide](docs/how-to/ogc-records.md) for runnable examples and validation boundaries.
+
+## Project conventions
+
+This project is templated a Hatch-based Python package with:
+
+- Apache-2.0 license
+- Keep a Changelog-compatible `CHANGELOG.md`
+- Diátaxis documentation under `docs/`
+- top-level `mkdocs.yaml`
+- Taskfile integration with `Terradue/taskfile-utils`
+- GitHub Actions CI
+
+## Documentation
+
+Read the [project documentation](https://terradue.github.io/pystac-ext-osc/) for Python examples, the field reference, and API documentation.
+
+To preview it locally:
+
+```bash
+python -m pip install . "mkdocs<2" mkdocs-material "mkdocstrings[python]"
+mkdocs serve
+```
+
+## Contribute
+
+Submit a [Github issue](/issues) if you have comments or suggestions.
+
+### Local quality checks
+
+Install [Hatch](https://hatch.pypa.io/) and [Taskfiles](https://taskfile.dev/docs/guide) then install the Git hook:
+
+```console
+task quality:pre-commit:install
+```
+
+Every commit runs Ruff (including the configured McCabe complexity limit),
+Ruff formatting, strict mypy checks, and the pytest suite.
+
+Run the complete hook explicitly with:
+
+```console
+task quality:pre-commit:run
+```
+
+## License
+
+[![Apache License, Version 2.0](https://img.shields.io/badge/license-Apache%20License%202.0-blue)](https://www.apache.org/licenses/LICENSE-2.0)

pystac_ext_osc-1.0.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+pystac/extensions/__about__.py,sha256=5sXKmeIQeA5m0T6u3gu6sqeF2e2PEKfzY-hAMnTjN_A,664
+pystac/extensions/ogc_record.py,sha256=AJgXsjTWd0A6tJjUY7uzoqhTePbCmC5-RVnehjC76Sw,19132
+pystac/extensions/osc.py,sha256=HcKM79YfFE57Yr6N-DW1CSmGmYLWPHFiTqpZ0u1nhuo,8635
+pystac/extensions/py.typed,sha256=AbpHGcgLb-kRsJGnwFEktk7uzpZOCcBY74-YBdrKVGs,1
+pystac_ext_osc-1.0.0.dist-info/METADATA,sha256=RdD4AJS6pY_-8J6Qz8tvT7ZnoieSq2cZ2eUyPgy0ZmA,4369
+pystac_ext_osc-1.0.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+pystac_ext_osc-1.0.0.dist-info/licenses/LICENSE,sha256=ncoZH9Riydi4edtpNYeB7IymLIEpnL1SQB0fM4A8NHA,11343
+pystac_ext_osc-1.0.0.dist-info/RECORD,,

pystac_ext_osc-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

pystac_ext_osc-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+           of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2026 Terradue
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.