[Microsoft.PlanetaryComputer][2025-04-30-preview] SDK review and emitter-driven breaking changes

[chahibi]

Breaking Changes - Microsoft Planetary Computer SDK

This is a AI-generated summary of all breaking changes detected in the 2025-04-30-preview OpenAPI specification for Microsoft.PlanetaryComputer. Changes are grouped by OAD (OpenAPI diff) rule code, with explanations of why each category of change was necessary.

Context: This is a preview API version. These breaking changes were introduced during the SDK generation and review process, none affect a GA API surface.

Root Causes

All breaking changes fall into three root-cause categories:

1. SDK Review Feedback (~60%): Model renames, enum renames, operation ID changes, parameter renames, and numeric type right-sizing were requested by SDK review boards for .NET, Java, JavaScript, and Python to ensure generated SDKs follow Azure SDK guidelines for naming, clarity, and ergonomics.

2. TypeSpec OpenAPI 2.0 Emitter Limitations (~25%): The TypeSpec compiler's OpenAPI 2.0 emitter could not properly represent certain constructs (union types, discriminated polymorphism, XML/binary responses). This produced empty definitions, missing discriminators, or incorrect types in the generated OpenAPI spec. These issues were silent in validation but caused real serialization/deserialization failures in SDK clients.

3. Specification Accuracy (~15%): Testing SDKs against the live service revealed mismatches between the spec and actual service behavior - missing response properties, incorrect parameter names (camelCase vs snake_case), wrong numeric formats, enum typos, and incorrect response codes.

---

1017 - ReferenceRedirection (217 occurrences)

What: The $ref property points to different model definitions in the new version compared to the old.

Affected models (old → new):

Old Definition	New Definition
ImageRequest	ImageParameters
ImageResponse	ImageResponse (restructured)
TileJsonResponse	TileJsonMetadata
BoundsResponse	StacItemBounds
Extent	StacExtensionExtent
SpatialExtent	StacExtensionSpatialExtent
FeatureCollections	StacCatalogCollections
LandingPage	StacLandingPage
Asset	StacAsset
Metadata	MosaicMetadata
PgStacSearch	TilerStacSearchDefinition
TitilerPgstacModelInfo	TilerStacSearchRegistration
SasToken	SharedAccessSignatureToken
FeaturePolygonDictStrRioTilerModelsInfo	TilerInfoGeoJsonFeature
GeoJsonStatisticsItemCollectionResponse	StacItemStatisticsGeoJson

Why necessary: SDK reviewers flagged that many auto-generated model names were non-idiomatic, too verbose, or leaked internal implementation details (e.g. PgStacSearch, TitilerPgstacModelInfo, FeaturePolygonDictStrRioTilerModelsInfo). Models were renamed to follow Azure SDK naming conventions using clear, domain-specific prefixes (e.g. Stac*, Tiler*, Mosaic*). Additionally, some models ending in Collection were renamed to avoid collision with SDK client name conventions (e.g. FeatureCollections → StacCatalogCollections). In several cases, the TypeSpec OpenAPI 2.0 emitter produced empty definitions for union types which could not be properly deserialized by SDK clients - forcing use of discriminated types which changed the $ref targets.

---

1042 - ChangedParameterOrder (109 occurrences)

What: The order of parameters in operations changed between versions.

Affected operations: Tiler tile endpoints (tilejson.json, WMTSCapabilities.xml, tile gets), mosaic endpoints, and statistics endpoints. Path parameters (e.g. collectionId, itemId) moved to different positions relative to query parameters.

Why necessary: The TypeSpec specification was refactored to use common parameter models and the @query/@path decorator ordering was standardized. Query parameters were grouped logically (rendering parameters first, then path parameters). This is a cosmetic change in the OpenAPI spec - the wire protocol is unchanged since parameter names and locations (path vs query) remain the same. SDK generators had issues with excessively long operation signatures, and parameters were reordered for better ergonomics.

---

1043 - AddingOptionalParameter (102 occurrences)

What: New optional parameters were added to existing operations.

Key addition: asset_bidx parameter added across all tiler, WMTS, and statistics endpoints.

Why necessary: The assetBidx parameter (camelCase) was renamed to asset_bidx (snake_case) to match the wire-format the service actually expects. The old camelCase name was a serialization artifact from the TypeSpec emitter. Since the parameter name changed, OAD reports it as a removal of assetBidx and addition of asset_bidx. This was required to fix actual SDK serialization failures when calling the service.

---

1047 - XmsEnumChanged (82 occurrences)

What: The x-ms-enum name on enum types changed between versions.

Key renames:

Old x-ms-enum name	New x-ms-enum name
TileJsonScheme	TileAddressingScheme
ImageType	TilerImageFormat
ImageRequestFormat	TilerImageExportFormat
SignType	AssetUrlSigningMode
SortDirections	StacQueryResultsSortingDirection
Algorithm	TerrainAlgorithm
JsonSchema	StacQueryableJsonSchema

Why necessary: SDK reviewers required that enum type names be descriptive and unambiguous. Generic names like ImageType, SignType, and Algorithm caused naming collisions in generated SDKs and did not convey their purpose. Renaming to domain-qualified names (e.g. TilerImageFormat, AssetUrlSigningMode) resolved these issues and satisfied SDK review guidelines.

---

1034 - AddedRequiredProperty (48 occurrences)

What: New properties were marked as required that were not required before.

Key additions:

• type - added as required on Geometry (discriminator property for GeoJSON types)
• url - added as required on ImageResponse
• bbox - added as required on bounding box models
• geometry, collection, assets - added as required on STAC item models

Why necessary: The original TypeSpec used union types for GeoJSON geometry which emitted as empty definitions in OpenAPI 2.0. These empty definitions silently passed model validation but caused deserialization failures in actual SDK usage - the SDK could not determine which concrete type to instantiate. Switching to discriminated types with type as the required discriminator property fixed serialization/deserialization in all language SDKs. Required properties like url on ImageResponse were added because the previous file response type could not be properly handled by SDK emitters, requiring a structured response model instead.

---

1023 - TypeFormatChanged (46 occurrences)

What: Property format changed (e.g. double → float, int64 → int32, added date-time or int32 formats).

Key changes:

• double → float on bounding box coordinates, statistics values
• int64 → int32 on zoom levels, tile coordinates, dimensions
• Added explicit int32/date-time formats where none existed before

Why necessary: The original spec used float64 and int64 TypeSpec types which are unnecessarily wide for geospatial data (tile zoom levels are 0–24, coordinates fit in float32). Using 64-bit types caused AOT trim warnings in .NET and unnecessary memory overhead. SDK reviewers requested right-sized numeric types. Additionally, some properties lacked explicit format annotations, causing SDK generators to use default types that didn't match the actual data.

---

1026 - TypeChanged (45 occurrences)

What: Properties or response schemas changed their JSON type.

Key changes:

• file → object on static image export response (structured ImageResponse model)
• string → file on WMTS XML capabilities response (actual XML document)
• '' (empty) → object on geometry properties (discriminated union)
• object → '' (empty) or array → '' (empty) on models restructured from union types

Why necessary: The TypeSpec OpenAPI 2.0 emitter could not represent union types properly, producing empty type definitions or incorrect type annotations. For example, XML responses were typed as string when they should be file (binary stream), and image export responses were file when they needed to be a structured ImageResponse containing a URL. These changes fixed SDK generation failures where the emitter could not handle the response types, and fixed runtime deserialization errors discovered during SDK testing against the live service.

---

1046 - RemovedOptionalParameter (43 occurrences)

What: Optional parameters were removed from operations.

Key removal: assetBidx was removed across all tiler and statistics endpoints.

Why necessary: This is the counterpart of the asset_bidx addition (code 1043). The camelCase assetBidx parameter name was a serialization artifact that did not match the wire-format the service expects (asset_bidx). Renaming the parameter fixed SDK requests that were silently failing or being ignored by the service. See code 1043 above.

---

1033 - RemovedProperty (37 occurrences)

What: Properties found in the old version are missing in the new version.

Key removals:

Removed Property	Model	Reason
filter-lang, filter, sortby	Cql	Model restructured; CQL filter properties moved to ImageParameters and flattened
format, mask	ImageRequest → ImageParameters	format became a query parameter; mask was not used by the service
data	AssetStatisticsResponse	Response restructured to use additionalProperties map for dynamic per-band statistics
bbox, features, links, context	Various collection models	Properties moved to proper STAC-compliant model structures
stac_version, stac_extensions	Collection models	Moved to parent/inherited STAC models
msft:_created, msft:_updated, msft:short_description	LandingPage → StacLandingPage	Model renamed; properties still exist on the new model

Why necessary: SDK testing against the live service revealed that the original model structure produced empty/incorrect JSON during serialization. Properties like data on AssetStatisticsResponse didn't match the actual service response shape (which returns a dynamic map of band names to statistics). CQL filter properties were restructured after SDK review feedback to provide a cleaner API surface. Some "removed" properties appear as removals because the containing model was renamed entirely.

---

1012 - RemovedResponseCode (29 occurrences)

What: The 204 No Content response code was removed from multiple operations.

Affected operations: Static image export status, WMTS capabilities, asset listing, and other operations that previously returned 204.

Why necessary: The JavaScript SDK emitter could not handle void result types for async operations that returned 204. The LRO (long-running operation) pattern was reworked to always return a result body. Additionally, 204 responses on GET operations (WMTS, assets) were incorrect - these operations always return content when the resource exists and should return 404 when it doesn't.

---

1025 - ModifiedOperationId (26 occurrences)

What: Operation IDs changed, which directly impacts generated SDK method names.

Key renames:

Old Operation ID	New Operation ID
StacCollectionOperations_GetAll	StacCollections_GetAll
TilerPoints_GetLonLat	TilerPoints_GetPoint
MosaicsAssetsForPoints_GetLonLatAssets	MosaicsAssetsForPoints_GetPointAssets
MapsClassmapLegends_Get	MapsClassMapLegends_Get
MapsIntervalLegends_GetByClassmapName	MapsIntervalLegends_GetByClassMapName
TilerGeoJsonStatistics_GetAll	TilerGeoJsonStatistics_Get
*_GetZxyScalexFormat	*_GetZxyScaleByFormat
*_CropWidthxHeightFormat	*_CropWidthByHeightFormat
*_GetMinxMinyMaxxMaxyFormat	*_GetCroppedToBoundingBox

Why necessary: SDK reviewers required operation names to be clear and self-documenting. Names using x as a separator (e.g. ScalexFormat) were ambiguous - is x a multiplication sign or a separator? These were changed to ScaleByFormat. Abbreviations like LonLat were expanded to Point for clarity. Internal implementation details in operation groups (e.g. StacCollectionOperations) were simplified to StacCollections. Casing fixes (Classmap → ClassMap) were required for PascalCase consistency.

---

1035 - AddingRequiredParameter (12 occurrences)

What: New required parameters were added to existing operations.

Key additions: collection, colorMapName, latitude, longitude

Why necessary: These are the renamed counterparts of removed parameters (code 1039). lat/lon were renamed to latitude/longitude for clarity per SDK review. cmapName was renamed to colorMapName. The collection parameter was added to mosaic asset endpoints that previously inferred it.

---

1021 - AddedAdditionalProperties (11 occurrences)

What: additionalProperties was added to model definitions.

Affected models: ImageParameters.cql, AssetStatisticsResponse, and others.

Why necessary: The CQL filter object and statistics response contain dynamic keys that cannot be modeled with fixed property names. The original spec attempted to model these as concrete types, but this caused SDK serialization to fail because the actual JSON payloads from the service contain arbitrary property names (e.g. band names in statistics, CQL filter expressions). Using additionalProperties (mapped to Record<unknown> in TypeSpec) correctly models these dynamic payloads and enables proper deserialization in Java and C# SDKs.

---

1032 - RemovedEnumValue (10 occurrences)

What: Enum values were removed from enum types.

Key removals:

• FeatureCollection removed (replaced by Feature on response type discriminator)
• lastbandhight removed (typo corrected to lastbandhigh)

Why necessary: FeatureCollection was incorrectly placed on a single-feature response discriminator - the correct value is Feature. The lastbandhight value was a typo in the original spec that was corrected to lastbandhigh.

---

1031 - AddedEnumValue (10 occurrences)

What: New enum values were added.

Key additions:

• Feature added (correct discriminator value)
• lastbandhigh added (corrected spelling)

Why necessary: Counterparts to the removed enum values above. These are bug fixes to the spec.

---

1039 - RemovedRequiredParameter (10 occurrences)

What: Required parameters were removed from operations.

Key removals: cmapName, lat, lon

Why necessary: These parameters were renamed for clarity per SDK review feedback. lat/lon → latitude/longitude, cmapName → colorMapName. See code 1035 above.

---

1027 - AddedPropertyInResponse (8 occurrences)

What: New properties appeared in response models.

Key additions: bbox, collection, crs, properties on various STAC item and GeoJSON response models.

Why necessary: The original TypeSpec spec used empty/underspecified models for GeoJSON responses. When the SDK hit the live service, the response JSON contained properties (bbox, collection, crs, properties) that were not in the spec, causing deserialization warnings or lost data. These properties were added to match the actual service response shape.

---

1030 - DifferentDiscriminator (7 occurrences)

What: The discriminator property changed on polymorphic models.

Affected models: Geometry (GeoJSON geometry types), tiler response types.

Why necessary: The original spec used TypeSpec union types for GeoJSON geometry, which the OpenAPI 2.0 emitter rendered without discriminators (or with empty base types). This made it impossible for SDKs to deserialize polymorphic geometry - the SDK could not determine whether a geometry was a Point, Polygon, MultiPolygon, etc. Switching to discriminated types with type as the discriminator property is the standard GeoJSON approach and enabled proper polymorphic deserialization across all SDKs.

---

1028 - ArrayCollectionFormatChanged (6 occurrences)

What: The collectionFormat for array-type query parameters changed.

Affected parameters: assets, asset_bidx on statistics and tiler endpoints.

Why necessary: The default collectionFormat emitted by TypeSpec did not match what the service expects. The service requires multi-valued query parameters in a specific format. This was discovered during SDK testing when array parameters were not being serialized correctly.

---

1036 - ConstraintChanged (2 occurrences)

What: Validation constraints (pattern) changed on parameters.

Why necessary: UUID patterns and other string validation constraints were updated to use consistent, standard regex patterns across the spec. The previous patterns were either too permissive or inconsistent with Azure SDK conventions for resource identifiers.

---

Summary

Code	Count	Category
1017 - ReferenceRedirection	217	Model renames (SDK review)
1042 - ChangedParameterOrder	109	Parameter reordering (signature ergonomics)
1043 - AddingOptionalParameter	102	Parameter rename (wire-format fix)
1047 - XmsEnumChanged	82	Enum renames (SDK review)
1034 - AddedRequiredProperty	48	Required discriminators & properties (deserialization fix)
1023 - TypeFormatChanged	46	Numeric type right-sizing (AOT/SDK review)
1026 - TypeChanged	45	Response type corrections (emitter workaround)
1046 - RemovedOptionalParameter	43	Parameter rename counterpart (wire-format fix)
1033 - RemovedProperty	37	Model restructuring (serialization fix)
1012 - RemovedResponseCode	29	Removed incorrect 204 responses (JS SDK fix)
1025 - ModifiedOperationId	26	Operation name clarity (SDK review)
1035 - AddingRequiredParameter	12	Parameter rename counterpart (SDK review)
1021 - AddedAdditionalProperties	11	Dynamic property maps (deserialization fix)
1032 - RemovedEnumValue	10	Typo/bug fixes
1039 - RemovedRequiredParameter	10	Parameter rename counterpart (SDK review)
1031 - AddedEnumValue	10	Typo/bug fixes
1027 - AddedPropertyInResponse	8	Missing response properties (spec accuracy)
1030 - DifferentDiscriminator	7	Polymorphic deserialization (emitter workaround)
1028 - ArrayCollectionFormatChanged	6	Array serialization fix
1001 - NoVersionChange	3	Informational (expected - same preview version)
1036 - ConstraintChanged	2	Pattern standardization
Total	863

[openapi-pipeline-app]

Next Steps to Merge

Next steps that must be taken to merge this PR:

• ❌ This PR targets either the main branch of the public specs repo or the RPSaaSMaster branch of the private specs repo. These branches are not intended for iterative development. Therefore, you must acknowledge you understand that after this PR is merged, the APIs are considered shipped to Azure customers. Any further attempts at in-place modifications to the APIs will be subject to Azure's versioning and breaking change policies. Additionally, for control plane APIs, you must acknowledge that you are following all the best practices documented by ARM at aka.ms/armapibestpractices. If you do intend to release the APIs to your customers by merging this PR, add the PublishToCustomers label to your PR in acknowledgement of the above. Otherwise, retarget this PR onto a feature branch, i.e. with prefix release- (see aka.ms/azsdk/api-versions#release--branches).
• ❌ This PR has at least one change violating Azure versioning policy (label: VersioningReviewRequired).
  To unblock this PR, either a) introduce a new API version with these changes instead of modifying an existing API version, or b) follow the process at aka.ms/brch.
• ❌ The required check named Automated merging requirements met has failed. This is the final check that must pass. Refer to the check in the PR's 'Checks' tab for details on how to fix it and consult the aka.ms/ci-fix guide. In addition, refer to step 4 in the PR workflow diagram

[openapi-pipeline-app]

PR validation pipeline restarted successfully. If there is ApiView generated, it will be updated in this comment.

[github-actions]

API Change Check

APIView identified API level changes in this PR and created the following API reviews

Language	API Review for Package
Swagger	Microsoft.PlanetaryComputer
TypeSpec	Microsoft.PlanetaryComputer
Python	azure-planetarycomputer
Java	com.azure:azure-analytics-planetarycomputer
JavaScript	@azure/planetarycomputer
C#	Azure.Analytics.PlanetaryComputer