diff --git a/docs/odata-csdl-json/odata-csdl-json-v4.02-csd01.html b/docs/odata-csdl-json/odata-csdl-json-v4.02-csd01.html index 2d40ff8b9..bfa3184c7 100644 --- a/docs/odata-csdl-json/odata-csdl-json-v4.02-csd01.html +++ b/docs/odata-csdl-json/odata-csdl-json-v4.02-csd01.html @@ -119,7 +119,7 @@

Editors:

Additional artifacts:

This prose specification is one component of a Work Product that also includes:

@@ -132,9 +132,13 @@

Abstract:

OData services are described by an Entity Model (EDM). The Common Schema Definition Language (CSDL) defines specific representations of the entity data model exposed by an OData service, using XML, JSON, and other formats. This document (OData CSDL JSON Representation) specifically defines the JSON representation of CSDL.

@@ -198,6 +202,11 @@

Table of Contents

  • 4.2 Included Schema
  • 4.3 Included Annotations
  • +
  • 5 Schema +
  • A References -
    [RFC2119]
    -

    Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
    -http://www.rfc-editor.org/info/rfc2119.

    -
    [RFC8174]
    -

    Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
    -http://www.rfc-editor.org/info/rfc8174.

    -
    [RFC6570]
    -

    Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012.
    -http://tools.ietf.org/html/rfc6570.

    -
    [RFC7493]
    -

    Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015.
    -https://tools.ietf.org/html/rfc7493.

    -
    [RFC8259]
    -

    Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017.
    -http://tools.ietf.org/html/rfc8259.

    [ECMAScript]

    ECMAScript 2016 Language Specification, 7th Edition. June 2016. Standard ECMA-262. http://www.ecma-international.org/publications/standards/Ecma-262.htm.

    [EPSG]
    -

    European Petroleum Survey Group (EPSG). http://www.epsg.org/.

    +

    European Petroleum Survey Group (EPSG). http://www.epsg.org/.###### [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015.
    +https://tools.ietf.org/html/rfc7493.###### [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
    +http://www.rfc-editor.org/info/rfc2119.

    [OData-ABNF]

    OData ABNF Construction Rules Version 4.01.
    See link in "Additional artifacts" section on cover page.

    [OData-CSDL-Schema]

    OData CSDL JSON Schema.
    See link in "Related work" section on cover page.

    +
    [OData-CSDLJSON]
    +

    OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01.
    +See link in "Related work" section on cover page.

    [OData-CSDLXML]

    OData Common Schema Definition Language (CSDL) XML Representation Version 4.01.
    See link in "Related work" section on cover page.

    +
    [OData-EDM]
    +

    OData EDM XML Schema.
    +See link in "Additional artifacts" section on cover page.

    +
    [OData-EDMX]
    +

    OData EDM XML Schema.
    +See link in "Additional artifacts" section on cover page.

    [OData-JSON]

    OData JSON Format Version 4.01.
    See link in "Related work" section on cover page.

    @@ -741,13 +793,33 @@
    [OData-VocMeasures]Related work" section on cover page.

    [OData-VocValidation]

    OData Vocabularies Version 4.0: Validation Vocabulary.
    -See link in "Related work" section on cover page.

    -
    [XML-Schema-2]
    +See link in "Related work" section on cover page.###### [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012.
    +http://tools.ietf.org/html/rfc6570.

    +
    [RFC2119]
    +

    Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
    +https://www.rfc-editor.org/info/rfc2119.

    +
    [RFC6570]
    +

    Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, “URI Template”, RFC 6570, March 2012.
    +http://tools.ietf.org/html/rfc6570.

    +
    [RFC8174]
    +

    Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
    +http://www.rfc-editor.org/info/rfc8174.

    +
    [RFC8259]
    +

    Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017.
    +http://tools.ietf.org/html/rfc8259.

    +
    [XML-1.1]
    +

    Extensible Markup Language (XML) 1.1 (Second Edition). F. Yergeau, E. Maler, J. Cowan, T. Bray, C. M. Sperberg-McQueen, J. Paoli, Editors, W3C Recommendation, 16 August 2006.
    +http://www.w3.org/TR/2006/REC-xml11-20060816. Latest version available at http://www.w3.org/TR/xml11/.

    +
    [XML-Base]
    +

    XML Base (Second Edition). J. Marsh, R. Tobin, Editors, W3C Recommendation, 28 January 2009.
    +http://www.w3.org/TR/2009/REC-xmlbase-20090128/. Latest version available at http://www.w3.org/TR/xmlbase/.

    +
    [XML-Schema-1]
    +

    W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures. D. Beech, M. Maloney, C. M. Sperberg-McQueen, H. S. Thompson, S. Gao, N. Mendelsohn, Editors, W3C Recommendation, 5 April 2012.
    +http://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-1/.

    +
    [XML-Schema-2]

    W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. D. Peterson, S. Gao, C. M. Sperberg-McQueen, H. S. Thompson, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 5 April 2012.
    http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-2/.

    A.2 Informative References

    -
    [RFC3552]
    -

    Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003 https://www.rfc-editor.org/info/rfc3552.

    [OpenUI5]

    OpenUI5 Version 1.40.10 - OData V4 Metadata JSON Format.
    https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a414499b.html.

    @@ -771,6 +843,11 @@

    $Qualifier

  • $TargetNamespace
  • +
  • Schema Object +

  • diff --git a/docs/odata-csdl-json/odata-csdl-json-v4.02-csd01.md b/docs/odata-csdl-json/odata-csdl-json-v4.02-csd01.md index 3a7f73f78..36382897a 100644 --- a/docs/odata-csdl-json/odata-csdl-json-v4.02-csd01.md +++ b/docs/odata-csdl-json/odata-csdl-json-v4.02-csd01.md @@ -40,7 +40,7 @@ Heiko Theißen (heiko.theissen@sap.com), [SAP SE](http://www.sap.com/) #### Additional artifacts: This prose specification is one component of a Work Product that also includes: -* XML schemas: (list file names or directory name) +* XML schemas: _OData EDMX XML Schema and OData EDM XML Schema_. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/os/schemas/ * Other parts (list titles and/or file names) * `(Note: Any normative computer language definitions that are part of the Work Product, such as XML instances, schemas and Java(TM) code, including fragments of such, must be (a) well formed and valid, (b) provided in separate plain text files, (c) referenced from the Work Product; and (d) where any definition in these separate files disagrees with the definition found in the specification, the definition in the separate file prevails. Remove this note before submitting for publication.)` @@ -50,8 +50,12 @@ This specification replaces or supersedes: This specification is related to: * _OData Version 4.02_. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes: - * _OData Version 4.02 Part 1: Protocol_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html - * _OData Version 4.02 Part 2: URL Conventions_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html + * _OData Version 4.02 Part 1: Protocol_. Latest stage: https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html + * _OData Version 4.02 Part 2: URL Conventions_. Latest stage: https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html + * _ABNF components: OData ABNF Construction Rules Version 4.01 and OData ABNF Test Cases_. https://docs.oasis-open.org/odata/odata/v4.01/os/abnf/ +* _OData Vocabularies Version 4.0_. Edited by Michael Pizzo, Ralf Handl, and Ram Jeyaraman. Latest stage: https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html +* _OData Common Schema Definition Language (CSDL) XML Representation Version 4.01_. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html +* _OData JSON Format Version 4.01_. Edited by Ralf Handl, Mike Pizzo, and Mark Biamonte. Latest stage: https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html #### Abstract: OData services are described by an Entity Model (EDM). The Common Schema Definition Language (CSDL) defines specific representations of the entity data model exposed by an OData service, using XML, JSON, and other formats. This document (OData CSDL JSON Representation) specifically defines the JSON representation of CSDL. @@ -118,6 +122,9 @@ For complete copyright information please see the full Notices section in an App - [4.1 Reference](#Reference) - [4.2 Included Schema](#IncludedSchema) - [4.3 Included Annotations](#IncludedAnnotations) +- [5 Schema](#Schema) + - [5.1 Alias](#Alias) + - [5.2 Annotations with External Targeting](#AnnotationswithExternalTargeting) - [A References](#References) - [A.1 Normative References](#NormativeReferences) - [A.2 Informative References](#InformativeReferences) @@ -351,7 +358,7 @@ they have the default value. ## 2.3 JSON Schema Definition The structure of CSDL JSON documents can be verified with the JSON -Schema [OData-CSDL-Schema](#CSDLschema) provided as an +Schema [OData-CSDL-Schema](#ODataCSDL) provided as an additional artifact of this prose specification. This schema only defines the shape of a well-formed CSDL JSON document but is not descriptive enough to define what a correct CSDL JSON document MUST be @@ -470,7 +477,7 @@ Type|Meaning `Edm.GeometryCollection` |Collection of arbitrary Geometry values `Edm.Date` and `Edm.DateTimeOffset` follow -[XML-Schema-2](#XMLSchema) and use the proleptic Gregorian +[XML-Schema-2](#XMLSchema2) and use the proleptic Gregorian calendar, allowing the year `0000` (equivalent to 1 BCE) and negative years (year `-0001` being equivalent to 2 BCE etc.). The supported date range is service-specific and typically depends on the underlying @@ -869,6 +876,119 @@ a term from the `org.example.hcm` namespace to an element of the `com.example.Person` namespace and specify a `Tablet` qualifier. ::: +------- + +# 5 Schema + +One or more schemas describe the entity model exposed by an OData +service. The schema acts as a namespace for elements of the entity model +such as entity types, complex types, enumerations and terms. + +A schema is identified by a [namespace](#Namespace). Schema namespaces +MUST be unique within the scope of a document and SHOULD be globally +unique. A schema cannot span more than one document. + +The schema's namespace is combined with the name of elements in the +schema to create unique [qualified names](#QualifiedName), so +identifiers that are used to name types MUST be unique within a +namespace to prevent ambiguity. + +Names are case-sensitive, but service authors SHOULD NOT choose names +that differ only in case. + +The namespace MUST NOT be one of the reserved values `Edm`, `odata`, +`System`, or `Transient`. + +::: {.varjson .rep} +### Schema Object + +A schema is represented as a member of the document object whose name is +the schema namespace. Its value is an object that MAY contain the +members [`$Alias`](#Alias) and +[`$Annotations`](#AnnotationswithExternalTargeting). + +The schema object MAY contain members representing [entity +types](#EntityType), [complex types](#ComplexType), [enumeration +types](#EnumerationType), [type definitions](#TypeDefinition), +[actions](#Action), [functions](#Function), [terms](#Term), and an +[entity container](#EntityContainer). + +The schema object MAY also contain [annotations](#Annotation) that apply +to the schema itself. +::: + + +## 5.1 Alias + +A schema MAY specify an alias which MUST be a [simple +identifier](#SimpleIdentifier). + +::: varjson +If a schema specifies an alias, the alias MUST be used instead of the +namespace within qualified names throughout the document to identify +model elements of that schema. A mixed use of namespace-qualified names +and alias-qualified names is not allowed. +::: + + +Aliases are document-global, so all schemas defined within or included +into a document MUST have different aliases, and aliases MUST differ +from the namespaces of all schemas defined within or included into a +document. Aliases defined by a schema can be used throughout the +containing document and are not restricted to the schema that defines +them. + +The alias MUST NOT be one of the reserved values `Edm`, `odata`, +`System`, or `Transient`. + +::: {.varjson .rep} +### `$Alias` + +The value of `$Alias` is a string containing the alias for the schema. +::: + +::: {.varjson .example} +Example 6: document defining a schema `org.example` with an alias and a +description for the schema +```json +{ +  ... +  "org.example": { +    "$Alias": "self",     "@Core.Description": "Example schema", +    ...   }, +  ... } +``` +::: + + + +## 5.2 Annotations with External Targeting + +::: {.varjson .rep} +### `$Annotations` + +The value of `$Annotations` is an object with one member per [annotation +target](#Target). The member name is a path identifying the [annotation +target](#Target), the member value is an object containing +[annotations](#Annotation) for that target. +::: + +::: {.varjson .example} +Example 7: annotations targeting the `Person` type with qualifier +`Tablet` +```json +"org.example": { +  "$Alias": "self",   "$Annotations": { +    "self.Person": { +      "@Core.Description#Tablet": "Dummy", +      ... +    } +  } }, +``` +::: + + + ------- # Appendix A. References @@ -883,43 +1003,20 @@ While any hyperlinks included in this appendix were valid at the time of publica The following documents are referenced in such a way that some or all of their content constitutes requirements of this document. -`(Reference sources: -For references to IETF RFCs, use the approved citation formats at: -https://docs.oasis-open.org/templates/ietf-rfc-list/ietf-rfc-list.html. -For references to W3C Recommendations, use the approved citation formats at: -https://docs.oasis-open.org/templates/w3c-recommendations-list/w3c-recommendations-list.html. -Remove this note before submitting for publication.)` - ###### [OData-v4.02] - _OData Version 4.02_. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes: - _OData Version 4.02 Part 1: Protocol_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html - _OData Version 4.02 Part 2: URL Conventions_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html -###### [RFC2119] -_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. -http://www.rfc-editor.org/info/rfc2119. - -###### [RFC8174] -_Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_. -http://www.rfc-editor.org/info/rfc8174. - -###### [RFC6570] -_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012_. -http://tools.ietf.org/html/rfc6570. - -###### [RFC7493] -_Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015_. -https://tools.ietf.org/html/rfc7493. - -###### [RFC8259] -_Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017_. -http://tools.ietf.org/html/rfc8259. - ###### [ECMAScript] _ECMAScript 2016 Language Specification, 7th Edition_. June 2016. Standard ECMA-262. http://www.ecma-international.org/publications/standards/Ecma-262.htm. ###### [EPSG] -_European Petroleum Survey Group (EPSG)_. http://www.epsg.org/. +_European Petroleum Survey Group (EPSG)_. http://www.epsg.org/.###### [RFC7493] +_Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015_. +https://tools.ietf.org/html/rfc7493.###### [RFC2119] +_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. +http://www.rfc-editor.org/info/rfc2119. ###### [OData-ABNF] _OData ABNF Construction Rules Version 4.01_. @@ -929,10 +1026,22 @@ See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page _OData CSDL JSON Schema_. See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-CSDLJSON] +_OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01_. +See link in "[Related work](#RelatedWork)" section on cover page. + ###### [OData-CSDLXML] _OData Common Schema Definition Language (CSDL) XML Representation Version 4.01_. See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-EDM] +_OData EDM XML Schema_. +See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page. + +###### [OData-EDMX] +_OData EDM XML Schema_. +See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page. + ###### [OData-JSON] _OData JSON Format Version 4.01_. See link in "[Related work](#RelatedWork)" section on cover page. @@ -955,18 +1064,43 @@ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-VocValidation] _OData Vocabularies Version 4.0: Validation Vocabulary_. -See link in "[Related work](#RelatedWork)" section on cover page. +See link in "[Related work](#RelatedWork)" section on cover page.###### [RFC6570] +_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012_. +http://tools.ietf.org/html/rfc6570. + +###### [RFC2119] +_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. +https://www.rfc-editor.org/info/rfc2119. -###### [XML-Schema-2] +###### [RFC6570] +_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, “URI Template”, RFC 6570, March 2012_. +http://tools.ietf.org/html/rfc6570. + +###### [RFC8174] +_Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_. +http://www.rfc-editor.org/info/rfc8174. + +###### [RFC8259] +_Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017_. +http://tools.ietf.org/html/rfc8259. + +###### [XML-1.1] +_Extensible Markup Language (XML) 1.1 (Second Edition)_. F. Yergeau, E. Maler, J. Cowan, T. Bray, C. M. Sperberg-McQueen, J. Paoli, Editors, W3C Recommendation, 16 August 2006. +http://www.w3.org/TR/2006/REC-xml11-20060816. Latest version available at http://www.w3.org/TR/xml11/. + +###### [XML-Base] +_XML Base (Second Edition)_. J. Marsh, R. Tobin, Editors, W3C Recommendation, 28 January 2009. +http://www.w3.org/TR/2009/REC-xmlbase-20090128/. Latest version available at http://www.w3.org/TR/xmlbase/. +###### [XML-Schema-1] +_W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures_. D. Beech, M. Maloney, C. M. Sperberg-McQueen, H. S. Thompson, S. Gao, N. Mendelsohn, Editors, W3C Recommendation, 5 April 2012. +http://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-1/. + +###### [XML-Schema-2] _W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes_. D. Peterson, S. Gao, C. M. Sperberg-McQueen, H. S. Thompson, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 5 April 2012. http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-2/. ## A.2 Informative References -###### [RFC3552] -_Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003_ -https://www.rfc-editor.org/info/rfc3552. - ###### [OpenUI5] _OpenUI5 Version 1.40.10 - OData V4 Metadata JSON Format_. https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a414499b.html. @@ -988,6 +1122,9 @@ https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a4 - [`$TermNamespace`](#TermNamespace2.5) - [`$Qualifier`](#Qualifier2.6) - [`$TargetNamespace`](#TargetNamespace2.7) +- [Schema Object](#SchemaObject3) + - [`$Alias`](#Alias3.1) + - [`$Annotations`](#Annotations3.2) ::: ------- diff --git a/docs/odata-csdl-json/styles/odata.css b/docs/odata-csdl-json/styles/odata.css index 016fcf7f0..a3cafde6b 100644 --- a/docs/odata-csdl-json/styles/odata.css +++ b/docs/odata-csdl-json/styles/odata.css @@ -3,18 +3,21 @@ a:target { } a[href^="#OData"], -a[href^="#rfc"] { +a[href^="#rfc"], +a[href^="#XML"] { font-weight: bold; } a[href^="#OData"]::before, -a[href^="#rfc"]::before { +a[href^="#rfc"]::before, +a[href^="#XML"]::before { content: "["; font-weight: bold; } a[href^="#OData"]::after, -a[href^="#rfc"]::after { +a[href^="#rfc"]::after, +a[href^="#XML"]::after { content: "]"; font-weight: bold; } diff --git a/docs/odata-csdl-xml/odata-csdl-xml-v4.02-csd01.html b/docs/odata-csdl-xml/odata-csdl-xml-v4.02-csd01.html index ce7e41e85..991d68b74 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml-v4.02-csd01.html +++ b/docs/odata-csdl-xml/odata-csdl-xml-v4.02-csd01.html @@ -119,7 +119,7 @@

    Editors:

    Additional artifacts:

    This prose specification is one component of a Work Product that also includes:

    @@ -132,9 +132,13 @@

    Abstract:

    OData services are described by an Entity Model (EDM). The Common Schema Definition Language (CSDL) defines specific representations of the entity data model exposed by an OData service, using XML, JSON, and other formats. This document (OData CSDL JSON Representation) specifically defines the JSON representation of CSDL.

    @@ -194,6 +198,11 @@

    Table of Contents

  • 4.2 Included Schema
  • 4.3 Included Annotations
  • +
  • 5 Schema +
  • A References -
    [RFC2119]
    -

    Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
    -http://www.rfc-editor.org/info/rfc2119.

    -
    [RFC8174]
    -

    Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
    -http://www.rfc-editor.org/info/rfc8174.

    -
    [RFC6570]
    -

    Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012.
    -http://tools.ietf.org/html/rfc6570.

    -
    [RFC7493]
    -

    Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015.
    -https://tools.ietf.org/html/rfc7493.

    -
    [RFC8259]
    -

    Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017.
    -http://tools.ietf.org/html/rfc8259.

    [ECMAScript]

    ECMAScript 2016 Language Specification, 7th Edition. June 2016. Standard ECMA-262. http://www.ecma-international.org/publications/standards/Ecma-262.htm.

    [EPSG]
    -

    European Petroleum Survey Group (EPSG). http://www.epsg.org/.

    +

    European Petroleum Survey Group (EPSG). http://www.epsg.org/.###### [RFC7493] Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015.
    +https://tools.ietf.org/html/rfc7493.###### [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
    +http://www.rfc-editor.org/info/rfc2119.

    [OData-ABNF]

    OData ABNF Construction Rules Version 4.01.
    See link in "Additional artifacts" section on cover page.

    [OData-CSDL-Schema]

    OData CSDL JSON Schema.
    See link in "Related work" section on cover page.

    +
    [OData-CSDLJSON]
    +

    OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01.
    +See link in "Related work" section on cover page.

    [OData-CSDLXML]

    OData Common Schema Definition Language (CSDL) XML Representation Version 4.01.
    See link in "Related work" section on cover page.

    +
    [OData-EDM]
    +

    OData EDM XML Schema.
    +See link in "Additional artifacts" section on cover page.

    +
    [OData-EDMX]
    +

    OData EDM XML Schema.
    +See link in "Additional artifacts" section on cover page.

    [OData-JSON]

    OData JSON Format Version 4.01.
    See link in "Related work" section on cover page.

    @@ -710,13 +762,33 @@
    [OData-VocMeasures]Related work" section on cover page.

    [OData-VocValidation]

    OData Vocabularies Version 4.0: Validation Vocabulary.
    -See link in "Related work" section on cover page.

    -
    [XML-Schema-2]
    +See link in "Related work" section on cover page.###### [RFC6570] Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012.
    +http://tools.ietf.org/html/rfc6570.

    +
    [RFC2119]
    +

    Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997.
    +https://www.rfc-editor.org/info/rfc2119.

    +
    [RFC6570]
    +

    Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, “URI Template”, RFC 6570, March 2012.
    +http://tools.ietf.org/html/rfc6570.

    +
    [RFC8174]
    +

    Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017.
    +http://www.rfc-editor.org/info/rfc8174.

    +
    [RFC8259]
    +

    Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017.
    +http://tools.ietf.org/html/rfc8259.

    +
    [XML-1.1]
    +

    Extensible Markup Language (XML) 1.1 (Second Edition). F. Yergeau, E. Maler, J. Cowan, T. Bray, C. M. Sperberg-McQueen, J. Paoli, Editors, W3C Recommendation, 16 August 2006.
    +http://www.w3.org/TR/2006/REC-xml11-20060816. Latest version available at http://www.w3.org/TR/xml11/.

    +
    [XML-Base]
    +

    XML Base (Second Edition). J. Marsh, R. Tobin, Editors, W3C Recommendation, 28 January 2009.
    +http://www.w3.org/TR/2009/REC-xmlbase-20090128/. Latest version available at http://www.w3.org/TR/xmlbase/.

    +
    [XML-Schema-1]
    +

    W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures. D. Beech, M. Maloney, C. M. Sperberg-McQueen, H. S. Thompson, S. Gao, N. Mendelsohn, Editors, W3C Recommendation, 5 April 2012.
    +http://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-1/.

    +
    [XML-Schema-2]

    W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes. D. Peterson, S. Gao, C. M. Sperberg-McQueen, H. S. Thompson, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 5 April 2012.
    http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-2/.

    A.2 Informative References

    -
    [RFC3552]
    -

    Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003 https://www.rfc-editor.org/info/rfc3552.

    [OpenUI5]

    OpenUI5 Version 1.40.10 - OData V4 Metadata JSON Format.
    https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a414499b.html.

    @@ -744,6 +816,16 @@

    Attribute Qualifier

  • Attribute TargetNamespace
  • +
  • Element edm:Schema +
  • +
  • Element edm:Annotations +

  • diff --git a/docs/odata-csdl-xml/odata-csdl-xml-v4.02-csd01.md b/docs/odata-csdl-xml/odata-csdl-xml-v4.02-csd01.md index 68e65bbcf..192bb253f 100644 --- a/docs/odata-csdl-xml/odata-csdl-xml-v4.02-csd01.md +++ b/docs/odata-csdl-xml/odata-csdl-xml-v4.02-csd01.md @@ -40,7 +40,7 @@ Heiko Theißen (heiko.theissen@sap.com), [SAP SE](http://www.sap.com/) #### Additional artifacts: This prose specification is one component of a Work Product that also includes: -* XML schemas: (list file names or directory name) +* XML schemas: _OData EDMX XML Schema and OData EDM XML Schema_. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/os/schemas/ * Other parts (list titles and/or file names) * `(Note: Any normative computer language definitions that are part of the Work Product, such as XML instances, schemas and Java(TM) code, including fragments of such, must be (a) well formed and valid, (b) provided in separate plain text files, (c) referenced from the Work Product; and (d) where any definition in these separate files disagrees with the definition found in the specification, the definition in the separate file prevails. Remove this note before submitting for publication.)` @@ -50,8 +50,12 @@ This specification replaces or supersedes: This specification is related to: * _OData Version 4.02_. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes: - * _OData Version 4.02 Part 1: Protocol_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html - * _OData Version 4.02 Part 2: URL Conventions_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html + * _OData Version 4.02 Part 1: Protocol_. Latest stage: https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html + * _OData Version 4.02 Part 2: URL Conventions_. Latest stage: https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html + * _ABNF components: OData ABNF Construction Rules Version 4.01 and OData ABNF Test Cases_. https://docs.oasis-open.org/odata/odata/v4.01/os/abnf/ +* _OData Vocabularies Version 4.0_. Edited by Michael Pizzo, Ralf Handl, and Ram Jeyaraman. Latest stage: https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html +* _OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01_. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html +* _OData JSON Format Version 4.01_. Edited by Ralf Handl, Mike Pizzo, and Mark Biamonte. Latest stage: https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html #### Abstract: OData services are described by an Entity Model (EDM). The Common Schema Definition Language (CSDL) defines specific representations of the entity data model exposed by an OData service, using XML, JSON, and other formats. This document (OData CSDL JSON Representation) specifically defines the JSON representation of CSDL. @@ -116,6 +120,9 @@ For complete copyright information please see the full Notices section in an App - [4.1 Reference](#Reference) - [4.2 Included Schema](#IncludedSchema) - [4.3 Included Annotations](#IncludedAnnotations) +- [5 Schema](#Schema) + - [5.1 Alias](#Alias) + - [5.2 Annotations with External Targeting](#AnnotationswithExternalTargeting) - [A References](#References) - [A.1 Normative References](#NormativeReferences) - [A.2 Informative References](#InformativeReferences) @@ -204,13 +211,13 @@ This uses pandoc 3.1.2 from https://github.com/jgm/pandoc/releases/tag/3.1.2. OData CSDL XML is a full representation of the OData Common Schema Definition Language in the Extensible Markup Language (XML) 1.1 (Second -Edition) [XML-1.1](#BMXML) with further building blocks from the +Edition) [XML-1.1](#XML11) with further building blocks from the W3C XML Schema Definition Language (XSD) 1.1 as described in -[XML-Schema-1](#BMXMLSchema1) and -[XML-Schema-2](#BMXMLSchema2). +[XML-Schema-1](#XMLSchema1) and +[XML-Schema-2](#XMLSchema2). It is an alternative to the CSDL JSON representation defined in -[OData-CSDLJSON](#BMCSDLJSON) and neither adds nor +[OData-CSDLJSON](#ODataCSDLJSON) and neither adds nor removes features. ## 2.1 Requesting the XML Representation @@ -280,8 +287,8 @@ prescriptive. ## 2.3 XML Schema Definitions This specification contains normative XML schemas for the EDMX and EDM -namespaces; see [OData-EDMX](#BMEDMX) and -[OData-EDM](#BMEDM) +namespaces; see [OData-EDMX](#ODataEDMX) and +[OData-EDM](#ODataEDM) These XML schemas only define the shape of a well-formed CSDL XML document and are not descriptive enough to define what a correct CSDL @@ -410,7 +417,7 @@ Type|Meaning `Edm.GeometryCollection` |Collection of arbitrary Geometry values `Edm.Date` and `Edm.DateTimeOffset` follow -[XML-Schema-2](#XMLSchema) and use the proleptic Gregorian +[XML-Schema-2](#XMLSchema2) and use the proleptic Gregorian calendar, allowing the year `0000` (equivalent to 1 BCE) and negative years (year `-0001` being equivalent to 2 BCE etc.). The supported date range is service-specific and typically depends on the underlying @@ -806,6 +813,126 @@ a term from the `org.example.hcm` namespace to an element of the ------- +# 5 Schema + +One or more schemas describe the entity model exposed by an OData +service. The schema acts as a namespace for elements of the entity model +such as entity types, complex types, enumerations and terms. + +A schema is identified by a [namespace](#Namespace). Schema namespaces +MUST be unique within the scope of a document and SHOULD be globally +unique. A schema cannot span more than one document. + +The schema's namespace is combined with the name of elements in the +schema to create unique [qualified names](#QualifiedName), so +identifiers that are used to name types MUST be unique within a +namespace to prevent ambiguity. + +Names are case-sensitive, but service authors SHOULD NOT choose names +that differ only in case. + +The namespace MUST NOT be one of the reserved values `Edm`, `odata`, +`System`, or `Transient`. + + +::: {.varxml .rep} +### Element `edm:Schema` + +The `edm:Schema` element defines a +schema. It MUST contain the `Namespace` attribute and it MAY +contain the `Alias` attribute. + +It MAY contain elements [`edm:Action`](#Action), +[`edm:Annotations`](#AnnotationswithExternalTargeting), +[`edm:Annotation`](#Annotation), [`edm:ComplexType`](#ComplexType), +[`edm:EntityContainer`](#EntityContainer), +[`edm:EntityType`](#EntityType), [`edm:EnumType`](#EnumerationType), +[`edm:Function`](#Function), [`edm:Term`](#Term), or +[`edm:TypeDefinition`](#TypeDefinition). + +### Attribute `Namespace` + +The value of `Namespace` is the namespace of the schema +::: + +## 5.1 Alias + +A schema MAY specify an alias which MUST be a [simple +identifier](#SimpleIdentifier). + + +::: varxml +If a schema specifies an alias, the alias MAY be used instead of the +namespace within qualified names to identify model elements of that +schema. An alias only provides a more convenient notation, allowing a +short string to be substituted for a long namespace. Every model element +that can be identified via an alias-qualified name can alternatively be +identified via its full namespace-qualified name. +::: + +Aliases are document-global, so all schemas defined within or included +into a document MUST have different aliases, and aliases MUST differ +from the namespaces of all schemas defined within or included into a +document. Aliases defined by a schema can be used throughout the +containing document and are not restricted to the schema that defines +them. + +The alias MUST NOT be one of the reserved values `Edm`, `odata`, +`System`, or `Transient`. + + + +::: {.varxml .rep} +### Attribute `Alias` + +The value of `Alias` is a [simple identifier](#SimpleIdentifier). +::: + +::: {.varxml .example} +Example 6: schema `org.example` with an alias and a description for the +schema +```xml +   +  ... + +``` +::: + +## 5.2 Annotations with External Targeting + + + +::: {.varxml .rep} +### Element `edm:Annotations` + +The `edm:Annotations` element is used to apply a group of annotations to +a single model element. It MUST contain the `Target` attribute and it +MAY contain the `Qualifier` attribute. + +It MUST contain at least one [`edm:Annotation`](#Annotation) element. + +### Attribute `Target` + +The value of `Target` is a path expression identifying the [annotation +target](#Target). It MUST resolve to a model element in scope. + +### Attribute `Qualifier` + +The value of `Qualifier` is a [simple identifier](#SimpleIdentifier). +::: + +::: {.varxml .example} +Example 7: annotations should only be applied to tablet devices +```xml + + + ... + +``` +::: + +------- + # Appendix A. References @@ -818,43 +945,20 @@ While any hyperlinks included in this appendix were valid at the time of publica The following documents are referenced in such a way that some or all of their content constitutes requirements of this document. -`(Reference sources: -For references to IETF RFCs, use the approved citation formats at: -https://docs.oasis-open.org/templates/ietf-rfc-list/ietf-rfc-list.html. -For references to W3C Recommendations, use the approved citation formats at: -https://docs.oasis-open.org/templates/w3c-recommendations-list/w3c-recommendations-list.html. -Remove this note before submitting for publication.)` - ###### [OData-v4.02] - _OData Version 4.02_. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes: - _OData Version 4.02 Part 1: Protocol_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html - _OData Version 4.02 Part 2: URL Conventions_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html -###### [RFC2119] -_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. -http://www.rfc-editor.org/info/rfc2119. - -###### [RFC8174] -_Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_. -http://www.rfc-editor.org/info/rfc8174. - -###### [RFC6570] -_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012_. -http://tools.ietf.org/html/rfc6570. - -###### [RFC7493] -_Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015_. -https://tools.ietf.org/html/rfc7493. - -###### [RFC8259] -_Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017_. -http://tools.ietf.org/html/rfc8259. - ###### [ECMAScript] _ECMAScript 2016 Language Specification, 7th Edition_. June 2016. Standard ECMA-262. http://www.ecma-international.org/publications/standards/Ecma-262.htm. ###### [EPSG] -_European Petroleum Survey Group (EPSG)_. http://www.epsg.org/. +_European Petroleum Survey Group (EPSG)_. http://www.epsg.org/.###### [RFC7493] +_Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015_. +https://tools.ietf.org/html/rfc7493.###### [RFC2119] +_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. +http://www.rfc-editor.org/info/rfc2119. ###### [OData-ABNF] _OData ABNF Construction Rules Version 4.01_. @@ -864,10 +968,22 @@ See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page _OData CSDL JSON Schema_. See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-CSDLJSON] +_OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01_. +See link in "[Related work](#RelatedWork)" section on cover page. + ###### [OData-CSDLXML] _OData Common Schema Definition Language (CSDL) XML Representation Version 4.01_. See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-EDM] +_OData EDM XML Schema_. +See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page. + +###### [OData-EDMX] +_OData EDM XML Schema_. +See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page. + ###### [OData-JSON] _OData JSON Format Version 4.01_. See link in "[Related work](#RelatedWork)" section on cover page. @@ -890,18 +1006,43 @@ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-VocValidation] _OData Vocabularies Version 4.0: Validation Vocabulary_. -See link in "[Related work](#RelatedWork)" section on cover page. +See link in "[Related work](#RelatedWork)" section on cover page.###### [RFC6570] +_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012_. +http://tools.ietf.org/html/rfc6570. -###### [XML-Schema-2] +###### [RFC2119] +_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. +https://www.rfc-editor.org/info/rfc2119. + +###### [RFC6570] +_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, “URI Template”, RFC 6570, March 2012_. +http://tools.ietf.org/html/rfc6570. + +###### [RFC8174] +_Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_. +http://www.rfc-editor.org/info/rfc8174. + +###### [RFC8259] +_Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017_. +http://tools.ietf.org/html/rfc8259. + +###### [XML-1.1] +_Extensible Markup Language (XML) 1.1 (Second Edition)_. F. Yergeau, E. Maler, J. Cowan, T. Bray, C. M. Sperberg-McQueen, J. Paoli, Editors, W3C Recommendation, 16 August 2006. +http://www.w3.org/TR/2006/REC-xml11-20060816. Latest version available at http://www.w3.org/TR/xml11/. + +###### [XML-Base] +_XML Base (Second Edition)_. J. Marsh, R. Tobin, Editors, W3C Recommendation, 28 January 2009. +http://www.w3.org/TR/2009/REC-xmlbase-20090128/. Latest version available at http://www.w3.org/TR/xmlbase/. +###### [XML-Schema-1] +_W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures_. D. Beech, M. Maloney, C. M. Sperberg-McQueen, H. S. Thompson, S. Gao, N. Mendelsohn, Editors, W3C Recommendation, 5 April 2012. +http://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-1/. + +###### [XML-Schema-2] _W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes_. D. Peterson, S. Gao, C. M. Sperberg-McQueen, H. S. Thompson, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 5 April 2012. http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-2/. ## A.2 Informative References -###### [RFC3552] -_Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003_ -https://www.rfc-editor.org/info/rfc3552. - ###### [OpenUI5] _OpenUI5 Version 1.40.10 - OData V4 Metadata JSON Format_. https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a414499b.html. @@ -923,6 +1064,12 @@ https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a4 - [Attribute `TermNamespace`](#AttributeTermNamespace4.1) - [Attribute `Qualifier`](#AttributeQualifier4.2) - [Attribute `TargetNamespace`](#AttributeTargetNamespace4.3) +- [Element `edm:Schema`](#ElementedmSchema5) + - [Attribute `Namespace`](#AttributeNamespace5.1) + - [Attribute `Alias`](#AttributeAlias5.2) +- [Element `edm:Annotations`](#ElementedmAnnotations6) + - [Attribute `Target`](#AttributeTarget6.1) + - [Attribute `Qualifier`](#AttributeQualifier6.2) ::: ------- diff --git a/docs/odata-csdl-xml/styles/odata.css b/docs/odata-csdl-xml/styles/odata.css index 016fcf7f0..a3cafde6b 100644 --- a/docs/odata-csdl-xml/styles/odata.css +++ b/docs/odata-csdl-xml/styles/odata.css @@ -3,18 +3,21 @@ a:target { } a[href^="#OData"], -a[href^="#rfc"] { +a[href^="#rfc"], +a[href^="#XML"] { font-weight: bold; } a[href^="#OData"]::before, -a[href^="#rfc"]::before { +a[href^="#rfc"]::before, +a[href^="#XML"]::before { content: "["; font-weight: bold; } a[href^="#OData"]::after, -a[href^="#rfc"]::after { +a[href^="#rfc"]::after, +a[href^="#XML"]::after { content: "]"; font-weight: bold; } diff --git a/docs/odata-data-aggregation-ext/styles/odata.css b/docs/odata-data-aggregation-ext/styles/odata.css index 016fcf7f0..a3cafde6b 100644 --- a/docs/odata-data-aggregation-ext/styles/odata.css +++ b/docs/odata-data-aggregation-ext/styles/odata.css @@ -3,18 +3,21 @@ a:target { } a[href^="#OData"], -a[href^="#rfc"] { +a[href^="#rfc"], +a[href^="#XML"] { font-weight: bold; } a[href^="#OData"]::before, -a[href^="#rfc"]::before { +a[href^="#rfc"]::before, +a[href^="#XML"]::before { content: "["; font-weight: bold; } a[href^="#OData"]::after, -a[href^="#rfc"]::after { +a[href^="#rfc"]::after, +a[href^="#XML"]::after { content: "]"; font-weight: bold; } diff --git a/docs/odata-json-format/styles/odata.css b/docs/odata-json-format/styles/odata.css index 016fcf7f0..a3cafde6b 100644 --- a/docs/odata-json-format/styles/odata.css +++ b/docs/odata-json-format/styles/odata.css @@ -3,18 +3,21 @@ a:target { } a[href^="#OData"], -a[href^="#rfc"] { +a[href^="#rfc"], +a[href^="#XML"] { font-weight: bold; } a[href^="#OData"]::before, -a[href^="#rfc"]::before { +a[href^="#rfc"]::before, +a[href^="#XML"]::before { content: "["; font-weight: bold; } a[href^="#OData"]::after, -a[href^="#rfc"]::after { +a[href^="#rfc"]::after, +a[href^="#XML"]::after { content: "]"; font-weight: bold; } diff --git a/docs/odata-protocol/styles/odata.css b/docs/odata-protocol/styles/odata.css index 016fcf7f0..a3cafde6b 100644 --- a/docs/odata-protocol/styles/odata.css +++ b/docs/odata-protocol/styles/odata.css @@ -3,18 +3,21 @@ a:target { } a[href^="#OData"], -a[href^="#rfc"] { +a[href^="#rfc"], +a[href^="#XML"] { font-weight: bold; } a[href^="#OData"]::before, -a[href^="#rfc"]::before { +a[href^="#rfc"]::before, +a[href^="#XML"]::before { content: "["; font-weight: bold; } a[href^="#OData"]::after, -a[href^="#rfc"]::after { +a[href^="#rfc"]::after, +a[href^="#XML"]::after { content: "]"; font-weight: bold; } diff --git a/docs/odata-url-conventions/styles/odata.css b/docs/odata-url-conventions/styles/odata.css index 016fcf7f0..a3cafde6b 100644 --- a/docs/odata-url-conventions/styles/odata.css +++ b/docs/odata-url-conventions/styles/odata.css @@ -3,18 +3,21 @@ a:target { } a[href^="#OData"], -a[href^="#rfc"] { +a[href^="#rfc"], +a[href^="#XML"] { font-weight: bold; } a[href^="#OData"]::before, -a[href^="#rfc"]::before { +a[href^="#rfc"]::before, +a[href^="#XML"]::before { content: "["; font-weight: bold; } a[href^="#OData"]::after, -a[href^="#rfc"]::after { +a[href^="#rfc"]::after, +a[href^="#XML"]::after { content: "]"; font-weight: bold; } diff --git a/odata-csdl-json/0 frontmatter.md b/odata-csdl-json/0 frontmatter.md index e7ae7129c..b71a0a9f8 100644 --- a/odata-csdl-json/0 frontmatter.md +++ b/odata-csdl-json/0 frontmatter.md @@ -40,7 +40,7 @@ Heiko Theißen (heiko.theissen@sap.com), [SAP SE](http://www.sap.com/) #### Additional artifacts: This prose specification is one component of a Work Product that also includes: -* XML schemas: (list file names or directory name) +* XML schemas: _OData EDMX XML Schema and OData EDM XML Schema_. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/os/schemas/ * Other parts (list titles and/or file names) * `(Note: Any normative computer language definitions that are part of the Work Product, such as XML instances, schemas and Java(TM) code, including fragments of such, must be (a) well formed and valid, (b) provided in separate plain text files, (c) referenced from the Work Product; and (d) where any definition in these separate files disagrees with the definition found in the specification, the definition in the separate file prevails. Remove this note before submitting for publication.)` @@ -50,8 +50,17 @@ This specification replaces or supersedes: This specification is related to: * _OData Version 4.02_. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes: - * _OData Version 4.02 Part 1: Protocol_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html - * _OData Version 4.02 Part 2: URL Conventions_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html + * _OData Version 4.02 Part 1: Protocol_. Latest stage: https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html + * _OData Version 4.02 Part 2: URL Conventions_. Latest stage: https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html + * _ABNF components: OData ABNF Construction Rules Version 4.01 and OData ABNF Test Cases_. https://docs.oasis-open.org/odata/odata/v4.01/os/abnf/ +* _OData Vocabularies Version 4.0_. Edited by Michael Pizzo, Ralf Handl, and Ram Jeyaraman. Latest stage: https://docs.oasis-open.org/odata/odata-vocabularies/v4.0/odata-vocabularies-v4.0.html +: varxml +* _OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01_. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-json/v4.01/odata-csdl-json-v4.01.html +: +: varjson +* _OData Common Schema Definition Language (CSDL) XML Representation Version 4.01_. Edited by Michael Pizzo, Ralf Handl, and Martin Zurmuehl. Latest stage: https://docs.oasis-open.org/odata/odata-csdl-xml/v4.01/odata-csdl-xml-v4.01.html +: +* _OData JSON Format Version 4.01_. Edited by Ralf Handl, Mike Pizzo, and Mark Biamonte. Latest stage: https://docs.oasis-open.org/odata/odata-json-format/v4.01/odata-json-format-v4.01.html #### Abstract: OData services are described by an Entity Model (EDM). The Common Schema Definition Language (CSDL) defines specific representations of the entity data model exposed by an OData service, using XML, JSON, and other formats. This document (OData CSDL JSON Representation) specifically defines the JSON representation of CSDL. diff --git a/odata-csdl-json/1 Introduction.md b/odata-csdl-json/1 Introduction.md index 196e13337..94295bb1e 100644 --- a/odata-csdl-json/1 Introduction.md +++ b/odata-csdl-json/1 Introduction.md @@ -221,7 +221,7 @@ they have the default value. ## ##subsec JSON Schema Definition The structure of CSDL JSON documents can be verified with the JSON -Schema [OData-CSDL-Schema](#CSDLschema) provided as an +Schema [OData-CSDL-Schema](#ODataCSDL) provided as an additional artifact of this prose specification. This schema only defines the shape of a well-formed CSDL JSON document but is not descriptive enough to define what a correct CSDL JSON document MUST be @@ -236,13 +236,13 @@ this specification document take precedence. OData CSDL XML is a full representation of the OData Common Schema Definition Language in the Extensible Markup Language (XML) 1.1 (Second -Edition) [XML-1.1](#BMXML) with further building blocks from the +Edition) [XML-1.1](#XML11) with further building blocks from the W3C XML Schema Definition Language (XSD) 1.1 as described in -[XML-Schema-1](#BMXMLSchema1) and -[XML-Schema-2](#BMXMLSchema2). +[XML-Schema-1](#XMLSchema1) and +[XML-Schema-2](#XMLSchema2). It is an alternative to the CSDL JSON representation defined in -[OData-CSDLJSON](#BMCSDLJSON) and neither adds nor +[OData-CSDLJSON](#ODataCSDLJSON) and neither adds nor removes features. ## ##subsec Requesting the XML Representation @@ -312,8 +312,8 @@ prescriptive. ## ##subsec XML Schema Definitions This specification contains normative XML schemas for the EDMX and EDM -namespaces; see [OData-EDMX](#BMEDMX) and -[OData-EDM](#BMEDM) +namespaces; see [OData-EDMX](#ODataEDMX) and +[OData-EDM](#ODataEDM) These XML schemas only define the shape of a well-formed CSDL XML document and are not descriptive enough to define what a correct CSDL @@ -443,7 +443,7 @@ Type|Meaning `Edm.GeometryCollection` |Collection of arbitrary Geometry values `Edm.Date` and `Edm.DateTimeOffset` follow -[XML-Schema-2](#XMLSchema) and use the proleptic Gregorian +[XML-Schema-2](#XMLSchema2) and use the proleptic Gregorian calendar, allowing the year `0000` (equivalent to 1 BCE) and negative years (year `-0001` being equivalent to 2 BCE etc.). The supported date range is service-specific and typically depends on the underlying diff --git a/odata-csdl-json/4 CSDL JSON Document.md b/odata-csdl-json/4 CSDL Document.md similarity index 100% rename from odata-csdl-json/4 CSDL JSON Document.md rename to odata-csdl-json/4 CSDL Document.md diff --git a/odata-csdl-json/5 Schema.md b/odata-csdl-json/5 Schema.md new file mode 100644 index 000000000..0b15f6396 --- /dev/null +++ b/odata-csdl-json/5 Schema.md @@ -0,0 +1,186 @@ +------- + +# ##sec Schema + +One or more schemas describe the entity model exposed by an OData +service. The schema acts as a namespace for elements of the entity model +such as entity types, complex types, enumerations and terms. + +A schema is identified by a [namespace](#Namespace). Schema namespaces +MUST be unique within the scope of a document and SHOULD be globally +unique. A schema cannot span more than one document. + +The schema's namespace is combined with the name of elements in the +schema to create unique [qualified names](#QualifiedName), so +identifiers that are used to name types MUST be unique within a +namespace to prevent ambiguity. + +Names are case-sensitive, but service authors SHOULD NOT choose names +that differ only in case. + +The namespace MUST NOT be one of the reserved values `Edm`, `odata`, +`System`, or `Transient`. + +::: {.varjson .rep} +### ##isec Schema Object + +A schema is represented as a member of the document object whose name is +the schema namespace. Its value is an object that MAY contain the +members [`$Alias`](#Alias) and +[`$Annotations`](#AnnotationswithExternalTargeting). + +The schema object MAY contain members representing [entity +types](#EntityType), [complex types](#ComplexType), [enumeration +types](#EnumerationType), [type definitions](#TypeDefinition), +[actions](#Action), [functions](#Function), [terms](#Term), and an +[entity container](#EntityContainer). + +The schema object MAY also contain [annotations](#Annotation) that apply +to the schema itself. +::: + +::: {.varxml .rep} +### ##isec Element `edm:Schema` + +The `edm:Schema` element defines a +schema. It MUST contain the `Namespace` attribute and it MAY +contain the `Alias` attribute. + +It MAY contain elements [`edm:Action`](#Action), +[`edm:Annotations`](#AnnotationswithExternalTargeting), +[`edm:Annotation`](#Annotation), [`edm:ComplexType`](#ComplexType), +[`edm:EntityContainer`](#EntityContainer), +[`edm:EntityType`](#EntityType), [`edm:EnumType`](#EnumerationType), +[`edm:Function`](#Function), [`edm:Term`](#Term), or +[`edm:TypeDefinition`](#TypeDefinition). + +### ##subisec Attribute `Namespace` + +The value of `Namespace` is the namespace of the schema +::: + +## ##subsec Alias + +A schema MAY specify an alias which MUST be a [simple +identifier](#SimpleIdentifier). + +::: varjson +If a schema specifies an alias, the alias MUST be used instead of the +namespace within qualified names throughout the document to identify +model elements of that schema. A mixed use of namespace-qualified names +and alias-qualified names is not allowed. +::: + +::: varxml +If a schema specifies an alias, the alias MAY be used instead of the +namespace within qualified names to identify model elements of that +schema. An alias only provides a more convenient notation, allowing a +short string to be substituted for a long namespace. Every model element +that can be identified via an alias-qualified name can alternatively be +identified via its full namespace-qualified name. +::: + +Aliases are document-global, so all schemas defined within or included +into a document MUST have different aliases, and aliases MUST differ +from the namespaces of all schemas defined within or included into a +document. Aliases defined by a schema can be used throughout the +containing document and are not restricted to the schema that defines +them. + +The alias MUST NOT be one of the reserved values `Edm`, `odata`, +`System`, or `Transient`. + +::: {.varjson .rep} +### ##subisec `$Alias` + +The value of `$Alias` is a string containing the alias for the schema. +::: + +::: {.varjson .example} +Example ##ex: document defining a schema `org.example` with an alias and a +description for the schema +```json +{ +  ... +  "org.example": { +    "$Alias": "self", +    "@Core.Description": "Example schema", +    ... +  }, +  ... +} +``` +::: + +::: {.varxml .rep} +### ##subisec Attribute `Alias` + +The value of `Alias` is a [simple identifier](#SimpleIdentifier). +::: + +::: {.varxml .example} +Example ##ex: schema `org.example` with an alias and a description for the +schema +```xml + +  ... + +``` +::: + +## ##subsec Annotations with External Targeting + +::: {.varjson .rep} +### ##subisec `$Annotations` + +The value of `$Annotations` is an object with one member per [annotation +target](#Target). The member name is a path identifying the [annotation +target](#Target), the member value is an object containing +[annotations](#Annotation) for that target. +::: + +::: {.varjson .example} +Example ##ex: annotations targeting the `Person` type with qualifier +`Tablet` +```json +"org.example": { +  "$Alias": "self", +  "$Annotations": { +    "self.Person": { +      "@Core.Description#Tablet": "Dummy", +      ... +    } +  } +}, +``` +::: + +::: {.varxml .rep} +### ##isec Element `edm:Annotations` + +The `edm:Annotations` element is used to apply a group of annotations to +a single model element. It MUST contain the `Target` attribute and it +MAY contain the `Qualifier` attribute. + +It MUST contain at least one [`edm:Annotation`](#Annotation) element. + +### ##subisec Attribute `Target` + +The value of `Target` is a path expression identifying the [annotation +target](#Target). It MUST resolve to a model element in scope. + +### ##subisec Attribute `Qualifier` + +The value of `Qualifier` is a [simple identifier](#SimpleIdentifier). +::: + +::: {.varxml .example} +Example ##ex: annotations should only be applied to tablet devices +```xml + + + ... + +``` +::: diff --git a/odata-csdl-json/Appendix.md b/odata-csdl-json/Appendix.md index 012c99c08..3b36bd4f4 100644 --- a/odata-csdl-json/Appendix.md +++ b/odata-csdl-json/Appendix.md @@ -12,43 +12,20 @@ While any hyperlinks included in this appendix were valid at the time of publica The following documents are referenced in such a way that some or all of their content constitutes requirements of this document. -`(Reference sources: -For references to IETF RFCs, use the approved citation formats at: -https://docs.oasis-open.org/templates/ietf-rfc-list/ietf-rfc-list.html. -For references to W3C Recommendations, use the approved citation formats at: -https://docs.oasis-open.org/templates/w3c-recommendations-list/w3c-recommendations-list.html. -Remove this note before submitting for publication.)` - ###### [OData-v4.02] - _OData Version 4.02_. Edited by Michael Pizzo, Ralf Handl, and Heiko Theißen. A multi-part Work Product that includes: - _OData Version 4.02 Part 1: Protocol_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part1-protocol.html - _OData Version 4.02 Part 2: URL Conventions_. Latest stage. https://docs.oasis-open.org/odata/odata/v4.02/odata-v4.02-part2-url-conventions.html -###### [RFC2119] -_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. -http://www.rfc-editor.org/info/rfc2119. - -###### [RFC8174] -_Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_. -http://www.rfc-editor.org/info/rfc8174. - -###### [RFC6570] -_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012_. -http://tools.ietf.org/html/rfc6570. - -###### [RFC7493] -_Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015_. -https://tools.ietf.org/html/rfc7493. - -###### [RFC8259] -_Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017_. -http://tools.ietf.org/html/rfc8259. - ###### [ECMAScript] _ECMAScript 2016 Language Specification, 7th Edition_. June 2016. Standard ECMA-262. http://www.ecma-international.org/publications/standards/Ecma-262.htm. ###### [EPSG] -_European Petroleum Survey Group (EPSG)_. http://www.epsg.org/. +_European Petroleum Survey Group (EPSG)_. http://www.epsg.org/.###### [RFC7493] +_Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015_. +https://tools.ietf.org/html/rfc7493.###### [RFC2119] +_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. +http://www.rfc-editor.org/info/rfc2119. ###### [OData-ABNF] _OData ABNF Construction Rules Version 4.01_. @@ -58,10 +35,22 @@ See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page _OData CSDL JSON Schema_. See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-CSDLJSON] +_OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01_. +See link in "[Related work](#RelatedWork)" section on cover page. + ###### [OData-CSDLXML] _OData Common Schema Definition Language (CSDL) XML Representation Version 4.01_. See link in "[Related work](#RelatedWork)" section on cover page. +###### [OData-EDM] +_OData EDM XML Schema_. +See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page. + +###### [OData-EDMX] +_OData EDM XML Schema_. +See link in "[Additional artifacts](#AdditionalArtifacts)" section on cover page. + ###### [OData-JSON] _OData JSON Format Version 4.01_. See link in "[Related work](#RelatedWork)" section on cover page. @@ -84,18 +73,44 @@ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-VocValidation] _OData Vocabularies Version 4.0: Validation Vocabulary_. -See link in "[Related work](#RelatedWork)" section on cover page. +See link in "[Related work](#RelatedWork)" section on cover page.###### [RFC6570] +_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, "URI Template", RFC 6570, March 2012_. +http://tools.ietf.org/html/rfc6570. + +###### [RFC2119] +_Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997_. +https://www.rfc-editor.org/info/rfc2119. + +###### [RFC6570] +_Gregorio, J., Fielding, R., Hadley, M., Nottingham, M., and D. Orchard, “URI Template”, RFC 6570, March 2012_. +http://tools.ietf.org/html/rfc6570. -###### [XML-Schema-2] +###### [RFC8174] +_Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017_. +http://www.rfc-editor.org/info/rfc8174. + +###### [RFC8259] +_Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017_. +http://tools.ietf.org/html/rfc8259. + +###### [XML-1.1] +_Extensible Markup Language (XML) 1.1 (Second Edition)_. F. Yergeau, E. Maler, J. Cowan, T. Bray, C. M. Sperberg-McQueen, J. Paoli, Editors, W3C Recommendation, 16 August 2006. +http://www.w3.org/TR/2006/REC-xml11-20060816. Latest version available at http://www.w3.org/TR/xml11/. + +###### [XML-Base] +_XML Base (Second Edition)_. J. Marsh, R. Tobin, Editors, W3C Recommendation, 28 January 2009. +http://www.w3.org/TR/2009/REC-xmlbase-20090128/. Latest version available at http://www.w3.org/TR/xmlbase/. + +###### [XML-Schema-1] +_W3C XML Schema Definition Language (XSD) 1.1 Part 1: Structures_. D. Beech, M. Maloney, C. M. Sperberg-McQueen, H. S. Thompson, S. Gao, N. Mendelsohn, Editors, W3C Recommendation, 5 April 2012. +http://www.w3.org/TR/2012/REC-xmlschema11-1-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-1/. + +###### [XML-Schema-2] _W3C XML Schema Definition Language (XSD) 1.1 Part 2: Datatypes_. D. Peterson, S. Gao, C. M. Sperberg-McQueen, H. S. Thompson, P. V. Biron, A. Malhotra, Editors, W3C Recommendation, 5 April 2012. http://www.w3.org/TR/2012/REC-xmlschema11-2-20120405/. Latest version available at http://www.w3.org/TR/xmlschema11-2/. ## ##subasec Informative References -###### [RFC3552] -_Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003_ -https://www.rfc-editor.org/info/rfc3552. - ###### [OpenUI5] _OpenUI5 Version 1.40.10 - OData V4 Metadata JSON Format_. https://openui5.hana.ondemand.com/1.40.10/#docs/guide/87aac894a40640f89920d7b2a414499b.html. diff --git a/styles/odata.css b/styles/odata.css index 016fcf7f0..a3cafde6b 100644 --- a/styles/odata.css +++ b/styles/odata.css @@ -3,18 +3,21 @@ a:target { } a[href^="#OData"], -a[href^="#rfc"] { +a[href^="#rfc"], +a[href^="#XML"] { font-weight: bold; } a[href^="#OData"]::before, -a[href^="#rfc"]::before { +a[href^="#rfc"]::before, +a[href^="#XML"]::before { content: "["; font-weight: bold; } a[href^="#OData"]::after, -a[href^="#rfc"]::after { +a[href^="#rfc"]::after, +a[href^="#XML"]::after { content: "]"; font-weight: bold; }