Expand identifierIssuer support to other API methods

Author: mielvds

CHANGELOG.md

@@ -6,9 +6,10 @@
 - `pyld.FileDocumentLoader`: a document loader for local `file:` URLs with optional root confinement.
 - `pyld.SchemeDirectedDocumentLoader`: a document loader that dispatches URL
   strings to per-scheme loaders.
-- `jsonld.to_rdf()` now accepts an `identifierIssuer` option with an
-  `IdentifierIssuer` instance for blank node identifiers. Defaults to `IdentifierIssuer('_:b')`, 
-  which preserves the previous behaviour.
+- `jsonld.flatten()`, `jsonld.frame()`, and `jsonld.to_rdf()` now accept an
+  `identifierIssuer` option with an `IdentifierIssuer` instance for blank node
+  identifiers. Defaults to `IdentifierIssuer('_:b')`, which preserves the
+  previous behaviour.
 
 ## 3.2.0 - 2026-08-17
 

README.md

@@ -133,6 +133,7 @@ issuer = IdentifierIssuer('_:doc')
 rdf = jsonld.to_rdf(
     doc,
     {'identifierIssuer': issuer, 'format': 'application/n-quads'})
+# flatten() and frame() accept the same identifierIssuer option
 ```
 
 ## Features & conformance

docs/reference/flatten.md

@@ -12,6 +12,9 @@
       show_bases: false
       heading_level: 3
 
+Pass an `IdentifierIssuer` instance as the `identifierIssuer` option to control
+blank node identifiers generated during flattening.
+
 ## Example
 
 {{ example('flatten.py', 'json') }}

docs/reference/frame.md

@@ -12,6 +12,9 @@
       show_bases: false
       heading_level: 3
 
+Pass an `IdentifierIssuer` instance as the `identifierIssuer` option to control
+blank node identifiers generated during framing.
+
 ## Example
 
 {{ example('frame.py', 'json') }}

lib/pyld/jsonld.py

@@ -250,6 +250,8 @@ def link(input_, ctx, options=None):
         defaults to 'json-ld-1.1'.
       [documentLoader(url, options)] the document loader
         (default: _default_document_loader).
+      [identifierIssuer] an IdentifierIssuer instance to use for blank node
+        identifiers (default: IdentifierIssuer('_:b')).
 
     :return: the linked JSON-LD output.
     """
@@ -685,6 +687,8 @@ def flatten(self, input_, ctx, options):
             defaults to 'json-ld-1.1'.
           [documentLoader(url, options)] the document loader
             (default: _default_document_loader).
+          [identifierIssuer] an IdentifierIssuer instance to use for blank node
+            identifiers (default: IdentifierIssuer('_:b')).
 
         :return: the flattened JSON-LD output.
         """
@@ -697,6 +701,7 @@ def flatten(self, input_, ctx, options):
         )
         options.setdefault('extractAllScripts', True)
         options.setdefault('processingMode', 'json-ld-1.1')
+        options.setdefault('identifierIssuer', IdentifierIssuer('_:b'))
 
         try:
             # expand input
@@ -707,7 +712,7 @@ def flatten(self, input_, ctx, options):
             ) from cause
 
         # do flattening
-        flattened = self._flatten(expanded)
+        flattened = self._flatten(expanded, options)
 
         if ctx is None:
             return flattened
@@ -750,6 +755,8 @@ def frame(self, input_, frame, options):
           [requireAll] default @requireAll flag (default: False).
           [documentLoader(url, options)] the document loader
             (default: _default_document_loader).
+          [identifierIssuer] an IdentifierIssuer instance to use for blank node
+            identifiers (default: IdentifierIssuer('_:b')).
 
         :return: the framed JSON-LD output.
         """
@@ -769,6 +776,7 @@ def frame(self, input_, frame, options):
         )
         options.setdefault('extractAllScripts', False)
         options.setdefault('processingMode', 'json-ld-1.1')
+        options.setdefault('identifierIssuer', IdentifierIssuer('_:b'))
 
         # if frame is a string, attempt to dereference remote document
         if _is_string(frame):
@@ -901,6 +909,8 @@ def normalize(self, input_, options):
         )
         options.setdefault('extractAllScripts', True)
         options.setdefault('processingMode', 'json-ld-1.1')
+        # Prevent a custom identifier issuer accidentally messing up normalization.
+        options.pop('identifierIssuer', None)
 
         if options['algorithm'] not in ['URDNA2015', 'URGNA2012']:
             raise JsonLdError(
@@ -2845,7 +2855,7 @@ def _prepare_nested_context(self, active_ctx, element, options):
 
         return active_ctx, type_key, type_scoped_ctx
 
-    def _flatten(self, input):
+    def _flatten(self, input, options):
         """
         Performs JSON-LD flattening.
 
@@ -2854,7 +2864,7 @@ def _flatten(self, input):
         :return: the flattened JSON-LD output.
         """
         # produce a map of all subjects and label each bnode
-        issuer = IdentifierIssuer('_:b')
+        issuer = options['identifierIssuer'] or IdentifierIssuer('_:b')
         graphs = {'@default': {}}
         self._create_node_map(input, graphs, '@default', issuer)
 
@@ -2900,7 +2910,7 @@ def _frame(self, input_, frame, options):
         }
 
         # produce a map of all graphs and name each bnode
-        issuer = IdentifierIssuer('_:b')
+        issuer = options['identifierIssuer'] or IdentifierIssuer('_:b')
         self._create_node_map(input_, state['graphMap'], '@default', issuer)
         if options['merged']:
             state['graphMap']['@merged'] = self._merge_node_map_graphs(

lib/pyld/options.py

@@ -101,6 +101,9 @@ class FlattenOptions(ExpandContextOptions, total=False):
     expandContext: Context
     """A context to expand with."""
 
+    identifierIssuer: IdentifierIssuer
+    """An identifier issuer to use for blank node identifiers (default: `IdentifierIssuer('_:b')`)."""
+
 
 class FrameOptions(ExpandContextOptions, total=False):
     documentLoader: DocumentLoader | DocumentLoaderCallable
@@ -133,6 +136,9 @@ class FrameOptions(ExpandContextOptions, total=False):
     requireAll: bool
     """Default `@requireAll` flag (default: `False`)."""
 
+    identifierIssuer: IdentifierIssuer
+    """An identifier issuer to use for blank node identifiers (default: `IdentifierIssuer('_:b')`)."""
+
 
 class NormalizeOptions(ProcessingOptions, total=False):
     documentLoader: DocumentLoader | DocumentLoaderCallable

tests/test_jsonld.py

@@ -630,6 +630,22 @@ def test_processing_id_in_inner_context(self):
         assert "namespace" in output_json["system"][0]
         assert "uri" in output_json["system"][0]["contents"][0]
 
+    def test_frame_uses_identifier_issuer_option(self):
+        input = {'http://example.org/p': {'@id': '_:old'}}
+
+        result = jsonld.frame(
+            input,
+            {},
+            options={'identifierIssuer': IdentifierIssuer('_:custom')},
+        )
+
+        assert result == {
+            '@graph': [
+                {'http://example.org/p': {'@id': '_:custom1'}},
+                {'@id': '_:custom1'},
+            ]
+        }
+
     # PR: https://github.com/digitalbazaar/pyld/pull/31
 
     FRAME_0001_IN = {
@@ -933,6 +949,42 @@ def test_circular_references_link_and_embed(self):
             jsonld.frame(input, frame)
 
 
+class TestFlatten:
+    def test_flatten_uses_identifier_issuer_option(self):
+        input = {'http://example.org/p': {'@id': '_:old'}}
+
+        result = jsonld.flatten(
+            input,
+            options={'identifierIssuer': IdentifierIssuer('_:custom')},
+        )
+
+        assert result == [
+            {
+                '@id': '_:custom0',
+                'http://example.org/p': [{'@id': '_:custom1'}],
+            }
+        ]
+
+
+class TestNormalize:
+    def test_normalize_does_not_pass_identifier_issuer_to_to_rdf(self):
+        class RaisingIdentifierIssuer(IdentifierIssuer):
+            def get_id(self, old=None):
+                raise AssertionError('identifierIssuer leaked into normalize')
+
+        input = {'http://example.org/p': {'@id': '_:old'}}
+
+        result = jsonld.normalize(
+            input,
+            options={
+                'format': 'application/n-quads',
+                'identifierIssuer': RaisingIdentifierIssuer('_:custom'),
+            },
+        )
+
+        assert result == '_:c14n1 <http://example.org/p> _:c14n0 .\n'
+
+
 class TestToRdf:
     # PR: https://github.com/digitalbazaar/pyld/pull/202