SYSMOAS11 — Correct incomplete content negotiation mapping for lossless CBOR representations

The REST/HTTP endpoint mapping in Section 8.1.3 does not adequately specify how implementations may negotiate a lossless binary representation of the existing API payloads. The mapping should distinguish the API’s logical request and response content from its JSON wire encoding and explicitly permit equivalent CBOR representations through HTTP content negotiation.

This omission creates an interoperability and scalability problem. Large model payloads contain repeated property names, metaclass names, textual identifiers, and reference objects. Transmitting these structures exclusively as JSON imposes substantial representation overhead, particularly for bulk model retrieval and synchronization. Implementations can use more compact binary representations internally, but the specification provides no clear interoperable mapping for negotiating those representations at the REST/HTTP boundary.

An existing implementation demonstrates the practical significance of this problem. Its lossless, schema-aware CBOR representation produces full-form payloads approximately 10.9–11.6 times smaller than minified full JSON, and approximately 1.78 times smaller when both representations are deflate-compressed. These measurements demonstrate reduced transfer and storage requirements; they do not establish a universal encoding or decoding speed improvement.

Proposed correction

Add the following representation and content-negotiation rules to Section 8.1.3, and align the corresponding normative OpenAPI definitions:

“JSON support shall remain required wherever specified by this REST/HTTP mapping. An implementation may additionally support lossless CBOR representations of the request and response payloads defined by this mapping.

A client shall indicate acceptable response representations using the HTTP Accept header and shall identify the representation of a request body using the Content-Type header. A server shall identify the selected response representation using Content-Type and shall include Accept in Vary when response representation selection depends on that header.

Alternative representations shall preserve the logical payload defined for the operation, including element identities, property values, references, collection ordering where significant, and distinctions between absent properties, null values, and empty collections. Selection of a representation shall not change the operation’s semantics or validation requirements.

CBOR representations shall conform to RFC 8949 and shall use a media type that unambiguously identifies their encoding contract. Direct CBOR encodings of the existing JSON structures may use application/cbor with a defined JSON-to-CBOR mapping. Schema-aware encodings that replace property names, metaclass names, or references with codes or indices shall use a distinct media type or explicitly identified profile defining those mappings and their versioning.

Unsupported request representations and unacceptable response representations shall be handled using the applicable HTTP semantics for 415 Unsupported Media Type and 406 Not Acceptable.”

This correction addresses the completeness of the existing REST/HTTP representation mapping. It introduces no new service operations or model semantics and preserves interoperability with existing JSON clients. It permits efficient implementations to expose equivalent binary representations without requiring every implementation to support CBOR.

The existing implementation uses application/vnd.sysmlv2.s2c+cbor for its schema-aware encoding. This illustrates why adding application/cbor alone is insufficient: generic CBOR syntax does not define the application-specific field codes, reference indices, defaults, or version tables needed to interpret such a payload. The implementation’s media type is currently unregistered and is cited as implementation evidence, rather than proposed here as an already standardized OMG format.

Reference: RFC 8949, Concise Binary Object Representation (CBOR), https://www.rfc-editor.org/rfc/rfc8949.html
see https://github.com/Open-MBEE/sysml-toolkit for a reference implementation to convert textual syntax to CBOR and back