oscal — API reference

Initialize OSCAL support and run startup (table checks / population).

        Args:
            db_conn (str, optional): Database connection string or file path.
                Defaults to ``SUPPORT_DATABASE_DEFAULT_FILE``.
            db_type (str, optional): Database backend type (e.g. "sqlite3").
                Defaults to ``SUPPORT_DATABASE_DEFAULT_TYPE``.
            db_init_mode (str, optional): Database initialization mode. Defaults to "auto".
                - "auto": Extract from packaged resources if the file is missing/empty,
                  otherwise use the existing file.
                - "extract": Always try to extract from resources; create empty if that fails.
                - "create": Always create an empty database from scratch.
            db_compress_files (bool, optional): Whether to store support files
                compressed in the database. Defaults to
                ``COMPRESS_SUPPORT_FILES_IN_DATABASE``.

Add an asset to the support database. If the asset already exists, it will be replaced.
        This method supports both string and bytes content types.
        If the content is a string, it will be converted to bytes.
        If the content is already in bytes, it will be used as is.
        Args:
            oscal_version (str, required): The OSCAL version (e.g. "v1.0.0").
            model_name (str, required): The OSCAL model name (e.g. "system-security-plan").
            asset_type (str, required): The asset type (e.g. "xml-schema", "json-schema").
            content (str | bytes, required): The asset content; strings are encoded
                to UTF-8 bytes.
            filename (str, optional): Filename to record for the cached asset.
                Defaults to ``"{model_name}_{asset_type}"``.
        Returns:
            bool: True if the asset was added successfully, False otherwise.

Backward-compatible wrapper for :meth:`get_asset`.

        Args:
            oscal_version (str, required): The OSCAL version (e.g. "v1.0.0").
            model_name (str, required): The OSCAL model name (e.g. "system-security-plan").
            asset_type (str, required): The asset type (e.g. "xml-schema", "json-schema").

        Returns:
            Any: The asset content if found, otherwise None.

Download XML and JSON schema files to the filesystem.

        Files are written to ``{support_dir}/{version}_schemas/`` directories and
        are not stored in the support database.

        Args:
            support_dir: Root directory under which per-version schema folders are created.
            fetch: ``"all"`` to download every known version, or a specific version
                   tag (e.g. ``"v1.2.2"``) to download only that version.
        Returns:
            True if all files were saved without error, False otherwise.

Make support for OSCAL *version* available, acquiring or substituting it.

        Invoked when content declares an OSCAL version not present in the local support
        database. Resolution order:

        1. Already present locally → return it (``"exact"``).
        2. Merge that version from the library's bundled database, if present there
           (offline; logged INFO).
        3. Otherwise fetch it from the NIST OSCAL GitHub repository (logged INFO on success).
        4. If it still cannot be obtained → substitute the closest available version within
           the same OSCAL major (logged WARN; ``"closest-match"``).
        5. If nothing usable exists → ``"unavailable"`` (logged ERROR).

        Args:
            version (str, required): The requested OSCAL version tag (e.g. ``"v1.2.3"``).

        Returns:
            tuple[str | None, str]: ``(resolved_version, outcome)`` where ``outcome`` is
                ``"exact"``, ``"closest-match"``, or ``"unavailable"``. ``resolved_version``
                is None only when ``outcome`` is ``"unavailable"``.

Backward-compatible wrapper for :meth:`list_models`.

        Args:
            version (str, optional): The OSCAL version to enumerate models for, or
                "all". Defaults to "all".

        Returns:
            list[str]: Supported model-name strings (may be empty).

Export all cached support files to a directory tree, grouped by version.

        Args:
            export_path (str, optional): The directory to export support files to.
                Defaults to "./support_files".

        Returns:
            bool: True if the export was successful, False otherwise.

Returns the asset for the specified OSCAL version and model name.
        Args:
            version (str): The OSCAL version (e.g., "v1.0.0").
            model (str): The OSCAL model name (e.g., "system-security-plan").
            asset_type (str): The type of asset to retrieve (e.g., "xml-schema", "json-schema").
        Returns:
            The asset content if found, None otherwise.

Return the OSCAL Metaschema definition for a named data type.

        Provides the datatype's validation patterns (``xml-pattern``,
        ``json-pattern``, ``recommended-pattern``), ``base-type``, documentation,
        and reference links — e.g. so a UI can validate a field's input against the
        regex for that field's declared OSCAL data type. The full table is also
        available as the ``datatypes`` attribute.

        Args:
            datatype_name (str, required): OSCAL data type name (e.g. "uuid",
                "date-time-with-timezone", "token").

        Returns:
            dict | None: A safe copy of the datatype definition, or None if the
                name is not a recognized OSCAL data type.

Backward-compatible wrapper for :meth:`latest_version`.

        Returns:
            Optional[str]: The latest OSCAL version tag, or None if none are loaded.

Return the parsed metaschema index dict for the given OSCAL version and model.

        Results are held in the module-level ``_metaschema_index_cache`` so that
        only one copy of each index lives in memory and survives across calls.
        A cached entry is reused until it is older than :data:`INDEX_REFRESH`
        seconds (24 hours), at which point it is refreshed from the database.

        The index is identified by ``(version, model, index_version)``: a stored index
        whose ``index_version`` has a **different major** than the requested one is
        incompatible with this library and is rebuilt from the raw metaschema (stamping
        the current :data:`METASCHEMA_INDEX_VERSION`); a same-major difference is trusted
        as backward compatible and used as-is.

        Args:
            version: OSCAL version string, e.g. ``"v1.1.3"``.
            model:   OSCAL model name, e.g. ``"catalog"``.
            index_version: Metaschema-index-schema version to require. Defaults to this
                instance's :attr:`active_index_version` (resolved at startup).

        Returns:
            The model-specific index dict on success, or ``None`` when the index
            is unavailable.

Backward-compatible wrapper for :meth:`is_valid_model`.

        Args:
            model_name (str, required): The OSCAL model name to check.
            version (str, optional): The OSCAL version to check against, or "all".
                Defaults to "all".

        Returns:
            bool: True if the model is valid for the version, False otherwise.

Check if the specified OSCAL model is valid for the given version.
        Args:
            model (str): The OSCAL model name to check (e.g., "system-security-plan").
            version (str): The OSCAL version to check against (e.g., "v1.0.0").
        Returns:
            bool: True if the model is valid for the specified version, False otherwise.

Check if the specified OSCAL version is valid and supported.
        Args:
            version (str): The OSCAL version to check (e.g., "v1.0.0").
        Returns:
            bool: True if the version is valid and supported, False otherwise.

Return the latest supported OSCAL version.

        Returns:
            Optional[str]: The highest OSCAL version tag available in the support
                database, or None if none are loaded.

Enumerate the supported models for a given OSCAL version.
        Args:
            version (str): The OSCAL version to enumerate models for (e.g., "v1.0.0").
        Returns:
            list[str]: A list of model-name strings supported for the specified OSCAL version
                       (may be empty).

Load a file bundled in the ``oscal.data`` package resources, with caching.

        Args:
            name (str, required): Filename of the resource within ``oscal.data``.
            binary (bool, optional): If True, return raw bytes; otherwise return
                UTF-8 decoded text. Defaults to False.
            as_bytes (bool, optional): Keyword-only alias for ``binary``; overrides
                it when provided. Defaults to None.

        Returns:
            str | bytes | None: The file contents (text or bytes), or None on failure.

Remove support assets matching any combination of version / model / asset_type.

        At least one of the three criteria must be supplied; the criteria are ANDed. Every
        matching ``oscal_support`` row is deleted, and each cached file it referenced is
        deleted from ``filecache`` **once it is no longer referenced by any surviving
        asset row** — a single cached file can back more than one asset row (e.g. a
        document model's ``metaschema`` and ``document-model`` rows share one
        ``filecache_uuid``), so orphan-checking prevents deleting a file another row still
        needs.

        Args:
            version (str | None, optional): OSCAL version tag (e.g. ``"v1.2.3"``).
            model (str | None, optional): Model name (e.g. ``"catalog"``).
            asset_type (str | None, optional): Asset type (e.g. ``"metaschema"``,
                ``"document-model"``, ``"processed"``).

        Returns:
            int: The number of ``oscal_support`` rows removed (0 when nothing matched or
                no criterion was supplied).

Delete all support content for a single OSCAL version from the database.

        This is a standalone deletion for withdrawing a version that no longer
        belongs in the local support set (e.g. one removed upstream). Unlike
        :meth:`update`, it performs no GitHub fetch — it only deletes local
        content and keeps in-memory state consistent with the database.

        Args:
            version (str): The OSCAL version tag to remove (e.g. "v1.2.3"). The
                leading "v" is required and the tag is matched case-insensitively.

        Returns:
            bool: True if the version was found and deleted, False if the tag was
                invalid, not present, or the deletion failed.

Select the metaschema-index-schema version this instance will use.

        Reads the distinct ``index_version`` values recorded in ``oscal_versions`` and keeps
        those in the compatible range ``[METASCHEMA_INDEX_VERSION, next-major)``. When at
        least one qualifies, the **lowest** in range is chosen (the most conservative
        compatible schema) and assigned to :attr:`active_index_version`. When none qualify,
        the library's bundled database is merged into the local one (which supplies indexes
        built at this library's index version) and the resolution is retried once. Returns
        the resolved value.

Record the metaschema-index-schema version used to build *version*'s indexes.

        Writes ``index_version`` into the version's ``oscal_versions`` row and updates the
        in-memory registry. Called after a version's ``"processed"`` indexes are (re)built
        so the database records which index schema they conform to.

        Args:
            version (str, required): OSCAL version tag (e.g. ``"v1.2.3"``).
            index_version (str, optional): Index-schema version; defaults to the library's
                current :data:`METASCHEMA_INDEX_VERSION`.

        Returns:
            bool: True on success.

Perform startup tasks required to provide OSCAL support.

        Ensures the support database has the required tables and data, populating
        it from NIST's GitHub releases when empty, and sets ``self.ready``.

        Args:
            check_for_updates (bool, optional): Reserved flag to check for newer
                OSCAL versions during startup. Defaults to False.
            refresh_all (bool, optional): Reserved flag to force a full refresh of
                all support content. Defaults to False.

        Returns:
            bool: True if the support capability is ready, False otherwise.

        Process:
        1 Check for tables
          - If tables do not exist:
            - create tables
            - set state to "empty"
          - If tables exist, check for data
            - If no data, set state to "empty"
            - If data exists, set state to "populated"
        2 If state is "empty", check for connection to GitHub
         - If cannot connect to GitHub, EXIT (cannot proceed)
         - If connected to GitHub, update database
           - If update fails, EXIT (cannot proceed)
           - If update succeeds, set state to "populated"
        3 If state is "populated" set self.ready to True

Check whether the specified OSCAL version and assets are supported.

        Note:
            Currently not implemented; always returns False.

        Args:
            oscal_version (str, required): The OSCAL version to check (e.g. "v1.0.0").
            assets (list, required): The asset types to check for.

        Returns:
            bool: True if the version and assets are supported, False otherwise.

Update OSCAL support content based on a fetch directive.

        Args:
            mode (str, optional): The fetch directive. Defaults to "new".
                - "all": Clear and re-fetch all OSCAL versions and support files.
                - "latest"/"new": Check for new OSCAL versions and fetch any found.
                - "vX.Y.Z": Clear and re-fetch a specific OSCAL version.
            fetch (str, optional): Legacy alias for ``mode``; when provided it
                overrides ``mode``. Defaults to None.
            save_to_fs (bool, optional): When True, also emit the parsed
                metaschema index files to the local file system in addition to
                updating the database. When False (default), only the database
                is updated. Defaults to False.

        Returns:
            bool: True if the update was successful, False otherwise.

Reclaim free space in the support database (SQLite ``VACUUM``).

        A public wrapper over the internal VACUUM; a no-op on non-SQLite backends. Useful
        after a bulk :meth:`remove_asset` to shrink the database file on disk.

Return an HTML ``<div>`` detail view of a single metaschema node.

        Given a node's reference id (as produced by :meth:`view_outline`), returns its
        formal name and description, a format-appropriate representation, data type and
        regex (where available), constraints, and its immediate parent and children —
        each parent/child clickable by its own reference id.

        Args:
            version (str, required): OSCAL version, e.g. ``"v1.1.3"``.
            model (str, required): OSCAL model name, e.g. ``"catalog"``.
            format (str, required): ``"xml"``, ``"json"``, or ``"yaml"``.
            reference_uuid (str, required): The node reference id to describe.

        Returns:
            str: A detail ``<div>`` fragment, or a ``<div class="ms-error">`` when the
                model/version/format or reference is unknown.

Return an HTML ``<div>`` outline of a model's metaschema structure.

        The outline is a clickable tree rendered in the requested format's syntax
        (``"xml"``, ``"json"``, or ``"yaml"``), annotated with data types and
        cardinality. Each element links to its node by a stable reference id, for use
        with :meth:`view_detail`. Intended for a front-end: the HTML is a fragment
        (wrapped in a ``<div>``), never a full page.

        Args:
            version (str, required): OSCAL version, e.g. ``"v1.1.3"``.
            model (str, required): OSCAL model name, e.g. ``"catalog"``.
            format (str, required): ``"xml"``, ``"json"``, or ``"yaml"``.

        Returns:
            str: An outline ``<div>`` fragment, or a ``<div class="ms-error">`` when
                the model/version/format is unknown or the index is unavailable.

Initialize OSCAL support and run startup (table checks / population).

        Args:
            db_conn (str, optional): Database connection string or file path.
                Defaults to ``SUPPORT_DATABASE_DEFAULT_FILE``.
            db_type (str, optional): Database backend type (e.g. "sqlite3").
                Defaults to ``SUPPORT_DATABASE_DEFAULT_TYPE``.
            db_init_mode (str, optional): Database initialization mode. Defaults to "auto".
                - "auto": Extract from packaged resources if the file is missing/empty,
                  otherwise use the existing file.
                - "extract": Always try to extract from resources; create empty if that fails.
                - "create": Always create an empty database from scratch.
            db_compress_files (bool, optional): Whether to store support files
                compressed in the database. Defaults to
                ``COMPRESS_SUPPORT_FILES_IN_DATABASE``.

Add an asset to the support database. If the asset already exists, it will be replaced.
        This method supports both string and bytes content types.
        If the content is a string, it will be converted to bytes.
        If the content is already in bytes, it will be used as is.
        Args:
            oscal_version (str, required): The OSCAL version (e.g. "v1.0.0").
            model_name (str, required): The OSCAL model name (e.g. "system-security-plan").
            asset_type (str, required): The asset type (e.g. "xml-schema", "json-schema").
            content (str | bytes, required): The asset content; strings are encoded
                to UTF-8 bytes.
            filename (str, optional): Filename to record for the cached asset.
                Defaults to ``"{model_name}_{asset_type}"``.
        Returns:
            bool: True if the asset was added successfully, False otherwise.

Backward-compatible wrapper for :meth:`get_asset`.

        Args:
            oscal_version (str, required): The OSCAL version (e.g. "v1.0.0").
            model_name (str, required): The OSCAL model name (e.g. "system-security-plan").
            asset_type (str, required): The asset type (e.g. "xml-schema", "json-schema").

        Returns:
            Any: The asset content if found, otherwise None.

Download XML and JSON schema files to the filesystem.

        Files are written to ``{support_dir}/{version}_schemas/`` directories and
        are not stored in the support database.

        Args:
            support_dir: Root directory under which per-version schema folders are created.
            fetch: ``"all"`` to download every known version, or a specific version
                   tag (e.g. ``"v1.2.2"``) to download only that version.
        Returns:
            True if all files were saved without error, False otherwise.

Make support for OSCAL *version* available, acquiring or substituting it.

        Invoked when content declares an OSCAL version not present in the local support
        database. Resolution order:

        1. Already present locally → return it (``"exact"``).
        2. Merge that version from the library's bundled database, if present there
           (offline; logged INFO).
        3. Otherwise fetch it from the NIST OSCAL GitHub repository (logged INFO on success).
        4. If it still cannot be obtained → substitute the closest available version within
           the same OSCAL major (logged WARN; ``"closest-match"``).
        5. If nothing usable exists → ``"unavailable"`` (logged ERROR).

        Args:
            version (str, required): The requested OSCAL version tag (e.g. ``"v1.2.3"``).

        Returns:
            tuple[str | None, str]: ``(resolved_version, outcome)`` where ``outcome`` is
                ``"exact"``, ``"closest-match"``, or ``"unavailable"``. ``resolved_version``
                is None only when ``outcome`` is ``"unavailable"``.

Backward-compatible wrapper for :meth:`list_models`.

        Args:
            version (str, optional): The OSCAL version to enumerate models for, or
                "all". Defaults to "all".

        Returns:
            list[str]: Supported model-name strings (may be empty).

Export all cached support files to a directory tree, grouped by version.

        Args:
            export_path (str, optional): The directory to export support files to.
                Defaults to "./support_files".

        Returns:
            bool: True if the export was successful, False otherwise.

Returns the asset for the specified OSCAL version and model name.
        Args:
            version (str): The OSCAL version (e.g., "v1.0.0").
            model (str): The OSCAL model name (e.g., "system-security-plan").
            asset_type (str): The type of asset to retrieve (e.g., "xml-schema", "json-schema").
        Returns:
            The asset content if found, None otherwise.

Return the OSCAL Metaschema definition for a named data type.

        Provides the datatype's validation patterns (``xml-pattern``,
        ``json-pattern``, ``recommended-pattern``), ``base-type``, documentation,
        and reference links — e.g. so a UI can validate a field's input against the
        regex for that field's declared OSCAL data type. The full table is also
        available as the ``datatypes`` attribute.

        Args:
            datatype_name (str, required): OSCAL data type name (e.g. "uuid",
                "date-time-with-timezone", "token").

        Returns:
            dict | None: A safe copy of the datatype definition, or None if the
                name is not a recognized OSCAL data type.

Backward-compatible wrapper for :meth:`latest_version`.

        Returns:
            Optional[str]: The latest OSCAL version tag, or None if none are loaded.

Return the parsed metaschema index dict for the given OSCAL version and model.

        Results are held in the module-level ``_metaschema_index_cache`` so that
        only one copy of each index lives in memory and survives across calls.
        A cached entry is reused until it is older than :data:`INDEX_REFRESH`
        seconds (24 hours), at which point it is refreshed from the database.

        The index is identified by ``(version, model, index_version)``: a stored index
        whose ``index_version`` has a **different major** than the requested one is
        incompatible with this library and is rebuilt from the raw metaschema (stamping
        the current :data:`METASCHEMA_INDEX_VERSION`); a same-major difference is trusted
        as backward compatible and used as-is.

        Args:
            version: OSCAL version string, e.g. ``"v1.1.3"``.
            model:   OSCAL model name, e.g. ``"catalog"``.
            index_version: Metaschema-index-schema version to require. Defaults to this
                instance's :attr:`active_index_version` (resolved at startup).

        Returns:
            The model-specific index dict on success, or ``None`` when the index
            is unavailable.

Backward-compatible wrapper for :meth:`is_valid_model`.

        Args:
            model_name (str, required): The OSCAL model name to check.
            version (str, optional): The OSCAL version to check against, or "all".
                Defaults to "all".

        Returns:
            bool: True if the model is valid for the version, False otherwise.

Check if the specified OSCAL model is valid for the given version.
        Args:
            model (str): The OSCAL model name to check (e.g., "system-security-plan").
            version (str): The OSCAL version to check against (e.g., "v1.0.0").
        Returns:
            bool: True if the model is valid for the specified version, False otherwise.

Check if the specified OSCAL version is valid and supported.
        Args:
            version (str): The OSCAL version to check (e.g., "v1.0.0").
        Returns:
            bool: True if the version is valid and supported, False otherwise.

Return the latest supported OSCAL version.

        Returns:
            Optional[str]: The highest OSCAL version tag available in the support
                database, or None if none are loaded.

Enumerate the supported models for a given OSCAL version.
        Args:
            version (str): The OSCAL version to enumerate models for (e.g., "v1.0.0").
        Returns:
            list[str]: A list of model-name strings supported for the specified OSCAL version
                       (may be empty).

Load a file bundled in the ``oscal.data`` package resources, with caching.

        Args:
            name (str, required): Filename of the resource within ``oscal.data``.
            binary (bool, optional): If True, return raw bytes; otherwise return
                UTF-8 decoded text. Defaults to False.
            as_bytes (bool, optional): Keyword-only alias for ``binary``; overrides
                it when provided. Defaults to None.

        Returns:
            str | bytes | None: The file contents (text or bytes), or None on failure.

Remove support assets matching any combination of version / model / asset_type.

        At least one of the three criteria must be supplied; the criteria are ANDed. Every
        matching ``oscal_support`` row is deleted, and each cached file it referenced is
        deleted from ``filecache`` **once it is no longer referenced by any surviving
        asset row** — a single cached file can back more than one asset row (e.g. a
        document model's ``metaschema`` and ``document-model`` rows share one
        ``filecache_uuid``), so orphan-checking prevents deleting a file another row still
        needs.

        Args:
            version (str | None, optional): OSCAL version tag (e.g. ``"v1.2.3"``).
            model (str | None, optional): Model name (e.g. ``"catalog"``).
            asset_type (str | None, optional): Asset type (e.g. ``"metaschema"``,
                ``"document-model"``, ``"processed"``).

        Returns:
            int: The number of ``oscal_support`` rows removed (0 when nothing matched or
                no criterion was supplied).

Delete all support content for a single OSCAL version from the database.

        This is a standalone deletion for withdrawing a version that no longer
        belongs in the local support set (e.g. one removed upstream). Unlike
        :meth:`update`, it performs no GitHub fetch — it only deletes local
        content and keeps in-memory state consistent with the database.

        Args:
            version (str): The OSCAL version tag to remove (e.g. "v1.2.3"). The
                leading "v" is required and the tag is matched case-insensitively.

        Returns:
            bool: True if the version was found and deleted, False if the tag was
                invalid, not present, or the deletion failed.

Select the metaschema-index-schema version this instance will use.

        Reads the distinct ``index_version`` values recorded in ``oscal_versions`` and keeps
        those in the compatible range ``[METASCHEMA_INDEX_VERSION, next-major)``. When at
        least one qualifies, the **lowest** in range is chosen (the most conservative
        compatible schema) and assigned to :attr:`active_index_version`. When none qualify,
        the library's bundled database is merged into the local one (which supplies indexes
        built at this library's index version) and the resolution is retried once. Returns
        the resolved value.

Record the metaschema-index-schema version used to build *version*'s indexes.

        Writes ``index_version`` into the version's ``oscal_versions`` row and updates the
        in-memory registry. Called after a version's ``"processed"`` indexes are (re)built
        so the database records which index schema they conform to.

        Args:
            version (str, required): OSCAL version tag (e.g. ``"v1.2.3"``).
            index_version (str, optional): Index-schema version; defaults to the library's
                current :data:`METASCHEMA_INDEX_VERSION`.

        Returns:
            bool: True on success.

Perform startup tasks required to provide OSCAL support.

        Ensures the support database has the required tables and data, populating
        it from NIST's GitHub releases when empty, and sets ``self.ready``.

        Args:
            check_for_updates (bool, optional): Reserved flag to check for newer
                OSCAL versions during startup. Defaults to False.
            refresh_all (bool, optional): Reserved flag to force a full refresh of
                all support content. Defaults to False.

        Returns:
            bool: True if the support capability is ready, False otherwise.

        Process:
        1 Check for tables
          - If tables do not exist:
            - create tables
            - set state to "empty"
          - If tables exist, check for data
            - If no data, set state to "empty"
            - If data exists, set state to "populated"
        2 If state is "empty", check for connection to GitHub
         - If cannot connect to GitHub, EXIT (cannot proceed)
         - If connected to GitHub, update database
           - If update fails, EXIT (cannot proceed)
           - If update succeeds, set state to "populated"
        3 If state is "populated" set self.ready to True

Check whether the specified OSCAL version and assets are supported.

        Note:
            Currently not implemented; always returns False.

        Args:
            oscal_version (str, required): The OSCAL version to check (e.g. "v1.0.0").
            assets (list, required): The asset types to check for.

        Returns:
            bool: True if the version and assets are supported, False otherwise.

Update OSCAL support content based on a fetch directive.

        Args:
            mode (str, optional): The fetch directive. Defaults to "new".
                - "all": Clear and re-fetch all OSCAL versions and support files.
                - "latest"/"new": Check for new OSCAL versions and fetch any found.
                - "vX.Y.Z": Clear and re-fetch a specific OSCAL version.
            fetch (str, optional): Legacy alias for ``mode``; when provided it
                overrides ``mode``. Defaults to None.
            save_to_fs (bool, optional): When True, also emit the parsed
                metaschema index files to the local file system in addition to
                updating the database. When False (default), only the database
                is updated. Defaults to False.

        Returns:
            bool: True if the update was successful, False otherwise.

Reclaim free space in the support database (SQLite ``VACUUM``).

        A public wrapper over the internal VACUUM; a no-op on non-SQLite backends. Useful
        after a bulk :meth:`remove_asset` to shrink the database file on disk.

Return an HTML ``<div>`` detail view of a single metaschema node.

        Given a node's reference id (as produced by :meth:`view_outline`), returns its
        formal name and description, a format-appropriate representation, data type and
        regex (where available), constraints, and its immediate parent and children —
        each parent/child clickable by its own reference id.

        Args:
            version (str, required): OSCAL version, e.g. ``"v1.1.3"``.
            model (str, required): OSCAL model name, e.g. ``"catalog"``.
            format (str, required): ``"xml"``, ``"json"``, or ``"yaml"``.
            reference_uuid (str, required): The node reference id to describe.

        Returns:
            str: A detail ``<div>`` fragment, or a ``<div class="ms-error">`` when the
                model/version/format or reference is unknown.

Return an HTML ``<div>`` outline of a model's metaschema structure.

        The outline is a clickable tree rendered in the requested format's syntax
        (``"xml"``, ``"json"``, or ``"yaml"``), annotated with data types and
        cardinality. Each element links to its node by a stable reference id, for use
        with :meth:`view_detail`. Intended for a front-end: the HTML is a fragment
        (wrapped in a ``<div>``), never a full page.

        Args:
            version (str, required): OSCAL version, e.g. ``"v1.1.3"``.
            model (str, required): OSCAL model name, e.g. ``"catalog"``.
            format (str, required): ``"xml"``, ``"json"``, or ``"yaml"``.

        Returns:
            str: An outline ``<div>`` fragment, or a ``<div class="ms-error">`` when
                the model/version/format is unknown or the index is unavailable.

Configure and create the shared OSCAL support instance.

    Call this before ``get_support()`` and before any OSCAL content is loaded when
    non-default settings are needed. If the shared instance already exists, it is
    returned unchanged.

    Args:
        support_file (str, optional): Path to the support database file.
            Defaults to ``SUPPORT_DATABASE_DEFAULT_FILE``.
        db_init_mode (str, optional): Database initialization mode — ``"auto"``,
            ``"extract"``, or ``"create"``. Defaults to ``"auto"``.
        db_path (str, optional): Keyword-only alias for ``support_file``; overrides
            it when provided.
        init_mode (str, optional): Keyword-only alias for ``db_init_mode``;
            overrides it when provided.

    Returns:
        OSCALSupport: The shared support instance.

Return the shared OSCAL support instance, creating it if necessary.

    Creates the instance with default settings (via ``configure_support()``) if it
    does not already exist.

    Returns:
        OSCALSupport: The shared support instance.

Compatibility wrapper around ``configure_support()`` for update utility scripts.

    Args:
        support_file (str, optional): Path to the support database file.
            Defaults to ``SUPPORT_DATABASE_DEFAULT_FILE``.
        db_init_mode (str, optional): Database initialization mode
            (``"auto"``, ``"extract"``, or ``"create"``). Defaults to ``"auto"``.

    Returns:
        OSCALSupport: The shared support instance.

Append a single link dict to ``parent_obj["links"]``.

    Args:
        parent_obj (dict, required): OSCAL JSON object that will receive the link.
        link (dict, required): Link dict. Required key: "href".
            Optional keys: "rel", "media-type", "resource-fragment", "text".

    Returns:
        dict: The appended link entry (filtered to recognized keys).

Append multiple link dicts to ``parent_obj["links"]``.

    Args:
        parent_obj (dict, required): OSCAL JSON object that will receive the links.
        links (list, required): Link dicts, each with at minimum an "href" key.

    Returns:
        None

Append a single prop dict to ``parent_obj["props"]``.

    Args:
        parent_obj (dict, required): OSCAL JSON object that will receive the prop.
        prop (dict, required): Property dict. Required keys: "name", "value".
            Optional keys: "uuid", "ns", "class", "group", "remarks".

    Returns:
        dict: The appended prop entry (filtered to recognized keys).

Append multiple prop dicts to ``parent_obj["props"]``.

    Args:
        parent_obj (dict, required): OSCAL JSON object that will receive the props.
        props (list, required): Property dicts, each with at minimum "name" and "value".

    Returns:
        None

Retrieve matching prop dicts from ``parent_obj["props"]``.

    Either ``name`` or ``uuid`` must be supplied. The return value is always a
    list — empty when nothing matches (or when the required parameters are
    missing) — never ``None``.

    An absent ``ns`` on a prop is treated as the OSCAL default namespace
    (``_OSCAL_NS``), matching the way ``ns`` defaults on this function's own
    ``ns`` parameter. Correct default-``ns`` handling is essential: a prop with
    no ``ns`` is considered to be in the OSCAL namespace.

    Matching behaviour:
      * ``uuid`` supplied: every prop whose ``uuid`` equals ``uuid`` is
        returned. If any descriptor parameter (``name``, a non-default ``ns``,
        ``class_`` or ``group``) is also supplied and does not match a returned
        prop, a warning is logged, but the prop is still returned.
      * ``uuid`` not supplied: ``name`` is required. Props are matched on
        ``name`` **and** effective ``ns``. When ``class_`` and/or ``group`` are
        supplied they must also match. When ``class_``/``group`` are *not*
        supplied, all name+ns matches are returned, ordered best match first:
        props carrying fewer of the un-queried qualifiers (``class``/``group``)
        sort ahead of more-specific props. Document order is preserved among
        equally specific matches.

    Args:
        parent_obj (dict, required): OSCAL JSON object holding a ``props`` list.
        name (str, optional): Prop ``name`` to match. Required if ``uuid`` is
            not given.
        uuid (str, optional): Prop ``uuid`` to match. Required if ``name`` is
            not given.
        ns (str, optional): Namespace to match; defaults to ``_OSCAL_NS``.
        class_ (str, optional): Prop ``class`` to match. Maps to the ``"class"``
            key (``class`` is a reserved word in Python).
        group (str, optional): Prop ``group`` to match.

    Returns:
        list: Matching prop dicts (possibly empty), ordered best match first.

Generate a new random (version 4) UUID string.

    Returns:
        str: A newly generated UUID in canonical string form.

Convert OSCAL markdown text to an HTML ElementTree element.

    Calls ``oscal_markdown_to_html`` to format the markdown into HTML consistent
    with the OSCAL XML specification for markup-line / markup-multiline, then parses
    the resulting string into an XML element suitable for appending into a parent
    XML object.

    Args:
        markdown_text (str, required): The markdown text to convert.
        multiline (bool, optional): If True, handle markup-multiline (block elements);
            if False, handle markup-line (inline elements only). Defaults to True.

    Returns:
        Optional[ElementTree.Element]: The parsed XML element, or None if conversion fails.

Return a SAFE COPY of *node* with nested structural children limited to *depth*.

    Shared, model-agnostic helper for the node getters (catalog/profile groups and
    controls; assessment ``tasks`` once implemented). The returned value shares no
    references with *node*, so callers may read, mutate, or serialize it without
    affecting the source document — mutation of live content must go through the
    OSCAL-standard-enforcing methods, never through a getter's return value.

    Only the collections named in *child_keys* are treated as structural children
    subject to depth pruning. The node's own intrinsic content (e.g. ``props``,
    ``links``, ``params``, ``parts``, ``title``) is always copied in full.

        depth = None  -> unlimited: a full deep copy of the entire subtree (the
                         default; mirrors the historical getter behavior).
        depth = 0     -> node only: the *child_keys* collections are omitted.
        depth = N     -> N levels of structural children retained, each recursively
                         pruned at ``depth - 1``.

    Args:
        node (dict | None, required): The group/control/task dict to copy, or None.
        depth (int | None, optional): Structural-child depth limit. Defaults to None.
        child_keys (tuple, optional): Keys treated as structural children. Defaults
            to ("groups", "controls"). Use ("tasks",) for assessment tasks.

    Returns:
        dict | None: A detached copy, or None when *node* is None.

    Raises:
        ValueError: If *depth* is a negative integer.

True when the original import href is a back-matter fragment reference.

Initialize the error.

        Args:
            code (ImportFailureCode, required): The typed import failure reason.
            uri (str, required): The URI that failed to load.
            message (str, optional): Human-readable detail; a default is derived from
                ``code`` and ``uri`` when omitted.

Classify a source reference by path/URI type and Python stdlib accessibility.

    Sets the ``source_type``, ``source_scheme``, and ``source_supported`` fields on
    ``ref`` in place. Classification intentionally does not use file extensions,
    because many valid content endpoints (e.g. APIs) lack predictable suffixes.

    Args:
        ref (OscalRef, required): The reference to classify; mutated in place.
        only_oscal (bool, optional): Reserved for future content-shape validation;
            currently does not affect classification. Defaults to False.

    Returns:
        bool: True if the reference was classified (even if unsupported), False only
            when the href is empty.

Load content from one or more sources and return the first successful payload.

    Args:
        source (str | dict | OscalRef | list, required): The source(s) to load, as a
            URI/path string, reference dict, ``OscalRef``, or a fallback list of these.
        media_type (str, optional): Expected media type hint. Defaults to "".
        only_oscal (bool, optional): When True, restrict acceptance to OSCAL content.
            Defaults to False.
        cache_directive (CacheDirective | None, optional): Caching directive applied
            to remote fetches. Defaults to the standard 24h behavior.

    Returns:
        str: The first successfully loaded content payload, or "" if none load and no
            typed error was raised.

    Raises:
        ImportLoadError: When a source fails with a typed reason (the last error is
            re-raised when every source in a list fails).

Fetch or read content from a classified ``OscalRef``.

    Args:
        ref (OscalRef, required): A reference that has already been classified
            (via :func:`classify_source`) to set its source type/scheme.
        cache_directive (CacheDirective | None, optional): Caching directive applied
            to remote (http/https) fetches. Defaults to the standard 24h behavior.

    Returns:
        str: The raw content as a string on success.

    Raises:
        ImportLoadError: With a typed ``ImportFailureCode`` on any load failure.

bool: True when the href already matched one of this document's imports.

bool: True when the model's import cardinality forbids the operation.

bool: True when an existing resource was modified in place (update_import).

bool: True when an import was added, replaced, or updated.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter defined anywhere in scope, or None.

        Searches this document and its import tree for a ``param`` with the given id —
        covering parameters defined at control, group, or catalog level (and reached
        through imported catalogs/profiles). Subclasses may override to prefer resolved
        content. See :meth:`_lookup_in_scope` for the ``with_source`` locator form.

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate OSCAL content against the metaschema index in sequenced phases.

        Phases (each recorded in ``validation_status``):
          structure      – all required fields and hierarchy are present
          data-types     – every leaf value matches its declared OSCAL datatype
          allowed-values – every constrained value is within its enumerated set
          cardinality    – every array satisfies its min-occurs/max-occurs bounds
          choice         – every choice is mutually exclusive (at most one member present) and has a member when one is required

        ``validation_status["well-formed"]`` is set by ``initial_validation()``, not here.
        All phases always run regardless of earlier failures, giving a complete picture
        of issues in a single call.  The format argument is accepted for API
        compatibility but does not alter the validation path — ``_dict`` is always the
        authoritative representation.

        Returns True only when every phase passes (content_state reaches VALID).

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

str: Precise, actionable detail for developers (the default ``str``).

str: A safe, generic message that omits internal detail.

Initialize the error.

        Args:
            method (str, required): The attribute/method name that was accessed.
            model (str, required): The model name of the instance it was used on.
            valid_on (list[str], optional): Model names that define ``method``.

str: Which model was called, the missing operation, and where it's valid.

str: A safe, generic message that omits internal detail.

Read up to ``size`` bytes/characters from the source (``-1`` reads all).

Appends a resource to the back-matter section of the OSCAL JSON content.

    Args:
        oscal_obj:   The OSCAL document to modify.
        uuid:        Resource UUID; generated if not supplied.
        title:       Optional resource title.
        description: Optional resource description.
        props:       Optional list of prop dicts (see append_prop).
        rlinks:      Optional list of rlink dicts with "href" and optional "media-type"/"hashes".
        base64:      Not yet implemented; a warning is logged if supplied.
        remarks:     Optional remarks (OSCAL markup-multiline / markdown string).

    Returns:
        dict | None: The appended resource dict, or None on error.

Returns a validated base OSCAL instance loaded from a template.
    Currently this is based on loading a template file from package data.
    In the future, this should be generated based on the latest metaschema definition.

    The supplied ``title`` (and ``version``/``published`` when given) overwrite the
    template's placeholder metadata, so ``Catalog.new("X")`` / ``Profile.new("X")`` set
    the document title as expected.

    The returned instance is always a base OSCAL object. Callers that need a
    specific model subclass (e.g. Catalog, Profile) are responsible for
    reassigning __class__ and calling _init_common() afterward.

    Args:
        model_name (str): The OSCAL model name (e.g., "catalog", "system-security-plan").
        title (str): The title for the new OSCAL content.
        version (str): Optional content version.
        published (str): Optional publication date.
        format (str): The desired format for the new content ("xml", "json", "yaml"). Defaults to "xml".

    Returns:
        Optional[OSCAL]: A base OSCAL instance loaded from template, or None on failure.

Return the current actor (view/session) id, or None when unset.

    Returns:
        str | None: The actor id activated by :func:`use_actor`, else None.

Decorator marking content dirty after a successful mutation.

    Wraps a mutation method; when it returns a non-None result, sets
    ``self.is_unsaved = True`` and updates ``self.last_modified``.

    Args:
        fn (Callable, required): The mutation method to wrap.

    Returns:
        Callable: The wrapped method.

Register an OSCAL model subclass so factory methods return typed instances.

    Args:
        model_name (str, required): The OSCAL model name (e.g. "catalog").
        cls (type, required): The ``OSCAL`` subclass implementing that model.

Decorator factory gating a method on instance attribute/property values.

    The wrapped method runs only when every ``attr == expected`` condition holds
    on ``self``; otherwise it logs an error and returns None.

    Args:
        **conditions: Mapping of instance attribute/property name to its required
            value (e.g. ``writable=True``, ``is_remote=True``).

    Returns:
        Callable: A decorator that wraps the target method with the guard.

    Example:
        >>> @requires(is_read_only=False)
        ... def mutate(self): ...

Set the current actor for the duration of the ``with`` block.

    Mutations performed inside the block are attributed to ``actor``; a document
    write-locked by a *different* actor is read-only within the block.

    Args:
        actor (str | None, required): The actor (view/session) id.

    Yields:
        str | None: The activated actor id.

Best-effort conversion of a non-conformant value into a valid URI-reference.

    Defensive coding for URI values that arrive with characters RFC 3986 does not permit
    unescaped — e.g. a Windows path with backslashes (``R:\a\b.json``), a raw space, or a
    non-ASCII (IRI) character. Backslashes are converted to forward slashes (the usual
    Windows-path intent) and every remaining disallowed character is percent-encoded using
    UTF-8, while URI-structural characters and existing ``%XX`` escapes are preserved. A
    value that is already conformant (and any non-string/empty input) is returned unchanged.

    Note this cannot invent a missing scheme, so it does not, on its own, make a bare
    ``#fragment`` a valid *absolute* ``uri`` — it only repairs the character set.

    Args:
        value (str): The candidate URI-reference.

    Returns:
        str: A character-set-conformant URI-reference.

Convert a date/time to UTC and format it as an OSCAL date-time-with-timezone string.

    Args:
        date_time (datetime | str, optional): The date and time to convert. May be a
            ``datetime`` object or an ISO-8601 string parseable into one. Naive values
            are assumed to be UTC. Defaults to the current date and time.
        format (str, optional): The ``strftime`` format string to apply.
            Defaults to ``"%Y-%m-%dT%H:%M:%SZ"`` (the OSCAL standard format).

    Returns:
        str: The formatted date-time string, or an empty string if parsing or
            formatting fails.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Add a part to an existing control, group, or part.

        Parts are valid on controls and groups (and nest inside other parts), so
        ``parent_id`` may identify any of those by id. There is no limit on how many
        parts of a given ``name`` a level may hold (e.g. multiple ``guidance`` parts).

        Args:
            parent_id (str, required): ID of the control, group, or part to add to.
            name (str, required): The part ``name`` token (e.g. "overview",
                "guidance", "example", "assessment-objective").
            title (str, optional): Part title (markup-line).
            prose (str, optional): Part prose (markup-multiline / markdown).
            ns (str, optional): Part namespace URI.
            part_class (str, optional): Part ``class`` value.
            part_id (str, optional): ID for the new part (needed to target it later,
                e.g. to nest a child part or set its title).
            props (list, optional): Property dicts to add.
            links (list, optional): Link dicts to add.
            parts (list, optional): Pre-built child part dicts to nest.

        Returns:
            Optional[dict]: The newly created part dict, or None on failure — including
                when the part would violate a "leaf part" rule (e.g. a ``guidance``
                part cannot contain child parts).

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Create a new control under the specified parent group or control.

        Args:
            parent_id (str, required): ID of the parent to add the control to —
                ``'[root]'`` (or an empty string) for the catalog top level, a group
                id, or a control id. Nesting a control under a control models a
                control enhancement (e.g. ``ac-2.1`` under ``ac-2``). The add fails if
                it would mix controls and groups at the same level (not allowed in OSCAL).
            id (str, required): ID of the new control.
            title (str, optional): Title of the new control. Defaults to the label,
                or the id, when empty.
            params (list, optional): Parameters to add. Items may be parameter id
                strings or full parameter dicts.
            props (list, optional): Additional property dicts to add.
            links (list, optional): Link dicts to add.
            label (str, optional): Value for the inline ``label`` property.
            sort_id (str, optional): Value for the inline ``sort-id`` property.
            alt_identifier (str, optional): Value for the inline ``alt-identifier`` property.
            overview (str, optional): Prose (markdown) for the ``overview`` part.
            statements (list, optional): Statement items — strings or
                ``{'id':..., 'prose':...}`` dicts.
            guidance (str, optional): Prose (markdown) for the ``guidance`` part.
            example (str, optional): Prose (markdown) for the ``example`` part.
            objectives (list, optional): Assessment objective items.
            objects (list, optional): Assessment object items.
            methods (list, optional): Assessment method items.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            Optional[dict]: The newly created control dict, or None on failure.

        Note:
            Refreshes ``controls_tree`` when a control is successfully added.

Create a new catalog group.

        Args:
            parent_id (str, required): ID of the parent group, or ``'[root]'`` (or an
                empty string) for the catalog top level. The add fails if it would mix
                controls and groups at the same level (not allowed in OSCAL).
            id (str, required): ID of the new group.
            title (str, optional): Title of the new group.
            params (list, optional): Parameters to add to the group.
            props (list, optional): Additional property dicts to add.
            links (list, optional): Link dicts to add.
            label (str, optional): Value for the inline ``label`` property.
            sort_id (str, optional): Value for the inline ``sort-id`` property.
            alt_identifier (str, optional): Value for the inline ``alt-identifier`` property.
            overview (str, optional): Prose (markdown) for the ``overview`` part.
            instruction (str, optional): Prose (markdown) for the ``instruction`` part.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            Optional[dict]: The newly created group dict, or None on failure.

        Note:
            Refreshes ``controls_tree`` when a group is successfully added.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Retrieve a control by its ID as a safe copy, searching all groups recursively.

        The returned dict is a detached copy — mutating it does NOT change the catalog;
        use the catalog's mutation methods to make persistent changes. The control's own
        content (``parts``, ``props``, ``links``, ``params`` …) is always returned in full;
        ``depth`` limits only nested child controls (enhancements).

        Args:
            control_id (str, required): The ``id`` of the control to find.
            depth (int | None, optional): Nested-enhancement depth. ``None`` (default)
                returns the full subtree; ``0`` omits enhancements; ``N`` keeps N levels.

        Returns:
            Optional[dict]: A safe copy of the matching control, or None if not found.

Return a flat list of every control in the catalog, at all levels, as safe copies.

        The returned list is detached from the document: each control is a copy, so
        mutating any element does NOT change the catalog. A single deep copy of the whole
        list preserves internal identity relationships (an enhancement nested inside its
        parent is the same object as its own standalone entry). Use the catalog's mutation
        methods to make persistent changes.

        Returns:
            list: Safe copies of all controls found across the catalog and its groups.

Retrieve a group by its ID as a safe copy, searching nested groups recursively.

        The returned dict is a detached copy — mutating it does NOT change the catalog;
        use the catalog's mutation methods to make persistent changes. The group's own
        content (``props``, ``links`` …) is always returned in full; ``depth`` limits only
        nested child groups and controls.

        Args:
            group_id (str, required): The ``id`` of the group to find.
            depth (int | None, optional): Nested group/control depth. ``None`` (default)
                returns the full subtree; ``0`` omits child groups/controls; ``N`` keeps
                N levels.

        Returns:
            Optional[dict]: A safe copy of the matching group, or None if not found.

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter defined anywhere in scope, or None.

        Searches this document and its import tree for a ``param`` with the given id —
        covering parameters defined at control, group, or catalog level (and reached
        through imported catalogs/profiles). Subclasses may override to prefer resolved
        content. See :meth:`_lookup_in_scope` for the ``with_source`` locator form.

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

Insert a pre-formed control subtree whole under a parent, as a safe copy.

        Unlike :meth:`create_control` (which authors a control from discrete parts),
        this inserts an already-formed control dict — including its nested enhancements,
        parts, props, params, and links — without reshaping it. It is the faithful-copy
        path used by profile resolution (and, later, alter directives) to move a control
        from a source catalog into a resolved one.

        The incoming dict is deep-copied before insertion, so the caller's object is not
        aliased into the catalog (getters still return detached copies).

        Args:
            parent_id (str, required): ID of the parent to add the control to —
                ``'[root]'`` (or an empty string) for the catalog top level, a group id,
                or a control id (control-under-control models an enhancement). The add
                fails if it would mix controls and groups at the same level.
            control (dict, required): The control subtree to insert. Must be a dict with
                a non-empty ``id``.
            validate (bool, optional): When True (default), the control is validated
                against the ``control`` metaschema node first; on any error the insert is
                rejected and the catalog is left unchanged.

        Returns:
            Optional[dict]: A safe copy of the inserted control, or None on failure —
                bad input, parent not found, an id collision with an existing control, a
                controls/groups mix, or failed validation.

Insert a group node under a parent, as a safe copy.

        Companion to :meth:`insert_control` for faithful-copy workflows. By default the
        insert is *shallow*: the group's intrinsic content (title, params, props, links,
        parts) is inserted but its child ``groups``/``controls`` are dropped, to be filled
        in afterward via :meth:`insert_control`/:meth:`insert_group`. This lets callers
        (e.g. profile resolution) build a group hierarchy incrementally while keeping
        empty-group pruning and duplicate handling under their own control.

        Args:
            parent_id (str, required): ID of the parent group, or ``'[root]'`` (or an
                empty string) for the catalog top level. The add fails if it would mix
                controls and groups at the same level.
            group (dict, required): The group node to insert. Must be a dict with a
                non-empty ``id``.
            shallow (bool, optional): When True (default), drop the group's child
                ``groups`` and ``controls`` before insertion. When False, insert the
                group subtree whole.
            validate (bool, optional): When True (default), validate the (possibly
                shallow) group against the ``group`` metaschema node first; on any error
                the insert is rejected and the catalog is left unchanged.

        Returns:
            Optional[dict]: A safe copy of the inserted group, or None on failure — bad
                input, parent not found, an id collision with an existing group, a
                controls/groups mix, or failed validation.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove a control or group (found by id) from the catalog.

        Two independent locks guard the delete; either can block it, and the return
        value makes the reason explicit:

          * **cascade** — when ``cascade`` is False, a node with *immediate* children
            (direct groups, controls, or parts) is not removed. The block report
            lists those immediate child ids under ``"children"``. Set ``cascade=True``
            to remove the node together with everything beneath it.
          * **referential integrity** — when ``ignore_references`` is False, the node
            is not removed if any id in its subtree (the node, nested groups/controls,
            or any part) is referenced by a link elsewhere in the catalog. The block
            report lists those referenced ids under ``"referenced_ids"``. Set
            ``ignore_references=True`` to delete anyway; the now-dangling references
            are then returned under ``"dangling_refs"``.

        Both conditions are evaluated; if both block, ``"blocked_by"`` contains both
        reasons and both detail lists are present. Nothing is modified when blocked.

        References in *other* documents (profiles, SSPs, mappings) cannot be seen or
        fixed from here; on a successful delete a warning notes they may now break.
        Refreshes ``controls_tree`` on success.

        Args:
            id (str, required): The id of the control or group to remove.
            cascade (bool, optional): Permit removing a node that has immediate
                children. Defaults to False.
            ignore_references (bool, optional): Permit removing a node that is
                referenced elsewhere in the catalog. Defaults to False.

        Returns:
            Optional[dict]:
                * ``None`` when no control/group has that id.
                * On block: ``{"removed": False, "blocked_by": [...],
                  "children": [...]?, "referenced_ids": [...]?}``.
                * On success: ``{"removed": True, "removed_ids": [...],
                  "dangling_refs": [...]}``.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set (or clear) the ``label`` property of a control or group, found by id.

        The targeted property is the ``label`` prop in the default OSCAL namespace
        whose ``class``/``group`` qualifiers match the arguments: by default the one
        with **no** class and **no** group — the same property the navigation tree
        reads. Supplying ``class_`` and/or ``group`` targets (or creates) the label
        carrying exactly those qualifiers instead.

        Behaviour:
          * A matching prop exists  → its value is updated (the first, if several).
          * No matching prop exists → one is created with the given qualifiers.
          * ``label`` is empty       → every matching prop is removed.

        Refreshes ``controls_tree`` on success.

        Args:
            id (str, required): The id of the control or group to modify.
            label (str, required): The new label value; an empty string removes the
                matching label property.
            class_ (str, optional): The prop ``class`` to target/create.
            group (str, optional): The prop ``group`` to target/create.

        Returns:
            Optional[dict]: The modified control/group dict, or None if no such id
                exists.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Set or remove the title of an existing part.

        Args:
            part_id (str, required): ID of the part to modify. The part must carry an
                ``id`` to be targetable.
            title (str, optional): The new title. When empty, the part's ``title`` is
                removed.

        Returns:
            Optional[dict]: The modified part dict, or None if no part with that id
                is found.

Set the title of a control or group, found by id.

        Refreshes ``controls_tree`` on success, since a node's ``title`` is drawn
        from the object's title.

        Args:
            id (str, required): The id of the control or group to modify.
            title (str, required): The new title. Must be non-empty — a control's
                title is required by OSCAL, so blanking it is rejected.

        Returns:
            Optional[dict]: The modified control/group dict, or None if no such id
                exists or ``title`` is empty.

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate the catalog, then (re)build ``controls_tree`` on success.

        Extends :meth:`OSCAL.validate` so the navigation tree is refreshed the
        moment the catalog is converted and found to be valid OSCAL. When the
        content is not valid the tree is emptied — an invalid catalog exposes no
        navigable hierarchy.

        Args:
            format (str, optional): Accepted for API compatibility with the base
                method; does not alter the validation path.

        Returns:
            bool: True when every validation phase passes.

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter defined anywhere in scope, or None.

        Searches this document and its import tree for a ``param`` with the given id —
        covering parameters defined at control, group, or catalog level (and reached
        through imported catalogs/profiles). Subclasses may override to prefer resolved
        content. See :meth:`_lookup_in_scope` for the ``with_source`` locator form.

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate OSCAL content against the metaschema index in sequenced phases.

        Phases (each recorded in ``validation_status``):
          structure      – all required fields and hierarchy are present
          data-types     – every leaf value matches its declared OSCAL datatype
          allowed-values – every constrained value is within its enumerated set
          cardinality    – every array satisfies its min-occurs/max-occurs bounds
          choice         – every choice is mutually exclusive (at most one member present) and has a member when one is required

        ``validation_status["well-formed"]`` is set by ``initial_validation()``, not here.
        All phases always run regardless of earlier failures, giving a complete picture
        of issues in a single call.  The format argument is accepted for API
        compatibility but does not alter the validation path — ``_dict`` is always the
        authoritative representation.

        Returns True only when every phase passes (content_state reaches VALID).

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Ensure a ``modify.alters`` entry exists for *control_id* and return a safe copy.

        Idempotent: creates the (initially empty) alter when absent, otherwise returns the
        existing one unchanged. The document is only marked unsaved when an alter is
        actually created. Used by :meth:`add_alter_adds` / :meth:`add_alter_removes`.

        Args:
            control_id (str, required): The control the alter targets.

        Returns:
            Optional[dict]: A safe copy of the alter, or None (read-only, or blank id).

Add an ``adds`` (addition) to *control_id*'s alter, creating the alter if needed.

        The addition is built from the supplied fields, pruned/validated through the
        metaschema staging gate, then appended. At least one content field
        (``title``/``params``/``props``/``links``/``parts``) must be supplied. The alter is
        only created once the addition validates, so a rejected call leaves nothing behind.

        Args:
            control_id (str, required): The control the alter targets.
            position (str, optional): ``before``/``after``/``starting``/``ending``.
            by_id (str, optional): The id the addition is positioned relative to.
            title (str, optional): A title to add.
            params (list, optional): Parameter dicts to add.
            props (list, optional): Property dicts to add.
            links (list, optional): Link dicts to add.
            parts (list, optional): Part dicts to add.

        Returns:
            Optional[dict]: A safe copy of the addition, or None on failure.

Add a ``removes`` (removal) to *control_id*'s alter, creating the alter if needed.

        The removal is built from the supplied ``by-*`` selectors (at least one required),
        validated through the metaschema staging gate, then appended. The alter is only
        created once the removal validates, so a rejected call leaves nothing behind.

        Args:
            control_id (str, required): The control the alter targets.
            by_name (str, optional): Match the named flag/field/part to remove.
            by_class (str, optional): Match by ``class``.
            by_id (str, optional): Match by ``id``.
            by_item_name (str, optional): Match by item (element) name.
            by_ns (str, optional): Match by namespace.

        Returns:
            Optional[dict]: A safe copy of the removal, or None on failure.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Retrieve a control by its ID, as a safe copy (thin alias of
        :meth:`get_control_by_id`).

        Works whether or not the profile is resolved: resolved fetches from
        ``self.catalog``; unresolved materializes on demand from the source via the
        profile's controls_tree.

        Args:
            control_id (str, required): The ``id`` of the control to retrieve.
            with_history (bool, optional): Reserved for including tailoring history.
                Defaults to False.
            depth (int | None, optional): Nested-enhancement depth. ``None`` (default)
                returns the full subtree; ``0`` omits enhancements; ``N`` keeps N levels.

        Returns:
            Optional[dict]: A safe copy of the control, or None if not found.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Write the resolved catalog to a file — wrapper over ``self.catalog.dump``.

        Requires the profile to be resolved (``self.catalog`` is None until
        :meth:`resolve`); returns False with a warning otherwise.

        Args:
            filename (str, optional): Path to write to; defaults to the catalog's original
                location when empty.
            format (str, optional): Output format ("xml", "json", "yaml"); defaults to the
                catalog's original format when empty.
            pretty_print (bool, optional): Whether to pretty-print. Defaults to False.

        Returns:
            bool: True on success, False when unresolved or the write fails.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Serialize the resolved catalog to a string — wrapper over ``self.catalog.dumps``.

        Requires the profile to be resolved (``self.catalog`` is None until
        :meth:`resolve`); returns ``""`` with a warning otherwise.

        Args:
            format (str, optional): Target format ("xml", "json", "yaml"); defaults to the
                catalog's original format.
            pretty_print (bool, optional): Whether to pretty-print. Defaults to False.

        Returns:
            str: The serialized resolved catalog, or ``""`` when unresolved.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Return a safe copy of the ``modify.alters`` entry for *control_id*.

        Args:
            control_id (str, required): The ``control-id`` of the alter to fetch.

        Returns:
            Optional[dict]: A deep copy of the alter (with its ``adds``/``removes``), or
                None if no alter targets *control_id*.

Retrieve a control as a safe copy — from the resolved catalog if resolved,
        otherwise materialized on demand from the source via the profile's controls_tree.

        Both paths return the same shape (the control with its in-scope enhancements
        nested per ``depth``, this profile's ``modify`` directives applied). When
        unresolved, the control is materialized from its origin source on each call.

        Args:
            control_id (str, required): The control id (as it appears in this profile's
                scope — a duplicate's suffixed id is valid).
            depth (int | None, optional): Enhancement depth (``None`` full).

        Returns:
            Optional[dict]: A safe copy of the control, or None when absent.

Return safe copies of every in-scope control, at all levels.

        Resolved: pass-through to :meth:`Catalog.get_control_list`. Unresolved: each
        control node in the profile's controls_tree is materialized standalone (depth 0),
        mirroring the flat, enhancement-inclusive list a catalog returns.

Return the profile's merge directives as a simple, normalized dict.

        A library-level view of the ``merge`` element that does not pass the raw OSCAL
        through. Always includes:

        * ``combine`` — ``"use-first"`` when that method is set; ``"keep"`` when ``keep``
          is set *or* no ``combine`` is present (the effective default); ``"invalid"`` for
          any other stored method (e.g. the OSCAL ``merge`` method, which this library does
          not model).
        * ``hierarchy`` — ``"flat"`` / ``"as-is"`` / ``"custom"`` from whichever directive
          is present (an ``as-is`` directive maps to ``"as-is"`` regardless of its boolean
          value). Defaults to ``"as-is"`` — OSCAL's default organization — when no
          directive (or no ``merge``) is present.

        And, only when ``hierarchy == "custom"``:

        * ``custom`` — a safe copy of the ``custom`` object (with its ``groups`` /
          ``insert-controls`` children).

        Returns:
            dict: ``{"combine": ..., "hierarchy": ...[, "custom": {...}]}``.

Retrieve a group as a safe copy — from the resolved catalog if resolved,
        otherwise materialized on demand from the source via the profile's controls_tree.

        Args:
            group_id (str, required): The group id (as it appears in this profile's scope).
            depth (int | None, optional): Nested group/control depth (``None`` full).

        Returns:
            Optional[dict]: A safe copy of the group, or None when absent.

Return an import statement's control-selection structures as a safe copy.

        Fetches the ``include-all``, ``include-controls``, and ``exclude-controls``
        structures for the import identified by *href* (any tracked href form — see
        :meth:`_locate_import_statement`). Only the keys actually present are returned, so
        an import that selects via ``include-controls`` yields no ``include-all`` key.

        Args:
            href (str, required): Any href that identifies the import statement.

        Returns:
            Optional[dict]: A deep-copied dict containing whichever of ``include-all`` /
                ``include-controls`` / ``exclude-controls`` are present (``{}`` when the
                import carries none), or None when no import matches *href*.

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter as a safe copy — from the resolved catalog if resolved,
        otherwise located in the import tree (its source, unmutated).

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a safe copy of the ``modify.set-parameters`` entry for *param_id*.

        Args:
            param_id (str, required): The ``param-id`` of the set-parameter to fetch.

        Returns:
            Optional[dict]: A deep copy of the set-parameter, or None if none matches.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

The control-tree assembly strategy (:class:`MergeStrategy`).

        Defaults to ``REFERENTIAL`` (reconstruct source hierarchy). Assigning a new
        value marks the controls_tree stale, drops any resolved catalog, and rebuilds
        the tree so subsequent reads reflect the chosen strategy.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove ``adds`` from *control_id*'s alter that match the given selectors.

        Scope is the alter for *control_id*. ``by_id`` is required; ``position`` is
        optional. Every addition whose supplied selectors **all** match is removed (so
        ``by_id`` alone removes all additions with that ``by-id`` regardless of position;
        adding ``position`` narrows it). An emptied ``adds`` array, an alter left with no
        ``adds``/``removes``, an emptied ``alters`` array, and an emptied ``modify`` are all
        pruned.

        Args:
            control_id (str, required): The control whose alter is edited.
            by_id (str, required): Match additions with this ``by-id``.
            position (str, optional): Also require this ``position``.

        Returns:
            bool: True if at least one addition was removed, else False.

Remove ``removes`` from *control_id*'s alter that match the given selectors.

        Scope is the alter for *control_id*. Every removal whose **supplied** ``by-*``
        selectors all match is deleted (unspecified selectors are ignored). With no
        selector supplied, every removal for the control is deleted. An emptied ``removes``
        array, an alter left with no ``adds``/``removes``, an emptied ``alters`` array, and
        an emptied ``modify`` are all pruned.

        Args:
            control_id (str, required): The control whose alter is edited.
            by_name, by_class, by_id, by_item_name, by_ns (str, optional): Selectors that
                must match (all supplied ones) for a removal to be deleted.

        Returns:
            bool: True if at least one removal was removed, else False.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Remove the ``modify.set-parameters`` entry for *param_id*.

        Prunes an emptied ``set-parameters`` array and an emptied ``modify`` object.

        Args:
            param_id (str, required): The ``param-id`` of the set-parameter to remove.

        Returns:
            bool: True if a set-parameter was removed, else False (no match, blank
                ``param_id``, or read-only content).

Materialize the profile's controls_tree into a fresh ``self.catalog``.

        Resolution is the cacheable heavy step: it walks the profile's
        controls_tree — the authoritative scope/organization built at load — and for each
        node fetches the real control/group content from its origin source, applies this
        profile's ``modify`` directives (removes → adds → set-parameters), applies full
        internal ``__<uuid>`` id renaming for duplicates, then inserts it into a brand-new
        ``Catalog``. Any previously resolved catalog is discarded and replaced. After
        placement it: hoists cited-but-externally-defined parameters to the catalog root
        (:meth:`_insert_shared_params`), assembles metadata, carries forward referenced
        back-matter resources (:meth:`_carry_backmatter`), rewrites references to
        out-of-scope ids to their source URIs (:meth:`_rewrite_out_of_scope_refs`), and
        validates.

        Because content is fetched through each source's own getters, imported *profiles*
        need not be pre-resolved — their load-time controls_tree and lazy getters suffice.

        Returns:
            ResolutionStatus: ``RESOLVED`` on success, or ``BLOCKED`` when content is
                missing or an import could not be resolved.

Resolve the profile, then write the resolved catalog to a file.

        Convenience for the common one-shot case: it runs the (potentially expensive)
        :meth:`resolve` and then :meth:`dump_catalog`. For finer control — e.g. to resolve
        once and write several outputs, or to manage *when* the heavy resolution runs — call
        :meth:`resolve` and :meth:`dump_catalog` separately instead.

        Note: each call performs a full resolution (rebuilds ``self.catalog`` from scratch).

        Args:
            filename (str, optional): Path to write to; defaults to the catalog's original
                location when empty.
            format (str, optional): Output format ("xml", "json", "yaml").
            pretty_print (bool, optional): Whether to pretty-print. Defaults to False.

        Returns:
            bool: True on success, False if resolution was blocked or the write failed.

Resolve the profile, then serialize the resolved catalog to a string.

        Convenience for the common one-shot case: it runs the (potentially expensive)
        :meth:`resolve` and then :meth:`dumps_catalog`. For finer control — e.g. to resolve
        once and serialize many times, or to manage *when* the heavy resolution runs — call
        :meth:`resolve` and :meth:`dumps_catalog` separately instead.

        Note: each call performs a full resolution (rebuilds ``self.catalog`` from scratch).

        Args:
            format (str, optional): Target format ("xml", "json", "yaml").
            pretty_print (bool, optional): Whether to pretty-print. Defaults to False.

        Returns:
            str: The serialized resolved catalog, or ``""`` if resolution was blocked.

Manually collapse duplicate instances of a control in the resolved catalog.

        Requires a resolved catalog. Merging logic is out of scope (handled by the
        caller, e.g. a GUI); this keeps, relocates, or wholesale-replaces:

          * ``replacement`` given — remove every live variant (the original id and each
            tracked ``new_id``) and insert ``replacement`` (validated) under ``parent_id``
            (or the original variant's current parent).
          * ``keep`` given (or defaulted to ``control_id``) — remove every variant except
            ``keep``; if ``parent_id`` is given, relocate the kept control there.

        Args:
            control_id (str, required): The ORIGINAL (unsuffixed) control id.
            keep (str, optional): Which variant id to retain. Defaults to ``control_id``.
            parent_id (str, optional): Where to place the survivor. Defaults to in place.
            replacement (dict, optional): A full control dict superseding all variants.

        Returns:
            Optional[dict]: A safe copy of the surviving control, or None on failure.

Manually collapse duplicate instances of a group in the resolved catalog.

        The group analogue of :meth:`resolve_duplicate`. NOTE: removing a group removes
        its contained controls too (cascade), so prefer resolving duplicate *controls*
        first when both are tracked.

        Args:
            group_id (str, required): The ORIGINAL (unsuffixed) group id.
            keep (str, optional): Which variant group id to retain. Defaults to ``group_id``.
            parent_id (str, optional): Where to place the survivor. Defaults to in place.
            replacement (dict, optional): A full group dict superseding all variants.

        Returns:
            Optional[dict]: A safe copy of the surviving group, or None on failure.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set the profile's merge directives without raw pass-through to OSCAL.

        Edits ``combine`` and/or the hierarchy directive independently; at least one of
        ``combine`` / ``hierarchy`` must be given. Changes are assembled in a **staging**
        copy and committed only when the whole result is valid — a rejected call changes
        nothing (roll back). The counterpart reader is :meth:`get_directives`.

        Args:
            combine (str, optional): ``"use-first"`` or ``"keep"``. Replaces
                ``merge.combine.method`` with that value. Any other value is rejected.
            hierarchy (str, optional): ``"flat"``, ``"as-is"``, or ``"custom"``.

                * ``"flat"`` — remove any ``as-is`` / ``custom``; add ``flat`` if absent.
                * ``"as-is"`` — remove any ``flat`` / ``custom``; set ``as-is`` to ``true``.
                * ``"custom"`` — requires the ``custom`` argument (below); remove any
                  ``as-is`` / ``flat``; set ``custom`` to the provided object.
            custom (dict, optional): Required when ``hierarchy == "custom"`` (ignored
                otherwise). Must be a dict following the OSCAL ``merge.custom`` syntax; it
                is pruned/validated through the shared metaschema staging gate
                (:meth:`_stage_against_index`). If it is not valid the hierarchy is left
                unchanged and the method returns ``False``.

        Returns:
            bool: ``True`` on success; ``False`` on any failure (read-only content, no
                directive supplied, an invalid ``combine``/``hierarchy`` value, a missing
                or invalid ``custom``, or a result with no hierarchy directive).

Replace an import statement's control-selection structures.

        Wholesale-replaces the ``include-all`` / ``include-controls`` / ``exclude-controls``
        of the import identified by *href* (any tracked href form). The resulting selection
        is exactly what is supplied: an argument left as ``None`` is *omitted* from the
        rewritten import (pass ``exclude_controls=[]`` to clear an exclusion while keeping
        it present as an empty array). ``href`` and any other schema-valid keys on the
        statement are carried through unchanged.

        Supplied structures are not stored blindly. The whole candidate import is assembled
        and checked in a **staging** copy via :meth:`_stage_against_index`, and the live
        import is only overwritten once every check passes — a rejected replacement **rolls
        back** to the prior content, changing nothing. The candidate is *pruned* to exactly
        the keys and nesting the OSCAL ``import`` schema permits (the metaschema represents
        OSCAL syntax in full and is authoritative, so anything it does not permit — at any
        depth — is dropped with a warning; a wrong array/scalar shape is rejected) and
        validated for *required* content and correctness: exactly one of ``include-all`` /
        ``include-controls`` must be present (the mutually-exclusive OSCAL choice —
        supplying neither fails), and datatypes, allowed values, required fields, and
        cardinality are enforced. On success the ``controls_tree`` is rebuilt and any
        resolved catalog is dropped, since scope has changed.

        Args:
            href (str, required): Any href that identifies the import statement.
            include_all (dict, optional): The ``include-all`` object (typically ``{}``).
                Mutually exclusive with ``include_controls``.
            include_controls (list, optional): A list of ``select-control-by-id`` dicts
                (e.g. ``[{"with-ids": ["ac-1"]}]``). Mutually exclusive with
                ``include_all``.
            exclude_controls (list, optional): A list of ``select-control-by-id`` dicts to
                exclude.

        Returns:
            Optional[dict]: A safe copy of the rewritten import statement, or None on
                failure — no matching import, a wrong argument type, or a replacement that
                fails metaschema validation (including supplying both/neither include form).

Set the profile's ``merge`` directives (``combine`` plus flat/as-is/custom).

        .. deprecated::
            Prefer :meth:`set_directives` (paired with :meth:`get_directives`), which
            edits ``combine`` and the hierarchy directive independently and validates
            ``custom`` through the shared metaschema staging gate. This method writes the
            whole ``merge`` element as a direct pass-through and is retained for
            compatibility.

        The ``merge`` assembly instructs how imported controls are organized after
        profile resolution. Exactly one of ``flat``, ``as_is``, or ``custom`` must be
        chosen — they are mutually exclusive — while ``combine`` is optional and may
        accompany any of those choices.

        The ``custom`` object is accepted whole and validated against the ``custom``
        portion of the profile metaschema index; if it fails validation the profile is
        left unchanged. Fine-grained management of ``custom`` internals (its ``groups``
        and ``insert-controls``) is intentionally deferred to future methods, as custom
        merges are uncommon.

        Args:
            flat (bool, optional): When True, select the ``flat`` directive (resolved
                controls are flattened, without groups). Defaults to False.
            as_is (bool, optional): When set, select the ``as-is`` directive with this
                boolean value (True keeps the source organization). Defaults to None
                (not selected).
            custom (dict, optional): When set, select the ``custom`` directive using
                this object. Validated against the metaschema index. Defaults to None
                (not selected).
            combine (str, optional): The ``combine`` method — one of ``"use-first"``,
                ``"merge"``, or ``"keep"``. When None, no ``combine`` is written.

        Returns:
            Optional[dict]: The ``merge`` dict written to the profile, or None on
                failure — when not exactly one of flat/as-is/custom is given, an
                argument has the wrong type, ``combine`` is not a valid method, or the
                ``custom`` object fails metaschema validation.

Change just the profile's merge *directive* (``as-is`` / ``flat`` / ``custom``).

        .. deprecated::
            Prefer :meth:`set_directives`, which changes the hierarchy directive (and/or
            ``combine``) independently and validates ``custom`` through the shared
            metaschema staging gate. Retained for compatibility.

        A focused convenience wrapper over :meth:`set_merge` for the common case of
        switching the organization directive without restating the other arguments. The
        existing ``combine`` method is preserved unless a new one is supplied, and when
        switching to ``custom`` the profile's existing ``custom`` object is reused unless
        one is provided. On success :attr:`merge_directive` and the ``controls_tree`` are
        refreshed (both handled by :meth:`set_merge`).

        Args:
            directive (str, required): One of ``"as-is"``, ``"flat"``, or ``"custom"``.
            custom (dict, optional): The ``custom`` object to use when
                ``directive == "custom"``. Defaults to the profile's current ``custom``
                object; required (here or already present) for a custom directive.
            combine (str, optional): A ``combine`` method to set. Defaults to the
                profile's current ``combine`` method (preserved).

        Returns:
            Optional[dict]: The ``merge`` dict written (a safe copy), or None on failure —
                an unknown ``directive``, a ``custom`` directive with no object available,
                or any failure surfaced by :meth:`set_merge`.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Create or update a ``modify.set-parameters`` entry (upsert, per-field merge).

        When no ``set-parameter`` with *param_id* exists one is created from the supplied
        fields. When one exists, each supplied field **overwrites** the corresponding
        content; a field left as ``None`` leaves any existing content untouched. Most
        commonly used to set a ``value`` or a ``constraint``.

        ``values`` and the ``select`` form (``select_cardinality`` / ``select_choices``)
        are the OSCAL mutually-exclusive choice: supplying both is rejected. Supplying
        ``values`` clears any existing ``select`` (and vice versa). The assembled entry is
        pruned/validated through the metaschema staging gate before it is committed, so an
        invalid input leaves the profile unchanged.

        Args:
            param_id (str, required): The ``param-id`` this setting targets.
            class_ (str, optional): The parameter ``class``.
            props (list, optional): Property dicts.
            links (list, optional): Link dicts.
            label (str, optional): Parameter label (markup-line).
            usage (str, optional): Usage prose (markup-multiline).
            constraints (list, optional): Constraint dicts.
            guidelines (list, optional): Guideline dicts.
            values (list, optional): Parameter value strings. Mutually exclusive with the
                ``select_*`` arguments.
            select_cardinality (str, optional): ``select.how-many`` (e.g. "one",
                "one-or-more").
            select_choices (list, optional): ``select.choice`` value strings.

        Returns:
            Optional[dict]: A safe copy of the written ``set-parameter``, or None on
                failure (missing/blank ``param_id``, both value and select supplied, a
                wrong argument type, or a result that fails metaschema validation).

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate the profile, then (re)build ``controls_tree`` on success.

        Mirrors :meth:`Catalog.validate`: the profile's authoritative scope and
        organization tree is refreshed the moment the content is converted and
        found to be valid OSCAL — no call to :meth:`resolve` is required. Building
        the tree resolves the profile's imports if they are not already resolved.
        When the content is not valid the tree is emptied and left marked stale so a
        later access rebuilds it.

        Args:
            format (str, optional): Accepted for API compatibility with the base
                method; does not alter the validation path.

        Returns:
            bool: True when every validation phase passes.

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

Render metaschema-walk errors (from ``_walk_instance``) as a compact one-liner.

    Args:
        errors (list, required): The structured error dicts collected by a walk.

    Returns:
        str: A ``"; "``-joined summary, one clause per error.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter defined anywhere in scope, or None.

        Searches this document and its import tree for a ``param`` with the given id —
        covering parameters defined at control, group, or catalog level (and reached
        through imported catalogs/profiles). Subclasses may override to prefer resolved
        content. See :meth:`_lookup_in_scope` for the ``with_source`` locator form.

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate OSCAL content against the metaschema index in sequenced phases.

        Phases (each recorded in ``validation_status``):
          structure      – all required fields and hierarchy are present
          data-types     – every leaf value matches its declared OSCAL datatype
          allowed-values – every constrained value is within its enumerated set
          cardinality    – every array satisfies its min-occurs/max-occurs bounds
          choice         – every choice is mutually exclusive (at most one member present) and has a member when one is required

        ``validation_status["well-formed"]`` is set by ``initial_validation()``, not here.
        All phases always run regardless of earlier failures, giving a complete picture
        of issues in a single call.  The format argument is accepted for API
        compatibility but does not alter the validation path — ``_dict`` is always the
        authoritative representation.

        Returns True only when every phase passes (content_state reaches VALID).

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Add a by-component statement to one of the SSP's implemented-requirements.

        The by-component is **built from the supplied scalar fields** — no caller-provided
        dict is stored verbatim — so it is schema-aligned by construction. It is appended
        to the implemented-requirement identified by *implemented_requirement_uuid* and
        returned as a safe copy (the live node stays in ``_dict``; further edits go through
        methods). Through the method decorators this also enforces the read-only guard and
        marks the document unsaved.

        Args:
            implemented_requirement_uuid (str, required): ``uuid`` of the target
                implemented-requirement under ``control-implementation``.
            component_uuid (str, required): UUID of the referenced system component.
            description (str, required): How the component satisfies the requirement.
            by_component_uuid (str, optional): UUID for the by-component; a new one is
                generated when empty.
            implementation_status (str, optional): ``implementation-status.state`` value.
                Defaults to "implemented".
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            Optional[dict]: A safe copy of the new by-component, or None when the SSP has
                no implemented-requirement with that uuid.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Add a component to the SSP's ``system-implementation`` section.

        Args:
            component_type (str, required): The component ``type`` (e.g. "software").
            component_title (str, required): The component title.
            component_description (str, required): The component description.
            op_status (str, optional): Operational ``status.state`` value.
                Defaults to "operational".
            component_uuid (str, optional): UUID for the component. A new UUID is
                generated when empty.
            props (list, optional): Property dicts to add.
            links (list, optional): Link dicts to add.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            Optional[dict]: The newly created component dict, or None on failure.

Add an implemented-requirement to the SSP's ``control-implementation`` section.

        Args:
            control_id (str, required): The ID of the control being implemented.
            props (list, optional): Property dicts to add.
            links (list, optional): Link dicts to add.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            Optional[dict]: The newly created implemented-requirement dict (with a
                generated UUID), or None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter defined anywhere in scope, or None.

        Searches this document and its import tree for a ``param`` with the given id —
        covering parameters defined at control, group, or catalog level (and reached
        through imported catalogs/profiles). Subclasses may override to prefer resolved
        content. See :meth:`_lookup_in_scope` for the ``with_source`` locator form.

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate OSCAL content against the metaschema index in sequenced phases.

        Phases (each recorded in ``validation_status``):
          structure      – all required fields and hierarchy are present
          data-types     – every leaf value matches its declared OSCAL datatype
          allowed-values – every constrained value is within its enumerated set
          cardinality    – every array satisfies its min-occurs/max-occurs bounds
          choice         – every choice is mutually exclusive (at most one member present) and has a member when one is required

        ``validation_status["well-formed"]`` is set by ``initial_validation()``, not here.
        All phases always run regardless of earlier failures, giving a complete picture
        of issues in a single call.  The format argument is accepted for API
        compatibility but does not alter the validation path — ``_dict`` is always the
        authoritative representation.

        Returns True only when every phase passes (content_state reaches VALID).

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

Add a component to an SSP's ``system-implementation`` section.

    Args:
        ssp_obj (OSCAL, required): The SSP instance to modify.
        component_type (str, required): The component ``type`` (e.g. "software").
        component_title (str, required): The component title.
        component_description (str, required): The component description.
        op_status (str, optional): Operational ``status.state`` value.
            Defaults to "operational".
        component_uuid (str, optional): UUID for the component. A new UUID is
            generated when empty.
        props (list, optional): Property dicts to add.
        links (list, optional): Link dicts to add.
        remarks (str, optional): Remarks prose (markdown).

    Returns:
        Optional[dict]: The newly created component dict, or None on failure.

Add an implemented-requirement to an SSP's ``control-implementation`` section.

    Args:
        ssp_obj (OSCAL, required): The SSP instance to modify.
        control_id (str, required): The ID of the control being implemented.
        props (list, optional): Property dicts to add.
        links (list, optional): Link dicts to add.
        remarks (str, optional): Remarks prose (markdown).

    Returns:
        Optional[dict]: The newly created implemented-requirement dict (with a
            generated UUID), or None on failure.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter defined anywhere in scope, or None.

        Searches this document and its import tree for a ``param`` with the given id —
        covering parameters defined at control, group, or catalog level (and reached
        through imported catalogs/profiles). Subclasses may override to prefer resolved
        content. See :meth:`_lookup_in_scope` for the ``with_source`` locator form.

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate OSCAL content against the metaschema index in sequenced phases.

        Phases (each recorded in ``validation_status``):
          structure      – all required fields and hierarchy are present
          data-types     – every leaf value matches its declared OSCAL datatype
          allowed-values – every constrained value is within its enumerated set
          cardinality    – every array satisfies its min-occurs/max-occurs bounds
          choice         – every choice is mutually exclusive (at most one member present) and has a member when one is required

        ``validation_status["well-formed"]`` is set by ``initial_validation()``, not here.
        All phases always run regardless of earlier failures, giving a complete picture
        of issues in a single call.  The format argument is accepted for API
        compatibility but does not alter the validation path — ``_dict`` is always the
        authoritative representation.

        Returns True only when every phase passes (content_state reaches VALID).

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter defined anywhere in scope, or None.

        Searches this document and its import tree for a ``param`` with the given id —
        covering parameters defined at control, group, or catalog level (and reached
        through imported catalogs/profiles). Subclasses may override to prefer resolved
        content. See :meth:`_lookup_in_scope` for the ``with_source`` locator form.

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate OSCAL content against the metaschema index in sequenced phases.

        Phases (each recorded in ``validation_status``):
          structure      – all required fields and hierarchy are present
          data-types     – every leaf value matches its declared OSCAL datatype
          allowed-values – every constrained value is within its enumerated set
          cardinality    – every array satisfies its min-occurs/max-occurs bounds
          choice         – every choice is mutually exclusive (at most one member present) and has a member when one is required

        ``validation_status["well-formed"]`` is set by ``initial_validation()``, not here.
        All phases always run regardless of earlier failures, giving a complete picture
        of issues in a single call.  The format argument is accepted for API
        compatibility but does not alter the validation path — ``_dict`` is always the
        authoritative representation.

        Returns True only when every phase passes (content_state reaches VALID).

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

Acquire OSCAL content from one or more URI/reference sources.

        The sources are treated as an ordered fallback list; the first that
        resolves successfully is used.

        Args:
            source (str | dict | OscalRef | list, required): The reference(s) to
                acquire. May be a URI/path string, an ``OscalRef``, a reference dict
                containing at least ``"href"``, or a list mixing any of these.
            cache (CacheDirective | None, optional): Caching directive applied to
                remote fetches (e.g. ``CacheDirective.never()``,
                ``CacheDirective.refresh_now()``). Keyword-only. Defaults to the
                standard 24h behavior.

        Returns:
            OSCAL: A new instance populated from the first resolvable source.

Add a first-level import to this document, backed by a back-matter resource.

        Uniform across every model; legality is governed by :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — ``invalid``.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR) — ``invalid``; set
          their single import with :meth:`retry_import` instead of add/remove.
        * Otherwise an import is added while the count of *real* imports is below the
          model's ``max`` (unbounded when ``max`` is None).

        The import references a back-matter ``resource`` by UUID fragment
        (``href="#<uuid>"``): if a resource whose ``rlink`` already targets ``href``
        exists it is reused, otherwise one is created via :meth:`append_resource` with
        which this method shares its resource parameters (``uuid``/``title``/
        ``description``/``props``/``remarks``). The ``href`` becomes the resource's
        single ``rlink`` (with a best-effort ``media-type`` inferred from it), and
        ``version`` is appended to ``props`` as a ``prop`` named ``"version"``. An empty
        placeholder import (href ``""``/``"#"``) is filled in place; otherwise the entry
        is appended (list models) or set (single-import models). After placement the
        import tree and any derived state are refreshed via :meth:`_after_imports_changed`.

        Args:
            href (str, required): Reference to the imported OSCAL file (XML/JSON/YAML);
                becomes the created resource's ``rlink`` href.
            uuid (str, optional): UUID for the created resource; generated when empty.
                Ignored when an existing resource is reused. Mirrors :meth:`append_resource`.
            title (str, optional): Title for the created resource.
            description (str, optional): Description for the created resource.
            props (list, optional): Property dicts for the created resource; ``version``
                (below) is appended to these. Mirrors :meth:`append_resource`.
            version (str, optional): Convenience — appended to ``props`` as a ``prop``
                named ``"version"`` (resources have no native version field).
            remarks (str, optional): Remarks (markdown) for the created resource.
            include_all (bool, optional): Keyword-only, profile-only. When True a new
                profile import selects all controls via ``include-all`` instead of the
                default empty ``include-controls``/``with-ids`` placeholder. Ignored by
                models whose imports carry no selection. Defaults to False.

        Returns:
            ImportResult: ``status`` of "added", "replaced", "duplicate", "invalid",
                or "error", with the relevant ``entry`` and ``resource``.

Appends a child dict to the list at the given JSON path.

        Path segments are '/' separated, relative to the model root.  The leaf
        segment names the list key; it is created as an empty list if absent.

        Args:
            path (str):  Slash-separated path to the target list relative to the
                         model root, e.g. "metadata/props" or "back-matter/resources".
            child (dict): Dict to append to the list.

        Returns:
            dict | None: The appended child on success, None on failure.

Append a resource to the document's ``back-matter`` section.

        Args:
            uuid (str, optional): Resource UUID. A new UUID is generated when empty.
            title (str, optional): Resource title.
            description (str, optional): Resource description.
            props (list, optional): Property dicts to add.
            rlinks (list, optional): Resource-link (``rlink``) dicts to add.
            base64 (str, optional): Base64-encoded inline content.
            remarks (str, optional): Remarks prose (markdown).

        Returns:
            dict | None: The newly created resource dict, or None on failure.

Write the current OSCAL content to a file.
        With no parameters, saves to the original location in the original format.
        This will save to any valid filename, even if the file extension does not match the format.
        Output keys/elements are emitted in canonical metaschema order (see :meth:`dumps`).

        Args:
            filename (str, optional): Path to write to. Defaults to the original
                source location when empty.
            format (str, optional): Output format — one of ``OSCAL_FORMATS``
                ("xml", "json", "yaml", "yml"). Defaults to the original format when empty.
            pretty_print (bool, optional): Whether to pretty-print the output.
                Defaults to False.

        Returns:
            bool: True if the write succeeded, False otherwise.

Serialize the current content to a string in the specified format.

        Keys/elements are emitted in canonical NIST metaschema order: XML element
        order is schema-required and always canonical; JSON/YAML key order is
        canonical on a best-effort basis (see :meth:`_ordered_dict`).

        Parameters:
        - format (str): The target format for serialization ("xml", "json", or "yaml")
            Defaults to the original format of the content if not specified.
        - pretty_print (bool): Whether to pretty-print the output. Defaults to False.

        Returns:
        - str: The serialized content as a string.

Return import_list entries detected as duplicates of an earlier import.

        Duplicates are non-blocking — they do NOT prevent imports_resolved from
        becoming True — but they remain available for the caller to act on via
        retry_import (supply a different source), ignore_import, or remove_import.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        duplicate entry holds no document of its own (the original READY entry carries
        it), so for every entry here ``object_uuid`` is always ``None`` and the six
        summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are always ``""``.

Return import_list entries that failed, each carrying a populated 'failure' field.

        These are blocking: while any failed import remains, content_state stays
        at VALID and imports_resolved is False.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception: a
        failed import never acquires its document, so for every entry here ``object_uuid``
        is always ``None`` and the six summary fields (``model``, ``title``,
        ``oscal_version``, ``version``, ``published``, ``last_modified``) are always ``""``.

Resolve an id/uuid by searching this document and its import tree.

        OSCAL cross-references (``href="#..."``) can point at content that lives in an
        imported document — a back-matter ``resource`` (by uuid), a metadata ``role`` (by
        id), ``party`` (by uuid), ``location`` (by uuid), or ``responsible-party`` (by
        role-id), or a ``control``/``group``/``param``/``part`` (by id). This walks
        ``self`` first, then each imported document depth-first (de-duplicated,
        cycle-safe), and returns the first match together with the document that owns it.

        Args:
            fragment_id (str, required): The bare id/uuid to resolve (no leading ``#``).
            kinds (Iterable[str] | None, optional): Restrict the search to these element
                kinds (subset of :attr:`_RESOLVE_KINDS`); ``None`` searches all.
            _seen (set | None, optional): Internal cycle-guard.

        Returns:
            Optional[dict]: ``{"element", "kind", "id", "object_uuid", "href"}`` — a safe
                copy of the found element, its kind, the owning document's root uuid and
                resolved href — or None when not found anywhere in the tree.

Explicit constructor for in-memory OSCAL string content.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): URI identifying the source. Keyword-only.
                Defaults to None.

        Returns:
            OSCAL: A new instance (delegates to :meth:`loads`).

Return a metadata ``location`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.locations`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a location with the given uuid
        is found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return the LIVE imported OSCAL document whose root UUID matches ``uuid``.

        Searches this document and its resolved imports depth-first, de-duplicating
        objects shared across multiple import paths (the same large catalog reached
        two ways is visited once). This underpins the import mechanism's object reuse
        and is the companion to :attr:`import_tree`: the tree carries each node's
        ``object_uuid``; pass one here to obtain the corresponding live instance.

        Unlike the model getters, this returns the LIVE object (not a copy) — it is a
        document handle meant for working with that instance through its own methods.

        Args:
            uuid (str, required): The root UUID of the document to locate.
            _seen (set | None, optional): Object ids already visited; used internally
                for cycle-safety. Defaults to None.

        Returns:
            OSCAL | None: The matching live document, or None if not found.

Return a parameter defined anywhere in scope, or None.

        Searches this document and its import tree for a ``param`` with the given id —
        covering parameters defined at control, group, or catalog level (and reached
        through imported catalogs/profiles). Subclasses may override to prefer resolved
        content. See :meth:`_lookup_in_scope` for the ``with_source`` locator form.

Return a metadata ``party`` (by uuid) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a party with the given uuid is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Return a back-matter resource defined anywhere in scope, or None.

        Looks in THIS document's ``back-matter`` first; on a local miss the search
        cascades out through the immediately imported documents and continues depth-first
        along every branch (de-duplicated and cycle-safe) until a ``resource`` whose
        ``uuid`` matches is found or every branch is exhausted. This lets a cross-reference
        (``href="#uuid"``) resolve even when the resource is defined in an imported
        document rather than locally. Subclasses may override to prefer resolved content.

        Args:
            resource_uuid (str, required): The bare resource UUID to resolve (no ``#``).
            with_source (bool, optional): Return the full locator (element + owning
                ``object_uuid``/``href``) instead of the bare resource; useful for
                resolving the resource's relative rlink hrefs. Defaults to False.
            local_only (bool, optional): Search only THIS document, never imports.
                Defaults to False.

        Returns:
            Optional[dict]: A safe copy of the matching resource (or locator), or None.

Return a metadata ``responsible-party`` (by role-id) in scope, or None.

        A ``responsible-party`` is keyed by the ``role-id`` it fulfills. Looks in THIS
        document's ``metadata.responsible-parties`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until one with the given role-id is
        found or every branch is exhausted. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

        Note: this targets metadata-level ``responsible-parties`` only. The
        ``responsible-role`` assemblies embedded throughout implementation/assessment
        models are model-specific and handled by a separate, later cascade.

Return a metadata ``role`` (by id) defined anywhere in scope, or None.

        Looks in THIS document's ``metadata.roles`` first, then (unless ``local_only``)
        cascades depth-first through the import tree until a role with the given id is
        found or every branch is exhausted — so a ``role-id`` reference resolves even when
        the role is defined in an imported document. See :meth:`_lookup_in_scope` for
        ``with_source`` and ``local_only``.

Mark an import as intentionally ignored.

        The entry remains in import_list with status IGNORED.  Like DUPLICATE,
        IGNORED entries are treated as non-blocking: once all remaining entries
        are READY, DUPLICATE, or IGNORED, content_state advances to
        IMPORTS_RESOLVED.

        Typical use: the caller presents a DUPLICATE entry to the user and the
        user explicitly chooses to ignore it rather than supply a replacement.

        The same priority ordering used by retry_import applies when multiple
        entries share the same href — DUPLICATE and INVALID are preferred over
        READY.

        Args:
            href: Any href that identifies the entry (href_original, href_valid,
                  failure.uri, or an href_list item href).

        Returns:
            True if an entry was found and updated, False if no match was found.

Recursive import tree built lazily on first access and cached.

        Returns a root node dict representing this document, with an ``imports`` key
        holding the first-level imports; each import is a node of the same shape,
        recursively. The tree is a SAFE COPY of the cached structure — mutating it does
        not affect the cache; use :meth:`rebuild_import_tree` to force a fresh traversal.

        The tree carries no live OSCAL objects, so it stays small and safe to
        serialize/transmit. Instead, each node identifies its document by UUID and
        summary metadata; call :meth:`get_oscal_object` with ``object_uuid`` to obtain
        the live instance when one is actually needed.

        Each node (root and every import) has these keys:

        * ``href_original`` (str): the import href as written in the source document.
        * ``href_valid`` (str): the resolved href actually loaded, if any.
        * ``href_list`` (list[dict]): every href attempted, with per-attempt status.
        * ``status`` (ImportState): READY, INVALID, DUPLICATE, or IGNORED.
        * ``is_valid`` / ``is_local`` / ``is_remote`` / ``is_cached`` (bool): provenance.
        * ``object_uuid`` (str | None): the imported document's root UUID, or None when
          it was not acquired. Pass to :meth:`get_oscal_object` for the live object.
        * ``model`` (str): the imported document's model type (e.g. "catalog").
        * ``title`` (str): the imported document's metadata title.
        * ``oscal_version`` (str): the OSCAL version (no ``v`` prefix, e.g. "1.1.3").
        * ``version`` (str): the document's own metadata version.
        * ``published`` (str): the metadata publication timestamp (RFC-3339), if present.
        * ``last_modified`` (str): the metadata last-modified timestamp (RFC-3339).
        * ``failure`` (ImportFailure | None): the failure record when ``status`` is
          INVALID, else None.
        * ``imports`` (list[dict]): child import nodes (empty when none or unacquired).

        The six summary fields (``model``, ``title``, ``oscal_version``, ``version``,
        ``published``, ``last_modified``) are populated only when the object was
        successfully acquired; otherwise each is an empty string ``""``.

        This is the single source of truth for the node/entry field schema. The import
        getters :attr:`failed_imports`, :attr:`duplicate_imports`, and
        :attr:`unresolved_imports` return these same per-entry fields as flat lists
        (without the recursive ``imports`` key). Note that those getters only ever hold
        failed or duplicate entries, which carry no loaded document — so in their results
        ``object_uuid`` is always ``None`` and the six summary fields are always ``""``.

bool: True when all imports resolved (``content_state >= IMPORTS_RESOLVED``).

Perform initial validation of content and advance the content state.

        Detects the format, checks that the content is a recognized, well-formed
        OSCAL format (XML, JSON, or YAML), identifies the model/version and extracts
        summary metadata, then invokes full OSCAL schema validation. Updates
        ``self.content_state`` progressively as each stage passes.

        Args:
            content (str, required): The raw OSCAL content to validate.

        Returns:
            bool: True if initial validation is successful, False otherwise.

bool: True once content has been acquired (``content_state >= ACQUIRED``).

True when remote cached content has exceeded its TTL.

Can this content be modified?

True when content is local or cached and within its TTL.

bool: True when the content may not be mutated (most-restrictive-wins).

        Read-only when any of these hold: the underlying writable flag is set,
        the content is canonical/published (``is_canonical``), or the document is
        write-locked by a *different* actor in its workspace (see
        :meth:`_locked_by_other`). Because every mutation gate checks this property,
        canonical status and workspace locks are enforced uniformly.

bool: True when the content originates from a remote source (not a local file).

True when remote cached content has exceeded its TTL.

bool: True when content passes OSCAL validation (``content_state >= VALID``).

bool: True when content is well-formed (``content_state >= WELL_FORMED``).

Return the content as a JSON string in canonical key order.

Query the JSON content using JSON key name syntax (via :class:`NativePath`).

        Steps use the actual JSON key names (``controls``, ``props``, ``parts``, …)
        with no metaschema translation required.  Arrays are iterated
        transparently, so ``//controls[id='ac-2.2']`` navigates directly into
        any ``controls`` array at any depth.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits.

        Parameters
        ----------
        path : str
            Path expression using JSON key names, e.g.
            ``"//controls[id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`json_query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using JSON key names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Initialize an instance from a local file path or file-like object.

        Aligns with Python's conventional ``load(...)`` behavior (cf. ``json.load`` /
        ``pickle.load``): the source is a **local** path or a file-like object. Use
        ``loads(...)`` for in-memory strings/dicts, and ``acquire(...)`` for URI/reference
        sources (``http``/``https``/``file``/``ftp``/…) — ``load`` does not fetch remotely.

        Args:
            source (str | os.PathLike | file-like, required): A filesystem path or an
                object with a ``read()`` method.
            href (str | None, optional): URI label identifying the source; defaults to
                the path or the object's ``name``. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the loaded content.

        Raises:
            TypeError: If ``source`` is neither path-like nor file-like.

Initialize an instance from in-memory OSCAL content.

        Args:
            content (str | dict, required): OSCAL content already in memory, as a
                serialized string or a dict.
            href (str | None, optional): URI identifying the original content
                source. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance populated from the content.

Create a new OSCAL document from a template.

        Must be called on a specific model class (``Catalog.new()``,
        ``Profile.new()``, etc.), not on ``OSCAL`` directly.

        Args:
            title (str, required): Document title (stored in metadata).
            version (str, optional): Document version (stored in metadata).
                Defaults to "".
            published (str, optional): Publication date (stored in metadata).
                Defaults to "".

        Returns:
            OSCAL: A new editable instance of the model subclass.

        Raises:
            TypeError: If called on the ``OSCAL`` base class instead of a subclass.

Universal constructor — inspects the source type and delegates to
        the appropriate loader.

        Delegates to:
            load()    — file-like objects (anything with .read()), PathLike
                        objects, and bare string paths (no URI scheme)
            acquire() — URI strings (http/https/file/ftp/...), OscalRef,
                        reference dicts, and fallback lists

        Args:
            source (str | os.PathLike | dict | OscalRef | list | file-like, required):
                Any supported OSCAL source. String values with a URI scheme are
                acquired; bare paths and file-like objects are loaded.
            href (str | None, optional): URI label passed through to ``load()`` when
                applicable. Keyword-only. Defaults to None.

        Returns:
            OSCAL: A new instance from the appropriate loader.

Computed from is_local, is_cached, and TTL. Changes over time for cached remote content.

Write a value into the JSON content at a slash-separated path.

        This is the shared, guarded entry point for JSON mutations. It centralizes the
        defensive behavior that would otherwise be repeated at every call site:
        the read-only / content guard (:meth:`_can_mutate`), auto-creation of missing
        intermediate objects and optional OSCAL arrays, and dirty-state bookkeeping
        (``is_unsaved`` / ``last_modified``).

        Path segments are ``'/'`` separated and relative to the model root (e.g.
        ``"metadata/title"`` or ``"metadata/roles/0/title"``). A numeric segment
        indexes a list; any other segment names a dict key. Missing intermediate dict
        keys are created automatically.

        Args:
            path (str, required): Slash-separated path relative to the model root.
            value (Any, required): The JSON-compatible value to write.
            mode (str, optional): ``"replace"`` (default) sets the value at ``path``;
                ``"insert"`` treats the leaf as an optional array — creating it if
                absent — and appends ``value`` to it.
            validate (bool, optional): When True, run metaschema-driven datatype/regex
                and allowed-value checks before writing (see :meth:`_validate_write`).
                Currently a permissive extension point. Defaults to False.
            check_refs (bool, optional): When True, run referential-integrity checks
                before writing (see :meth:`_check_referential_integrity`). Currently a
                permissive extension point. Defaults to False.

        Returns:
            bool: True on success, False on any failure (guard, bad path/index,
                validation, or type mismatch). No mutation occurs on failure.

Query the JSON content using XML element name syntax (via :class:`OSCALPath`).

        Steps use OSCAL XML element names (``control``, ``prop``, ``part``, …)
        and the metaschema index translates them to the correct JSON keys
        (``controls``, ``props``, ``parts``, …) including array/BY_KEY grouping.

        The returned list contains SAFE COPIES — mutating a result does not change the
        document; use the model's mutation methods for persistent edits. A single deep
        copy of the whole result set preserves internal identity between overlapping
        matches.

        Parameters
        ----------
        path : str
            Path expression using XML element names, e.g.
            ``"//control[@id='ac-2.2']"`` or ``"/*/metadata/title"``.
        context : dict, optional
            Sub-dict to query within.  Defaults to the full document dict
            (``self._dict``).

        Returns a list of matching JSON values (as copies), or ``[]`` on error / no match.

Return the first result of :meth:`query` as a safe copy, or ``default``.

        Args:
            path (str, required): Path expression using OSCAL XML element names.
            context (dict | None, optional): Sub-dict to query within. Defaults to the
                full document dict.
            default (Any, optional): Value to return when there is no match. Returned
                as-is (not copied). Defaults to None.

        Returns:
            Any: A safe copy of the first matching JSON value, or ``default``.

Return every ``id``/``uuid`` value in this document and its import tree.

        Used to decide whether a cross-reference resolves somewhere in scope. The walk
        is de-duplicated and cycle-safe across the import graph.

Discard the cached import tree and rebuild it from the current import_list.

        Returns:
            dict: The freshly built root node of the recursive import tree.

Remove a first-level import statement from this document.

        Operates only on this document's own imports, never on descendants. The
        import *statement* is deleted from ``self._dict``; any back-matter resource
        it referenced via a URI fragment (``href="#uuid"``) is intentionally
        preserved. The affected part of the import tree is refreshed and any
        model-specific derived state (e.g. a Profile's resolved catalog) is reset
        via :meth:`_after_imports_changed`.

        Cardinality is enforced from :data:`_IMPORT_SPEC`:

        * Models with no top-level import (catalog, mapping-collection) — invalid.
        * Fixed-cardinality models where ``min == max`` (SSP/AP/AR require exactly
          one) — invalid; change that import with :meth:`retry_import` instead.
        * Otherwise the removal is rejected when it would drop the count of *real*
          imports (non-empty, non-``"#"`` href) below the model's minimum. Removing
          an empty placeholder is always allowed for variable-cardinality models.

        Args:
            href: Any href that identifies the import — its literal href (including
                a ``"#uuid"`` fragment or an empty ``""``/``"#"`` placeholder), or
                the resolved target href of the back-matter resource it references.

        Returns:
            True if an import was found and removed; False if not found, the
            cardinality forbids removal, or the content is read-only.

Discover and load every OSCAL document referenced by this document's
        import declarations.  Populates (and returns) self.import_list.

        Because ``validate()`` resolves imports, loading a document cascades this
        depth-first down the whole import tree. Two guards prevent runaway on shared
        or circular graphs: the object registry ensures a file loaded via multiple
        branches (a diamond) is held once, and an import that resolves back to an
        ancestor still being resolved (a cycle) is marked ``ImportState.CYCLIC`` and
        not loaded — the ancestor stays valid and recursion stops there.

        A ``cache_directive`` is applied to this document's direct imports; a
        ``refresh`` or ``CACHE_NEVER`` directive bypasses the in-memory registry so
        the imported content is genuinely reloaded rather than reused.

        Recognised import locations by model:
            profile                    → import/@href
            component-definition       → import-component-definition/@href,
                                         component/control-implementation/@source,
                                         capability/control-implementation/@source
            system-security-plan       → import-profile/@href
            assessment-plan            → import-ssp/@href
            plan-of-action-and-milestones → import-ssp/@href
            assessment-results         → import-ap/@href
            mapping-collection         → mapping/source/@href,
                                         mapping/target/@href

        Args:
            base_path (str, optional): Directory used to resolve relative hrefs.
                Defaults to the directory of this document's own href.
            cache_directive (CacheDirective | None, optional): Caching directive
                applied to this document's direct import fetches. Keyword-only.
                Defaults to the standard 24h behavior.

        Returns:
            list[dict]: self.import_list, one entry per discovered reference.

Retry a failed import identified by href, using a replacement source.

        The failed import is matched by href (original or previously resolved),
        then re-attempted using ``replacement_href`` (resolved relative to this
        document's location).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Compatibility alias for :meth:`retry_import` (plural method name).

        Args:
            failed_href (str, required): The href of the failed import to retry.
            replacement_href (str, required): The replacement href to attempt.

        Returns:
            bool: True if the import was successfully resolved on retry, False otherwise.

Set simple metadata fields on the OSCAL content's ``metadata`` section.

        Complex metadata collections (revisions, roles, parties, links, props, etc.)
        are not yet supported and are skipped with a warning.

        Args:
            content (dict, optional): Mapping of metadata field name to value to set.
                Defaults to an empty dict.

        Returns:
            bool: True on success, or None when the content cannot be mutated.

Return True if this model exposes ``name`` as a method or attribute.

        Lets callers look before they leap when an operation is only valid for
        some OSCAL models::

            if doc.supports("add_control"):
                doc.add_control(...)

        Only class-level (shared, model-defined) members count; per-instance
        attributes set at runtime are ignored, so the check reflects the model's
        capabilities rather than incidental state.

        Args:
            name (str, required): The method/attribute name to test.

        Returns:
            bool: True if the model defines ``name``.

Return import_list entries that still warrant user attention.

        Includes failed imports (INVALID) and duplicates (DUPLICATE).  Excludes
        READY (resolved) and IGNORED (explicitly dismissed by the caller).

        This is the signal a UI should use to decide whether to keep showing
        import-resolution affordances.  It stays non-empty while there is still
        something the user can act on — even when ``imports_resolved`` is already
        True because the only remaining items are non-blocking duplicates.
        Once every entry is READY or IGNORED, this list is empty and the
        resolution UI can close.

        Each entry is a safe copy shaped like an :attr:`import_tree` node (same field
        schema, but a flat list without the recursive ``imports`` key). Exception:
        unresolved entries (failed or duplicate) never carry a loaded document, so for
        every entry here ``object_uuid`` is always ``None`` and the six summary fields
        (``model``, ``title``, ``oscal_version``, ``version``, ``published``,
        ``last_modified``) are always ``""``.

Modify the single import of a one-import model (SSP, AP, AR, or POA&M).

        These models carry exactly one import (POA&M: at most one), so :meth:`add_import`
        and :meth:`remove_import` do not apply — this is how their import is changed. It
        takes the same resource fields as :meth:`update_resource` (``title``,
        ``description``, ``props``, ``rlinks``, ``remarks`` — ``None`` leaves a field
        unchanged; arrays replace wholesale) plus ``new_resource``. The behavior depends
        on what the existing import points at:

        * **No import yet** (only possible for POA&M): the call is forwarded to
          :meth:`add_import` (``new_resource`` does not apply and is omitted); the import
          target's href is taken from the first supplied ``rlink``.
        * **Import is a direct URI** (or an empty ``""``/``"#"`` placeholder): a new
          back-matter resource is created (via :meth:`append_resource`) — its ``rlink`` is
          the supplied ``rlinks`` when given, otherwise the existing URI — and the import's
          href is repointed to that resource's ``#uuid``. (``new_resource`` does not apply:
          there is no backing resource to update.) Status: "replaced".
        * **Import is a ``#uuid`` fragment**:

          - ``new_resource=True`` (default): a brand-new resource with a new UUID is
            created via :meth:`append_resource` from the supplied fields, and the import's
            href is repointed to it. The prior resource is **left in place** — it is not
            deleted, because other content may reference it (including OSCAL documents not
            currently loaded that import this one and cite that resource by UUID). Because
            the new resource is built only from the fields you pass, supply ``rlinks`` (and
            any props) for the new target; read the old resource first with
            :meth:`get_resource_by_uuid` if you want to carry values forward. Status:
            "replaced".
          - ``new_resource=False``: the existing resource is edited in place via
            :meth:`update_resource` (same wholesale array-replacement semantics and
            data-loss caveats — see that method). The import's href is unchanged. Status:
            "updated".

        Args:
            title (str | None, optional): Resource title; ``""`` removes it.
            description (str | None, optional): Resource description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). Also the source of the import target's
                href when creating a resource or bootstrapping a POA&M import.
            remarks (str | None, optional): Resource remarks (markdown); ``""`` removes it.
            new_resource (bool, optional): When the import already references a ``#uuid``
                resource, True (default) creates a new resource and repoints; False edits
                the existing resource in place. Ignored for the direct-URI/placeholder and
                no-import cases. Defaults to True.

        Returns:
            ImportResult: ``status`` "added"/"replaced"/"updated" on success (``ok`` True),
                or "invalid"/"error" otherwise, carrying the import ``entry`` and the
                created/updated ``resource``.

Update fields of an existing ``back-matter`` resource, selected by ``uuid``.

        Only a resource defined in THIS document's own ``back-matter`` is editable
        (imported resources are not). Each field is optional and independent:

        * ``None`` (the default) leaves that field untouched.
        * A scalar (``title``/``description``/``remarks``) replaces the current value;
          an empty string removes the field entirely.
        * An array (``props``/``rlinks``) **replaces the existing array wholesale** — the
          old list is discarded and the supplied list becomes the new one. Passing an
          empty list removes the field.

        .. warning::
            Array replacement is destructive and total, not a merge. Whatever you pass
            for ``props`` or ``rlinks`` becomes the *complete* new list; every entry not
            present in your list is permanently dropped. A resource frequently carries
            entries you did not author and may not be aware of — for example multiple
            ``rlinks`` pointing at format variants (``.xml``/``.json``) of the same file,
            ``rlinks`` bearing ``hashes`` for integrity, a ``base64`` payload, or ``props``
            added by other tools or pipelines. Supplying a partial list here silently
            deletes all of those. There is no undo.

            **Recommended pattern:** read the current resource first with
            :meth:`get_resource_by_uuid`, mutate the copy it returns (append to / edit the
            existing ``props``/``rlinks`` rather than rebuilding them from scratch), then
            pass those full arrays back to this method. That way you extend the resource
            instead of overwriting it, and nothing you did not intend to touch is lost::

                res = doc.get_resource_by_uuid(uuid)          # safe copy of the whole resource
                res["rlinks"].append({"href": "catalog.json",
                                      "media-type": "application/json"})
                doc.update_resource(uuid, rlinks=res["rlinks"])   # full list, nothing dropped

        Args:
            uuid (str, required): UUID of the local back-matter resource to update.
            title (str | None, optional): New title; ``""`` removes it. ``None`` = unchanged.
            description (str | None, optional): New description; ``""`` removes it.
            props (list | None, optional): Replacement property dicts (see
                :func:`append_props`). ``[]`` removes all props. ``None`` = unchanged.
            rlinks (list | None, optional): Replacement ``rlink`` dicts (``href`` plus
                optional ``media-type``/``hashes``). ``[]`` removes all rlinks.
            remarks (str | None, optional): New remarks (markdown); ``""`` removes them.

        Returns:
            dict | None: A safe copy of the updated resource, or None when the content is
                read-only, ``uuid`` is empty, or no local resource with that UUID exists.

Validate OSCAL content against the metaschema index in sequenced phases.

        Phases (each recorded in ``validation_status``):
          structure      – all required fields and hierarchy are present
          data-types     – every leaf value matches its declared OSCAL datatype
          allowed-values – every constrained value is within its enumerated set
          cardinality    – every array satisfies its min-occurs/max-occurs bounds
          choice         – every choice is mutually exclusive (at most one member present) and has a member when one is required

        ``validation_status["well-formed"]`` is set by ``initial_validation()``, not here.
        All phases always run regardless of earlier failures, giving a complete picture
        of issues in a single call.  The format argument is accepted for API
        compatibility but does not alter the validation path — ``_dict`` is always the
        authoritative representation.

        Returns True only when every phase passes (content_state reaches VALID).

Walk the import tree depth-first, calling ``visitor_fn(entry, depth)`` for each entry.

        Args:
            visitor_fn (Callable, required): Callable receiving ``(entry_dict, depth_int)``.
            depth (int, optional): Current recursion depth; used internally. Defaults to 0.
            _seen (set | None, optional): Object ids already visited; used internally to
                prevent cycles. Defaults to None.
            scope (str, optional): Keyword-only. Which entries to visit — "successful"
                (default) visits only READY imports and recurses into them; "failed" visits
                only INVALID/NOT_LOADED imports without recursion; "all" visits every entry,
                recursing only into READY imports.

        Returns:
            None

Return the content as an XML string in canonical element order.

        Rebuilds from the current dict via the metaschema converter (reflecting
        the latest edits, in schema-required element order) and retains no tree.

Return the content as a YAML string in canonical key order.

Initialize an empty registry (weak identity/href maps and a resolution stack).

Point an additional canonical href at an already-registered object.

        Args:
            href (str, required): The canonical href to alias.
            obj (Any, required): The object the href should resolve to.

Drop all entries (primarily for test isolation).

Mark a canonical href as currently being resolved (push onto the DFS stack).

Unmark a canonical href once its resolution completes (pop from the stack).

Remove every reference to ``obj`` from the registry (thread-safe).

        Used to drop a document that was only transiently registered (e.g. a root
        registered by identity key for the duration of its import resolution).

Return a live, fresh object matching ``href`` (checked first) or ``key``.

        Args:
            key (tuple | None, optional): Composite content-identity key.
            href (str, optional): Canonicalized href.

        Returns:
            Any | None: The registered object, or None on miss or when the match is
                stale (its ``is_cache_expired`` is True), in which case it is dropped.

Return True when ``href`` is an ancestor currently being resolved (a cycle).

Register ``obj`` under its content-identity key and/or canonical href.

        Args:
            obj (Any, required): The object to register.
            key (tuple | None, optional): Composite content-identity key.
            href (str, optional): Canonicalized href.

        Returns:
            Any: The registered object (``obj``).

Return the currently active object registry.

    Returns the registry activated by :func:`use_registry` (e.g. a Workspace's own
    registry) when one is in effect on the current context, otherwise the
    process-global default. Because a document load cascades synchronously, every
    object created during the load picks up whichever registry is active.

    Returns:
        ObjectRegistry: The active registry, or the process-global default.

Activate ``registry`` for the duration of the ``with`` block.

    Objects created while this context is active (including transitively-loaded
    imports) use ``registry`` instead of the process-global default.

    Args:
        registry (ObjectRegistry, required): The registry to activate.

    Yields:
        ObjectRegistry: The activated registry.

Default behavior: 24h TTL, no forced refresh.

        Returns:
            CacheDirective: A directive with the default TTL and no refresh.

Keep the cached copy until manually purged or refreshed.

        Returns:
            CacheDirective: A directive with ``ttl=CACHE_FOREVER``.

Never cache: purge any existing copy and always fetch remotely.

        Returns:
            CacheDirective: A directive with ``ttl=CACHE_NEVER``.

Cache with a specific TTL.

        Args:
            seconds (int, required): Freshness window in seconds.

        Returns:
            CacheDirective: A directive with ``ttl=seconds``.

Force a refetch now, then cache the result.

        Args:
            ttl (int, optional): TTL to apply to the refreshed copy. Defaults to
                ``LOCAL_CACHE_TTL`` (24h).

        Returns:
            CacheDirective: A directive with ``refresh=True`` and the given ``ttl``.

Initialize the cache.

        Args:
            db_path (str, optional): Explicit path to the cache database. When empty,
                the path is resolved lazily to ``local_cache.db`` beside the support
                database.

Remove all cached entries (primarily for maintenance/tests).

Apply ``directive``, then return cached content for ``url`` if reusable.

        The directive is applied first: ``CACHE_NEVER`` purges any copy; ``refresh``
        forces a miss. Freshness is then evaluated by comparing the directive's TTL
        against the entry's last-fetch time (``CACHE_FOREVER`` reuses any age).

        Args:
            url (str, required): The (canonicalized) remote URL key.
            directive (CacheDirective | None, optional): Caching directive; defaults
                to :meth:`CacheDirective.default` (24h, no refresh).

        Returns:
            Optional[str]: The cached content to reuse, or None to fetch remotely.

Remove the cached entry for a single ``url`` (manual deletion).

        Args:
            url (str, required): The (canonicalized) remote URL key.

Store or refresh cached content for ``url``, resetting its last-fetch time.

        A ``CACHE_NEVER`` directive stores nothing (the content is used but not cached).

        Args:
            url (str, required): The (canonicalized) remote URL key.
            content (str | bytes, required): The fetched content to cache.
            directive (CacheDirective | None, optional): Caching directive; defaults
                to :meth:`CacheDirective.default`.

        Returns:
            bool: True when stored, False when skipped or on error.

Return the process-global default remote-content cache.

    Returns:
        LocalCache: The shared cache instance (its database is created on first use).

Create a workspace.

        Args:
            title (str, optional): Project title.
            path (str, optional): Default path for the workspace's project file.
            registry (ObjectRegistry | None, optional): Registry to use; a fresh
                isolated one is created when omitted.

Context manager that attributes mutations in the block to ``actor``.

        Args:
            actor (str, required): The actor (view/session) id.

        Returns:
            A context manager activating ``actor`` as the current actor.

Stop tracking a document (releasing the workspace's strong reference and lock).

Release all tracked documents and their locks.

list: The workspace's open root documents.

Return True when ``doc`` is write-locked by any actor.

Load a workspace from its SQLite project file (self-contained; no refetch).

        Args:
            path (str, required): The workspace project file.

        Returns:
            Workspace: The reconstructed workspace, with documents rehydrated and
                their import trees rewired from the persisted content and state.

Open in-memory content into the workspace.

        Args:
            content (str, required): Serialized OSCAL content.
            href (str | None, optional): Source URI to key/track the document by.

        Returns:
            OSCAL: The opened document.

Acquire the write lock on ``doc`` for ``actor`` (exclusive editing).

        While held, the document is read-only to every other actor. Re-locking by
        the same actor succeeds (idempotent).

        Args:
            doc (OSCAL, required): The document to lock.
            actor (str | None, optional): The actor; defaults to the current actor.

        Returns:
            bool: True if the lock is held by ``actor`` afterward, False if another
                actor already holds it.

        Raises:
            ValueError: When no actor is given and none is active.

Return the actor holding the write lock on ``doc``, or None.

        Args:
            doc (OSCAL, required): The document.

        Returns:
            Optional[str]: The lock-holding actor, or None when unlocked.

Create a new document in the workspace.

        Args:
            model_cls (type, required): A model class (e.g. ``Catalog``).
            title (str, required): Document title.
            **kwargs: Passed through to ``model_cls.new``.

        Returns:
            OSCAL: The new document, tracked by the workspace.

Open a document into the workspace (loading it under the workspace registry).

        Re-opening the same source returns the already-open document (shared root).

        Args:
            source (str, required): A path or URI to load.

        Returns:
            OSCAL: The (possibly already-open) document.

ObjectRegistry: This workspace's isolated object registry.

Save the workspace (content + state + project metadata) to a SQLite file.

        Every reachable document (roots and their resolved imports) is serialized as
        JSON into the shared ``filecache`` table, with its state and import edges
        recorded in ``workspace_documents``; project metadata goes in
        ``workspace_meta``. Reusing ``filecache`` means no schema change to the
        support database.

        Args:
            path (str, optional): Destination path. Defaults to ``self.path``.

        Returns:
            bool: True on success.

Release the write lock on ``doc``.

        Args:
            doc (OSCAL, required): The document to unlock.
            actor (str | None, optional): The actor; defaults to the current actor.
                A caller may only release its own lock (unless ``actor`` is None-held).

        Returns:
            bool: True when the document is unlocked afterward; False when the lock
                is held by a different actor and cannot be released.

Initialize a parser for one metaschema document.

        Args:
            metaschema (str, required): The resolved-metaschema XML content to parse.
            support (OSCALSupport, required): The OSCAL support object used to fetch
                imported metaschemas and store results.
            oscal_version (str, optional): The OSCAL version this metaschema belongs
                to. Defaults to "".
            import_registry (dict, optional): Shared registry of already-parsed imports
                (``href -> MetaschemaParser``), so a metaschema imported by more than one
                model is parsed once and reused. Endures across all models of one OSCAL
                version and is cleared when that version finishes. Defaults to ``None``
                (a fresh, isolated registry) — never a mutable default.

Build the full structural index for this metaschema's model.

        Recursively walks the root assembly to produce the node tree, applies
        constraints against a synthesized XML skeleton, prunes empty values, and
        annotates namespace conditions and JSON paths.

        Returns:
            dict: The metaschema index — model metadata plus a ``nodes`` tree — or an
                empty dict on error or when the root assembly cannot be found.

Construct a ``MetaschemaParser`` (preferred factory over direct instantiation).

        Args:
            metaschema (str, required): The resolved-metaschema XML content to parse.
            support (OSCALSupport, required): The OSCAL support object.
            oscal_version (str, optional): The OSCAL version. Defaults to "".
            import_registry (dict, optional): Shared per-version import registry (see
                :meth:`__init__`). Defaults to ``None`` — a fresh registry per top-level
                parse. Recursive import parsing threads the parent's registry down.

        Returns:
            MetaschemaParser: A new parser instance.

Run an XPath query and return its markup content as a string.

        Handles results that are either plain strings or nodes containing HTML
        (markup) formatting, returning a string in either case.

        Args:
            xExpr (str, required): An XPath expression.
            context (Element, optional): Node to evaluate the expression against.
                Defaults to None (whole document).

        Returns:
            str: The matched content as a string (markup preserved as HTML).

Prepend a resolved markup value onto an accumulating list of values.

        Used where a field/assembly reference's values must be added to (rather than
        replace) any values already defined on the referenced define-field/assembly.

        Args:
            current_value (list, required): The existing accumulated values; wrapped in
                a list if not already one.
            xExpr (str, required): XPath expression yielding the markup value to add.
            context (Element, optional): Node to evaluate against. Defaults to None.

        Returns:
            list: ``current_value`` with the resolved value inserted at the front (when
                non-empty).

Return an overriding value when present, otherwise keep the current value.

        Used where a field/assembly reference's value must replace any value already
        defined on the referenced define-field/assembly.

        Args:
            current_value (Any, required): The existing value to keep if no override
                is found.
            xExpr (str, required): XPath expression yielding the overriding value.
            context (Element, optional): Node to evaluate against. Defaults to None.

        Returns:
            Any: The resolved override value if non-empty, otherwise ``current_value``.

Map an XML definition's attributes onto a metaschema node.

        Translates attributes such as ``as-type`` (datatype), ``required``,
        ``min-occurs``/``max-occurs`` (cardinality), ``collapsible``, ``deprecated``,
        ``default``, and ``in-xml`` (XML wrapping) into node fields. Unhandled
        attributes are logged as warnings.

        Args:
            metaschema_node (dict, required): The node being built; updated in place.
            definition_obj (ET.Element, required): The XML definition element.
            structure_type (str, required): The definition's structure type.
            name (str, required): The definition name.
            parent (str, required): The parent path.

        Returns:
            dict: The updated ``metaschema_node``.

Resolve the child model of an assembly (fields, assemblies, choices, any).

        Walks the assembly's ``model`` (or a specific ``choice`` group), recursing to
        build each child node and constructing synthetic nodes for ``choice``/``any``.

        Args:
            name (str, required): The definition name being processed.
            structure_type (str, required): "define-assembly" or "choice".
            metaschema_node (dict, required): The parent node (provides path/source).
            context (Element, required): The XML context to search within.
            handle_choice (int, optional): 1-based index of the choice group to process
                when ``structure_type`` is "choice". Defaults to 0.

        Returns:
            list: The resolved child node dicts.

Process ``<constraint><allowed-values>`` elements from a definition object.

        Targets are handled as follows: ``.`` or absent applies to the current node;
        ``@flag-name`` applies to the named flag child; complex Metapath targets are
        resolved against the XML skeleton (or stored with the unresolved target
        preserved). Multiple allowed-values sets for the same target are cumulative;
        ``allow-other`` conflicts resolve with 'yes' winning and emit a warning.

        Args:
            metaschema_node (dict, required): The node being built; updated in place.
            definition_obj (ET.Element, required): The XML definition element.
            structure_type (str, required): The definition's structure type.
            name (str, required): The definition name.
            parent (str, required): The parent path.

        Returns:
            dict: The updated ``metaschema_node``.

Resolve the flags defined or referenced by a field or assembly.

        Finds each ``define-flag``/``flag`` child, recurses to build its node, and
        collects the results.

        Args:
            metaschema_node (dict, required): The parent node being built (used for
                path context).
            definition_obj (ET.Element, required): The field/assembly XML definition.
            structure_type (str, required): The parent's structure type.
            name (str, required): The parent definition name.
            parent (str, required): The parent path.

        Returns:
            list: The resolved flag node dicts (empty when none are present).

Apply a definition's ``group-as`` element to a metaschema node.

        Reads the ``group-as`` name and its ``in-xml``/``in-json`` grouping
        attributes and records them (and XML wrapping) on the node.

        Args:
            metaschema_node (dict, required): The node being built; updated in place.
            definition_obj (ET.Element, required): The XML definition element.
            structure_type (str, required): The definition's structure type.
            name (str, required): The definition name (for logging).
            parent (str, required): The parent path (used to build wrapped paths).

        Returns:
            dict: The updated ``metaschema_node``.

Map a definition's ``prop`` elements onto a metaschema node.

        Recognized props (``METASCHEMA_PROPS_HANDLED`` in the OSCAL namespace) are
        promoted to dedicated node keys; any other prop is appended to the node's
        ``props`` list as ``{"name", "value", "namespace"}``.

        Args:
            metaschema_node (dict, required): The node being built; updated in place.
            definition_obj (ET.Element, required): The XML definition element.
            structure_type (str, required): The definition's structure type.
            name (str, required): The definition name.
            parent (str, required): The parent path.

        Returns:
            dict: The updated ``metaschema_node``.

Create a new, fully-keyed metaschema index-constraint dict with default values.

        Called before each index constraint is populated, to guarantee a consistent
        key set (id, level, name, target, handled props, etc.).

        Returns:
            dict: A new index dict with all expected keys initialized.

Create a new, fully-keyed metaschema index node with default (empty) values.

        Called as each node is created, including the top-level node, to guarantee a
        consistent key set (path, name, datatype, cardinality, children, constraints,
        handled props, etc.).

        Returns:
            dict: A new node dict with all expected keys initialized.

Create a new, fully-keyed metaschema rule with default (empty) values.

        Called before each rule (e.g. an allowed-values constraint) is populated, to
        guarantee a consistent key set (id, level, datatype, allowed-values,
        allow-other, test, message, cardinality, etc.).

        Returns:
            dict: A new rule dict with all expected keys initialized.

Search imported metaschemas for a definition by name and structure type.

        Args:
            name (str, required): The definition name to find.
            structure_type (str, required): The structure type to match
                (e.g. "define-assembly", "define-field", "define-flag").
            parent (str, optional): Parent path for the resolved node. Defaults to "".
            ignore_local (bool, optional): Passed through to recursion; ignore local
                definitions in the imported metaschema. Defaults to False.
            already_searched (list | None, optional): Definition names already visited,
                to prevent cycles. Defaults to None.

        Returns:
            dict | None: The resolved node from the imported metaschema, or None if not
                found.

Recursively build a metaschema index node and its descendants.

        Processes the XML definition for ``name`` and extracts a node dict describing
        its attributes, flags, and child elements, recursing into referenced
        definitions.

        Args:
            name (str, required): The definition/element name to process (e.g. a model
                or field name).
            structure_type (str, optional): The kind of definition — "define-assembly",
                "define-field", "define-flag", or an inline assembly/field/flag.
                Defaults to "define-assembly".
            parent (str, optional): Name of the parent definition, for logging/paths.
                Defaults to "".
            ignore_local (bool, optional): When True, ignore local (non-exported)
                definitions; set True when recursing into an imported metaschema so its
                private locals are not exposed. Defaults to False.
            already_searched (list | None, optional): Definition names already visited,
                to prevent infinite recursion. Defaults to None.
            context (Element, optional): XML context node to search within.
                Defaults to None.
            skip_children (bool, optional): When True, do not recurse into child
                elements. Defaults to False.
            use_name (str | None, optional): Override for the node's effective
                (use-)name. Defaults to None.

        Returns:
            dict: The metaschema index node for ``name`` (with nested children).

Fill in default node values required by the metaschema specification.

        Applies spec defaults for any unset attributes — datatype ("string"),
        cardinality (0..1, or 1..1 for the root), ``json-collapsible``,
        ``deprecated``, ``default``, and XML wrapping for fields/assemblies.

        Args:
            metaschema_node (dict, required): The node being built; updated in place.
            definition_obj (ET.Element, required): The XML definition element.
            structure_type (str, required): The definition's structure type.
            name (str, required): The definition name.
            parent (str, required): The parent path; an empty value marks the root node.

        Returns:
            dict: The updated ``metaschema_node``.

Identify ``import`` elements and load each as a nested ``MetaschemaParser``.

        Imported metaschemas are fetched from the support database and stored in
        ``self.imports`` keyed by model name for later cross-metaschema lookups. Each
        import is also recorded as a child of this parser's ``import_inventory`` tree
        node, so the full import-relationship graph is captured.

        Duplicate imports (the same metaschema reached from more than one model, or via
        more than one path) are parsed only once: an :attr:`import_registry`, shared for
        the whole OSCAL version, is consulted first and its parsed object reused.

        Returns:
            None

Build a human-readable summary of a parsed metaschema index node.

        Args:
            node (dict, required): An index node produced by the parser, carrying
                keys such as ``formal-name``, ``use-name``, ``min-occurs``,
                ``max-occurs``, ``datatype``, ``children``, and ``constraints``.

        Returns:
            str: A multi-line, human-readable description of the node.

Perform the first parsing pass: deserialize XML and read top-level metadata.

        Parses the metaschema content, then extracts the model name, schema name,
        OSCAL version, namespace, and JSON base URI, and sets up imports.

        Returns:
            bool: True if the XML was well-formed and parsed, False otherwise.

Run an XPath query and return the matching element(s).

        Args:
            xExpr (str, required): An XPath expression.
            context (Element, optional): Node to evaluate the expression against.
                When None, the expression runs against the whole document.
                Defaults to None.

        Returns:
            ET.Element | list[ET.Element] | None: A single element, a list of
                elements, or None on error / no match.

Run an XPath query and return the first result as a string.

        Args:
            xExpr (str, required): An XPath expression.
            context (Element, optional): Node to evaluate the expression against.
                When None, the expression runs against the whole document.
                Defaults to None.

        Returns:
            str: The first matching result as a string, or "" on error / no match.

Recursively drop None values and empty containers from a dict.

    Removes key/value pairs whose value is None, and prunes empty nested dicts and
    lists (including dicts nested inside lists), returning a new cleaned dict.

    Args:
        dictionary (dict, required): The dictionary to clean.

    Returns:
        dict: A new dictionary with None values and empty containers removed.

Parse and store the OSCAL metaschema index for one or all supported versions.

    Args:
        support (OSCALSupport, optional): The OSCAL support object. Currently the
            shared instance is fetched internally via ``get_support()`` regardless
            of this argument. Defaults to None.
        oscal_version (str, optional): The OSCAL version to parse. When None, all
            supported versions are processed. Defaults to None.
        save_to_fs (bool, optional): When True, also write each model index (and the
            parse report) to the local file system. Defaults to False (database only).

    Returns:
        int: 0 on success, 1 on error (process-style exit code).

Parse and store every model index for a specific OSCAL version.

    Each model index is stored in the support database as
    ``(version, model, "processed")``. When ``save_to_fs`` is True it is also written
    to ``support/<version>/<model>.json`` alongside the support database.

    Args:
        support (OSCALSupport, required): The OSCAL support object providing
            metaschema assets and asset storage.
        oscal_version (str, required): The OSCAL version to parse.
        save_to_fs (bool, optional): When True, also write each model index (and the
            parse report) to the local file system. Defaults to False (database only).

    Returns:
        bool: True if all models parsed and stored successfully, False otherwise.