osdu-python-models 0.5.0__py3-none-any.whl

osdu_models/workproductcomponent/wellbore_trajectory/v1_4_0.py

@@ -0,0 +1,427 @@
+# generated by datamodel-codegen:
+#   filename:  workproductcomponent/wellbore_trajectory/v1_4_0.json
+
+from __future__ import annotations
+from pydantic import BaseModel, ConfigDict, Field, constr
+from typing import Any
+from ...abstract.abstract_facility_vertical_measurement import v1_0_0
+from ...abstract.abstract_common_resources.v1_0_0 import OsduCommonResources
+from ...abstract.abstract_wpcgroup_type.v1_2_0 import AbstractWPCGroupType
+from ...abstract.abstract_work_product_component.v1_1_0 import (
+    AbstractWorkProductComponent,
+)
+
+
+class AvailableTrajectoryStationProperty(BaseModel):
+    """
+    A set of properties describing a trajectory station property which is available for this instance of a WellboreTrajectory.
+    """
+
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    TrajectoryStationPropertyTypeID: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-TrajectoryStationPropertyType:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=[
+            'partition-id:reference-data--TrajectoryStationPropertyType:AzimuthTN:'
+        ],
+        title='Trajectory Station Property Type ID',
+    )
+    """
+    The reference to a trajectory station property type - or if interpreted as channels, the curve or channel name type, identifying e.g. MD, Inclination, Azimuth. This is a relationship to a reference-data--TrajectoryStationPropertyType record id.
+    """
+    StationPropertyUnitID: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-UnitOfMeasure:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=['partition-id:reference-data--UnitOfMeasure:dega:'],
+        title='Station Property Unit ID',
+    )
+    """
+    Unit of Measure for the station properties of type TrajectoryStationPropertyType.
+    """
+    Name: str | None = Field(None, examples=['AzimuthTN'], title='Name')
+    """
+    The name of the curve (e.g. column in a CSV document) as originally found. If absent The name of the TrajectoryStationPropertyType is intended to be used.
+    """
+
+
+class Data(OsduCommonResources, AbstractWPCGroupType, AbstractWorkProductComponent):
+    """
+    `data` payload for WellboreTrajectory 1.4.0.
+    """
+
+    model_config = ConfigDict(
+        extra='allow',
+    )
+    ServiceCompanyID: (
+        constr(pattern=r'^[\w\-\.]+:master-data\-\-Organisation:[\w\-\.\:\%]+:[0-9]*$')
+        | None
+    ) = Field(
+        None,
+        examples=['namespace:master-data--Organisation:SLB:'],
+        title='Service Company',
+    )
+    """
+    Name of the Survey Company.
+    """
+    WellboreID: constr(
+        pattern=r'^[\w\-\.]+:master-data\-\-Wellbore:[\w\-\.\:\%]+:[0-9]*$'
+    ) = Field(
+        ...,
+        examples=['namespace:master-data--Wellbore:11000091175501:'],
+        title='Wellbore',
+    )
+    """
+    A unique name, code or number designated to the Wellbore.
+    """
+    TopDepthMeasuredDepth: float = Field(
+        ..., examples=['0 m'], title='Survey Top Measured Depth'
+    )
+    """
+    Measured depth in the wellbore where the directional survey starts. This should equal the minimum station measured depth for this directional survey, regardless of whether the surveyed station represents an actual surveyed MD or not.
+    """
+    AzimuthReferenceType: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-AzimuthReferenceType:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=['namespace:reference-data--AzimuthReferenceType:Grid:'],
+        title='Azimuth Reference Type',
+    )
+    """
+    The North reference of the trajectory used to define the azimuth angular measurement values. For example, True North, Grid North, Magnetic North.
+    """
+    CalculationMethodType: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-CalculationMethodType:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=['namespace:reference-data--CalculationMethodType:MinumumCurvature:'],
+        title='Calculation Method Type',
+    )
+    """
+    Calculation Method used to calculate the Wellpath Trajectory from the directional survey data including TVD, X OFFSET, Y OFFSET and DOG LEG SEVERITY. Examples include Minimum Curvature, Radius of Curvature, Balanced Tangential, etc.
+    """
+    ProjectedCRSID: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-CoordinateReferenceSystem:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=[
+            'namespace:reference-data--CoordinateReferenceSystem:Projected:EPSG::32615:'
+        ],
+        title='Projected Coordinate Reference System ID',
+    )
+    """
+    Coordinate Reference System defining the Projection of the station EASTING and NORTHING values. If  type is "Grid North" and EASTING and NORTHING attributes are stored, clearly identifying their projection is required.
+    """
+    ActiveIndicator: bool | None = Field(
+        None, examples=[False], title='Active Survey Indicator'
+    )
+    """
+    A flag indicating if the survey is currently active or valid within his lifecycle stage, not necessarily the definitive survey.
+    """
+    SurveyType: str | None = Field(
+        None, examples=['Full Survey'], title='Directional Survey Type'
+    )
+    """
+    The type of this directional survey.  For example a "Directional Survey" where MD, Inclination and Azimuth are all measured or a "Position Log" where Inclination and Azimuth are both null and only MD, TVD and X/Y Offsets are available) - or "Full Survey" where everything is fully filled-up, depth-inclination-azimuth.
+    """
+    AcquisitionDate: str | None = Field(
+        None, examples=['2023-03-05T00:00:00+0000'], title='Effective Date'
+    )
+    """
+    The date that the survey data was acquired on the field.
+    """
+    GeographicCRSID: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-CoordinateReferenceSystem:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=[
+            'namespace:reference-data--CoordinateReferenceSystem:Geographic2D:EPSG::4326:'
+        ],
+        title='Geographic Coordinate Reference System',
+    )
+    """
+    Coordinate Reference System defining the Geodetic Datum of the station LATITUDE and LONGITUDE values. If LATITUDE and LONGITUDE attributes are stored, clearly identifying their Datum is required.
+    """
+    AcquisitionRemark: str | None = Field(
+        None, examples=['Vendor final survey'], title='Survey Remark'
+    )
+    """
+    Remarks related to acquisition context which is not the same as Description which is a summary of the work-product-component.
+    """
+    SurveyReferenceIdentifier: str | None = Field(
+        None, examples=['SLB-DS150'], title='Survey Reference Identifier'
+    )
+    """
+    Unique or Distinctive Survey Reference Number, Job Number, File Number, Identifier, Label, Name, etc. as indicated on a directional survey report, file, etc.  Use this attribute to allow correlation of the data in this Directional Survey back to the original source document, file, etc.
+    """
+    SurveyToolTypeID: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-SurveyToolType:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=['namespace:reference-data--SurveyToolType:Magnetic:'],
+        title='Type of the Survey Tool',
+    )
+    """
+    The type of tool or equipment used to acquire this Directional Survey.  For example, gyroscopic, magnetic, MWD, TOTCO, acid bottle, etc. Follow OWSG reference data and support the ISCWSA survey tool definitions.
+    """
+    SurveyVersion: str | None = Field(None, examples=['1'], title='Survey Version')
+    """
+    The version of the wellbore survey deliverable received from the service provider - as given by this provider
+    """
+    ExtrapolatedMeasuredDepth: float | None = Field(
+        None, examples=['2790 m'], title='Extrapolated Measured Depth'
+    )
+    """
+    The measured depth to which the survey segment was extrapolated.
+    """
+    ExtrapolatedMeasuredDepthRemark: str | None = Field(
+        None,
+        examples=['TD@2790m bDFE@32.5m'],
+        title='Extrapolated Measured Depth Remark',
+    )
+    """
+    Comment/Annotation made to WellboreTrajectory describing the projected MD Base or Bottomhole, e.g., listing the Depth Reference Name, Elevation and Bottomhole MD. This can be used for comparison against the survey at a later date.
+    """
+    BaseDepthMeasuredDepth: float = Field(
+        ..., examples=['2790 m'], title='Survey Base Measured Depth'
+    )
+    """
+    Measured depth within the wellbore of the LAST surveyed station with recorded data.  If a stored survey has been extrapolated to a deeper depth than the last surveyed station then that is the extrapolated measured depth and not the survey base depth.
+    """
+    TieMeasuredDepth: float | None = Field(
+        None, examples=['0 m'], title='Tie Measured Depth'
+    )
+    """
+    Tie-point depth measured along the wellbore from the measurement reference datum to the survey station - where tie point is the place on the originating survey where the current survey intersect it.
+    """
+    TieTrueVerticalDepth: float | None = Field(
+        None, examples=['0 m'], title='Tie True Vertical Depth'
+    )
+    """
+    True Vertical Depth of the TieMeasuredDepth
+    """
+    VerticalMeasurement: v1_0_0.AbstractFacilityVerticalMeasurement = Field(
+        ...,
+        examples=[
+            {
+                'VerticalReferenceEntityID': 'namespace:master-data--Wellbore:11000091175501:',
+                'VerticalReferenceID': 'DFE',
+            }
+        ],
+        title='Vertical Measurement',
+    )
+    """
+    References an entry in the Vertical Measurement array for the Wellbore identified by WellboreID, which defines the vertical reference datum for all survey station measured depths.
+    """
+    AvailableTrajectoryStationProperties: (
+        list[AvailableTrajectoryStationProperty] | None
+    ) = Field(None, title='Available Trajectory Station Properties')
+    """
+    The array of TrajectoryStationProperty definitions describing the available properties for this instance of WellboreTrajectory.
+    """
+    AppliedOperations: list[str] | None = Field(
+        None, examples=[['SSP QA/QC']], title='Applied Operations'
+    )
+    """
+    The audit trail of operations applied to the station coordinates from the original state to the current state. The list may contain operations applied prior to ingestion as well as the operations applied to produce the Wgs84Coordinates. The text elements refer to ESRI style CRS and Transformation names, which may have to be translated to EPSG standard names.
+    """
+    AppliedOperationsDateTime: str | None = Field(
+        None,
+        examples=['2023-03-15T00:00:00+0000'],
+        title='Applied Operations Date Time',
+    )
+    """
+    Date/time when the directional Survey QA/QC was performed.
+    """
+    AppliedOperationsUser: str | None = Field(
+        None, examples=['Joe Bloggs'], title='Applied Operations User'
+    )
+    """
+    Name of Borehole Survey specialist who performed the QA/QC work
+    """
+    AppliedOperationsRemarks: str | None = Field(
+        None,
+        examples=[
+            'Final survey SSP corrected. Mag corrections within tolerance. Meets QA/QC criteria.'
+        ],
+        title='Applied Operations Remarks',
+    )
+    """
+    Any comments captured by the Borehole Survey specialist when performing the QA/QC work.
+    """
+    StartDateTime: str | None = Field(
+        None, examples=['2023-01-15T00:00:00+0000'], title='Start DateTime'
+    )
+    """
+    The date and time capturing when the first survey station was measured.
+    """
+    EndDateTime: str | None = Field(
+        None, examples=['2023-02-27T00:00:00+0000'], title='End DateTime'
+    )
+    """
+    The date and time capturing when the last survey station was measured.
+    """
+    CompanyID: (
+        constr(pattern=r'^[\w\-\.]+:master-data\-\-Organisation:[\w\-\.\:\%]+:[0-9]*$')
+        | None
+    ) = Field(
+        None,
+        examples=['namespace:master-data--Organisation:PECTEN:'],
+        title='Company ID',
+    )
+    """
+    The relationship to company who engaged the service company (ServiceCompanyID) to perform the surveying.
+    """
+    SurfaceGridConvergence: float | None = Field(
+        None, examples=[0.0057596], title='Grid Convergence at Surface'
+    )
+    """
+    The Grid Convergence angle computed at the surface position, which was used for the WellboreTrajectory True North to Grid North Azimuths corrections. Only populated for projected CRSs. Recommended sign convention: Gauss-Bomford.
+    """
+    SurfaceScaleFactor: float | None = Field(
+        None, examples=[1.003], title='Scale Factor at Surface'
+    )
+    """
+    The Scale Factor computed for the wellbore's surface position used for calculating projected Map Coordinates from survey data in WellboreTrajectory.
+    """
+    Tortuosity: float | None = Field(None, examples=[0.00019], title='Tortuosity')
+    """
+    The calculated average Tortuosity for the WellboreTrajectory.
+    """
+    VerticalSectionAzimuth: float | None = Field(
+        None, examples=['45 dega'], title='Vertical Section Azimuth'
+    )
+    """
+    Azimuth angle used for vertical section projection/computations of the survey stations.
+    """
+    GeoMagneticModelID: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-GeoMagneticModel:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=['namespace:reference-data--GeoMagneticModel:BGGM2023:'],
+        title='Geomagnetic Model ID',
+    )
+    """
+    Geomagnetic Model Name including the applicable year used to calculate Geomagnetic field for a given date, coordinate and measured depth (when calculated down the wellbore).
+    """
+    MagneticFieldCalculationDate: str | None = Field(
+        None,
+        examples=['2023-01-01T00:00:00+0000'],
+        title='MagneticFieldCalculationDate',
+    )
+    """
+    Date against Geomagnetic field calculated
+    """
+    MagneticDeclinationUsed: float | None = Field(
+        None, examples=['1.76 dega'], title='Magnetic Declination Used'
+    )
+    """
+    Calculated magnetic declination used to correct a Magnetic North referenced azimuth to a True North azimuth. Magnetic declination angles are measured positive clockwise from True North to Magnetic North (or negative in the anti-clockwise direction). To convert a Magnetic azimuth to a True North azimuth, the magnetic declination should be added. Starting value if stations have individual values.
+    """
+    MagneticDeclinationUncertainty: float | None = Field(
+        None, examples=['0.10 dega'], title='Magnetic Declination Uncertainty'
+    )
+    """
+    Survey tool declination uncertainty.
+    """
+    MagneticDipAngleReference: float | None = Field(
+        None, examples=['57.01 dega'], title='Magnetic Dip Angle Reference'
+    )
+    """
+    Calculated magnetic dip angle theoretical / reference value.
+    """
+    MagneticDipAngleUncertainty: float | None = Field(
+        None, examples=['0.5 dega'], title='Magnetic Dip Angle Uncertainty'
+    )
+    """
+    Survey tool dip angle uncertainty.
+    """
+    TotalMagneticFieldStrength: float | None = Field(
+        None, examples=['45165 nT'], title='Total Magnetic Field Strength'
+    )
+    """
+    Calculated geomagnetic field theoretical/reference value.
+    """
+    TotalMagneticFieldStrengthUncertainty: float | None = Field(
+        None, examples=['250 nT'], title='Total Magnetic Field Strength Uncertainty'
+    )
+    """
+    Survey tool magnetic uncertainty.
+    """
+    GravityModelID: (
+        constr(
+            pattern=r'^[\w\-\.]+:reference-data\-\-GravityModel:[\w\-\.\:\%]+:[0-9]*$'
+        )
+        | None
+    ) = Field(
+        None,
+        examples=['namespace:reference-data--GravityModel:GARM:'],
+        title='Gravity Model ID',
+    )
+    """
+    Identifier of the Gravity Model in use for the survey.
+    """
+    TotalGravityFieldStrength: float | None = Field(
+        None, examples=['980.665 Gal'], title='Total Gravity Field Strength'
+    )
+    """
+    Calculated total gravity field.
+    """
+    TotalGravityFieldStrengthUncertainty: float | None = Field(
+        None, examples=['5 Gal'], title='Total Gravity Field Strength Uncertainty'
+    )
+    """
+    Survey tool gravity uncertainty.
+    """
+    VerticalSectionOriginNS: float | None = Field(
+        None, examples=['0 m'], title='Vertical Section Origin N/-S'
+    )
+    """
+    Vertical Section Origin North / -South relative to the Well SHL Projected CRS 0, 0 origin. 0 where Vertical Section Projection originates from the wellhead.
+    """
+    VerticalSectionOriginEW: float | None = Field(
+        None, examples=['0 m'], title='Vertical Section Origin E/-W'
+    )
+    """
+    Vertical Section Origin East / -West relative to the Well SHL Projected CRS 0, 0 origin. 0 where Vertical Section Projection originates from the wellhead.
+    """
+    IsDefinitive: bool | None = Field(None, examples=[True], title='Definitive')
+    """
+    True indicates that this trajectory is definitive for this wellbore as provided by the survey contractor. False or not given indicates otherwise. There can only be one trajectory per wellbore with definitive=true and it must define the geometry of the whole wellbore (surface to TD). The definitive trajectory may represent a composite of survey data from one or more other trajectories.
+    """
+    IsMemory: bool | None = Field(None, examples=[False], title='Memory')
+    """
+    Is trajectory a result of a memory dump from a tool?
+    """
+    IsFinal: bool | None = Field(None, examples=[True], title='Final')
+    """
+    From the survey contractors perspective providing the survey to the Operator is the trajectory final (true) or intermediate/preliminary (false)? Does not mean that the trajectory cannot be worked on further by the Operator.
+    """
+    ExtensionProperties: dict[str, Any] | None = None

osdu_python_models-0.5.0.dist-info/METADATA

@@ -0,0 +1,182 @@
+Metadata-Version: 2.4
+Name: osdu-python-models
+Version: 0.5.0
+Summary: Typed Pydantic models for OSDU data payloads — opt-in companion to osdu-python-client
+Author: Equinor
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://github.com/equinor/osdu-python-models
+Project-URL: Repository, https://github.com/equinor/osdu-python-models
+Project-URL: Issues, https://github.com/equinor/osdu-python-models/issues
+Keywords: osdu,pydantic,schemas,models,wellbore,ddms
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+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: Topic :: Software Development :: Libraries
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pydantic>=2.9
+Provides-Extra: dev
+Requires-Dist: datamodel-code-generator>=0.26; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# osdu-python-models
+
+Typed **Pydantic v2** models for OSDU `data` payloads — an opt-in companion to
+[`osdu-python-client`](https://community.opengroup.org/osdu/platform/system/sdks/osdu-python-client),
+mirroring the C# [`osdu-csharp-schemas`](https://github.com/equinor/osdu-csharp-schemas)
+library.
+
+> **Scope.** Covers **all `work-product-component`,
+> `master-data` and `dataset` entity types** in the pinned OSDU snapshot — **194
+> entity types across 551 schema versions** (93 work-product-component + 73
+> master-data + 28 dataset), plus **128 shared `abstract` modules** pulled in on
+> demand. The generator is data-driven: the scope is the `SCOPE_GROUPS` list in
+> `tools/generate.py`, and every type and version is discovered from the snapshot
+> automatically, so a snapshot bump or adding a group needs no other code change.
+> `abstract` schemas are not listed explicitly — only those reachable from a
+> selected entity's `$ref` closure are generated.
+
+## Why
+
+`osdu-python-client` leaves the record `data` block free-form (a `dict`), matching
+the canonical `os-core-common` `Map<String, Object>` — the right call, because OSDU
+`data` is schema-on-read and versioned by `kind`. But consumers building ingestion
+or validation logic for a **specific kind + version** still want types: autocomplete,
+runtime validation, and self-documenting payloads. This package provides exactly
+that, without touching the client.
+
+```python
+from osdu_models.workproductcomponent.well_log.v1_5_0 import Data, Curve
+
+# Typed authoring — autocomplete + validation
+data = Data(
+    WellboreID="namespace:master-data--Wellbore:abc:",
+    TopMeasuredDepth=1234.5,
+    Curves=[Curve(Mnemonic="GR")],
+)
+
+# Bridge into the client's free-form `data` — just model_dump(), no client changes
+record = {"kind": "osdu:wks:work-product-component--WellLog:1.5.0",
+          "acl": ..., "legal": ...,
+          "data": data.model_dump(by_alias=True, exclude_none=True)}
+```
+
+Reading is the mirror image: `Data.model_validate(record["data"])`.
+
+## Install
+
+```sh
+pip install osdu-python-models
+```
+
+or with [uv](https://docs.astral.sh/uv/):
+
+```sh
+uv add osdu-python-models
+```
+
+Models are shipped pre-generated in the published distributions — no codegen step
+needed to consume them. To build from source instead, see
+[Build & test](https://github.com/equinor/osdu-python-models#build--test).
+
+> Each tagged version is also attached to its
+> [GitHub Release](https://github.com/equinor/osdu-python-models/releases) as
+> `.whl` / `.tar.gz` assets.
+
+## Design
+
+- **Types only the `data` block.** The client owns the envelope (id/kind/acl/legal);
+  this package owns `data`. The two compose via `model_dump()` / `model_validate()`.
+- **Side-by-side versions.** Each published version is its own module
+  (`well_log/v1_4_0.py`, `v1_5_0.py`) — no "latest wins", explicit per-`kind`.
+- **Shared abstract modules.** OSDU `abstract/*` building blocks are generated
+  **once** under `osdu_models/abstract/<type>/v<ver>.py`; each entity model
+  imports them rather than inlining a private copy. This removes the ~96 % class
+  duplication of a per-entity bundling approach (551 models: ~65,000 → 2,071 class
+  defs) and is what makes scaling to the full schema set viable. Same idea as
+  the C# library's `ExternalReferenceCode` abstract sharing.
+- **String-only constraints stripped off non-string nodes.** A few OSDU schemas
+  attach `pattern`/`format` to `array`/`integer` fields (e.g.
+  `AbstractColumnBasedTable.IntegerColumn`); the generator drops them so Pydantic
+  v2 doesn't reject otherwise-valid payloads.
+- **`extra='allow'` everywhere.** Unknown / forward-compatible fields round-trip
+  untouched (the Pydantic equivalent of C#'s `[JsonExtensionData]`).
+- **String `format` dropped → plain `str`.** This library types `data` for
+  *lossless* round-tripping, not semantic validation. Honouring `format` would
+  make codegen emit validating/normalising types that defeat that or pull
+  optional deps: `date`/`date-time`/`time` (OSDU payloads carry non-conformant
+  variants a strict parser rejects), `email` (`EmailStr`, needs `email-validator`),
+  `uri` (`AnyUrl`, normalises the value). Keeping plain `str` preserves the input.
+  Same pragmatic choice the C# library makes.
+- **Pinned snapshot.** `schemas/2026.05.22/` is a frozen copy of the OSDU
+  `data-definitions` `Generated/` schemas (shared with the C# library). Bumping it
+  is an explicit, reviewable change.
+
+## Layout
+
+```
+osdu-python-models/
+├── schemas/2026.05.22/        # pinned data-definitions snapshot (abstract + entities)
+├── tools/generate.py          # restructures the `data` sub-schemas, runs datamodel-codegen
+├── src/osdu_models/            # generated Pydantic models (gitignored, regenerable)
+│   ├── abstract/<type>/v<ver>.py          # shared abstract building blocks (generated once)
+│   ├── workproductcomponent/<type>/v<ver>.py
+│   ├── masterdata/<type>/v<ver>.py        # → class Data, importing the shared abstracts
+│   └── dataset/<type>/v<ver>.py           # e.g. dataset/file_generic/v1_1_0.py
+├── tests/test_roundtrip.py    # round-trip + typed-access tests vs real OSDU examples (all versions)
+└── samples/author_welllog.py  # end-to-end authoring demo (no network)
+```
+
+## Build & test
+
+```sh
+uv venv && uv pip install -e ".[dev]"
+uv run python tools/generate.py     # generate models from the pinned snapshot
+uv run ruff check tools tests samples  # lint hand-written sources (not generated)
+uv run pytest                       # round-trip tests against OSDU example payloads
+uv run python samples/author_welllog.py
+```
+
+## How it works
+
+OSDU record schemas put the payload under `properties.data` as an `allOf` of
+abstract building blocks (`../abstract/*.json`) plus inline fields. `tools/generate.py`
+uses `datamodel-codegen` **directory mode**, which turns cross-file `$ref`s into
+Python imports:
+
+1. lifts each entity's `data` sub-schema (titled `Data`) and transitively
+   collects the shared `abstract/*` files it references,
+2. lays both out in a temp tree mirroring the output package structure (every
+   file at the same depth, `<pkg>/<snake>/v<ver>.json`), cleaning schema quirks
+   and rewriting every `$ref` to a canonical root-relative path (`../../<pkg>/
+   <snake>/v<ver>.json`) so it resolves identically regardless of which file the
+   resolver treats as the base — sidestepping a `datamodel-codegen` quirk that
+   otherwise resolves a shared schema's nested `$ref`s against the *referencing*
+   entity's directory,
+3. runs `datamodel-codegen` **once** over that tree — emitting each abstract as a
+   shared module and each entity as a `Data` model that imports them.
+
+Generated code is gitignored — regenerable from the pinned snapshot, never
+hand-edited.
+
+## Contributing
+
+Contributions are welcome — see [`CONTRIBUTING.md`](https://github.com/equinor/osdu-python-models/blob/main/CONTRIBUTING.md) for
+development setup, the pull-request process, and commit conventions.
+
+## Security
+
+To report a security vulnerability, follow the process in
+[`SECURITY.md`](https://github.com/equinor/osdu-python-models/blob/main/SECURITY.md). Do not open a public issue.
+
+## License
+
+Licensed under the [Apache License 2.0](https://github.com/equinor/osdu-python-models/blob/main/LICENSE).