Skip to content

Commit

Permalink
Appendix, Chapter 1 from V4.01
Browse files Browse the repository at this point in the history
  • Loading branch information
@ralfhandl
ralfhandl committed Jul 20, 2023
1 parent 7d38943 commit a644ea0
Show file tree
Hide file tree
Showing 5 changed files with 354 additions and 226 deletions.
6 changes: 6 additions & 0 deletions .vscode/settings.json
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,6 @@
{
"cSpell.words": [
"subsec",
"subsubsec"
]
}
204 changes: 125 additions & 79 deletions docs/odata-json-format/odata-json-format.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -127,47 +127,65 @@ <h1 id="table-of-contents">Table of Contents</h1>
<li><a href="#Participants">C.2 Participants</a></li>
</ul></li>
<li><a href="#RevisionHistory">D Revision History</a></li>
<li><a href="#ExampleAppendixwithsubsections">E Example Appendix with subsections</a>
<ul>
<li><a href="#Subsectiontitle">E.1 Subsection title</a>
<ul>
<li><a href="#Subsubsection">E.1.1 Sub-subsection</a></li>
</ul></li>
</ul></li>
<li><a href="#Notices">F Notices</a></li>
<li><a href="#Notices">E Notices</a></li>
</ul>
</div>
<hr />
<h1 id="1-introduction"><a name="Introduction" href="#Introduction">1 Introduction</a></h1>
<!-- All text is normative unless otherwise labeled -->
<p>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 <a href="#ODataProtocol">OData-Protocol</a>; 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].</p>
<p>An OData JSON payload may represent:</p>
<!--TODO: insert links to sections -->

<p><em>The content in this section is non-normative, except where it is marked normative.</em></p>
<p>Here is a customized command line which will generate HTML from this markdown file (named odata-json-format-v4.02-csd01.md):</p>
<p>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"</p>
<p>OASIS staff are currently using pandoc 3.0 from <a href="https://github.com/jgm/pandoc/releases/tag/3.0">https://github.com/jgm/pandoc/releases/tag/3.0</a>.</p>
<p>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:</p>
<ul>
<li><a href="https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3.css">https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3.css</a></li>
<li><a href="https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3a.css">https://docs.oasis-open.org/templates/css/markdown-styles-v1.7.3a.css</a> (this one produces HTML that resembles the github display more closely, especially for blocks of code)</li>
<li>a single primitive value</li>
<li>a collection of primitive values</li>
<li>a single complex type value</li>
<li>a collection of complex type values</li>
<li>a single entity or entity reference</li>
<li>a collection of entities or entity references</li>
<li>a collection of changes</li>
<li>a service document describing the top-level resources exposed by the service</li>
<li>an error.</li>
</ul>
<p>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.</p>
<h2 id="11-changes-from-earlier-versions"><a name="ChangesfromearlierVersions" href="#ChangesfromearlierVersions">1.1 Changes from earlier Versions</a></h2>
<!-- Optional section -->
<!-- TODO -->

<!-- Describe significant changes from previous differently-numbered Versions, not changes between stages of the current Version -->

<h2 id="12-glossary"><a name="Glossary" href="#Glossary">1.2 Glossary</a></h2>
<!-- Optional section with suggested subsections -->

<h3 id="121-definitions-of-terms"><a name="Definitionsofterms" href="#Definitionsofterms">1.2.1 Definitions of terms</a></h3>
<!-- TODO -->

<h3 id="122-acronyms-and-abbreviations"><a name="Acronymsandabbreviations" href="#Acronymsandabbreviations">1.2.2 Acronyms and abbreviations</a></h3>
<!-- TODO -->

<h3 id="123-document-conventions"><a name="Documentconventions" href="#Documentconventions">1.2.3 Document conventions</a></h3>
<ul>
<li>Naming conventions</li>
<li>Font colors and styles</li>
<li>Typographic conventions</li>
</ul>
<p>Keywords defined by this specification use <code>this monospaced font</code>.</p>
<p>Some sections of this specification are illustrated with non-normative examples.</p>
<div class="example">
<p>Example 1: text describing an example uses this paragraph style</p>
<pre><code>Non-normative examples use this paragraph style.</code></pre>
</div>
<p>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.</p>
<p>All other text is normative unless otherwise labeled.</p>
<div class="example">
<p>Here is a customized command line which will generate HTML from this markdown file (named <code>odata-json-format-v4.02-csd01.md</code>). Line breaks are added for readability only:</p>
<pre><code>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=&quot;OData JSON Format Version 4.02&quot;
odata-json-format-v4.02-csd01.md</code></pre>
<p>This uses pandoc 3.1.2 from <a href="https://github.com/jgm/pandoc/releases/tag/3.1.2">https://github.com/jgm/pandoc/releases/tag/3.1.2</a>.</p>
</div>
<hr />
<!--TODO from here -->

<h1 id="2-section-heading"><a name="SectionHeading" href="#SectionHeading">2 Section Heading</a></h1>
<p>text.</p>
<h2 id="21-level-2-heading"><a name="LevelHeading" href="#LevelHeading">2.1 Level 2 Heading</a></h2>
Expand All @@ -189,67 +207,64 @@ <h1 id="3-conformance"><a name="Conformance" href="#Conformance">3 Conformance</
<p><code>Remove this note before submitting for publication.)</code></p>
<hr />
<h1 id="appendix-a-references"><a name="References" href="#References">Appendix A. References</a></h1>
<!-- Required section -->

<p>This appendix contains the normative and informative references that are used in this document.</p>
<p>While any hyperlinks included in this appendix were valid at the time of publication, OASIS cannot guarantee their long-term validity.</p>
<h2 id="a1-normative-references"><a name="NormativeReferences" href="#NormativeReferences">A.1 Normative References</a></h2>
<p>The following documents are referenced in such a way that some or all of their content constitutes requirements of this document.</p>
<h6 id="odata-abnf"><a name="ODataABNF">[OData-ABNF]</a></h6>
<p><em>ABNF components: OData ABNF Construction Rules Version 4.01 and OData ABNF Test Cases.</em><br />
<p><em>ABNF components: OData ABNF Construction Rules Version 4.02 and OData ABNF Test Cases.</em><br />
See link in "<a href="#RelatedWork">Related work</a>" section on cover page.</p>
<h6 id="odata-csdl"><a name="ODataCSDL">[OData-CSDL]</a></h6>
<p><em>OData Common Schema Definition Language (CSDL) JSON Representation Version 4.01.</em><br />
<p><em>OData Common Schema Definition Language (CSDL) JSON Representation Version 4.02.</em><br />
See link in "<a href="#RelatedWork">Related work</a>" section on cover page.</p>
<p><em>OData Common Schema Definition Language (CSDL) XML Representation Version 4.01.</em><br />
See link in "<a href="#RelatedWork">Related work</a>" section on cover page.</p>
<h6 id="odata-json"><a name="ODataJSON">[OData-JSON]</a></h6>
<p><em>OData JSON Format Version 4.01.</em><br />
<p><em>OData Common Schema Definition Language (CSDL) XML Representation Version 4.02.</em><br />
See link in "<a href="#RelatedWork">Related work</a>" section on cover page.</p>
<h6 id="odata-protocol"><a name="ODataProtocol">[OData-Protocol]</a></h6>
<p><em>OData Version 4.01. Part 1: Protocol.</em><br />
<p><em>OData Version 4.02. Part 1: Protocol.</em><br />
See link in "<a href="#RelatedWork">Related work</a>" section on cover page.</p>
<h6 id="odata-url"><a name="ODataURL">[OData-URL]</a></h6>
<p><em>OData Version 4.01. Part 2: URL Conventions.</em><br />
<p><em>OData Version 4.02. Part 2: URL Conventions.</em><br />
See link in "<a href="#RelatedWork">Related work</a>" section on cover page.</p>
<h6 id="odata-voccap"><a name="ODataVocCap">[OData-VocCap]</a></h6>
<p><em>OData Vocabularies Version 4.0: Capabilities Vocabulary.</em><br />
See link in "<a href="#RelatedWork">Related work</a>" section on cover page.</p>
<h6 id="odata-voccore"><a name="ODataVocCore">[OData-VocCore]</a></h6>
<p><em>OData Core Vocabulary.</em><br />
<p><em>OData Vocabularies Version 4.0: Core Vocabulary.</em><br />
See link in "<a href="#RelatedWork">Related work</a>" section on cover page.</p>
<h6 id="rfc2119"><a name="rfc2119">[RFC2119]</a></h6>
<p><em>Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997</em><br />
<a href="https://www.rfc-editor.org/info/rfc2119">https://www.rfc-editor.org/info/rfc2119</a>.</p>
<h6 id="rfc3986"><a name="rfc3986">[RFC3986]</a></h6>
<p><em>Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", IETF RFC3986, January 2005</em> <a href="https://tools.ietf.org/html/rfc3986">https://tools.ietf.org/html/rfc3986</a>.</p>
<h6 id="rfc3987"><a name="rfc3987">[RFC3987]</a></h6>
<p><em>Duerst, M. and, M. Suignard, "Internationalized Resource Identifiers (IRIs)", RFC 3987, January 2005</em> <a href="https://tools.ietf.org/html/rfc3987">https://tools.ietf.org/html/rfc3987</a>.</p>
<h6 id="rfc4648"><a name="rfc4648">[RFC4648]</a></h6>
<p><em>Josefsson, S,, "The Base16, Base32, and Base64 Data Encodings", RFC 4648, October 2006</em> _<a href="https://tools.ietf.org/html/rfc4648">https://tools.ietf.org/html/rfc4648</a>.</p>
<h6 id="rfc5646"><a name="rfc5646">[RFC5646]</a></h6>
<p><em>Phillips, A., Ed., and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, September 2009</em> <a href="http://tools.ietf.org/html/rfc5646">http://tools.ietf.org/html/rfc5646</a>.</p>
<h6 id="a-namerfc74932rfc7493">&lt;a name="rfc74932&gt;[RFC7493]</a></h6>
<p><em>Bray, T., Ed., "The I-JSON Message Format", RFC7493, March 2015</em> <a href="https://tools.ietf.org/html/rfc7493">https://tools.ietf.org/html/rfc7493</a>.</p>
<h6 id="rfc7946"><a name="rfc7946">[RFC7946]</a></h6>
<p><em>Howard Butler, Martin Daly, Alan Doyle, Sean Gillies, Stefan Hagen and Tim Schaub, "The GeoJSON Format", RFC 7946, August 2016.</em> <a href="http://tools.ietf.org/html/rfc7946">http://tools.ietf.org/html/rfc7946</a>.</p>
<h6 id="rfc8174"><a name="rfc8174">[RFC8174]</a></h6>
<p><em>Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017</em><br />
<a href="https://www.rfc-editor.org/info/rfc8174">https://www.rfc-editor.org/info/rfc8174</a>.</p>
<h6 id="rfc8259"><a name="rfc8259">[RFC8259]</a></h6>
<p><em>Bray, T., Ed., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 8259, December 2017</em> _<a href="http://tools.ietf.org/html/rfc8259">http://tools.ietf.org/html/rfc8259</a>.</p>
<h2 id="a2-informative-references-"><a name="InformativeReferences" href="#InformativeReferences">A.2 Informative References </a></h2>
<!--TODO: remove -->

<h6 id="rfc3552"><a name="rfc3552">[RFC3552]</h6>
<p>Rescorla, E. and B. Korver, "Guidelines for Writing RFC Text on Security Considerations", BCP 72, RFC 3552, DOI 10.17487/RFC3552, July 2003, <a href="https://www.rfc-editor.org/info/rfc3552">https://www.rfc-editor.org/info/rfc3552</a>.</p>
<h6 id="ecmascript"><a name="ECMAScript">[ECMAScript]</a></h6>
<p><em>ECMAScript 2023 Language Specification, 14th Edition</em>, June 2023. Standard ECMA-262. <a href="https://www.ecma-international.org/publications-and-standards/standards/ecma-262/">https://www.ecma-international.org/publications-and-standards/standards/ecma-262/</a>.</p>
<hr />
<h1 id="appendix-b-safety-security-and-privacy-considerations"><a name="SafetySecurityandPrivacyConsiderations" href="#SafetySecurityandPrivacyConsiderations">Appendix B. Safety, Security and Privacy Considerations</a></h1>
<!-- Optional section -->

<p><code>(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.</code></p>
<p><code>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.</code></p>
<p><code>In addition to considering and describing foreseeable risks, this section should include guidance on how implementers and adopters can protect against these risks.</code></p>
<p><code>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.</code></p>
<p><code>Remove this note before submitting for publication.)</code></p>
<p>This specification raises no security issues.</p>
<p>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.</p>
<p>For JSON-relevant security implications please cf. at least the relevant subsections of <a href="#rfc8259">RFC8259</a> as starting point.</p>
<hr />
<h1 id="appendix-c-acknowledgments"><a name="Acknowledgments" href="#Acknowledgments">Appendix C. Acknowledgments</a></h1>
<!-- Required section -->

<p><code>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.</code></p>
<h2 id="c1-special-thanks"><a name="SpecialThanks" href="#SpecialThanks">C.1 Special Thanks</a></h2>
<!-- This is an optional subsection to call out contributions from TC members. If a TC wants to thank non-TC members then they should avoid using the term "contribution" and instead thank them for their "expertise" or "assistance". -->

<p>Substantial contributions to this document from the following individuals are gratefully acknowledged:</p>
<p>Participant Name, Affiliation or "Individual Member"</p>
<p>The contributions of the OASIS OData Technical Committee members, enumerated in <a href="#ODataProtocol">OData-Protocol</a> are gratefully acknowledged.</p>
<h2 id="c2-participants"><a name="Participants" href="#Participants">C.2 Participants</a></h2>
<!-- A TC can determine who they list here, however, TC Observers must not be listed. It is common practice for TCs to list everyone that was part of the TC during the creation of the document, but this is ultimately a TC decision on who they want to list and not list, and in what order. -->

<p>The following individuals have participated in the creation of this specification and are gratefully acknowledged:</p>
<p><strong>OpenC2 TC Members:</strong></p>
<p><strong>OData TC Members:</strong></p>
<table>
<thead>
<tr class="header">
Expand All @@ -260,24 +275,59 @@ <h2 id="c2-participants"><a name="Participants" href="#Participants">C.2 Partici
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">Philippe</td>
<td style="text-align: left;">Alman</td>
<td style="text-align: left;">Something Networks</td>
<td style="text-align: left;">George</td>
<td style="text-align: left;">Ericson</td>
<td style="text-align: left;">Dell</td>
</tr>
<tr class="even">
<td style="text-align: left;">Hubert</td>
<td style="text-align: left;">Heijkers</td>
<td style="text-align: left;">IBM</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Ling</td>
<td style="text-align: left;">Jin</td>
<td style="text-align: left;">IBM</td>
</tr>
<tr class="even">
<td style="text-align: left;">Stefan</td>
<td style="text-align: left;">Hagen</td>
<td style="text-align: left;">Individual</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Michael</td>
<td style="text-align: left;">Pizzo</td>
<td style="text-align: left;">Microsoft</td>
</tr>
<tr class="even">
<td style="text-align: left;">Christof</td>
<td style="text-align: left;">Sprenger</td>
<td style="text-align: left;">Microsoft</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Ralf</td>
<td style="text-align: left;">Handl</td>
<td style="text-align: left;">SAP SE</td>
</tr>
<tr class="even">
<td style="text-align: left;">Alex</td>
<td style="text-align: left;">Amirnovman</td>
<td style="text-align: left;">Company B</td>
<td style="text-align: left;">Gerald</td>
<td style="text-align: left;">Krause</td>
<td style="text-align: left;">SAP SE</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Kris</td>
<td style="text-align: left;">Anderman</td>
<td style="text-align: left;">Mini Micro</td>
<td style="text-align: left;">Heiko</td>
<td style="text-align: left;">Theißen</td>
<td style="text-align: left;">SAP SE</td>
</tr>
<tr class="even">
<td style="text-align: left;">Darren</td>
<td style="text-align: left;">Anstman</td>
<td style="text-align: left;">Big Networks</td>
<td style="text-align: left;">Mark</td>
<td style="text-align: left;">Biamonte</td>
<td style="text-align: left;">Progress Software</td>
</tr>
<tr class="odd">
<td style="text-align: left;">Martin</td>
<td style="text-align: left;">Zurmühl</td>
<td style="text-align: left;">SAP SE</td>
</tr>
</tbody>
</table>
Expand All @@ -296,19 +346,15 @@ <h1 id="appendix-d-revision-history"><a name="RevisionHistory" href="#RevisionHi
</thead>
<tbody>
<tr class="odd">
<td style="text-align: left;">specname-v1.0-wd01</td>
<td style="text-align: left;">yyyy-mm-dd</td>
<td style="text-align: left;">Editor Name</td>
<td style="text-align: left;">Initial working draft</td>
<td style="text-align: left;">Working Draft 01</td>
<td style="text-align: left;">2023-07-20</td>
<td style="text-align: left;">Ralf Handl</td>
<td style="text-align: left;">Import material from OData JSON Format Version 4.01</td>
</tr>
</tbody>
</table>
<hr />
<h1 id="appendix-e-example-appendix-with-subsections"><a name="ExampleAppendixwithsubsections" href="#ExampleAppendixwithsubsections">Appendix E. Example Appendix with subsections</a></h1>
<h2 id="e1-subsection-title"><a name="Subsectiontitle" href="#Subsectiontitle">E.1 Subsection title</a></h2>
<h3 id="e11-sub-subsection"><a name="Subsubsection" href="#Subsubsection">E.1.1 Sub-subsection</a></h3>
<hr />
<h1 id="appendix-f-notices"><a name="Notices" href="#Notices">Appendix F. Notices</a></h1>
<h1 id="appendix-e-notices"><a name="Notices" href="#Notices">Appendix E. Notices</a></h1>
<!-- Required section. Do not modify. -->

<p>Copyright © OASIS Open 2023. All Rights Reserved.</p>
Expand Down
Loading

0 comments on commit a644ea0

Please sign in to comment.