From 9f311a919c157c44a415af624be5b37926fe336f Mon Sep 17 00:00:00 2001 From: Ralf Handl Date: Fri, 21 Jul 2023 12:46:01 +0200 Subject: [PATCH] Split out empty parts --- docs/odata-json-format/odata-json-format.html | 4 +- docs/odata-json-format/odata-json-format.md | 4 +- lib/number.js | 26 +- odata-json-format/1 Introduction.md | 328 ------------------ odata-json-format/23 Conformance.md | 133 +++++++ odata-json-format/3 to 22 TODO.md | 193 +++++++++++ 6 files changed, 355 insertions(+), 333 deletions(-) create mode 100644 odata-json-format/23 Conformance.md create mode 100644 odata-json-format/3 to 22 TODO.md diff --git a/docs/odata-json-format/odata-json-format.html b/docs/odata-json-format/odata-json-format.html index 4eb3a4f7..687b0660 100644 --- a/docs/odata-json-format/odata-json-format.html +++ b/docs/odata-json-format/odata-json-format.html @@ -272,8 +272,6 @@

https://github.com/jgm/pandoc/releases/tag/3.1.2.

- -

2 JSON Format Design

JSON, as described in RFC8259 defines a text format for serializing structured data. Objects are serialized as an unordered collection of name/value pairs.

JSON does not define any semantics around the name/value pairs that make up an object, nor does it define an extensibility mechanism for adding control information to a payload.

@@ -282,6 +280,8 @@

Payload Ordering Constraints.

+ +

3 Requesting the JSON Format

3.1 Controlling the Amount of Control Information in Responses

3.1.1 metadata=minimal (odata.metadata=minimal)

diff --git a/docs/odata-json-format/odata-json-format.md b/docs/odata-json-format/odata-json-format.md index 2be84f12..d71284e4 100644 --- a/docs/odata-json-format/odata-json-format.md +++ b/docs/odata-json-format/odata-json-format.md @@ -260,8 +260,6 @@ This uses pandoc 3.1.2 from https://github.com/jgm/pandoc/releases/tag/3.1.2. ------- - - # 2 JSON Format Design JSON, as described in [RFC8259](#rfc8259) defines @@ -304,6 +302,8 @@ Constraints](#PayloadOrderingConstraints). ------- + + # 3 Requesting the JSON Format ## 3.1 Controlling the Amount of Control Information in Responses diff --git a/lib/number.js b/lib/number.js index 97888e2c..6490c612 100644 --- a/lib/number.js +++ b/lib/number.js @@ -2,13 +2,37 @@ const { createInterface } = require("readline"); const fs = require("fs"); const yaml = require("js-yaml"); +function compareSectionNumbers(a, b) { + // Split section numbers into parts + const partsA = a.split(" ")[0].split("."); + const partsB = b.split(" ")[0].split("."); + + // Compare each part of the section numbers + for (let i = 0; i < Math.max(partsA.length, partsB.length); i++) { + const partA = parseInt(partsA[i]); + const partB = parseInt(partsB[i]); + + //TODO: if both partA and partB are NaN, compare lexicographically + + if (partA < partB) { + return -1; + } else if (partA > partB) { + return 1; + } + } + + // If all parts are equal, compare the lengths of the section numbers + return partsA.length - partsB.length; +} + class Number { constructor(dir) { this.dir = dir; this.chapters = fs .readdirSync(dir) .filter((fn) => fn.endsWith(".md")) - .sort(); + .sort(compareSectionNumbers); + // console.log(this.chapters); this.meta = yaml.load(fs.readFileSync(dir + "/meta.yaml")); } diff --git a/odata-json-format/1 Introduction.md b/odata-json-format/1 Introduction.md index bf17fc98..e4893a27 100644 --- a/odata-json-format/1 Introduction.md +++ b/odata-json-format/1 Introduction.md @@ -72,8 +72,6 @@ This uses pandoc 3.1.2 from https://github.com/jgm/pandoc/releases/tag/3.1.2. ------- - - # ##sec JSON Format Design JSON, as described in [RFC8259](#rfc8259) defines @@ -113,329 +111,3 @@ To optimize streaming scenarios, there are a few restrictions that MAY be imposed on the sequence in which name/value pairs appear within JSON objects. For details on the ordering requirements see [Payload Ordering Constraints](#PayloadOrderingConstraints). - -------- - -# ##sec Requesting the JSON Format - -## ##subsec Controlling the Amount of Control Information in Responses - -### ##subsubsec `metadata=minimal` (`odata.metadata=minimal`) - -### ##subsubsec `metadata=full` (`odata.metadata=full`) - -### ##subsubsec `metadata=none` (`odata.metadata=none`) - -## ##subsec Controlling the Representation of Numbers - -------- - -# ##sec Common Characteristics - -# ##subsec Header Content-Type - -# ##subsec Message Body - -# ##subsec Relative URLs - -# ##subsec Payload Ordering Constraints - -# ##subsec Control Information - -# ##subsubsec Control Information: `context` (`odata.context`) - -# ##subsubsec Control Information: `metadataEtag` (`odata.metadataEtag`) - -# ##subsubsec Control Information: `type` (`odata.type`) - -# ##subsubsec Control Information: `count` (`odata.count`) - -# ##subsubsec Control Information: `nextLink` (`odata.nextLink`) - -# ##subsubsec Control Information: `delta` (`odata.delta`) - -# ##subsubsec Control Information: `deltaLink` (`odata.deltaLink`) - -# ##subsubsec Control Information: `id` (`odata.id`) - -# ##subsubsec Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`) - -# ##subsubsec Control Information: `etag` (`odata.etag`) - -# ##subsubsec Control Information: `navigationLink` and `associationLink` (`odata.navigationLink` and `odata.associationLink`) - -# ##subsubsec Control Information: `media*` (`odata.media*`) - -# ##subsubsec Control Information: `removed` (`odata.removed`) - -# ##subsubsec Control Information: `collectionAnnotations` (`odata.collectionAnnotations`) - -------- - -# ##sec Service Document - -------- - -# ##sec Entity - -------- - -# ##sec Structural Property - -# ##subsec Primitive Value - -# ##subsec Complex Value - -# ##subsec Collection of Primitive Values - -# ##subsec Collection of Complex Values - -# ##subsec Untyped Value - -------- - -# ##sec Navigation Property - -# ##subsec Navigation Link - -# ##subsec Association Link - -# ##subsec Expanded Navigation Property - -# ##subsec Deep Insert - -# ##subsec Bind Operation - -# ##subsec Collection ETag - -------- - -# ##sec Stream Property - -------- - -# ##sec Media Entity - -------- - -# ##sec Individual Property or Operation Response - -------- - -# ##sec Collection of Operation Responses - -------- - -# ##sec Collection of Entities - -------- - -# ##sec Entity Reference - -------- - -# ##sec Delta Payload - -# ##subsec Delta Responses - -# ##subsec Added/Changed Entity - -# ##subsec Deleted Entity - -# ##subsec Added Link - -# ##subsec Deleted Link - -# ##subsec Update a Collection of Entities - -------- - -# ##sec Bound Function - -------- - -# ##sec Bound Action - -------- - -# ##sec Action Invocation - -------- - -# ##sec Batch Requests and Responses - -# ##subsec Batch Request - -# ##subsec Referencing New Entities - -# ##subsec Referencing an ETag - -# ##subsec Processing a Batch Request - -# ##subsec Batch Response - -# ##subsec Asynchronous Batch Requests - -------- - -# ##sec Instance Annotations - -# ##subsec Annotate a JSON Object - -# ##subsec Annotate a JSON Array or Primitive - -# ##subsec Annotate a Primitive Value within a JSON Array - -------- - -# ##sec Error Handling - -# ##subsec Error Response - -# ##subsec In-Stream Error - -# ##subsec Error Information in a Success Payload - -# ##subsubsec Primitive Value Errors - -# ##subsubsec Structured Type Errors - -# ##subsubsec Collection Errors - -------- - -# ##sec Extensibility - -------- - -# ##sec Conformance - -Conforming clients MUST be prepared to consume a service that uses any or all of the constructs defined in this specification. The exception to this are the constructs defined in Delta Response, which are only required for clients that request changes. - - - -In order to be a conforming consumer of the OData JSON format, a client or service: - -1. MUST either: - 1. understand `metadata=minimal` (section 3.1.1) or - 2. explicitly specify `metadata=none` (section 3.1.3) or `metadata=full` (section 3.1.2) in the request (client) - -2. MUST be prepared to consume a response with full metadata -3. MUST be prepared to receive all data types (section 7.1) - - 1. defined in this specification (client) - 2. exposed by the service (service) - -4. MUST interpret all `odata` control information defined according to the `OData-Version` header of the payload (section 4.5) - -5. MUST be prepared to receive any annotations and control information not defined in the `OData-Version` header of the payload (section 21.2) - -6. MUST NOT require `streaming=true` in the `Content-Type` header (section 4.4) - -7. MUST be a conforming consumer of the OData 4.0 JSON format, for payloads with an `OData-Version` header value of `4.0`. - - 1. MUST accept the `odata.` prefix, where defined, on format parameters and control information - - 2. MUST accept the `#` prefix in `@odata.type` values - - 3. MUST be prepared to handle binding through the use of the `@odata.bind` property in payloads to a `PATCH`, `PUT`, or `POST` request - - 4. MUST accept `TargetId` within in a deleted link for a relationship with a maximum cardinality of one - - 5. MUST accept the string values `-INF`, `INF`, and `NaN` for single and double values - - 6. MUST support property annotations that appear immediately before or after the property they annotate - -8. MAY be a conforming consumer of the OData 4.01 JSON format, for payloads with an `OData-Version` header value of `4.01`. - - 1. MUST be prepared to interpret control information with or without the `odata.` prefix - - 2. MUST be prepared for `@odata.type` primitive values with or without the `#` prefix - - 3. MUST be prepared to handle binding through inclusion of an entity reference within a collection-valued navigation property in the body of a `PATCH`, `PUT`, or `POST` request - - 4. MUST be prepared for `TargetId` to be included or omitted in a deleted link for a relationship with a maximum cardinality of one - - 5. MUST accept the string values `-INF`, `INF`, and `NaN` for decimal values with floating scale - - 6. MUST be prepared to handle related entities inline within a delta payload as well as a nested delta representation for the collection - - 7. MUST be prepared to handle decimal values written in exponential notation - - -In order to be a conforming producer of the OData JSON format, a client or service: - -9. MUST support generating OData 4.0 JSON compliant payloads with an `OData-Version` header value of `4.0`. - - 1. MUST NOT omit the `odata.` prefix from format parameters or control information - - 2. MUST NOT omit the `#` prefix from `@odata.type` values - - 3. MUST NOT include entity values or entity references within a collection-valued navigation property in the body of a `PATCH`, `PUT`, or `POST` request - - 4. MUST NOT return decimal values written in exponential notation unless the ExponentialDecimals format parameter is specified. - - 5. MUST NOT advertise available actions or functions using name/value pairs prefixed with a property name - - 6. MUST NOT return a null value for name/value pairs representing actions or functions that are not available - - 7. MUST NOT represent numeric value exceptions for values other than single and double values using the string values `-INF`, `INF`, and `NaN` - -10. MAY support generating OData 4.01 JSON compliant payloads for requests with an `OData-Version` header value of `4.01`. - - 1. MUST return property annotations immediately before the property they annotate - - 2. SHOULD omit the `odata.` prefix from format parameters and control information - - 3. SHOULD omit the `#` prefix from `@type` primitive values - - 4. MAY include inline related entities or nested delta collections within a delta payload - - 5. MAY include `TargetId` within a deleted link for a relationship with a maximum cardinality of 1 - - 6. MAY return decimal values written in exponential notation - - 7. MAY represent numeric value exceptions for decimal values with floating scale using the string values `-INF`, `INF`, and `NaN` - -In addition, in order to conform to the OData JSON format, a service: - -11. MUST comply with one of the conformance levels defined in [OData-Protocol](#ODataProtocol) - -12. MUST support the `application/json` media type in the `Accept` header (section 3) - -13. MUST return well-formed JSON payloads - -14. MUST support `odata.metadata=full` (section 3.1.2) - -15. MUST include the `odata.nextLink` control information in partial results for entity collections (section 4.5.5) - -16. MUST support entity instances with external metadata (section 4.5.1) - -17. MUST support properties with externally defined data types (section 4.5.3) - -18. MUST NOT violate any other aspects of this OData JSON specification - -19. SHOULD support the `$format` system query option (section 3) - -20. MAY support the `odata.streaming=true` parameter in the `Accept` header (section 4.4) - -21. MAY return full metadata regardless of `odata.metadata` (section 3.1.2) - -22. MUST NOT omit null or default values unless the `omit-values` preference is specified in the `Prefer` request header and the `omit-values` preference is included in the `Preference-Applied` response header - -23. MUST return OData JSON 4.0-compliant responses for requests with an `OData-MaxVersion` header value of `4.0` - -24. MUST support OData JSON 4.0-compliant payloads in requests with an `OData-Version` header value of `4.0` - -25. MUST support returning, in the final response to an asynchronous request, the `application/json` payload that would have been returned had the operation completed synchronously, wrapped in an `application/http` message - - -In addition, in order to comply with the OData 4.01 JSON format, a service: - -26. SHOULD return the OData JSON 4.01 format for requests with an `OData-MaxVersion` header value of `4.01` - -27. MUST support the OData JSON 4.01 format in request payloads for requests with an `OData-Version` header value of `4.01` - -28. MUST honor the `odata.etag` control information within `PUT`, `PATCH` or `DELETE` payloads, if specified - -29. MUST support returning, in the final response to an asynchronous request, the `application/json` payload that would have been returned had the operation completed synchronously diff --git a/odata-json-format/23 Conformance.md b/odata-json-format/23 Conformance.md new file mode 100644 index 00000000..9ed87701 --- /dev/null +++ b/odata-json-format/23 Conformance.md @@ -0,0 +1,133 @@ +------- + +# ##sec Conformance + +Conforming clients MUST be prepared to consume a service that uses any or all of the constructs defined in this specification. The exception to this are the constructs defined in Delta Response, which are only required for clients that request changes. + + + +In order to be a conforming consumer of the OData JSON format, a client or service: + +1. MUST either: + 1. understand `metadata=minimal` (section 3.1.1) or + 2. explicitly specify `metadata=none` (section 3.1.3) or `metadata=full` (section 3.1.2) in the request (client) + +2. MUST be prepared to consume a response with full metadata +3. MUST be prepared to receive all data types (section 7.1) + + 1. defined in this specification (client) + 2. exposed by the service (service) + +4. MUST interpret all `odata` control information defined according to the `OData-Version` header of the payload (section 4.5) + +5. MUST be prepared to receive any annotations and control information not defined in the `OData-Version` header of the payload (section 21.2) + +6. MUST NOT require `streaming=true` in the `Content-Type` header (section 4.4) + +7. MUST be a conforming consumer of the OData 4.0 JSON format, for payloads with an `OData-Version` header value of `4.0`. + + 1. MUST accept the `odata.` prefix, where defined, on format parameters and control information + + 2. MUST accept the `#` prefix in `@odata.type` values + + 3. MUST be prepared to handle binding through the use of the `@odata.bind` property in payloads to a `PATCH`, `PUT`, or `POST` request + + 4. MUST accept `TargetId` within in a deleted link for a relationship with a maximum cardinality of one + + 5. MUST accept the string values `-INF`, `INF`, and `NaN` for single and double values + + 6. MUST support property annotations that appear immediately before or after the property they annotate + +8. MAY be a conforming consumer of the OData 4.01 JSON format, for payloads with an `OData-Version` header value of `4.01`. + + 1. MUST be prepared to interpret control information with or without the `odata.` prefix + + 2. MUST be prepared for `@odata.type` primitive values with or without the `#` prefix + + 3. MUST be prepared to handle binding through inclusion of an entity reference within a collection-valued navigation property in the body of a `PATCH`, `PUT`, or `POST` request + + 4. MUST be prepared for `TargetId` to be included or omitted in a deleted link for a relationship with a maximum cardinality of one + + 5. MUST accept the string values `-INF`, `INF`, and `NaN` for decimal values with floating scale + + 6. MUST be prepared to handle related entities inline within a delta payload as well as a nested delta representation for the collection + + 7. MUST be prepared to handle decimal values written in exponential notation + + +In order to be a conforming producer of the OData JSON format, a client or service: + +9. MUST support generating OData 4.0 JSON compliant payloads with an `OData-Version` header value of `4.0`. + + 1. MUST NOT omit the `odata.` prefix from format parameters or control information + + 2. MUST NOT omit the `#` prefix from `@odata.type` values + + 3. MUST NOT include entity values or entity references within a collection-valued navigation property in the body of a `PATCH`, `PUT`, or `POST` request + + 4. MUST NOT return decimal values written in exponential notation unless the ExponentialDecimals format parameter is specified. + + 5. MUST NOT advertise available actions or functions using name/value pairs prefixed with a property name + + 6. MUST NOT return a null value for name/value pairs representing actions or functions that are not available + + 7. MUST NOT represent numeric value exceptions for values other than single and double values using the string values `-INF`, `INF`, and `NaN` + +10. MAY support generating OData 4.01 JSON compliant payloads for requests with an `OData-Version` header value of `4.01`. + + 1. MUST return property annotations immediately before the property they annotate + + 2. SHOULD omit the `odata.` prefix from format parameters and control information + + 3. SHOULD omit the `#` prefix from `@type` primitive values + + 4. MAY include inline related entities or nested delta collections within a delta payload + + 5. MAY include `TargetId` within a deleted link for a relationship with a maximum cardinality of 1 + + 6. MAY return decimal values written in exponential notation + + 7. MAY represent numeric value exceptions for decimal values with floating scale using the string values `-INF`, `INF`, and `NaN` + +In addition, in order to conform to the OData JSON format, a service: + +11. MUST comply with one of the conformance levels defined in [OData-Protocol](#ODataProtocol) + +12. MUST support the `application/json` media type in the `Accept` header (section 3) + +13. MUST return well-formed JSON payloads + +14. MUST support `odata.metadata=full` (section 3.1.2) + +15. MUST include the `odata.nextLink` control information in partial results for entity collections (section 4.5.5) + +16. MUST support entity instances with external metadata (section 4.5.1) + +17. MUST support properties with externally defined data types (section 4.5.3) + +18. MUST NOT violate any other aspects of this OData JSON specification + +19. SHOULD support the `$format` system query option (section 3) + +20. MAY support the `odata.streaming=true` parameter in the `Accept` header (section 4.4) + +21. MAY return full metadata regardless of `odata.metadata` (section 3.1.2) + +22. MUST NOT omit null or default values unless the `omit-values` preference is specified in the `Prefer` request header and the `omit-values` preference is included in the `Preference-Applied` response header + +23. MUST return OData JSON 4.0-compliant responses for requests with an `OData-MaxVersion` header value of `4.0` + +24. MUST support OData JSON 4.0-compliant payloads in requests with an `OData-Version` header value of `4.0` + +25. MUST support returning, in the final response to an asynchronous request, the `application/json` payload that would have been returned had the operation completed synchronously, wrapped in an `application/http` message + + +In addition, in order to comply with the OData 4.01 JSON format, a service: + +26. SHOULD return the OData JSON 4.01 format for requests with an `OData-MaxVersion` header value of `4.01` + +27. MUST support the OData JSON 4.01 format in request payloads for requests with an `OData-Version` header value of `4.01` + +28. MUST honor the `odata.etag` control information within `PUT`, `PATCH` or `DELETE` payloads, if specified + +29. MUST support returning, in the final response to an asynchronous request, the `application/json` payload that would have been returned had the operation completed synchronously diff --git a/odata-json-format/3 to 22 TODO.md b/odata-json-format/3 to 22 TODO.md new file mode 100644 index 00000000..d75ce49c --- /dev/null +++ b/odata-json-format/3 to 22 TODO.md @@ -0,0 +1,193 @@ +------- + + + +# ##sec Requesting the JSON Format + +## ##subsec Controlling the Amount of Control Information in Responses + +### ##subsubsec `metadata=minimal` (`odata.metadata=minimal`) + +### ##subsubsec `metadata=full` (`odata.metadata=full`) + +### ##subsubsec `metadata=none` (`odata.metadata=none`) + +## ##subsec Controlling the Representation of Numbers + +------- + +# ##sec Common Characteristics + +# ##subsec Header Content-Type + +# ##subsec Message Body + +# ##subsec Relative URLs + +# ##subsec Payload Ordering Constraints + +# ##subsec Control Information + +# ##subsubsec Control Information: `context` (`odata.context`) + +# ##subsubsec Control Information: `metadataEtag` (`odata.metadataEtag`) + +# ##subsubsec Control Information: `type` (`odata.type`) + +# ##subsubsec Control Information: `count` (`odata.count`) + +# ##subsubsec Control Information: `nextLink` (`odata.nextLink`) + +# ##subsubsec Control Information: `delta` (`odata.delta`) + +# ##subsubsec Control Information: `deltaLink` (`odata.deltaLink`) + +# ##subsubsec Control Information: `id` (`odata.id`) + +# ##subsubsec Control Information: `editLink` and `readLink` (`odata.editLink` and `odata.readLink`) + +# ##subsubsec Control Information: `etag` (`odata.etag`) + +# ##subsubsec Control Information: `navigationLink` and `associationLink` (`odata.navigationLink` and `odata.associationLink`) + +# ##subsubsec Control Information: `media*` (`odata.media*`) + +# ##subsubsec Control Information: `removed` (`odata.removed`) + +# ##subsubsec Control Information: `collectionAnnotations` (`odata.collectionAnnotations`) + +------- + +# ##sec Service Document + +------- + +# ##sec Entity + +------- + +# ##sec Structural Property + +# ##subsec Primitive Value + +# ##subsec Complex Value + +# ##subsec Collection of Primitive Values + +# ##subsec Collection of Complex Values + +# ##subsec Untyped Value + +------- + +# ##sec Navigation Property + +# ##subsec Navigation Link + +# ##subsec Association Link + +# ##subsec Expanded Navigation Property + +# ##subsec Deep Insert + +# ##subsec Bind Operation + +# ##subsec Collection ETag + +------- + +# ##sec Stream Property + +------- + +# ##sec Media Entity + +------- + +# ##sec Individual Property or Operation Response + +------- + +# ##sec Collection of Operation Responses + +------- + +# ##sec Collection of Entities + +------- + +# ##sec Entity Reference + +------- + +# ##sec Delta Payload + +# ##subsec Delta Responses + +# ##subsec Added/Changed Entity + +# ##subsec Deleted Entity + +# ##subsec Added Link + +# ##subsec Deleted Link + +# ##subsec Update a Collection of Entities + +------- + +# ##sec Bound Function + +------- + +# ##sec Bound Action + +------- + +# ##sec Action Invocation + +------- + +# ##sec Batch Requests and Responses + +# ##subsec Batch Request + +# ##subsec Referencing New Entities + +# ##subsec Referencing an ETag + +# ##subsec Processing a Batch Request + +# ##subsec Batch Response + +# ##subsec Asynchronous Batch Requests + +------- + +# ##sec Instance Annotations + +# ##subsec Annotate a JSON Object + +# ##subsec Annotate a JSON Array or Primitive + +# ##subsec Annotate a Primitive Value within a JSON Array + +------- + +# ##sec Error Handling + +# ##subsec Error Response + +# ##subsec In-Stream Error + +# ##subsec Error Information in a Success Payload + +# ##subsubsec Primitive Value Errors + +# ##subsubsec Structured Type Errors + +# ##subsubsec Collection Errors + +------- + +# ##sec Extensibility