From a644ea03c4aeaf993de7b4f06a230c6ecf3940a0 Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Thu, 20 Jul 2023 17:41:11 +0200 Subject: [PATCH] Appendix, Chapter 1 from V4.01 --- .vscode/settings.json | 6 + docs/odata-json-format/odata-json-format.html | 204 +++++++++++------- docs/odata-json-format/odata-json-format.md | 188 +++++++++------- odata-json-format/1 Introduction.md | 73 +++++-- odata-json-format/Appendix.md | 109 +++++----- 5 files changed, 354 insertions(+), 226 deletions(-) create mode 100644 .vscode/settings.json diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 00000000..a8b76a97 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,6 @@ +{ + "cSpell.words": [ + "subsec", + "subsubsec" + ] +} diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index e16cfdb0..5dfa5f7e 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -127,47 +127,65 @@

Table of Contents

  • C.2 Participants
  • D Revision History
    • -
  • E Example Appendix with subsections -
    • -
  • F Notices
    • +
  • E Notices

    • 1 Introduction

    - +

    The OData protocol is comprised of a set of specifications for representing and interacting with structured content. The core specification for the protocol is in OData-Protocol; this document is an extension of the core protocol. This document defines representations for the OData requests and responses using the JavaScript Object Notation (JSON), see [RFC8259].

    +

    An OData JSON payload may represent:

    + -

    The content in this section is non-normative, except where it is marked normative.

    -

    Here is a customized command line which will generate HTML from this markdown file (named odata-json-format-v4.02-csd01.md):

    -

    pandoc -f gfm -t html odata-json-format-v4.02-csd01.md -c styles/markdown-styles-v1.7.3b.css --toc --toc-depth=5 -s -o odata-json-format-v4.02-csd01.html --metadata title="OData JSON Format Version 4.02"

    -

    OASIS staff are currently using pandoc 3.0 from https://github.com/jgm/pandoc/releases/tag/3.0.

    -

    Generating HTML in OASIS style requires a reference to a .css file containing the HTML styles. The .css file may be either included with the markdown file (like styles/markdown-styles-v1.7.3b.css) or a reference to one of the online stylesheets:

    -

    Note this command generates a Table of Contents (TOC) in HTML which is located at the top of the HTML document, and which requires additional editing in order to be published in the expected OASIS style. This editing can be handled by OASIS staff during publication. A TC may use other ways to generate HTML from markdown, which may generate a TOC in a different way.

    1.1 Changes from earlier Versions

    - +

    1.2 Glossary

    - -

    1.2.1 Definitions of terms

    + +

    1.2.2 Acronyms and abbreviations

    + +

    1.2.3 Document conventions

    - +

    Keywords defined by this specification use this monospaced font.

    +

    Some sections of this specification are illustrated with non-normative examples.

    +
    +

    Example 1: text describing an example uses this paragraph style

    +
    Non-normative examples use this paragraph style.
    +
    +

    All examples in this document are non-normative and informative only. Examples labeled with ⚠ contain advanced concepts or make use of keywords that are defined only later in the text, they can be skipped at first reading.

    +

    All other text is normative unless otherwise labeled.

    +
    +

    Here is a customized command line which will generate HTML from this markdown file (named odata-json-format-v4.02-csd01.md). Line breaks are added for readability only:

    +
    pandoc -f gfm+tex_math_dollars+fenced_divs
+       -t html
+       -o odata-json-format-v4.02-csd01.html
+       -c styles/markdown-styles-v1.7.3b.css
+       -c styles/odata.css
+       -s
+       --mathjax
+       --eol=lf
+       --wrap=none
+       --metadata pagetitle="OData JSON Format Version 4.02"
+       odata-json-format-v4.02-csd01.md
    +

    This uses pandoc 3.1.2 from https://github.com/jgm/pandoc/releases/tag/3.1.2.

    +
    + +

    2 Section Heading

    text.

    2.1 Level 2 Heading

    @@ -189,67 +207,64 @@

    3 ConformanceRemove this note before submitting for publication.)

    Appendix A. References

    - -

    This appendix contains the normative and informative references that are used in this document.

    While any hyperlinks included in this appendix were valid at the time of publication, OASIS cannot guarantee their long-term validity.

    A.1 Normative References

    The following documents are referenced in such a way that some or all of their content constitutes requirements of this document.

    [OData-ABNF]
    -

    ABNF components: OData ABNF Construction Rules Version 4.01 and OData ABNF Test Cases.
    +

    ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases.
    See link in "Related work" section on cover page.

    [OData-CSDL]
    -

    OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01.
    +

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

    -

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

    -
    [OData-JSON]
    -

    OData JSON Format Version 4.01.
    +

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

    [OData-Protocol]
    -

    OData Version 4.01. Part 1: Protocol.
    +

    OData Version 4.02. Part 1: Protocol.
    See link in "Related work" section on cover page.

    [OData-URL]
    -

    OData Version 4.01. Part 2: URL Conventions.
    +

    OData Version 4.02. Part 2: URL Conventions.
    +See link in "Related work" section on cover page.

    +
    [OData-VocCap]
    +

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

    [OData-VocCore]
    -

    OData Core Vocabulary.
    +

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

    [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.

    +
    [RFC3986]
    +

    Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", IETF RFC3986, January 2005 https://tools.ietf.org/html/rfc3986.

    +
    [RFC3987]
    +

    Duerst, M. and, M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005 https://tools.ietf.org/html/rfc3987.

    +
    [RFC4648]
    +

    Josefsson, S,, "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006 _https://tools.ietf.org/html/rfc4648.

    +
    [RFC5646]
    +

    Phillips, A., Ed., and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009 http://tools.ietf.org/html/rfc5646.

    +
    <a name="rfc74932>[RFC7493]
    +

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

    +
    [RFC7946]
    +

    Howard Butler, Martin Daly, Alan Doyle, Sean Gillies, Stefan Hagen and Tim Schaub, "The GeoJSON Format", RFC 7946, August 2016. http://tools.ietf.org/html/rfc7946.

    [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.

    +
    [RFC8259]
    +

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

    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.

    +
    [ECMAScript]
    +

    ECMAScript 2023 Language Specification, 14th Edition, June 2023. Standard ECMA-262. https://www.ecma-international.org/publications-and-standards/standards/ecma-262/.

    Appendix B. Safety, Security and Privacy Considerations

    - - -

    (Note: OASIS strongly recommends that Technical Committees consider issues that might affect safety, security, privacy, and/or data protection in implementations of their specification and document them for implementers and adopters. For some purposes, you may find it required, e.g. if you apply for IANA registration.

    -

    While it may not be immediately obvious how your specification might make systems vulnerable to attack, most specifications, because they involve communications between systems, message formats, or system settings, open potential channels for exploit. For example, IETF [[RFC3552](#rfc3552)] lists “eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle” as well as potential denial of service attacks as threats that must be considered and, if appropriate, addressed in IETF RFCs.

    -

    In addition to considering and describing foreseeable risks, this section should include guidance on how implementers and adopters can protect against these risks.

    -

    We encourage editors and TC members concerned with this subject to read _Guidelines for Writing RFC Text on Security Considerations_, IETF [[RFC3552](#rfc3552)], for more information.

    -

    Remove this note before submitting for publication.)

    +

    This specification raises no security issues.

    +

    This section is provided as a service to the application developers, information providers, and users of OData version 4.0 giving some references to starting points for securing OData services as specified. OData is a REST-full multi-format service that depends on other services and thus inherits both sides of the coin, security enhancements and concerns alike from the latter.

    +

    For JSON-relevant security implications please cf. at least the relevant subsections of RFC8259 as starting point.

    Appendix C. Acknowledgments

    - - -

    Note: A Work Product approved by the TC must include a list of people who participated in the development of the Work Product. This is generally done by collecting the list of names in this appendix. This list shall be initially compiled by the Chair, and any Member of the TC may add or remove their names from the list by request. Remove this note before submitting for publication.

    C.1 Special Thanks

    - - -

    Substantial contributions to this document from the following individuals are gratefully acknowledged:

    -

    Participant Name, Affiliation or "Individual Member"

    +

    The contributions of the OASIS OData Technical Committee members, enumerated in OData-Protocol are gratefully acknowledged.

    C.2 Participants

    - - -

    The following individuals have participated in the creation of this specification and are gratefully acknowledged:

    -

    OpenC2 TC Members:

    +

    OData TC Members:

    @@ -260,24 +275,59 @@

    C.2 Partici

    - - - + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + - - - + + + - - - + + + - - - + + + + + + + +
    PhilippeAlmanSomething NetworksGeorgeEricsonDell
    HubertHeijkersIBM
    LingJinIBM
    StefanHagenIndividual
    MichaelPizzoMicrosoft
    ChristofSprengerMicrosoft
    RalfHandlSAP SE
    AlexAmirnovmanCompany BGeraldKrauseSAP SE
    KrisAndermanMini MicroHeikoTheißenSAP SE
    DarrenAnstmanBig NetworksMarkBiamonteProgress Software
    MartinZurmühlSAP SE
    @@ -296,19 +346,15 @@

    -specname-v1.0-wd01 -yyyy-mm-dd -Editor Name -Initial working draft +Working Draft 01 +2023-07-20 +Ralf Handl +Import material from OData JSON Format Version 4.01
    -

    Appendix E. Example Appendix with subsections

    -

    E.1 Subsection title

    -

    E.1.1 Sub-subsection

    -
    -

    Appendix F. Notices

    +

    Appendix E. Notices

    Copyright © OASIS Open 2023. All Rights Reserved.

    diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index e4aa0b9b..6addc7fe 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -112,54 +112,84 @@ For complete copyright information please see the full Notices section in an App - [C.1 Special Thanks](#SpecialThanks) - [C.2 Participants](#Participants) - [D Revision History](#RevisionHistory) -- [E Example Appendix with subsections](#ExampleAppendixwithsubsections) - - [E.1 Subsection title](#Subsectiontitle) - - [E.1.1 Sub-subsection](#Subsubsection) -- [F Notices](#Notices) +- [E Notices](#Notices) ::: ------- # 1 Introduction - -*The content in this section is non-normative, except where it is marked -normative.* +The OData protocol is comprised of a set of specifications for representing and interacting with structured content. The core specification for the protocol is in [OData-Protocol](#ODataProtocol); this document is an extension of the core protocol. This document defines representations for the OData requests and responses using the JavaScript Object Notation (JSON), see [RFC8259]. -Here is a customized command line which will generate HTML from this markdown file (named odata-json-format-v4.02-csd01.md): +An OData JSON payload may represent: -pandoc -f gfm -t html odata-json-format-v4.02-csd01.md -c styles/markdown-styles-v1.7.3b.css --toc --toc-depth=5 -s -o odata-json-format-v4.02-csd01.html --metadata title="OData JSON Format Version 4.02" - -OASIS staff are currently using pandoc 3.0 from https://github.com/jgm/pandoc/releases/tag/3.0. - -Generating HTML in OASIS style requires a reference to a .css file containing the HTML styles. The .css file may be either included with the markdown file (like styles/markdown-styles-v1.7.3b.css) or a reference to one of the online stylesheets: -- https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3.css -- https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3a.css (this one produces HTML that resembles the github display more closely, especially for blocks of code) - -Note this command generates a Table of Contents (TOC) in HTML which is located at the top of the HTML document, and which requires additional editing in order to be published in the expected OASIS style. This editing can be handled by OASIS staff during publication. -A TC may use other ways to generate HTML from markdown, which may generate a TOC in a different way. + +- a single primitive value +- a collection of primitive values +- a single complex type value +- a collection of complex type values +- a single entity or entity reference +- a collection of entities or entity references +- a collection of changes +- a service document describing the top-level resources exposed by the service +- an error. ## 1.1 Changes from earlier Versions - + ## 1.2 Glossary - - ### 1.2.1 Definitions of terms + + ### 1.2.2 Acronyms and abbreviations + + ### 1.2.3 Document conventions -- Naming conventions -- Font colors and styles -- Typographic conventions +Keywords defined by this specification use `this monospaced font`. + +Some sections of this specification are illustrated with non-normative examples. + +::: example +Example 1: text describing an example uses this paragraph style +``` +Non-normative examples use this paragraph style. +``` +::: + +All examples in this document are non-normative and informative only. Examples labeled with ⚠ contain advanced concepts or make use of keywords that are defined only later in the text, they can be skipped at first reading. + +All other text is normative unless otherwise labeled. + +::: example +Here is a customized command line which will generate HTML from this markdown file (named `odata-json-format-v4.02-csd01.md`). Line breaks are added for readability only: + +``` +pandoc -f gfm+tex_math_dollars+fenced_divs + -t html + -o odata-json-format-v4.02-csd01.html + -c styles/markdown-styles-v1.7.3b.css + -c styles/odata.css + -s + --mathjax + --eol=lf + --wrap=none + --metadata pagetitle="OData JSON Format Version 4.02" + odata-json-format-v4.02-csd01.md +``` + +This uses pandoc 3.1.2 from https://github.com/jgm/pandoc/releases/tag/3.1.2. +::: ------- + + # 2 Section Heading text. @@ -197,8 +227,6 @@ https://docs.oasis-open.org/templates/TCHandbook/ConformanceGuidelines.html.` # Appendix A. References - - This appendix contains the normative and informative references that are used in this document. While any hyperlinks included in this appendix were valid at the time of publication, OASIS cannot guarantee their long-term validity. @@ -208,92 +236,108 @@ 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. ###### [OData-ABNF] -_ABNF components: OData ABNF Construction Rules Version 4.01 and OData ABNF Test Cases._ +_ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-CSDL] -_OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01._ -See link in "[Related work](#RelatedWork)" section on cover page. - -_OData Common Schema Definition Language (CSDL) XML Representation Version 4.01._ +_OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. -###### [OData-JSON] -_OData JSON Format Version 4.01._ +_OData Common Schema Definition Language (CSDL) XML Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-Protocol] -_OData Version 4.01. Part 1: Protocol._ +_OData Version 4.02. Part 1: Protocol._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-URL] -_OData Version 4.01. Part 2: URL Conventions._ +_OData Version 4.02. Part 2: URL Conventions._ +See link in "[Related work](#RelatedWork)" section on cover page. + +###### [OData-VocCap] +_OData Vocabularies Version 4.0: Capabilities Vocabulary._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-VocCore] -_OData Core Vocabulary._ +_OData Vocabularies Version 4.0: Core Vocabulary._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [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. +###### [RFC3986] +_Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", IETF RFC3986, January 2005_ +https://tools.ietf.org/html/rfc3986. + +###### [RFC3987] +_Duerst, M. and, M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005_ +https://tools.ietf.org/html/rfc3987. + +###### [RFC4648] +_Josefsson, S,, "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006_ +_https://tools.ietf.org/html/rfc4648. + +###### [RFC5646] +_Phillips, A., Ed., and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009_ +http://tools.ietf.org/html/rfc5646. + +###### [RFC7946] +_Howard Butler, Martin Daly, Alan Doyle, Sean Gillies, Stefan Hagen and Tim Schaub, "The GeoJSON Format", RFC 7946, August 2016._ +http://tools.ietf.org/html/rfc7946. + ###### [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. +###### [RFC8259] +_Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017_ +_http://tools.ietf.org/html/rfc8259. + ## 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. +###### [ECMAScript] +_ECMAScript 2023 Language Specification, 14th Edition_, June 2023. Standard ECMA-262. https://www.ecma-international.org/publications-and-standards/standards/ecma-262/. ------- # Appendix B. Safety, Security and Privacy Considerations - - -`(Note: OASIS strongly recommends that Technical Committees consider issues that might affect safety, security, privacy, and/or data protection in implementations of their specification and document them for implementers and adopters. For some purposes, you may find it required, e.g. if you apply for IANA registration.` - -`While it may not be immediately obvious how your specification might make systems vulnerable to attack, most specifications, because they involve communications between systems, message formats, or system settings, open potential channels for exploit. For example, IETF [[RFC3552](#rfc3552)] lists “eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle” as well as potential denial of service attacks as threats that must be considered and, if appropriate, addressed in IETF RFCs.` +This specification raises no security issues. -`In addition to considering and describing foreseeable risks, this section should include guidance on how implementers and adopters can protect against these risks.` +This section is provided as a service to the application developers, information providers, and users of OData version 4.0 giving some references to starting points for securing OData services as specified. OData is a REST-full multi-format service that depends on other services and thus inherits both sides of the coin, security enhancements and concerns alike from the latter. -`We encourage editors and TC members concerned with this subject to read _Guidelines for Writing RFC Text on Security Considerations_, IETF [[RFC3552](#rfc3552)], for more information.` - -`Remove this note before submitting for publication.)` +For JSON-relevant security implications please cf. at least the relevant subsections of [RFC8259](#rfc8259) as starting point. ------- # Appendix C. Acknowledgments - - -`Note: A Work Product approved by the TC must include a list of people who participated in the development of the Work Product. This is generally done by collecting the list of names in this appendix. This list shall be initially compiled by the Chair, and any Member of the TC may add or remove their names from the list by request. Remove this note before submitting for publication.` - ## C.1 Special Thanks - - -Substantial contributions to this document from the following individuals are gratefully acknowledged: - -Participant Name, Affiliation or "Individual Member" +The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. ## C.2 Participants - - -The following individuals have participated in the creation of this specification and are gratefully acknowledged: - -**OpenC2 TC Members:** +**OData TC Members:** | First Name | Last Name | Company | | :--- | :--- | :--- | -Philippe | Alman | Something Networks -Alex | Amirnovman | Company B -Kris | Anderman | Mini Micro -Darren | Anstman | Big Networks +| George | Ericson | Dell | +| Hubert | Heijkers | IBM | +| Ling | Jin | IBM | +| Stefan | Hagen | Individual | +| Michael | Pizzo | Microsoft | +| Christof | Sprenger | Microsoft | +| Ralf | Handl | SAP SE | +| Gerald | Krause | SAP SE | +| Heiko | Theißen | SAP SE | +| Mark | Biamonte | Progress Software | +| Martin | Zurmühl | SAP SE | ------- @@ -303,19 +347,11 @@ Darren | Anstman | Big Networks | Revision | Date | Editor | Changes Made | | :--- | :--- | :--- | :--- | -| specname-v1.0-wd01 | yyyy-mm-dd | Editor Name | Initial working draft | - -------- - -# Appendix E. Example Appendix with subsections - -## E.1 Subsection title - -### E.1.1 Sub-subsection +| Working Draft 01 | 2023-07-20 | Ralf Handl | Import material from OData JSON Format Version 4.01 | ------- -# Appendix F. Notices +# Appendix E. Notices diff --git a/odata-json-format/1 Introduction.md b/odata-json-format/1 Introduction.md index ebc1de8b..3a479a8e 100644 --- a/odata-json-format/1 Introduction.md +++ b/odata-json-format/1 Introduction.md @@ -2,44 +2,77 @@ # ##sec Introduction - -*The content in this section is non-normative, except where it is marked -normative.* +The OData protocol is comprised of a set of specifications for representing and interacting with structured content. The core specification for the protocol is in [OData-Protocol](#ODataProtocol); this document is an extension of the core protocol. This document defines representations for the OData requests and responses using the JavaScript Object Notation (JSON), see [RFC8259]. -Here is a customized command line which will generate HTML from this markdown file (named odata-json-format-v4.02-csd01.md): +An OData JSON payload may represent: -pandoc -f gfm -t html odata-json-format-v4.02-csd01.md -c styles/markdown-styles-v1.7.3b.css --toc --toc-depth=5 -s -o odata-json-format-v4.02-csd01.html --metadata title="OData JSON Format Version 4.02" - -OASIS staff are currently using pandoc 3.0 from https://github.com/jgm/pandoc/releases/tag/3.0. - -Generating HTML in OASIS style requires a reference to a .css file containing the HTML styles. The .css file may be either included with the markdown file (like styles/markdown-styles-v1.7.3b.css) or a reference to one of the online stylesheets: -- https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3.css -- https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3a.css (this one produces HTML that resembles the github display more closely, especially for blocks of code) - -Note this command generates a Table of Contents (TOC) in HTML which is located at the top of the HTML document, and which requires additional editing in order to be published in the expected OASIS style. This editing can be handled by OASIS staff during publication. -A TC may use other ways to generate HTML from markdown, which may generate a TOC in a different way. + +- a single primitive value +- a collection of primitive values +- a single complex type value +- a collection of complex type values +- a single entity or entity reference +- a collection of entities or entity references +- a collection of changes +- a service document describing the top-level resources exposed by the service +- an error. ## ##subsec Changes from earlier Versions - + ## ##subsec Glossary - - ### ##subsubsec Definitions of terms + + ### ##subsubsec Acronyms and abbreviations + + ### ##subsubsec Document conventions -- Naming conventions -- Font colors and styles -- Typographic conventions +Keywords defined by this specification use `this monospaced font`. + +Some sections of this specification are illustrated with non-normative examples. + +::: example +Example ##ex: text describing an example uses this paragraph style +``` +Non-normative examples use this paragraph style. +``` +::: + +All examples in this document are non-normative and informative only. Examples labeled with ⚠ contain advanced concepts or make use of keywords that are defined only later in the text, they can be skipped at first reading. + +All other text is normative unless otherwise labeled. + +::: example +Here is a customized command line which will generate HTML from this markdown file (named `$$$filename$$$.md`). Line breaks are added for readability only: + +``` +pandoc -f gfm+tex_math_dollars+fenced_divs + -t html + -o $$$filename$$$.html + -c styles/markdown-styles-v1.7.3b.css + -c styles/odata.css + -s + --mathjax + --eol=lf + --wrap=none + --metadata pagetitle="$$$pagetitle$$$" + $$$filename$$$.md +``` + +This uses pandoc 3.1.2 from https://github.com/jgm/pandoc/releases/tag/3.1.2. +::: ------- + + # ##sec Section Heading text. diff --git a/odata-json-format/Appendix.md b/odata-json-format/Appendix.md index edddb1bd..82f9e1e3 100644 --- a/odata-json-format/Appendix.md +++ b/odata-json-format/Appendix.md @@ -3,8 +3,6 @@ # Appendix ##asec References - - This appendix contains the normative and informative references that are used in this document. While any hyperlinks included in this appendix were valid at the time of publication, OASIS cannot guarantee their long-term validity. @@ -14,92 +12,109 @@ 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. ###### [OData-ABNF] -_ABNF components: OData ABNF Construction Rules Version 4.01 and OData ABNF Test Cases._ +_ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-CSDL] -_OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01._ -See link in "[Related work](#RelatedWork)" section on cover page. - -_OData Common Schema Definition Language (CSDL) XML Representation Version 4.01._ +_OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. -###### [OData-JSON] -_OData JSON Format Version 4.01._ +_OData Common Schema Definition Language (CSDL) XML Representation Version 4.02._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-Protocol] -_OData Version 4.01. Part 1: Protocol._ +_OData Version 4.02. Part 1: Protocol._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-URL] -_OData Version 4.01. Part 2: URL Conventions._ +_OData Version 4.02. Part 2: URL Conventions._ +See link in "[Related work](#RelatedWork)" section on cover page. + +###### [OData-VocCap] +_OData Vocabularies Version 4.0: Capabilities Vocabulary._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [OData-VocCore] -_OData Core Vocabulary._ +_OData Vocabularies Version 4.0: Core Vocabulary._ See link in "[Related work](#RelatedWork)" section on cover page. ###### [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. +###### [RFC3986] +_Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", IETF RFC3986, January 2005_ +https://tools.ietf.org/html/rfc3986. + +###### [RFC3987] +_Duerst, M. and, M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005_ +https://tools.ietf.org/html/rfc3987. + +###### [RFC4648] +_Josefsson, S,, "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006_ +_https://tools.ietf.org/html/rfc4648. + +###### [RFC5646] +_Phillips, A., Ed., and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009_ +http://tools.ietf.org/html/rfc5646. + +###### [RFC7946] +_Howard Butler, Martin Daly, Alan Doyle, Sean Gillies, Stefan Hagen and Tim Schaub, "The GeoJSON Format", RFC 7946, August 2016._ +http://tools.ietf.org/html/rfc7946. + ###### [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. +###### [RFC8259] +_Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017_ +_http://tools.ietf.org/html/rfc8259. + ## ##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. +###### [ECMAScript] +_ECMAScript 2023 Language Specification, 14th Edition_, June 2023. Standard ECMA-262. +https://www.ecma-international.org/publications-and-standards/standards/ecma-262/. ------- # Appendix ##asec Safety, Security and Privacy Considerations - - -`(Note: OASIS strongly recommends that Technical Committees consider issues that might affect safety, security, privacy, and/or data protection in implementations of their specification and document them for implementers and adopters. For some purposes, you may find it required, e.g. if you apply for IANA registration.` +This specification raises no security issues. -`While it may not be immediately obvious how your specification might make systems vulnerable to attack, most specifications, because they involve communications between systems, message formats, or system settings, open potential channels for exploit. For example, IETF [[RFC3552](#rfc3552)] lists “eavesdropping, replay, message insertion, deletion, modification, and man-in-the-middle” as well as potential denial of service attacks as threats that must be considered and, if appropriate, addressed in IETF RFCs.` +This section is provided as a service to the application developers, information providers, and users of OData version 4.0 giving some references to starting points for securing OData services as specified. OData is a REST-full multi-format service that depends on other services and thus inherits both sides of the coin, security enhancements and concerns alike from the latter. -`In addition to considering and describing foreseeable risks, this section should include guidance on how implementers and adopters can protect against these risks.` - -`We encourage editors and TC members concerned with this subject to read _Guidelines for Writing RFC Text on Security Considerations_, IETF [[RFC3552](#rfc3552)], for more information.` - -`Remove this note before submitting for publication.)` +For JSON-relevant security implications please cf. at least the relevant subsections of [RFC8259](#rfc8259) as starting point. ------- # Appendix ##asec Acknowledgments - - -`Note: A Work Product approved by the TC must include a list of people who participated in the development of the Work Product. This is generally done by collecting the list of names in this appendix. This list shall be initially compiled by the Chair, and any Member of the TC may add or remove their names from the list by request. Remove this note before submitting for publication.` - ## ##subasec Special Thanks - - -Substantial contributions to this document from the following individuals are gratefully acknowledged: - -Participant Name, Affiliation or "Individual Member" +The contributions of the OASIS OData Technical Committee members, enumerated in [OData-Protocol](#ODataProtocol) are gratefully acknowledged. ## ##subasec Participants - - -The following individuals have participated in the creation of this specification and are gratefully acknowledged: - -**OpenC2 TC Members:** +**OData TC Members:** | First Name | Last Name | Company | | :--- | :--- | :--- | -Philippe | Alman | Something Networks -Alex | Amirnovman | Company B -Kris | Anderman | Mini Micro -Darren | Anstman | Big Networks +| George | Ericson | Dell | +| Hubert | Heijkers | IBM | +| Ling | Jin | IBM | +| Stefan | Hagen | Individual | +| Michael | Pizzo | Microsoft | +| Christof | Sprenger | Microsoft | +| Ralf | Handl | SAP SE | +| Gerald | Krause | SAP SE | +| Heiko | Theißen | SAP SE | +| Mark | Biamonte | Progress Software | +| Martin | Zurmühl | SAP SE | ------- @@ -109,15 +124,7 @@ Darren | Anstman | Big Networks | Revision | Date | Editor | Changes Made | | :--- | :--- | :--- | :--- | -| specname-v1.0-wd01 | yyyy-mm-dd | Editor Name | Initial working draft | - -------- - -# Appendix ##asec Example Appendix with subsections - -## ##subasec Subsection title - -### ##subsubasec Sub-subsection +| Working Draft 01 | 2023-07-20 | Ralf Handl | Import material from OData JSON Format Version 4.01 | -------