Skip to content

Story: Allow partially null point ordinates #36

Closed

Description

@Alexandre-T

As a developer using spatial-types,
I want to represent a point with some ordinates set to null, without coordinate-completeness validation in the library,
so that supplied data is preserved and geometric validity can be checked explicitly through spatial-validator.

Parent Epic: #23 — Finalize spatial-types 1.0.0.
Target release: spatial-types 1.0.0.
Blocks: #26 — Review normative conformance for spatial-types 1.0.0. That review cannot be completed until this Story is complete.

Context

spatial-types currently rejects a point when some ordinates in its declared coordinate dimension are supplied and others are null. For example, an XY point with X = 0 and Y = null cannot be represented. Here, null means PHP null, not numeric zero.

This rejection enforces geometric validity rather than structural typing.

spatial-validator#3 — Transfer validators and remove functional validation from spatial-types, implemented on the model side by spatial-types#33, already requires removing functional validation, including equivalent inline checks. The prohibition on partially null ordinates is a remaining check to remove.

spatial-validator#14 — Validate points and common coordinate rules explicitly assigns coordinate-completeness validation to spatial-validator: mixed supplied/null ordinates must produce a violation during explicit validation.

Historically, spatial-types#8 — Allow empty points as MultiPoint elements required preserving other geometries' invariants while allowing EMPTY Point members. That requirement must no longer be interpreted as requiring the model to enforce geometric coordinate completeness.

This change must be implemented for spatial-types 1.0.0. It blocks completion of #26, whose review must assess the resulting contract and distinguish data representation from geometric validation.

Acceptance Criteria

  • Geometry and Geography points accept every combination of supplied and null ordinates within their declared XY, XYZ, XYM or XYZM dimension.
  • Public construction and copy-with-replacement paths support these states without direct or indirect rejection based on geometric coordinate completeness.
  • Accessors and array representations preserve supplied values, including null ordinates, without replacement, omission or normalization.
  • A point with only some declared ordinates set to null is not treated as EMPTY.
  • A point with all declared ordinates set to null retains EMPTY semantics; numeric zero remains a supplied ordinate.
  • All checks enforcing geometric coordinate completeness are removed from spatial-types source code, including affected coordinate value objects, factories and shared paths; equivalent disabled or bypassed checks are not retained.
  • Structural typing and declared-dimension guarantees remain enforced: a null ordinate does not change the point's dimension.
  • spatial-types neither invokes spatial-validator automatically nor introduces a dependency on it.

Constraints

  • Geometric validity remains spatial-validator's responsibility and validation is explicitly requested by the consumer.
  • An axis belonging to the declared dimension is distinct from a supplied value for that axis: an XYZ point with Z = null remains XYZ.
  • This Story covers null-ordinate representation and removal of associated checks. It does not change the geometric validation rules defined by spatial-validator#14.
  • Acceptance of a representable state by spatial-types is not a declaration of geometric conformity with applicable ISO/IEC 13249-3 or OGC requirements.

Definition of Done

The project's common Definition of Done applies.

  • composer test-local passes.
  • composer quality passes.
  • Tests cover combinations of null and supplied ordinates in all four dimensions and both families, including X = 0, Y = null.
  • Tests verify value preservation and distinguish partially supplied points from EMPTY points.
  • Tests enforcing geometric rejection of partially null ordinates are removed or replaced with verification of the new representation contract.
  • Source review confirms that no equivalent residual check remains in affected paths.
  • Existing comments, PHPDoc and documentation describing the former rejection are corrected.
  • The resulting contract is available for continuation and completion of the normative review in Story: Review normative conformance for spatial-types 1.0.0 #26.

Metadata

Metadata

Assignees

Labels

impact:apiAffects the public APIspatial:geometryRelated to geometry models or types

Type

Projects

No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions