Consider a narrow YAML parser-compatibility check for js-yaml 5 failures

[hdamker]

Problem description

Some current CAMARA OpenAPI YAML files pass CAMARA's yamllint/PyYAML/Spectral
validation path but fail with js-yaml@5.0.0. The affected shape appears to be
a YAML 1.2 indentation problem in a flow mapping embedded in a block mapping,
not just a parser preference.

The current Redocly dependency path in CAMARA Validation still resolves to
js-yaml@4.1.1, so this is not an immediate Redocly break under the current
lockfile. The risk is future parser drift in validation/release tools and
downstream consumers that already use stricter YAML parsers.

On current ConnectedNetworkType main (8448fe9381e0), js-yaml@5.0.0
rejects code/API_definitions/connected-network-type-subscriptions.yaml:

        sinkCredential: {
          "credentialType": "ACCESSTOKEN",
          "accessToken": "xxx",
          "accessTokenExpiresUtc": "2024-02-17T16:23:45Z",
          "accessTokenType": "bearer"
        }
        protocol: HTTP

Parser result: YAMLException: deficient indentation (1681:9). The same file
has no yamllint finding with the CAMARA config and parses with PyYAML.

OpenAPI 3.0.3 recommends YAML 1.2 for YAML OpenAPI documents. YAML 1.2.2 is the
current YAML 1.2 revision used here as the grammar reference.

Possible evolution

Please decide whether CAMARA Validation should add a narrow warning/advisory
YAML 1.2 parser-conformance check for code/API_definitions/*.yaml.

If accepted, keep the change small: use an explicit pinned parser dependency,
emit one normal validation finding per parser error, and add one regression
fixture for this subscription-example shape. Historical release tags should stay
out of scope; release tooling that reads already-published artifacts should keep
tolerant or pinned parser behavior.

Alternative solution

Keep validation unchanged, fix the affected current API specs as content
cleanup, and rely on release tooling or downstream tools to pin or tolerate
their YAML parser dependencies.

Additional context

An isolated js-yaml@5.0.0 scan found six current-main failures across this
same subscription-example shape:

• ConnectedNetworkType/code/API_definitions/connected-network-type-subscriptions.yaml
• DeviceReachabilityStatus/code/API_definitions/device-reachability-status-subscriptions.yaml
• DeviceRoamingStatus/code/API_definitions/device-roaming-status-subscriptions.yaml
• the corresponding split files under DeviceStatus

[hdamker]

Implementation proposal:

Add a narrow Python Validation check backed by an explicit js-yaml@5.0.0
dependency, not a yamllint or Spectral rule. The check should parse current
code/API_definitions/*.yaml files and emit one advisory warning per invalid
file with the parser reason, line, and column.

That covers the known affected subscription specs, while any other file rejected
by js-yaml@5 gets only one warning for the first parser error.

Keep historical release tags out of scope for this Validation check; release
traversal tooling still needs tolerant or pinned parser behavior.

[tanjadegroot]

From Release Management meeting (23/06/26):

• Commonalities to provide guidelines to not use "JSON-like" style in examples in API definitions, as it induced mistakes in indentation for YAML. @rartych to create the issue to be included in the next patch release.

[hdamker]

• Commonalities to provide guidelines to not use "JSON-like" style in examples in API definitions, as it induced mistakes in indentation for YAML. @rartych to create the issue to be included in the next patch release.

@tanjadegroot that is outside of the scope of this issue and it's PR. Even if the guideline will be defined in Commonalities it does not change the need to check the parser compliance (there could be also other issues braking js-yaml@5 beyond the found ones. E.g. there was one in a prior traffic-influence release which is not related to "JSON-like" style examples.