XML Returns Incorrectly Wrapped with Outer Tag

[brian-comply0]

Description

For the GET method dealing with the following endpoints, the XML return incorrectly wraps the OSCAL content with an outer tag, resulting in non-OSCAL content being returned:

• GET /{model-name}/{identifier}
• GET /{model-name}/{identifier}/snapshot/{identifier}
• GET /profile/{identifier}/resolved-snapshot/{identifier}
• GET /profile/{id}/resolved-catalog [Added April 10]

The returned content for the above should be valid OSCAL content. Wrapping the content with an additional outer tag prevents our goal of pointing to OSCAL content via API endpoints from within other OSCAL files.

NOTE, this issue is related specifically to the XML return definition. For all three formats, the root element name is incorrectly modified for snapshots. #77 addresses that issue. Both #77 and this issue need to be resolved before snapshots of XML content will return valid OSCAL.

Acceptance Criteria [Added April 10]

The following endpoints have their XML return values adjusted to be exactly OSCAL content and nothing more. The result should no longer be wrapped in an extra outer tag:

• GET /{model-name}/{identifier}
• GET /{model-name}/{identifier}/snapshot/{identifier}
• GET /profile/{identifier}/resolved-snapshot/{identifier}
• GET /profile/{id}/resolved-profile

[brian-comply0]

This StackOverflow Article seems to describe the situation and offer possible resolution. It's almost six years old, so there may be better solutions available now.

In summary, it clarifies that Swagger handles JSON and XML schemas differently, thus simply pointing for the same schema for both XML and JSON will yield different results. In this case, the JSON return is rendered correct, but the XML return is wrapped.

The recommended solution is to have a different schema definition for XM. Can Swagger use the NIST-published XML schema definitions for the XML responses? (oscal_model-name_schema.xsd)

NOTE: There appear to also be multiple unaddressed issues open in the Swagger API repo related to this issue:

• Issues with output of XmlElementWrapper in swagger-ui 3.x swagger-api/swagger-ui#2907
• Example for Wrapped Xml array elements is generated incorrectly swagger-api/swagger-ui#4274

[brian-comply0]

2024-02-07 deferring until controls internal MVP is achieved. Moving to next sprint just to track.

[brian-comply0]

Made good progress on the collection of issues. This one will be addressed in sprint 68.

[mpemy]

Made good progress on the collection of issues. This one will be addressed in sprint 69.

[brian-comply0]

@mpemy this better, but still isn't quite right. In XML, the root element has a uuid attribute. It's not a separate element.

In other words, the first lines of an XML catalog should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<catalog uuid="9b0c9c43-2722-4bbb-b132-13d34fb94d45">

Currently, the API spec is sowing uuid as a child element to catalog instead of an attribute. This is not correct:

<?xml version="1.0" encoding="UTF-8"?>
<catalog>
	<uuid>eE84dB6A-9F7c-431b-B94e-eA4b5c7a3C98</uuid>

Moving back to in-progress.

[brian-comply0]

Regarding my above comment, @mpemy and I dug into this and learned the following:

• OpenAPI only works with JSON schemas, even if they are intended to represent XML content. We are unable to use the NIST XML schema for the XML content.
• OpenAPI has a known issue expressing XML element attributes as there is no way for the JSON schema to differentiate element children from element attributes. (JSON has no element attribute concept).

As a result, there is no way to represent fully compliant OSCAL XML syntax using the OpenAPI 3.1 specification. Older OpenAPI specifications have the same known issue.

@brian-comply0 will ensure our documentation cites this as the reason for the incorrect representation of OSCAL XML syntax, and assure adopters that the intention is for the implementations to accept fully compliant OSCAL XML as documented by NIST.