Skip to content

v1.4.1 API Additions — Knowledge Serializer Elevation

Status: Shipped in v1.4.1. Impact: Additive only — no breaking changes. Drives: ice_ext/STATUS.md §47-72 item #4.

Summary

Two new public symbols have been elevated into fcc.api.knowledge and re-exported from the top-level fcc.api namespace:

  • fcc.api.JSONLDSerializer
  • fcc.api.RDFSerializer

Both are thin class-based facades over the existing module-level serialize_jsonld, serialize_turtle, serialize_ntriples, and serialize_skos functions in fcc.knowledge.serializers. They carry the same runtime behaviour as the function-level helpers, but wrap the configuration (ontology, output format) into an instance-bound surface that downstream consumers have repeatedly asked for.

Why now

The ice_ext constellation project currently pulls the serializers directly via from fcc.knowledge.serializers import .... That private submodule import ties ice_ext to FCC's internal layout — any refactor of the fcc.knowledge tree would break ice_ext even though the stable serializer behaviour is unchanged.

ice_ext/STATUS.md §4 flagged this as an upstream ask. v1.4.1 resolves it by promoting the two classes into the public API surface.

New public symbols

JSONLDSerializer

from fcc.api import JSONLDSerializer

serializer = JSONLDSerializer(ontology=my_ontology)  # ontology optional
jsonld_doc = serializer.serialize(graph)
# Optional per-call ontology override:
jsonld_doc = serializer.serialize(graph, ontology=other_ontology)

RDFSerializer

from fcc.api import RDFSerializer

serializer = RDFSerializer(format="turtle")          # default
serializer = RDFSerializer(format="ntriples")
serializer = RDFSerializer(format="skos")
rdf_doc = serializer.serialize(graph)

RDFSerializer.SUPPORTED_FORMATS == ("turtle", "ntriples", "skos"). An unsupported format raises ValueError at construction time.

Migration for ice_ext (and similar consumers)

Before (v1.4.0):

from fcc.knowledge.serializers import serialize_jsonld, serialize_turtle

jsonld = serialize_jsonld(graph)
turtle = serialize_turtle(graph)

After (v1.4.1+):

from fcc.api import JSONLDSerializer, RDFSerializer

jsonld = JSONLDSerializer().serialize(graph)
turtle = RDFSerializer(format="turtle").serialize(graph)

The function-level helpers remain importable from fcc.knowledge.serializers for backward compatibility, but consumers are encouraged to migrate to the fcc.api surface so they inherit the 1.x SemVer guarantee (see below).

SemVer commitment

Starting from v1.4.1, both JSONLDSerializer and RDFSerializer are covered by the same 1.x backward-compatibility guarantee as every other symbol listed in fcc.api.__all__:

  • Constructor signatures will not change incompatibly inside the 1.x series.
  • serialize(graph, ontology=None) is the canonical method and will remain callable with that positional-plus-keyword shape for the full 1.x line.
  • RDFSerializer.SUPPORTED_FORMATS may grow (additive) but will not remove values.

Deprecations, if any, will follow the standard 6-month window signalled via the preview namespace (see fcc.plugins.v1_5_preview).

Test coverage

See tests/test_api_serializer_elevation.py for the six tests that pin this elevation, including backward-compatibility validation against the original fcc.knowledge.serializers import path and symbol-identity checks to guarantee fcc.api.JSONLDSerializer is fcc.knowledge.serializers.JSONLDSerializer.