Feature Request: Adopt Python Data Models and C# SDKs
## Status
- [x] Proposed
- [x] Approved
- [ ] Implementing (incl. documenting)
- [ ] Testing
- [ ] Released
## Summary
Adopt three existing OSDU SDK libraries into the community SDK group, alongside the Python client that is already hosted there.
| Library | Version | Current source | Proposed community location |
| --- | --- | --- | --- |
| `osdu-python-client` | — | already hosted | [`osdu/platform/system/sdks/osdu-python-client`](https://community.opengroup.org/osdu/platform/system/sdks/osdu-python-client) |
| `osdu-python-models` | v0.7.1 | [equinor/osdu-python-models](https://github.com/equinor/osdu-python-models) | `osdu/platform/system/sdks/osdu-python-models` |
| `osdu-csharp-client` | v2.2.1 | [equinor/osdu-csharp-client](https://github.com/equinor/osdu-csharp-client) | `osdu/platform/system/sdks/osdu-csharp-client` |
| `osdu-csharp-models` | v1.0.0 | [equinor/osdu-csharp-models](https://github.com/equinor/osdu-csharp-models) | `osdu/platform/system/sdks/osdu-csharp-models` |
The request covers two independent decisions:
- **Decision A** — adopt `osdu-python-models`.
- **Decision B** — adopt `osdu-csharp-client`, with `osdu-csharp-models` as an optional companion package.
All three libraries already exist and follow the architecture and continuous-release approach of `osdu-python-client`. This is a request about community adoption, repository placement, CI/CD integration, release management and long-term maintenance — not about designing a new SDK architecture.
## Context
`osdu-python-client` is already integrated with the community CI/CD process. It is tested across Python versions on every pipeline, its vendored OpenAPI specifications are checked against the upstream services on a schedule, upstream changes result in a merge request, and it publishes to the GitLab registry and PyPI on tag.
The proposal is to apply the same architecture and automation to the additional libraries.
## Proposed changes
### A. `osdu-python-models`
Typed Pydantic v2 models for record `data` payloads, covering 204 entity types across 573 schema versions of the pinned data-definitions snapshot (M27.0).
The package has no dependency on the client; its only runtime dependency is Pydantic. The existing Python build and release templates already cover it, so adopting it requires no new CI/CD infrastructure.
### B. `osdu-csharp-client`
The C# SDK for OSDU services, providing:
- Typed asynchronous clients for 18 OSDU services, generated from the service OpenAPI specifications.
- A hand-written facade responsible for authentication, retries, `data-partition-id` and base URIs.
- MSAL support as a separate package, so non-Azure consumers do not carry it.
The client is deliberately independent of the typed data models: a .NET consumer can use it without installing the models package.
### B (optional). `osdu-csharp-models`
Typed models for the same 204 entity types across 573 schema versions. Each schema version lives in its own namespace, so consumers can support several versions at once.
The models are opt-in. `osdu-csharp-client` does not depend on them, and consumers who do not need typed payloads use the client alone.
## Repository placement
All libraries belong in the existing [`osdu/platform/system/sdks`](https://community.opengroup.org/osdu/platform/system/sdks) group. This gives consumers one place to find every OSDU SDK, and lets the libraries share group-level runners, variables and issue boards alongside the common `ci-cd-pipelines` templates.
One repository per library is sufficient; a monorepo is not required. This follows the precedent set by `osdu-python-client`.
## How the libraries are built
There are two kinds of library, generated from two different upstream sources.
**Clients** are generated from the upstream service OpenAPI specifications:
`Upstream service specification` → `Vendored, checksummed specification` → `Generator run in CI` → `Published package`
**Models** are generated from a pinned snapshot of the OSDU data-definitions JSON Schemas:
`data-definitions release` → `Pinned schema snapshot` → `Generator run in CI` → `Published package`
In both cases generated code is never committed and never hand-edited. It is produced by the pipeline on every build, with the provenance of its inputs recorded. The hand-written surface is limited to the client facades, the generators and the CI/CD configuration.
## Keeping the libraries current
**Clients — specification drift detection.** Each client includes the drift mechanism already running for `osdu-python-client` (`osdu-csharp-client` has an equivalent job today):
1. A scheduled job re-fetches every vendored specification from its publishing service.
2. Each is compared with its recorded checksum. If nothing changed, no action is taken.
3. If a specification changed, a merge request is opened automatically.
4. The merge request contains the updated specifications and provenance manifest; CI regenerates, builds and tests the client against them.
5. The change is reviewed and released under the `Impact::` labelling convention.
**Models — snapshot bumps.** The models track a pinned data-definitions snapshot, which is updated when a new data-definitions release is adopted. A published schema version is never modified — only new versions and new schemas are added — so a snapshot bump is additive by construction. The models repositories do not currently automate detection of new data-definitions releases; that can be added, but it is not a prerequisite for adoption.
## Release model
The SDKs should follow an independent continuous-release model rather than the platform milestone train.
There is established precedent for this:
- [ADR #52](https://community.opengroup.org/osdu/platform/home/-/issues/52) moved the core libraries off milestone versioning to independent semantic versioning, on the grounds that they do not need to follow the milestone cadence.
- `osdu-python-client` already releases this way, using the community's continuous-release template.
The case for SDKs is stronger still: nothing deploys together, and consumers choose which version to take and when to upgrade. SDK releases therefore remain independent of the platform milestone process.
## .NET CI/CD infrastructure
The one new infrastructure requirement is a .NET build and release pipeline. There is currently no .NET template in `ci-cd-pipelines`.
A .NET template will be contributed as part of this proposal, following the conventions of the existing templates — the `standard-setup.yml` stage layout, and the language-agnostic `continuous-release-general.yml` for `Impact::`-label versioning. It will:
- Generate the SDK from its vendored inputs.
- Build and test it.
- Publish packages to the agreed destination.
- Support the continuous-release model.
- Run on the community's runners.
## Maintenance and ownership
Two maintenance models are proposed for community consideration.
### Option 1 — Core Subgroup maintenance
The relevant OSDU Core Subgroup takes responsibility for the SDK repositories, including:
- Reviewing and merging SDK changes.
- Maintaining the SDK CI/CD configuration, including the .NET template.
- Managing releases.
- Reviewing merge requests raised by specification drift detection.
### Option 2 — A dedicated SDK / API Clients subgroup
A dedicated subgroup — for example **OSDU Clients** or **OSDU API Clients**, subject to community agreement — provides a formal home and cross-company governance for client libraries in every language.
It would initially own `osdu-python-client`, `osdu-python-models`, `osdu-csharp-client` and `osdu-csharp-models`, and would be the natural home for further language SDKs. It would be established through the applicable OSDU governance process, with responsibilities documented through the PMC portal, covering at minimum:
- Repository ownership and maintainer assignments.
- Review, merge and release responsibilities.
- CI/CD ownership, including the shared .NET template.
- The process for reviewing merge requests raised by drift detection.
- The process for adding further SDKs.
- An escalation path for inactive or unavailable maintainers.
### Equinor's role
Under either model, Equinor will nominate the initial maintainers and continue maintaining the libraries through the transition, and will provide the documentation and knowledge transfer needed to broaden the maintainer base across member companies over time.
Regardless of the model chosen, generated code is regenerated automatically from its upstream sources, so the ongoing maintenance surface is the facades, generators, CI/CD configuration and release process — not the generated source files.
## OpenAPI conformance benefit
Generating the clients acts as a conformance check on the upstream OSDU OpenAPI specifications. Building them surfaced the following defects, each verified byte-identical against the live upstream specification and filed with the owning service:
| Issue | Defect |
| --- | --- |
| [unit-service#502](https://community.opengroup.org/osdu/platform/system/reference/unit-service/-/issues/502) | 59 parameters with neither `schema` nor `content` — invalid OpenAPI 3.x |
| [storage#442](https://community.opengroup.org/osdu/platform/system/storage/-/issues/442) | Four record-returning operations documented as `type: string` |
| [entitlements#374](https://community.opengroup.org/osdu/platform/security-and-compliance/entitlements/-/issues/374) | A `204 No Content` response declaring a response body |
| [crs-conversion-service#290](https://community.opengroup.org/osdu/platform/system/reference/crs-conversion-service/-/issues/290) | Properties differing only by case, colliding in generated code |
| [wellbore-domain-services#161](https://community.opengroup.org/osdu/platform/domain-data-mgmt-services/wellbore/wellbore-domain-services/-/issues/161) | Examples attached to Schema Objects rather than Media Type Objects |
| [dataset#254](https://community.opengroup.org/osdu/platform/system/dataset/-/issues/254) | Duplicate tag declaration |
Each workaround in the SDKs reports what it changed, so it can be removed once the upstream fix lands.
## Consequences
- The community repositories become the source of truth for these libraries; the Equinor repositories would then be archived with a pointer to the new location.
- Release automation moves from GitHub Actions and release-please to the community's GitLab CI and `Impact::` labelling convention.
- The community gains a .NET template in `ci-cd-pipelines` and a NuGet publishing destination, both of which need an owner.
- If package identifiers change on adoption (see open questions), existing consumers face a one-time breaking change.
- SDK releases are decoupled from milestone releases, so SDK versions do not map to platform milestones.
## Acceptance criteria
### Python models
- `osdu-python-models` is hosted under `osdu/platform/system/sdks/`.
- It builds and publishes using the existing Python build and release templates.
- It remains independent of `osdu-python-client`.
- The process for bumping the pinned data-definitions snapshot is documented.
### C# client
- `osdu-csharp-client` is hosted under `osdu/platform/system/sdks/`.
- A .NET template is added to `ci-cd-pipelines`, and the client builds and tests on community runners.
- Packages publish to the agreed NuGet destination under the continuous-release model.
- Specification drift detection is enabled.
- The client does not require `osdu-csharp-models`.
### C# models
- `osdu-csharp-models` is hosted under `osdu/platform/system/sdks/` and published as a separate package.
- Schema versions remain available side by side.
- The models remain optional for users of `osdu-csharp-client`.
- The process for bumping the pinned data-definitions snapshot is documented.
### CI/CD and release
- Generated code is produced by the pipeline and not committed.
- Client specifications are checksum- and provenance-tracked, and specification changes automatically open a merge request.
- SDK releases are independent of platform milestone releases.
- Publication targets are agreed for PyPI, NuGet and the GitLab registry as applicable.
### Maintenance
- A maintenance model is agreed: Core Subgroup ownership, or a dedicated SDK / API Clients subgroup.
- If a dedicated subgroup is chosen, it is established through the applicable governance process and its responsibilities are documented through the PMC portal.
- Named maintainers are assigned for each repository, with a community co-maintainer identified for the C# libraries.
- Responsibilities for CI/CD and release maintenance, including the .NET template, are defined.
- Documentation and knowledge transfer are completed.
## Open questions
1. Should the Core Subgroup take long-term ownership, or should a dedicated SDK / API Clients subgroup be established?
2. Which member company will provide a co-maintainer for the C# libraries?
3. Where should the NuGet packages be published — the GitLab registry, nuget.org under a community identity, or both?
4. The NuGet package identifiers currently carry an `Equinor.` prefix (`Equinor.OsduCsharpClient`, `Equinor.OsduCsharpClient.Msal`, `Equinor.Osdu.Models`). What prefix should they be given upon migration?
5. Which existing `ci-cd-pipelines` conventions should the .NET template follow beyond `standard-setup.yml` and `continuous-release-general.yml`?
6. What repository permissions and ownership model should the new repositories use?
7. Which community group approves SDK releases and changes to the shared .NET template?
## Requested decision
Two separate, independent decisions:
- **Decision A — Python models.** Adopt `osdu-python-models` into `osdu/platform/system/sdks/`. This is the lower-risk decision: the existing Python CI/CD infrastructure is reused and nothing new is required.
- **Decision B — C# SDK.** Adopt `osdu-csharp-client` and `osdu-csharp-models` into `osdu/platform/system/sdks/`, with the models remaining optional. The required .NET pipeline is contributed as part of the proposal.
Decision A should not be blocked by the .NET infrastructure or C# maintenance questions in Decision B.
The overall goal is to extend the OSDU SDK catalogue using the architecture, automation and continuous-release principles already demonstrated by `osdu-python-client`.
issue