From 0db3c948cf074ce1ce895e6ed9c1d853a92fc746 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Wed, 26 Jun 2024 17:42:29 +0200 Subject: [PATCH] Deprecate SRID value `variable` (#1937) Fixes #1935 --- docs/odata-csdl-json/odata-csdl-json.html | 21 ++++++++++------- docs/odata-csdl-json/odata-csdl-json.md | 10 ++++---- docs/odata-csdl-xml/odata-csdl-xml.html | 23 +++++++++++-------- docs/odata-csdl-xml/odata-csdl-xml.md | 10 ++++---- docs/odata-json-format/odata-json-format.html | 7 +++++- docs/odata-json-format/odata-json-format.md | 3 +++ odata-csdl/1 Introduction.md | 10 ++++---- odata-csdl/13 Entity Container.md | 2 +- odata-json-format/1 Introduction.md | 3 +++ odata-json-format/7 Structural Property.md | 2 ++ 10 files changed, 58 insertions(+), 33 deletions(-) diff --git a/docs/odata-csdl-json/odata-csdl-json.html b/docs/odata-csdl-json/odata-csdl-json.html index 61814122f..e83140bf1 100644 --- a/docs/odata-csdl-json/odata-csdl-json.html +++ b/docs/odata-csdl-json/odata-csdl-json.html @@ -400,31 +400,36 @@

525 +Section 3.4.5 +SRID value variable is deprecated +1935 + + Section 4 Additional $Version value 4.02 - + Section 14.3.13 Constant Geo values in annotations 654 - + Section 14.3.14 Constant Stream values in annotations 654 - + Section 14.4.1.2 New path evaluation rules for annotations targeting annotations and external targeting via container 575 - + Section 14.4.7 Nested If without else part in collections 326 - + Section 17 Additional conformance clauses for version 4.02 @@ -738,7 +743,7 @@

3.3

Edm.Decimal with a Scale value of floating, Edm.Double, and Edm.Single allow the special numeric values -INF, INF, and NaN.

Edm.Stream is a primitive type that can be used as a property of an entity type or complex type, the underlying type for a type definition, or a binding or non-binding parameter or return type of an action or function. Edm.Stream, or a type definition whose underlying type is Edm.Stream, cannot be used in collections.

Some of these types allow facets, defined in section “Type Facets”.

-

See rule primitiveLiteral in OData-ABNF for the representation of primitive type values in URLs and OData-JSON for the representation in requests and responses.

+

Representation of primitive type values within a URL is defined by the rule primitiveLiteral in OData-ABNF. Representation within request and response bodies is format specific.

3.4 Type Facets

@@ -843,7 +848,7 @@

$Unicode

3.4.5 SRID

For a geometry- or geography-typed model element the SRID facet identifies which spatial reference system is applied to its values.

-

The value of the SRID facet MUST be a non-negative integer or the special value variable. If no value is specified, the facet defaults to 0 for Geometry types or 4326 for Geography types.

+

The value of the SRID facet MUST be a non-negative integer or the special value variable. If no value is specified, the facet defaults to 0 for Geometry types or 4326 for Geography types. Services SHOULD NOT use the special value variable as some formats, for example OData-JSON, do not define a representation for instance-specific spatial reference systems.

The valid values of the SRID facet and their meanings are as defined by the European Petroleum Survey Group EPSG.

$SRID

@@ -2103,7 +2108,7 @@

An entity container MAY specify that it extends another entity container in scope. All children of the “base” entity container are added to the “extending” entity container.

If the “extending” entity container defines an entity set with the same name as defined in any of its “base” containers, then the entity set’s type MUST specify an entity type derived from the entity type specified for the identically named entity set in the “base” container. The same holds for singletons. Action imports and function imports cannot be redefined, nor can the “extending” container define a child with the same name as a child of a different kind in a “base” container.

-

Note: services should not introduce cycles by extending entity containers. Clients should be prepared to process cycles introduced by extending entity containers.

+

Note: services SHOULD NOT introduce cycles by extending entity containers. Clients should be prepared to process cycles introduced by extending entity containers.

$Extends

The value of $Extends is the qualified name of the entity container to be extended.

diff --git a/docs/odata-csdl-json/odata-csdl-json.md b/docs/odata-csdl-json/odata-csdl-json.md index 8c6c5c4c2..f59c00566 100644 --- a/docs/odata-csdl-json/odata-csdl-json.md +++ b/docs/odata-csdl-json/odata-csdl-json.md @@ -265,6 +265,7 @@ modifications made necessary to fully cover OData CSDL Version 4.01. Section | Feature / Change | Issue --------|------------------|------ [Section 3.3](#PrimitiveTypes)| Allow stream-valued non-binding parameters| [525](https://github.com/oasis-tcs/odata-specs/issues/525) +[Section 3.4.5](#SRID)| SRID value `variable` is deprecated| [1935](https://github.com/oasis-tcs/odata-specs/issues/1935) [Section 4](#CSDLJSONDocument) | Additional `$Version` value `4.02` | [Section 14.3.13](#GeoValues) | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) [Section 14.3.14](#StreamValues) | Constant Stream values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) @@ -640,10 +641,8 @@ underlying type is `Edm.Stream`, cannot be used in collections. Some of these types allow facets, defined in section "[Type Facets](#TypeFacets)". -See rule `primitiveLiteral` in [OData-ABNF](#ODataABNF) for the -representation of primitive type values in URLs and -[OData-JSON](#ODataJSON) for the representation in requests and -responses. +Representation of primitive type values within a URL is defined by the rule `primitiveLiteral` in [OData-ABNF](#ODataABNF). +Representation within request and response bodies is format specific. ## 3.4 Type Facets @@ -846,6 +845,7 @@ spatial reference system is applied to its values. The value of the `SRID` facet MUST be a non-negative integer or the special value `variable`. If no value is specified, the facet defaults to `0` for `Geometry` types or `4326` for `Geography` types. +Services SHOULD NOT use the special value `variable` as some formats, for example [OData-JSON](#ODataJSON), do not define a representation for instance-specific spatial reference systems. The valid values of the `SRID` facet and their meanings are as defined by the European Petroleum Survey Group [EPSG](#_EPSG). @@ -3162,7 +3162,7 @@ holds for singletons. Action imports and function imports cannot be redefined, nor can the "extending" container define a child with the same name as a child of a different kind in a "base" container. -Note: services should not introduce cycles by extending entity +Note: services SHOULD NOT introduce cycles by extending entity containers. Clients should be prepared to process cycles introduced by extending entity containers. diff --git a/docs/odata-csdl-xml/odata-csdl-xml.html b/docs/odata-csdl-xml/odata-csdl-xml.html index 8a248ebdf..3cc4f2dcc 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.html +++ b/docs/odata-csdl-xml/odata-csdl-xml.html @@ -399,36 +399,41 @@

525 +Section 3.4.5 +SRID value variable is deprecated +1935 + + Section 4 Additional Version value 4.02 - + Section 13 All children of edm:EntityContainer are optional 464 - + Section 14.3.13 Constant Geo values in annotations 654 - + Section 14.3.14 Constant Stream values in annotations 654 - + Section 14.4.1.2 New path evaluation rules for annotations targeting annotations and external targeting via container 575 - + Section 14.4.7 Nested If without else part in collections 326 - + Section 17 Additional conformance clauses for version 4.02 @@ -734,7 +739,7 @@

3.3

Edm.Decimal with a Scale value of floating, Edm.Double, and Edm.Single allow the special numeric values -INF, INF, and NaN.

Edm.Stream is a primitive type that can be used as a property of an entity type or complex type, the underlying type for a type definition, or a binding or non-binding parameter or return type of an action or function. Edm.Stream, or a type definition whose underlying type is Edm.Stream, cannot be used in collections.

Some of these types allow facets, defined in section “Type Facets”.

-

See rule primitiveLiteral in OData-ABNF for the representation of primitive type values in URLs and OData-JSON for the representation in requests and responses.

+

Representation of primitive type values within a URL is defined by the rule primitiveLiteral in OData-ABNF. Representation within request and response bodies is format specific.

3.4 Type Facets

@@ -823,7 +828,7 @@

Attribute

3.4.5 SRID

For a geometry- or geography-typed model element the SRID facet identifies which spatial reference system is applied to its values.

-

The value of the SRID facet MUST be a non-negative integer or the special value variable. If no value is specified, the facet defaults to 0 for Geometry types or 4326 for Geography types.

+

The value of the SRID facet MUST be a non-negative integer or the special value variable. If no value is specified, the facet defaults to 0 for Geometry types or 4326 for Geography types. Services SHOULD NOT use the special value variable as some formats, for example OData-JSON, do not define a representation for instance-specific spatial reference systems.

The valid values of the SRID facet and their meanings are as defined by the European Petroleum Survey Group EPSG.

Attribute SRID

@@ -1934,7 +1939,7 @@

An entity container MAY specify that it extends another entity container in scope. All children of the “base” entity container are added to the “extending” entity container.

If the “extending” entity container defines an entity set with the same name as defined in any of its “base” containers, then the entity set’s type MUST specify an entity type derived from the entity type specified for the identically named entity set in the “base” container. The same holds for singletons. Action imports and function imports cannot be redefined, nor can the “extending” container define a child with the same name as a child of a different kind in a “base” container.

-

Note: services should not introduce cycles by extending entity containers. Clients should be prepared to process cycles introduced by extending entity containers.

+

Note: services SHOULD NOT introduce cycles by extending entity containers. Clients should be prepared to process cycles introduced by extending entity containers.

Attribute Extends

The value of Extends is the qualified name of the entity container to be extended.

diff --git a/docs/odata-csdl-xml/odata-csdl-xml.md b/docs/odata-csdl-xml/odata-csdl-xml.md index c31414098..dada55534 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml.md +++ b/docs/odata-csdl-xml/odata-csdl-xml.md @@ -265,6 +265,7 @@ Schema Definition Language (XSD) 1.1 as described in Section | Feature / Change | Issue --------|------------------|------ [Section 3.3](#PrimitiveTypes)| Allow stream-valued non-binding parameters| [525](https://github.com/oasis-tcs/odata-specs/issues/525) +[Section 3.4.5](#SRID)| SRID value `variable` is deprecated| [1935](https://github.com/oasis-tcs/odata-specs/issues/1935) [Section 4](#CSDLXMLDocument) | Additional `Version` value `4.02` | [Section 13](#EntityContainer)| All children of `edm:EntityContainer` are optional| [464](https://github.com/oasis-tcs/odata-specs/issues/464) [Section 14.3.13](#GeoValues) | Constant Geo values in annotations | [654](https://github.com/oasis-tcs/odata-specs/issues/654) @@ -583,10 +584,8 @@ underlying type is `Edm.Stream`, cannot be used in collections. Some of these types allow facets, defined in section "[Type Facets](#TypeFacets)". -See rule `primitiveLiteral` in [OData-ABNF](#ODataABNF) for the -representation of primitive type values in URLs and -[OData-JSON](#ODataJSON) for the representation in requests and -responses. +Representation of primitive type values within a URL is defined by the rule `primitiveLiteral` in [OData-ABNF](#ODataABNF). +Representation within request and response bodies is format specific. ## 3.4 Type Facets @@ -779,6 +778,7 @@ spatial reference system is applied to its values. The value of the `SRID` facet MUST be a non-negative integer or the special value `variable`. If no value is specified, the facet defaults to `0` for `Geometry` types or `4326` for `Geography` types. +Services SHOULD NOT use the special value `variable` as some formats, for example [OData-JSON](#ODataJSON), do not define a representation for instance-specific spatial reference systems. The valid values of the `SRID` facet and their meanings are as defined by the European Petroleum Survey Group [EPSG](#_EPSG). @@ -2971,7 +2971,7 @@ holds for singletons. Action imports and function imports cannot be redefined, nor can the "extending" container define a child with the same name as a child of a different kind in a "base" container. -Note: services should not introduce cycles by extending entity +Note: services SHOULD NOT introduce cycles by extending entity containers. Clients should be prepared to process cycles introduced by extending entity containers. diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 32da9f7a6..ca164815a 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -338,6 +338,11 @@

mediaContentType can be null 536 + +Section 7, Section A.2 +Removed reference to obsolete version of GeoJSON +456 +

@@ -892,7 +897,7 @@

7.1

Primitive values that cannot be represented, for example due to server conversion issues or IEEE754 limitations on the size of an Edm.Int64 or Edm.Decimal value, are annotated with the Core.ValueException term. In this case, the payload MAY include an approximation of the value and MAY specify a string representation of the exact value in the value property of the annotation.

Enumeration values are represented as JSON strings whose content satisfies the rule enumValue in OData-ABNF. The preferred representation is the enumerationMember. If no enumerationMember (or combination of named enumeration members) is available, the enumMemberValue representation may be used.

Geography and geometry values are represented as geometry types as defined in RFC7946.

-

Geography and geometry types have the same representation in a JSON payload. Whether the value represents a geography type or geometry type is inferred from its usage or specified using the type control information.

+

Geography and geometry types have the same representation in a JSON payload. Whether the value represents a geography type or geometry type is inferred from its usage or specified using the type control information. RFC7946 does not define means for expressing instance-specific Coordinate Reference Systems.

Example 12:

{
diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md
index adf117543..fc06a36aa 100644
--- a/docs/odata-json-format/odata-json-format.md
+++ b/docs/odata-json-format/odata-json-format.md
@@ -217,6 +217,7 @@ Section | Feature / Change | Issue
 --------|------------------|------
 [Section 4.5.1](#ControlInformationcontextodatacontext)| Fragment portion of Context URL is not percent-encoded| [368](https://github.com/oasis-tcs/odata-specs/issues/368)
 [Section 4.5.12](#ControlInformationmediaodatamedia)|  `mediaContentType` can be `null`| [536](https://github.com/oasis-tcs/odata-specs/issues/536)
+[Section 7](#StructuralProperty), [Section A.2](#InformativeReferences)| Removed reference to obsolete version of GeoJSON| [456](https://github.com/oasis-tcs/odata-specs/issues/456)
 
 ## 1.2 Glossary
 
@@ -1410,6 +1411,8 @@ payload. Whether the value represents a geography type or geometry type
 is inferred from its usage or specified using the
 [`type`](#ControlInformationtypeodatatype)
 control information.
+[RFC7946](#rfc7946) does not define means for expressing instance-specific
+[Coordinate Reference Systems](https://datatracker.ietf.org/doc/html/rfc7946#section-4).
 
 ::: example
 Example 12:
diff --git a/odata-csdl/1 Introduction.md b/odata-csdl/1 Introduction.md
index 0a63f2c82..3ff3e739a 100644
--- a/odata-csdl/1 Introduction.md	
+++ b/odata-csdl/1 Introduction.md	
@@ -32,6 +32,9 @@ Section | Feature / Change | Issue
 [Section ##PrimitiveTypes]| 
 Allow stream-valued non-binding parameters| 
 [525](https://github.com/oasis-tcs/odata-specs/issues/525)
+[Section ##SRID]| 
+SRID value `variable` is deprecated| 
+[1935](https://github.com/oasis-tcs/odata-specs/issues/1935)
 : varjson
 [Section ##CSDLJSONDocument] | Additional `$Version` value `4.02` |
 :
@@ -525,10 +528,8 @@ underlying type is `Edm.Stream`, cannot be used in collections.
 Some of these types allow facets, defined in section
 "[Type Facets](#TypeFacets)".
 
-See rule `primitiveLiteral` in [OData-ABNF](#ODataABNF) for the
-representation of primitive type values in URLs and
-[OData-JSON](#ODataJSON) for the representation in requests and
-responses.
+Representation of primitive type values within a URL is defined by the rule `primitiveLiteral` in [OData-ABNF](#ODataABNF).
+Representation within request and response bodies is format specific.
 
 ## ##subsec Type Facets
 
@@ -812,6 +813,7 @@ spatial reference system is applied to its values.
 The value of the `SRID` facet MUST be a non-negative integer or the
 special value `variable`. If no value is specified, the facet defaults
 to `0` for `Geometry` types or `4326` for `Geography` types.
+Services SHOULD NOT use the special value `variable` as some formats, for example [OData-JSON](#ODataJSON), do not define a representation for instance-specific spatial reference systems.
 
 The valid values of the `SRID` facet and their meanings are as defined
 by the European Petroleum Survey Group [EPSG](#_EPSG).
diff --git a/odata-csdl/13 Entity Container.md b/odata-csdl/13 Entity Container.md
index a7fa49a91..d027bc4f2 100644
--- a/odata-csdl/13 Entity Container.md	
+++ b/odata-csdl/13 Entity Container.md	
@@ -211,7 +211,7 @@ holds for singletons. Action imports and function imports cannot be
 redefined, nor can the "extending" container define a child with the
 same name as a child of a different kind in a "base" container.
 
-Note: services should not introduce cycles by extending entity
+Note: services SHOULD NOT introduce cycles by extending entity
 containers. Clients should be prepared to process cycles introduced by
 extending entity containers.
 
diff --git a/odata-json-format/1 Introduction.md b/odata-json-format/1 Introduction.md
index 6c9316788..de6d5929d 100644
--- a/odata-json-format/1 Introduction.md	
+++ b/odata-json-format/1 Introduction.md	
@@ -27,6 +27,9 @@ Fragment portion of Context URL is not percent-encoded|
 [Section ##ControlInformationmediaodatamedia]| 
  `mediaContentType` can be `null`| 
 [536](https://github.com/oasis-tcs/odata-specs/issues/536)
+[Section ##StructuralProperty], [Section ##InformativeReferences]| 
+Removed reference to obsolete version of GeoJSON| 
+[456](https://github.com/oasis-tcs/odata-specs/issues/456)
 
 ## ##subsec Glossary
 
diff --git a/odata-json-format/7 Structural Property.md b/odata-json-format/7 Structural Property.md
index 7860651a0..7942d3209 100644
--- a/odata-json-format/7 Structural Property.md	
+++ b/odata-json-format/7 Structural Property.md	
@@ -63,6 +63,8 @@ payload. Whether the value represents a geography type or geometry type
 is inferred from its usage or specified using the
 [`type`](#ControlInformationtypeodatatype)
 control information.
+[RFC7946](#rfc7946) does not define means for expressing instance-specific
+[Coordinate Reference Systems](https://datatracker.ietf.org/doc/html/rfc7946#section-4).
 
 ::: example
 Example ##ex: