From: Matthew Watkins Date: Tue, 3 Mar 2026 14:28:32 +0000 (+0000) Subject: Docs: Add advisory for JSON Pointer errors in OpenAPI specs X-Git-Url: https://gerrit.onap.org/r/gitweb?a=commitdiff_plain;h=4094b23ebd7a720b03d7f70f002bd0c1f5255d03;p=doc.git Docs: Add advisory for JSON Pointer errors in OpenAPI specs Add documentation advisory explaining the JSON Pointer resolution failure caused by forward slash (/) characters in Swagger 2.0 definition key names. When migrating from the deprecated swaggerv2doc directive to the openapi directive, auto-generated Swagger specs from OpenDaylight YANG tooling contain definition names like: ASDC-API/artifacts(config)artifact The / character is the JSON Pointer path separator (RFC 6901), so jsonschema incorrectly interprets these as nested paths rather than flat keys under definitions, resulting in: _RefResolutionError: Unresolvable JSON pointer The advisory documents two fix approaches: Option A (recommended): Rename keys, replacing / with . Option B: Use RFC 6901 tilde escaping (~1) in $ref values Also adds a cross-reference from the existing api-swagger-guide. Ref: https://gerrit.onap.org/r/c/ccsdk/distribution/+/143029 Issue-ID: CIMAN-33 Change-Id: I201a82e8de14e3cba5ae4abbfaf88748710341a8 Signed-off-by: Matthew Watkins --- diff --git a/docs/guides/onap-documentation/api-swagger-guide.rst b/docs/guides/onap-documentation/api-swagger-guide.rst index d56dfa45a..622ed473c 100644 --- a/docs/guides/onap-documentation/api-swagger-guide.rst +++ b/docs/guides/onap-documentation/api-swagger-guide.rst @@ -28,6 +28,8 @@ API Documentation .. seealso:: - `OpenAPI Specification `_ - `Swagger vs OpenAPI `_ + - :ref:`api-swagger-json-pointer-fix` — Advisory on JSON Pointer errors + caused by ``/`` characters in Swagger definition key names Swagger diff --git a/docs/guides/onap-documentation/api-swagger-json-pointer-fix.rst b/docs/guides/onap-documentation/api-swagger-json-pointer-fix.rst new file mode 100644 index 000000000..eed0e77ba --- /dev/null +++ b/docs/guides/onap-documentation/api-swagger-json-pointer-fix.rst @@ -0,0 +1,216 @@ +.. This work is licensed under a Creative Commons Attribution 4.0 +.. International License. http://creativecommons.org/licenses/by/4.0 +.. Copyright 2025 The ONAP Contributors. All rights reserved. + +.. _api-swagger-json-pointer-fix: + +Advisory: JSON Pointer Errors in OpenAPI Spec Files +==================================================== + +Summary +------- + +When migrating API documentation from the deprecated ``.. swaggerv2doc::`` +directive to the ``.. openapi::`` directive, some Swagger 2.0 JSON spec files +cause Sphinx builds to fail with an error like: + +.. code-block:: none + + jsonschema.exceptions._RefResolutionError: Unresolvable JSON pointer: + 'definitions/ASDC-API/artifacts(config)artifact' + +This error occurs when **definition key names contain forward slash** (``/``) +**characters**. The ``/`` character is the path separator in JSON Pointer +(`RFC 6901 `_), so the JSON schema +resolver misinterprets the key name as a nested path rather than a single key +at the ``definitions`` level. + +Background +---------- + +Several ONAP projects use auto-generated Swagger 2.0 JSON specs originally +produced by OpenDaylight YANG tooling. These specs contain definition names +that embed hierarchical paths using ``/`` as a separator, for example: + +- ``ASDC-API/artifacts(config)artifact`` +- ``ASDC-API/vf-license-model-versions(config)vf-license-model-version`` +- ``LCM/common-header(config)flags`` + +These names appear both as keys under ``definitions`` and inside ``$ref`` +pointer values: + +.. code-block:: json + + { + "definitions": { + "ASDC-API/artifacts(config)artifact": { + "properties": { } + } + }, + "paths": { + "/config/ASDC-API:artifacts": { + "post": { + "parameters": [{ + "schema": { + "$ref": "#/definitions/ASDC-API/artifacts(config)artifact" + } + }] + } + } + } + } + +While having ``/`` in a JSON object key is valid JSON, it creates an +unresolvable ``$ref`` when parsed as a JSON Pointer. The pointer +``#/definitions/ASDC-API/artifacts(config)artifact`` is interpreted as: + +1. Navigate into ``definitions`` ✓ +2. Navigate into ``ASDC-API`` ✗ — no such nested key exists + +The actual definition lives at ``definitions["ASDC-API/artifacts(config)artifact"]`` +as a single flat key, but the JSON Pointer specification has no way to +distinguish a ``/`` that is part of a key name from a ``/`` that is a path +separator — unless the reference is properly escaped. + +Affected Projects +----------------- + +This issue was originally identified on Gerrit change +`143029 `_ +(``ccsdk/distribution``, topic: ``remove-swaggerdoc``), where the GitHub +documentation workflow failed during ``sphinx-build`` for both the ``docs`` +and ``docs-linkcheck`` tox environments. + +Any project with auto-generated Swagger specs from OpenDaylight YANG tooling +may be affected. The issue only manifests when using ``sphinxcontrib-openapi`` +(the ``.. openapi::`` directive); the older ``sphinxcontrib-swaggerdoc`` +extension did not perform strict JSON Pointer resolution on ``$ref`` values. + +Fix: Rename Definition Keys (Option A — Recommended) +----------------------------------------------------- + +Replace ``/`` in definition key names with a safe separator character such as +``.`` (period), and update all corresponding ``$ref`` values to match. + +**Before:** + +.. code-block:: json + + { + "definitions": { + "ASDC-API/artifacts(config)artifact": { } + }, + "$ref": "#/definitions/ASDC-API/artifacts(config)artifact" + } + +**After:** + +.. code-block:: json + + { + "definitions": { + "ASDC-API.artifacts(config)artifact": { } + }, + "$ref": "#/definitions/ASDC-API.artifacts(config)artifact" + } + +This can be accomplished with a script that: + +1. Loads the JSON spec. +2. Identifies all definition keys containing ``/``. +3. Replaces ``/`` with ``.`` in those keys. +4. Performs a global find-and-replace of all ``$ref`` values referencing the + old key names. +5. Writes the corrected JSON back out. + +**Example (Python):** + +.. code-block:: python + + import json, re, sys + + with open(sys.argv[1], "r") as f: + raw = f.read() + + data = json.loads(raw) + definitions = data.get("definitions", {}) + + # Build a mapping of old key -> new key for any key containing "/" + renames = {} + for key in list(definitions.keys()): + if "/" in key: + new_key = key.replace("/", ".") + renames[key] = new_key + + # Replace in $ref strings (operate on raw text for simplicity) + for old_key, new_key in renames.items(): + old_ref = f"#/definitions/{old_key}" + new_ref = f"#/definitions/{new_key}" + raw = raw.replace(f'"{old_ref}"', f'"{new_ref}"') + + # Replace definition keys + data = json.loads(raw) + new_definitions = {} + for key, value in data["definitions"].items(): + new_definitions[renames.get(key, key)] = value + data["definitions"] = new_definitions + + with open(sys.argv[1], "w") as f: + json.dump(data, f, indent=2) + +Run as: + +.. code-block:: bash + + python fix_json_pointers.py docs/sli/apis/specs/asdc-api.json + python fix_json_pointers.py docs/sli/apis/specs/lcm.json + +Alternative: JSON Pointer Tilde Escaping (Option B) +---------------------------------------------------- + +RFC 6901 defines ``~1`` as the escape sequence for a literal ``/`` inside a +JSON Pointer token. Under this approach, definition key names are left +unchanged, but all ``$ref`` values are updated to use the escaped form: + +**Before:** + +.. code-block:: json + + "$ref": "#/definitions/ASDC-API/artifacts(config)artifact" + +**After:** + +.. code-block:: json + + "$ref": "#/definitions/ASDC-API~1artifacts(config)artifact" + +This is technically correct per the RFC, but has drawbacks: + +- Less readable and harder to maintain. +- Requires that all consumers (including ``sphinxcontrib-openapi`` and any + other tooling) correctly implement ``~1`` decoding, which is not always + guaranteed in practice. +- The definition keys still contain ``/``, which may cause issues with other + tools in the future. + +**Option A (renaming keys) is preferred** for clarity and portability. + +Verification +------------ + +After applying the fix, verify the documentation builds cleanly: + +.. code-block:: bash + + cd docs + tox -e docs,docs-linkcheck + +Both environments should complete without ``_RefResolutionError`` exceptions. + +References +---------- + +- `RFC 6901 — JavaScript Object Notation (JSON) Pointer `_ +- `Swagger 2.0 Specification — Reference Object `_ +- `sphinxcontrib-openapi documentation `_ +- `Gerrit Change 143029 `_ \ No newline at end of file diff --git a/docs/guides/onap-documentation/index.rst b/docs/guides/onap-documentation/index.rst index 0797dd218..ef2fc02c0 100644 --- a/docs/guides/onap-documentation/index.rst +++ b/docs/guides/onap-documentation/index.rst @@ -19,4 +19,5 @@ contribute to the ONAP documentation project. converting-to-rst updates-and-review api-swagger-guide + api-swagger-json-pointer-fix templates/index