component defintion schema is missing port-ranges fields

[degenaro]

Describe the bug

The reference for v1.2.0 under component-definition.components.protocols.port-ranges comprises start, end, transport which are missing from the json schema.

Who is the bug affecting

OSCAL 1.2.0 json schema users.

What is affected by this bug

Metaschema

How do we replicate this issue

Simply compare the OSCAL 1.2.0 json schema with the reference outline and notice the missing fields.

Expected behavior (i.e. solution)

The missing fields are rectified (either added to json schema or removed from reference materials).

Other comments

No response

Revisions

No response

[vikas-agarwal76]

It seems these fields are present in the XSD but not in JSON Schema for component definition.

[iMichaela]

@degenaro - Thank you.

ANALYSIS
oscal_implementation-common_metaschema.xml defines the port-range assembly with flags and constraints as follows:

<define-assembly name="port-range">
            <formal-name>Port Range</formal-name>
            <description>Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses.</description>
            <define-flag name="start" as-type="non-negative-integer">
                  <formal-name>Start</formal-name>
                  <description>Indicates the starting port number in a port range for a transport layer protocol</description>
                  <remarks>
                        <p>Should be a number within a permitted range</p>
                  </remarks>
            </define-flag>
            <define-flag name="end" as-type="non-negative-integer">
                  <formal-name>End</formal-name>
                  <description>Indicates the ending port number in a port range for a transport layer protocol</description>
                  <remarks>
                        <p>Should be a number within a permitted range</p>
                  </remarks>
            </define-flag>
            <define-flag name="transport" as-type="token">
                  <formal-name>Transport</formal-name>
                  <description>Indicates the transport type.</description>
                  <constraint>
                        <allowed-values id="oscal-component-protocol-transport-values">
                              <enum value="TCP">Transmission Control Protocol</enum>
                              <enum value="UDP">User Datagram Protocol</enum>
                        </allowed-values>
                  </constraint>
            </define-flag>
         <constraint>
                  <expect id="oscal-component-protocol-port-range-has-start" level="WARNING" target="." test="exists(@start)">
                        <message>A port range should have a start port given.</message>
                  </expect>
                  <expect id="oscal-component-protocol-port-range-has-end" level="WARNING" target="." test="exists(@end)">
                        <message>A port range should have an end port given. To define a single port, the start and end should be the same value.</message>
                  </expect>
                  <expect id="oscal-component-protocol-port-range-starts-before-end" level="WARNING" target="." test="not(@start > @end)">
                        <message>The port range start should not be after its end.</message>
                  </expect>
            </constraint>
            <remarks>
                  <p>To be validated as a natural number (integer &gt;= 1). A single port uses the same value for start and end. Use multiple 'port-range' entries for non-contiguous ranges.</p>
            </remarks>
            <example>
                  <service xmlns="http://csrc.nist.gov/ns/oscal/example" id="svc-01" name="Domain Name Service (DNS) Lookup">
                        <protocol name="dns">
                              <port-range start="53" end="53" transport="tcp"/>
                        </protocol>
                  </service>
            </example>
      </define-assembly>

The generated documentation:

and the XSD schema for XML are correctly including all flags:

   <xs:complexType name="oscal-implementation-common-port-range-ASSEMBLY">
      <xs:annotation>
         <xs:appinfo>
            <m:formal-name>Port Range</m:formal-name>
            <m:description>Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses.</m:description>
         </xs:appinfo>
         <xs:documentation>
            <b>Port Range</b>: Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses.</xs:documentation>
      </xs:annotation>
      <xs:attribute name="start" type="NonNegativeIntegerDatatype">
         <xs:annotation>
            <xs:appinfo>
               <m:formal-name>Start</m:formal-name>
               <m:description>Indicates the starting port number in a port range for a transport layer protocol</m:description>
            </xs:appinfo>
            <xs:documentation>
               <b>Start</b>: Indicates the starting port number in a port range for a transport layer protocol</xs:documentation>
         </xs:annotation>
      </xs:attribute>
      <xs:attribute name="end" type="NonNegativeIntegerDatatype">
         <xs:annotation>
            <xs:appinfo>
               <m:formal-name>End</m:formal-name>
               <m:description>Indicates the ending port number in a port range for a transport layer protocol</m:description>
            </xs:appinfo>
            <xs:documentation>
               <b>End</b>: Indicates the ending port number in a port range for a transport layer protocol</xs:documentation>
         </xs:annotation>
      </xs:attribute>
      <xs:attribute name="transport" type="TokenDatatype">
         <xs:annotation>
            <xs:appinfo>
               <m:formal-name>Transport</m:formal-name>
               <m:description>Indicates the transport type.</m:description>
            </xs:appinfo>
            <xs:documentation>
               <b>Transport</b>: Indicates the transport type.</xs:documentation>
         </xs:annotation>
      </xs:attribute>
   </xs:complexType>

The generated JSON schema is missing the start, end and transport properties for the array of port-range objects:

   "oscal-component-definition-oscal-implementation-common:port-range" : 
   { "title" : "Port Range",
    "description" : "Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses.",
    "$id" : "#/definitions/oscal-component-definition-oscal-implementation-common:port-range",
    "type" : "object",
    "additionalProperties" : false },

[david-waltermire]

This is likely an issue in the XSLT tooling.

I just checked schema generation using oscal-cli and it produces the schema object as:

    "AssemblyOscalImplementationCommonPortRangeType" : {
      "$id" : "#/definitions/AssemblyOscalImplementationCommonPortRangeType",
      "title" : "Port Range",
      "description" : "Where applicable this is the transport layer protocol port range an IPv4-based or IPv6-based service uses.\n\nTo be validated as a natural number (integer \\>= 1). A single port uses the same value for start and end. Use multiple 'port-range' entries for non-contiguous ranges.",
      "type" : "object",
      "properties" : {
        "start" : {
          "title" : "Start",
          "description" : "Indicates the starting port number in a port range for a transport layer protocol\n\nShould be a number within a permitted range",
          "$ref" : "#/definitions/NonNegativeIntegerDatatype"
        },
        "end" : {
          "title" : "End",
          "description" : "Indicates the ending port number in a port range for a transport layer protocol\n\nShould be a number within a permitted range",
          "$ref" : "#/definitions/NonNegativeIntegerDatatype"
        },
        "transport" : {
          "title" : "Transport",
          "description" : "Indicates the transport type.",
          "allOf" : [ {
            "$ref" : "#/definitions/TokenDatatype"
          }, {
            "enum" : [ "TCP", "UDP" ]
          } ]
        }
      },
      "additionalProperties" : false
    },

[vikas-agarwal76]

Seems this same issue is there in SSP JSON schema also.

[iMichaela]

Seems this same issue is there in SSP JSON schema also.

I can confirm that this port-range bug also manifests in the SSP JSON schema. Although the assembly definition itself has not been modified (similar to the earlier issue affecting related-observations in the Assessment Results JSON schema), there appears to be something specific to this particular assembly that is affecting the XSLT 3.0 functions in our new toolchain.

The prior related-observations issue was caused by a duplicate assembly definition and was resolved by correcting that definition, not by changing the toolchain. The fact that other assemblies are being transformed correctly suggests a comparable definition issue in this case, but further debugging is required to determine the root cause.

The NIST oscal-cli does generate the assembly successfully; however, as in the example above, the identifiers are rendered in CamelCase format. This convention was changed some time ago, and as a result, JSON schemas generated today with any oscal-cli are not backwards compatible. There may be additional differences, but the structural divergence between the files is significant enough that meaningful diffs are difficult to interpret.

[iMichaela]

Fixed in develop by the commit: 01eb411