Skip to content

Commit

Permalink
Use deep links in cross-spec references (#2014)
Browse files Browse the repository at this point in the history 
The [OData-Protocol] spec references the two [OData-CSDL] specs (JSON
and XML format) as two entries with separate hyperlinks. This is useful
for text like

https://github.com/oasis-tcs/odata-specs/blob/9439daa138217848097520383d302985ac47666c/odata-protocol/1%20Introduction.md?plain=1#L16-L20

All other specs reference the two [OData-CSDL] specs as one, see
https://github.com/oasis-tcs/odata-specs/compare/HEAD..9439daa138217848097520383d302985ac47666c#diff-db5ad1be4d39d16383ddb159ad2e1168888539f3a62b9bdd79b7e72189e446bb.

---------

Co-authored-by: Ralf Handl <[email protected]>
  • Loading branch information
@HeikoTheissen @ralfhandl
HeikoTheissen and ralfhandl authored Nov 6, 2024
1 parent d3177e0 commit 5096493
Show file tree
Hide file tree
Showing 49 changed files with 432 additions and 432 deletions.
44 changes: 23 additions & 21 deletions docs/odata-csdl-json/odata-csdl-json.html
View file

Large diffs are not rendered by default.

50 changes: 27 additions & 23 deletions docs/odata-csdl-json/odata-csdl-json.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -673,7 +673,7 @@ length.

The value of `$MaxLength` is a positive integer.

Note: [OData-CSDL-XML](#ODataCSDL) defines a symbolic
Note: [OData-CSDLXML, section 3.4.1](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#MaxLength) defines a symbolic
value `max` that is only allowed in OData 4.0 responses. This symbolic
value is not allowed in CDSL JSON documents at all. Services MAY instead
specify the concrete maximum length supported for the type by the
Expand Down Expand Up @@ -993,8 +993,8 @@ The
annotation, defined in [OData-VocCore](#ODataVocCore), MAY be used to
indicate a particular version of the referenced document. If the
[`Core.SchemaVersion`](https://github.com/oasis-tcs/odata-vocabularies/blob/main/vocabularies/Org.OData.Core.V1.md#SchemaVersion)
annotation is present, the `$schemaversion` system query option, defined
[OData-Protocol](#ODataProtocol), SHOULD be used when retrieving the
annotation is present, the `$schemaversion` system query option, defined in
[OData-Protocol, section 11.2.12](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#SystemQueryOptionschemaversion), SHOULD be used when retrieving the
referenced schema document.

::: {.varjson .rep}
Expand Down Expand Up @@ -1500,7 +1500,7 @@ Note: structural and navigation properties MAY be returned by the
service on instances of any structured type, whether or not the type is
marked as open. Clients MUST always be prepared to deal with additional
properties on instances of any structured type, see
[OData-Protocol](#ODataProtocol).
[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel).

::: {.varjson .rep}
### <a id="OpenType.5.3" href="#OpenType.5.3">`$OpenType`</a>
Expand All @@ -1521,7 +1521,7 @@ entity with one or more properties of type `Edm.Stream` if the
structured data of the entity is the main topic of interest and the
stream data is just additional information attached to the structured
data. For more information on media entities see
[OData-Protocol](#ODataProtocol).
[OData-Protocol, section 11.2.3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#RequestingtheMediaStreamofaMediaEntityusingvalue).

An entity type derived from a media entity type MUST indicate that it is
also a media entity type.
Expand Down Expand Up @@ -1582,7 +1582,7 @@ on one of these primitive types:

Key property values MAY be language-dependent, but their values MUST be
unique across all languages and the entity-ids (defined in
[OData-Protocol](#ODataProtocol)) MUST be language independent.
[OData-Protocol, section 4.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#EntityIdsandEntityReferences)) MUST be language independent.

A key property MUST be a non-nullable primitive property of the entity
type itself, including non-nullable primitive properties of non-nullable
Expand Down Expand Up @@ -1865,7 +1865,7 @@ If no value is specified, the client SHOULD NOT assume a default value.

The value of `$DefaultValue` is the type-specific JSON representation of
the default value of the property, see
[OData-JSON](#ODataJSON). For properties of type
[OData-JSON, section 7.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue). For properties of type
`Edm.Decimal` and `Edm.Int64` the representation depends on the media
type parameter
[`IEEE754Compatible`](#ControllingtheRepresentationofNumbers).
Expand Down Expand Up @@ -2072,7 +2072,7 @@ the entities referenced by the containment navigation property. The
canonical URL for contained entities is the canonical URL of the
containing instance, followed by the path segment of the navigation
property and the key of the contained entity, see
[OData-URL](#ODataURL).
[OData-URL, section 4.3.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURLforContainedEntities).

Entity types used in collection-valued containment navigation properties
MUST have a [key](#Key) defined.
Expand Down Expand Up @@ -2394,7 +2394,7 @@ Note: structural and navigation properties MAY be returned by the
service on instances of any structured type, whether or not the type is
marked as open. Clients MUST always be prepared to deal with additional
properties on instances of any structured type, see
[OData‑Protocol](#ODataProtocol).
[OData-Protocol, section 3](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#DataModel).

::: {.varjson .rep}
### <a id="OpenType.8.3" href="#OpenType.8.3">`$OpenType`</a>
Expand Down Expand Up @@ -3541,7 +3541,7 @@ Metadata annotations are applied in CSDL documents describing or
referencing an entity model.

*Instance annotations* are terms applied to a particular instance within
an OData payload, such as described in [OData-JSON](#ODataJSON). An
an OData payload, such as described in [OData-JSON, section 20](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#InstanceAnnotations). An
instance annotation can be used to define additional information
associated with a particular result, entity, property, or error. For
example, whether a property is read-only for a particular instance.
Expand Down Expand Up @@ -3683,10 +3683,10 @@ of the collection and specifies whether the collection MAY contain

The value of `$DefaultValue` is the type-specific JSON representation of
the default value of the term, see
[OData-JSON](#ODataJSON).
[OData-JSON, section 7.1](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#PrimitiveValue).

Note: the `$DefaultValue` member is purely for documentation and
isomorphy to [OData-CSDLXML](#ODataCSDL). Annotations in
isomorphy to [OData-CSDLXML, section 7.3](https://docs.oasis-open.org/odata/odata-csdl-xml/v4.02/odata-csdl-xml-v4.02.html#DefaultValue). Annotations in
CSDL JSON documents MUST always specify an explicit value.
:::

Expand Down Expand Up @@ -4203,7 +4203,7 @@ Example 57:
### <a id="GeoValues" href="#GeoValues">14.3.13 Geo Values</a>

::: {.varjson .rep}
Values are represented as GeoJSON, see [OData-JSON](#ODataJSON).
Values are represented as GeoJSON, see [RFC7946](#rfc7946).
:::

::: {.varjson .example}
Expand All @@ -4218,7 +4218,7 @@ Example 58:
### <a id="StreamValues" href="#StreamValues">14.3.14 Stream Values</a>

::: {.varjson .rep}
Constant values of type `Edm.Stream` are represented according to [OData-JSON](#ODataJSON) and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted.
Constant values of type `Edm.Stream` are represented according to [OData-JSON, section 9](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#StreamProperty) and MUST be accompanied by the `mediaContentType` control information to indicate how the stream value is to be interpreted.
:::


Expand Down Expand Up @@ -4266,7 +4266,7 @@ than the `Edm.*Path` types.
#### <a id="PathSyntax" href="#PathSyntax">14.4.1.1 Path Syntax</a>

Model paths and instance paths share a common syntax which is derived
from the path expression syntax of URLs, see [OData-URL](#ODataURL).
from the path expression syntax of URLs, see [OData-URL, section 5.1.1.15](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#PathExpressions).

A path MUST be composed of zero or more path segments joined together by
forward slashes (`/`).
Expand Down Expand Up @@ -4402,7 +4402,7 @@ vs. term cast addressing an annotation on the resource addressed by the navigati
An instance path MAY contain path segments starting with an entity set
or a collection-valued navigation property, then followed by a key
predicate using parentheses-style convention, see
[OData-URL](#ODataURL). The key values are either primitive literals or
[OData-URL, section 4.3.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalURL). The key values are either primitive literals or
instance paths. If the key value is a relative instance path, it is
interpreted according to the same rule below as the instance path it is
part of, *not* relative to the instance identified by the preceding path
Expand Down Expand Up @@ -4774,7 +4774,7 @@ they MAY be used anywhere instead of a Boolean expression.
The `And` and `Or` operators require two operand expressions that
evaluate to Boolean values. The `Not` operator requires a single operand
expression that evaluates to a Boolean value. For details on null
handling for comparison operators see [OData-URL](#ODataURL).
handling for comparison operators see [OData-URL, section 5.1.1.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#LogicalOperators).

The other comparison operators require two operand expressions that
evaluate to comparable values.
Expand Down Expand Up @@ -4912,7 +4912,7 @@ to a numeric value. These expressions MAY be combined, and they MAY be
used anywhere instead of a numeric expression of the appropriate type.
The semantics and evaluation rules for each arithmetic expression is
identical to the corresponding arithmetic operator defined in
[OData-URL](#ODataURL).
[OData-URL, section 5.1.1.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#ArithmeticOperators).

Operator|Description
--------|-----------
Expand Down Expand Up @@ -5045,10 +5045,10 @@ specification and its future versions.

#### <a id="CanonicalFunctions" href="#CanonicalFunctions">14.4.4.1 Canonical Functions</a>

All canonical functions defined in [OData-URL](#ODataURL) can be used as
All canonical functions defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions) can be used as
client-side functions, qualified with the namespace `odata`. The
semantics of these client-side functions is identical to their
counterpart function defined in [OData-URL](#ODataURL).
counterpart function defined in [OData-URL, section 5.1.1.4](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#CanonicalFunctions).

For example, the `odata.concat` client-side function takes two
expressions as arguments. Each argument MUST evaluate to a primitive or
Expand Down Expand Up @@ -5230,7 +5230,7 @@ Example 80:
The cast expression casts the value obtained from its single child
expression to the specified type. The cast expression follows the same
rules as the `cast` canonical function defined in
[OData-URL](#ODataURL).
[OData-URL, section 5.1.1.10.1](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html#cast).

::: {.varjson .rep}
### <a id="Cast.21.22" href="#Cast.21.22">`$Cast`</a>
Expand Down Expand Up @@ -5558,7 +5558,7 @@ property value expression. The member name is the property name, and the
member value is the property value expression.

The type of a record expression is represented as the `type` control
information, see [OData-JSON](#ODataJSON).
information, see [OData-JSON, section 4.6.3](https://docs.oasis-open.org/odata/odata-json-format/v4.02/odata-json-format-v4.02.html#ControlInformationtypeodatatype).

It MAY contain [annotations](#Annotation) for itself and its members.
Annotations for record members are prefixed with the member name.
Expand Down Expand Up @@ -6153,6 +6153,10 @@ https://www.rfc-editor.org/info/rfc6570.
_The I-JSON Message Format", RFC 7493, DOI 10.17487/RFC7493, March 2015_.
https://www.rfc-editor.org/info/rfc7493.

###### [RFC7946]{id=rfc7946}
_Butler, H., Daly, M., Doyle, A., Gillies, S., Hagen, S., and T. Schaub, "The GeoJSON Format", RFC 7946, DOI 10.17487/RFC7946, August 2016_.
https://www.rfc-editor.org/info/rfc7946.

###### [RFC8174]{id=rfc8174}
_Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_.
https://www.rfc-editor.org/info/rfc8174.
Expand Down Expand Up @@ -6314,7 +6318,7 @@ especially the contributions of
- Patric Ksinsik (SAP SE)

The contributions of the OASIS OData Technical Committee members,
enumerated in [ODataProtocol](#ODataProtocol), are gratefully
enumerated in [OData-Protocol, section C.2](https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html#Participants), are gratefully
acknowledged.

## <a id="Participants" href="#Participants">C.2 Participants</a>
Expand Down
Loading

0 comments on commit 5096493

Please sign in to comment.