docs(gfql): clarify schema accessor scope

Author: lmeyerov

docs/source/api/plotter.rst

@@ -29,6 +29,9 @@ declared Arrow types after normal Arrow conversion. The default
 
 Use the experimental read-only ``g.schema`` accessor to inspect the bound
 ``GraphSchema`` object, or ``g.has_schema()`` when only a predicate is needed.
+This reports only the local declaration attached through ``bind(schema=...)``:
+it does not infer a schema from data, fetch a remote dataset schema, or serialize
+the schema into ``gfql_remote()`` requests.
 
 .. toctree::
    :maxdepth: 3

docs/source/gfql/schema.rst

@@ -102,6 +102,16 @@ Schema Objects
   Read back the experimental ``GraphSchema`` bound with ``bind(schema=...)``.
   ``g.schema`` returns the bound object or ``None``; ``g.has_schema()`` returns
   a matching boolean. Use ``bind(schema=...)`` to attach schemas, not assignment.
+  This is local declaration introspection only. It does not infer schemas from
+  data, fetch or hydrate remote dataset schemas, or serialize schemas into
+  ``gfql_remote()`` requests in this release.
+
+  Per-type declarations such as Cat, Dog, and Car are represented by
+  ``GraphSchema.node_types``. The stable public type identity is
+  ``NodeType.name``; ``NodeType.labels`` are the GFQL label predicates that map
+  onto label columns such as ``label__Cat``. For example, Cat and Dog can both
+  carry an ``Animal`` label while still preserving separate Cat and Dog
+  property contracts.
 
 ``NodeType.to_arrow()`` and ``EdgeType.to_arrow()``
   Export declarations as ``pyarrow.Schema`` objects through GFQL's row-schema
@@ -198,12 +208,17 @@ The public schema is consumed by local validation APIs, including:
 ``gfql_remote(...)`` is different. It compiles Cypher strings locally and sends
 the resulting GFQL wire payload to the server, but this release does **not**
 serialize a bound ``GraphSchema`` into remote GFQL requests. Remote execution
-therefore still depends on the server-side dataset schema and GFQL support. If
-you want declared schema checks before a remote call, run
+therefore still depends on the server-side dataset metadata and GFQL support. If
+you want local declared-schema checks before a remote call, run
 ``g.gfql_validate(query)`` locally first, then call ``g.gfql_remote(query)``.
 
 Remote schema transport is planned as a follow-on after the local schema
-contract and serialization boundary are stable.
+contract and serialization boundary are stable. The intended direction is a
+versioned graph-schema envelope derived from ``GraphSchema.to_arrow()``: exact
+Arrow schemas for merged node/edge tables and per-type declarations, plus a
+JSON summary for dataset metadata, UI, and REST consumers. That future transport
+should live beside ``gfql_query`` / ``gfql_operations`` rather than as fake data
+tables.
 
 Compatibility Notes
 -------------------

graphistry/PlotterBase.py

@@ -1799,11 +1799,15 @@ def schema(self) -> Optional["GraphSchema"]:
         The returned object is the same schema instance supplied through
         ``bind(schema=...)``. The accessor is read-only: use ``bind(schema=...)``
         to attach a schema to a new plotter.
+
+        This is local declaration introspection only. It does not infer a schema
+        from data, fetch a remote dataset schema, or serialize the schema into
+        ``gfql_remote()`` requests in this release.
         """
         return self._gfql_schema
 
     def has_schema(self) -> bool:
-        """Return ``True`` when this plotter has a GFQL ``GraphSchema`` bound."""
+        """Return ``True`` when this plotter has a local GFQL schema bound."""
         return self._gfql_schema is not None
 
     def copy(self) -> Plottable:

graphistry/tests/compute/gfql/test_public_schema.py

@@ -190,6 +190,8 @@ def test_bind_schema_is_chainable_and_used_by_preflight() -> None:
     g = _graph(schema).bind(point_color="name")
 
     assert g._gfql_schema is schema
+    assert g.schema is schema
+    assert g.has_schema() is True
     report = g.gfql_validate("MATCH (p:Person)-[:WORKS_AT]->(c:Company) RETURN p.name AS name")
     assert report["ok"] is True