Finalize spatial-types 1.0.0

As a maintainer of the LongitudeOne spatial libraries,
I want to establish a stable and standards-compliant spatial-types 1.0.0 baseline,
so that dependent libraries can rely on its public contracts while additional spatial types continue to be delivered incrementally in later minor releases.

Context

spatial-types provides the concrete spatial objects used throughout the LongitudeOne spatial ecosystem.

Releasing version 1.0.0 establishes the first stable public contract of the library. From that point onward, existing public APIs and behaviors must be preserved according to the project's backward-compatibility and semantic-versioning policy.

The objective of 1.0.0 is therefore not to implement every instantiable geometry type defined by spatial-core.

Instead, 1.0.0 must provide:

• a deliberately reviewed and stable public API;
• standards-compliant behavior for every geometry reported as fully implemented;
• the geometry types required by the current EWKT decoding scope;
• dependency constraints suitable for use by consuming libraries and applications;
• automated validation of the supported dependency combinations;
• sufficient integration guarantees for downstream LongitudeOne libraries.

The remaining EWKT work in spatial-decoder, including the work related to Story #14, requires concrete support for:

• CIRCULARSTRING;
• COMPOUNDCURVE.

These geometry types are therefore part of the 1.0.0 release boundary.

Other geometry types defined by spatial-core are not 1.0.0 blockers unless they are required by an existing public contract or by the targeted EWKT decoding scope. They may be implemented incrementally in subsequent backward-compatible minor releases such as 1.1.0, 1.2.0 and later.

Architectural Boundary

                    spatial-core
                         |
                         | defines the spatial model
                         v
              +----------------------+
              | spatial-types 1.0.0  |
              |                      |
              | Stable public API    |
              | Normative contracts  |
              | Supported types      |
              | CIRCULARSTRING       |
              | COMPOUNDCURVE        |
              +----------+-----------+
                         |
                         | provides concrete
                         | spatial objects
                         v
                 spatial-decoder
                         |
                         v
                    EWKT support

       Other spatial types are NOT a 1.0.0 blocker.
                         |
                         v
               spatial-types 1.x

spatial-core defines the spatial model and the geometry types known by the LongitudeOne ecosystem.

spatial-types implements concrete representations of selected instantiable geometry types.

spatial-decoder consumes those concrete representations when decoding external spatial formats.

The completion of EWKT decoding therefore defines part of the minimum functional boundary of spatial-types 1.0.0 without requiring every geometry type known by spatial-core to be implemented.

Scope

Dependency compatibility

The Symfony Validator dependency must no longer unnecessarily restrict consumers to a single Symfony generation.

The supported Validator versions must be explicitly declared and verified by the integration pipeline.

Compatibility must be demonstrated against representative releases of each supported generation rather than relying only on Composer dependency resolution.

CIRCULARSTRING

CIRCULARSTRING must become a fully implemented spatial type.

Its public representation, invariants, supported coordinate dimensions and validation rules must conform to the normative spatial model adopted by LongitudeOne.

Once completed, it must be reported as fully implemented by the spatial type implementation status API.

COMPOUNDCURVE

COMPOUNDCURVE must become a fully implemented spatial type.

Its representation and validation must correctly model a compound curve composed of compatible curve components and satisfy the normative requirements adopted by LongitudeOne.

Once completed, it must be reported as fully implemented by the spatial type implementation status API.

Public API stabilization

The public API exposed by spatial-types must be deliberately reviewed before the 1.0.0 release.

The review must identify which contracts are intended to remain backward compatible after 1.0.0, including as applicable:

• public interfaces;
• public geometry classes;
• constructors and public methods;
• public enums;
• public exceptions and their hierarchy;
• public validation constraints;
• spatial-reference objects;
• namespaces;
• coordinate-dimension semantics;
• empty geometry semantics.

Implementation details and explicitly internal APIs must not accidentally become part of the supported public contract.

Any known API design issue that would reasonably require a backward-incompatible correction must be addressed before 1.0.0.

Normative conformance

A geometry does not need to be implemented merely because it exists in the spatial model.

However, every geometry reported as fully implemented must conform to the normative behavior claimed by the library.

The applicable invariants must be identified and covered by automated tests, with ISO/IEC 13249-3 and the applicable ISO, OGC and related spatial standards used as the normative basis of the LongitudeOne spatial model.

The 1.0.0 release must not claim implementation completeness for a geometry whose required invariants are knowingly incomplete.

Consumer and release validation

The release must be validated from the perspective of a consumer of the library, not only through its internal unit tests.

The supported public API must be usable without relying on internal implementation details.

Dependency constraints must allow the intended compatible versions of the LongitudeOne libraries and external dependencies while preventing unsupported major versions from being accepted implicitly.

spatial-types 1.0.0 must provide all concrete spatial contracts required to complete the targeted EWKT implementation in spatial-decoder.

Out of Scope

The following work does not block spatial-types 1.0.0:

• implementing every instantiable geometry type defined by spatial-core;
• implementing geometry types not required by the current stable API or targeted EWKT decoding scope;
• completing the EWKT decoder itself;
• implementing future spatial formats or unrelated decoder strategies.

Geometry types outside the 1.0.0 boundary must remain explicitly identifiable as not yet implemented.

Their implementation is expected to extend the library through backward-compatible minor releases after 1.0.0.

Acceptance Criteria

Dependency compatibility

• The Symfony Validator compatibility Story is completed.
• Symfony Validator 5.4.x is explicitly verified by CI.
• Symfony Validator 6.4.x is explicitly verified by CI.
• Symfony Validator 7.4.x is explicitly verified by CI.
• Symfony Validator 8.1.x is explicitly verified by CI.
• Supported dependency ranges do not implicitly accept unverified future major versions.

Required geometry types

• CIRCULARSTRING is fully implemented.
• CIRCULARSTRING is reported as fully implemented by the implementation status API.
• COMPOUNDCURVE is fully implemented.
• COMPOUNDCURVE is reported as fully implemented by the implementation status API.
• Both types support the coordinate dimensions required by their spatial contracts and the targeted EWKT decoding scope.
• Their normative invariants are covered by automated tests.

Public API

• The public API intended to be supported after 1.0.0 has been reviewed.
• Public and internal contracts are clearly distinguishable.
• Namespaces, interfaces, constructors, public methods and exception contracts have been reviewed for long-term compatibility.
• No known API design issue requiring a foreseeable backward-incompatible change remains unresolved.
• Backward-compatibility expectations after 1.0.0 are defined.

Normative conformance

• Every geometry reported as fully implemented has its applicable normative invariants covered by tests.
• No geometry with a known incomplete required invariant is reported as fully implemented.
• Geometry types outside the 1.0.0 scope remain explicitly reported as not yet implemented.

Downstream readiness

• The public API can be exercised from the perspective of an external consumer without relying on internal APIs.
• spatial-types provides all concrete geometry contracts required to complete the targeted EWKT work in spatial-decoder.
• No additional geometry type is known to be required solely to complete that EWKT scope.

Release readiness

• The complete test suite passes.
• All supported dependency compatibility jobs pass.
• All project quality checks pass.
• A clean Composer installation succeeds using the declared production dependencies.
• No known blocking issue remains for publishing spatial-types 1.0.0.

Versioning Principle

Version 1.0.0 establishes a stable baseline, not an exhaustive implementation of the spatial model.

After 1.0.0:

• backward-compatible additions may be released as minor versions;
• additional geometry types may be introduced incrementally in 1.x releases;
• fixes preserving the established public contract may be released as patch versions;
• backward-incompatible changes to established public contracts require a new major version.

The existence of a geometry type in spatial-core alone does not make its implementation a prerequisite for spatial-types 1.0.0.

Additional Stories

• #36 — Allow partially null point ordinates — Required for 1.0.0; blocks completion of the normative conformance review in Story: Review normative conformance for spatial-types 1.0.0 #26.