diff --git a/docs/changes.rst b/docs/changes.rst
index 5bc8e96..01ff671 100644
--- a/docs/changes.rst
+++ b/docs/changes.rst
@@ -2,6 +2,12 @@
Changelog
=========
+v0.26.3
+-------
+
+* Add some documentation on ``referencing`` public and non-public API.
+
+
v0.26.2
-------
diff --git a/docs/compatibility.rst b/docs/compatibility.rst
new file mode 100644
index 0000000..69bd3eb
--- /dev/null
+++ b/docs/compatibility.rst
@@ -0,0 +1,25 @@
+=============
+Compatibility
+=============
+
+``referencing`` is currently in beta so long as version numbers begin with a ``0``, meaning its public interface may change if issues are uncovered, though not typically without reason.
+Once it seems clear that the interfaces look correct (likely after ``referencing`` is in use for some period of time) versioning will move to `CalVer `_ and interfaces will not change in backwards-incompatible ways without deprecation periods.
+
+In the spirit of `having some explicit detail on Bowtie's public interfaces `, here is a non-exhaustive list of things which are *not* part of the ``referencing`` public interface, and therefore which may change without warning, even once no longer in beta:
+
+* All commonly understood indicators of privacy in Python -- in particular, (sub)packages, modules and identifiers beginning with a single underscore.
+ In the case of modules or packages, this includes *all* of their contents recursively, regardless of their naming.
+* All contents in the ``referencing.tests`` package unless explicitly indicated otherwise
+* The precise contents and wording of exception messages raised by any callable, private *or* public.
+* The precise contents of the ``__repr__`` of any type defined in the package.
+* The ability to *instantiate* exceptions defined in `referencing.exceptions`, with the sole exception of those explicitly indicating they are publicly instantiable (notably `referencing.exceptions.NoSuchResource`).
+* The instantiation of any type with no public identifier, even if instances of it are returned by other public API.
+ E.g., `referencing._core.Resolver` is not publicly exposed, and it is not public API to instantiate it in ways other than by calling `referencing.Registry.resolver` or an equivalent.
+ All of its public attributes are of course public, however.
+* Any identifiers in any modules which are imported from other modules.
+ In other words, if ``referencing.foo`` imports ``bar`` from ``referencing.quux``, it is *not* public API to use ``referencing.foo.bar``; only ``referencing.quux.bar`` is public API.
+ This does not apply to any objects exposed directly on the ``referencing`` package (e.g. `referencing.Resource`), which are indeed public.
+* Subclassing of any class defined throughout the package.
+ Doing so is not supported for any object, and in general most types will raise exceptions to remind downstream users not to do so.
+
+If any API usage may be questionable, feel free to open a discussion (or issue if appropriate) to clarify.
diff --git a/docs/conf.py b/docs/conf.py
index f06c62f..6ee794b 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -101,11 +101,12 @@ def entire_domain(host):
intersphinx_mapping = {
"hatch": ("https://hatch.pypa.io/latest/", None),
"jsonschema-specifications": (
- "https://jsonschema-specifications.readthedocs.io/en/latest/",
+ "https://jsonschema-specifications.readthedocs.io/en/stable/",
None,
),
+ "regret": ("https://regret.readthedocs.io/en/stable/", None),
"python": ("https://docs.python.org/", None),
- "setuptools": ("https://setuptools.pypa.io/en/latest/", None),
+ "setuptools": ("https://setuptools.pypa.io/en/stable/", None),
}
# -- extlinks --
diff --git a/docs/index.rst b/docs/index.rst
index b2b0226..3dd09c4 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -11,3 +11,4 @@ In other words, a way for e.g. JSON Schema tooling to resolve the ``$ref`` keywo
schema-packages
api
changes
+ compatibility
diff --git a/docs/spelling-wordlist.txt b/docs/spelling-wordlist.txt
index dc04af7..c63d656 100644
--- a/docs/spelling-wordlist.txt
+++ b/docs/spelling-wordlist.txt
@@ -7,11 +7,14 @@ dereferenced
deserialized
discoverability
filesystem
+instantiable
+instantiation
metaschemas
referenceable
resolvers
runtime
schemas
+subclassing
submodules
subresource
subresources
diff --git a/referencing/exceptions.py b/referencing/exceptions.py
index eb5dd6e..d720685 100644
--- a/referencing/exceptions.py
+++ b/referencing/exceptions.py
@@ -18,6 +18,9 @@
class NoSuchResource(KeyError):
"""
The given URI is not present in a registry.
+
+ Unlike most exceptions, this class *is* intended to be publicly
+ instantiable and *is* part of the public API of the package.
"""
ref: URI